# 视觉小说模板实现收口与交接说明 2026-05-07

## 1. 范围

本文记录 `AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md` 的 `VN-13` 收口结果，作为视觉小说模板后续维护的一页式入口。

本文只总结当前已经落地且需要长期遵守的实现边界，不再把视觉小说描述成外部 TXT 平台迁移，也不重复旧迁移方案里的临时讨论。

## 2. 当前正式入口

后续维护时优先看这些文档：

1. [AI 原生视觉小说模板 PRD](../prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md)
2. [SpacetimeDB 表说明与查询目录](./SPACETIMEDB_TABLE_CATALOG.md)
3. [视觉小说 VN-03 Prompt 与 LLM 工具实现说明](./VISUAL_NOVEL_PROMPT_AND_LLM_TOOLS_VN03_2026-05-05.md)
4. [视觉小说 VN-11 负向扫描报告](../audits/VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md)
5. [视觉小说模板交接与维护经验](../experience/VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md)

旧的 `TXT_MODE_VISUAL_NOVEL_MIGRATION_EXECUTION_PLAN_2026-04-20.md` 只保留历史参考意义，不再作为实现口径。

## 3. 已收口的实现边界

### 3.1 创作链路

- 创作链统一走 `/api/creation/visual-novel/*`。
- 入口、工作台、结果页和服务端 prompt 已围绕 `visual-novel` 模板闭环对齐。
- `VisualNovelResultDraft`、`VisualNovelCreationSessionSnapshot` 等共享契约已经成型。

### 3.2 运行链路

- 运行链统一走 `/api/runtime/visual-novel/*`。
- 运行时只认 typed step 和快照，不让前端从 `raw_text` 猜业务真相。
- `visual_novel_runtime_history_entry` 只用于继续体验和历史重生成边界，不是回放表。

### 3.3 数据链路

- SpacetimeDB 首版只保留 6 张视觉小说表。
- `visual_novel_runtime_event` 是 `public event` 审计事件表，不是 replay 数据源。
- 表结构变化必须同步 `migration.rs`、`SPACETIMEDB_TABLE_CATALOG.md` 和 Rust bindings。

### 3.4 作品与发布

- 作品架、广场和分享都复用平台现有链路。
- 公开作品码统一使用 `VN-` 前缀。
- 发布后要刷新作品架和公开聚合。

### 3.5 资产与登录态

- 文档、封面、背景、角色和音乐都只保留平台资产对象引用。
- 不保存大 Data URL、不走独立对象存储、不新增视觉小说私有存档系统。
- 退出登录时要清空视觉小说私有 session、work、run 和错误状态。

## 4. 长期维护规则

1. 看到视觉小说相关改动，先确认是不是契约改动；如果是，先同步 TS / Rust shared contracts。
2. 看到表结构改动，先同步 `migration.rs` 和表目录，再补 bindings。
3. 看到资产链路改动，只改平台资产引用，不回退到本地路径或二进制直存。
4. 看到运行时历史改动，只维护 typed history 和审计事件，不把它改成回放能力。
5. 看到旧 TXT 文档时，只把它当历史来源，不把其中的平台工程目标重新带回实现。

## 5. 验证口径

收口后建议按下面顺序检查：

```bash
npm run check:encoding
npm run check:visual-novel-vn11
npm run typecheck

cd server-rs
cargo test -p shared-contracts
cargo test -p module-visual-novel
cargo check -p api-server
```

如果本轮没有改代码，只要编码检查和负向扫描通过，通常就说明 VN-13 的文档收口已经站稳。