# 视觉小说模板交接与维护经验 2026-05-07

## 1. 先读什么

新开发者接手视觉小说时，建议按这个顺序看：

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

## 2. 最容易踩的坑

1. 不要把 `visual_novel_runtime_history_entry` 当回放表来扩。
2. 不要把 `visual_novel_runtime_event` 当业务回放数据源来用。
3. 不要绕过平台资产对象去保存图片、音乐或文档。
4. 不要让旧 TXT 迁移文档重新变成实现口径。
5. 不要忘记发布后刷新作品架和公开聚合。
6. 不要忘记退出登录时清理视觉小说私有状态。

## 3. 维护时的判断顺序

1. 先看是不是共享契约变化。
2. 再看是不是 SpacetimeDB 表或 facade 变化。
3. 然后看是不是作品架、广场或 runtime 的前端分流变化。
4. 最后才看文档措辞和历史说明。

## 4. 常用检查

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

如果改了后端，再补：

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

## 5. 一句话结论

视觉小说模板已经是平台内的正式模板玩法，不是外部平台迁移；后续维护只需要沿着 PRD、表目录、prompt 文档和这份交接说明往下走。