1

docs/experience/VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md

@@ -0,0 +1,48 @@
+# 视觉小说模板交接与维护经验 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 文档和这份交接说明往下走。