feat: expand novel IP and production workflows

2026-09-18 08:14:05 +02:00
parent b2ae4600b4
commit d9c81a3ac0
235 changed files with 117971 additions and 2721 deletions
@@ -0,0 +1,133 @@
+# Work 与代码同步协议 V1
+
+> 目标：让 Work 的设计世界持续认识 Git + Codex 的代码现实，同时避免把源码和敏感信息塞进知识库。
+
+## 1. 权责划分
+
+### Work 负责
+
+- 产品定位和业务规则。
+- 新功能讨论、替代方案和优先级。
+- 跨模块架构决策。
+- 用户体验、质量标准和未来路线。
+- 形成 `FEATURE_*.md`、ADR 和验收口径。
+
+### Git + Codex 负责
+
+- 当前源码和数据库迁移。
+- 实现细节和接口事实。
+- 自动测试、构建和部署状态。
+- 当前生产配置与运行验证。
+- 生成状态快照和同步包。
+
+## 2. 文档层级
+
+```text
+L0  PROJECT_STATUS：不可变事实快照
+L1  SYSTEM/ENGINE/PIPELINE/DATABASE：当前有效设计
+L2  FEATURE/ADR：未来设计和决策
+L3  CHANGELOG：已发生变化
+L4  历史设计/讨论记录：仅供追溯
+```
+
+L2 不能在代码完成前冒充 L1；L4 不能覆盖 L0。
+
+## 3. 标准闭环
+
+```mermaid
+flowchart LR
+  Idea[想法] --> Work[Work 讨论]
+  Work --> Feature[FEATURE/ADR]
+  Feature --> Codex[Codex 实现]
+  Codex --> Verify[测试/构建/部署验证]
+  Verify --> Change[更新 CHANGELOG]
+  Change --> Domain[更新领域文档]
+  Domain --> Status[必要时生成新状态快照]
+  Status --> Upload[上传同步包]
+```
+
+## 4. 何时更新哪些文档
+
+| 变化 | 必须更新 |
+| --- | --- |
+| 小缺陷修复，不改变契约 | CHANGELOG |
+| API、状态或领域规则变化 | CHANGELOG + 对应领域文档 |
+| 新功能设计、尚未实现 | 新建 FEATURE 文档 |
+| 跨模块技术决策 | 新建 ADR |
+| Prisma schema 变化 | DATABASE + CHANGELOG + 迁移 |
+| Provider/队列/Prompt 机制变化 | AI_PIPELINE + CHANGELOG |
+| 小说生产逻辑变化 | NOVEL_ENGINE + CHANGELOG |
+| 短剧/视频/合成逻辑变化 | DRAMA_ENGINE + CHANGELOG |
+| 架构、部署、测试或风险显著变化 | 新建 PROJECT_STATUS_Vn |
+
+## 5. 版本规则
+
+- 状态快照：`PROJECT_STATUS_V1.md`、`V2.md`，发布后不可改写事实。
+- 当前设计：结构性改变升 V2；旧版本移入历史区或保留只读。
+- FEATURE/ADR：决策变化升版本，不覆盖已评审版本。
+- CHANGELOG：只追加，不回写历史结论；错误修正新增一条说明。
+- 同步批次：`WORK_SYNC_YYYY-MM-DD_Vn`。
+
+## 6. 上传前检查
+
+1. 文件只包含当前项目必要信息。
+2. 没有 `.env` 值、API Key、JWT、密码、签名 URL 和个人数据。
+3. 状态、数量和测试结果标注采集日期。
+4. “已实现”“部分实现”“待实现”区分清楚。
+5. 文档中的模型、路由和队列说法与源码一致。
+6. 所有文件列入 `SYNC_MANIFEST.md` 并生成 SHA-256。
+7. `CHANGELOG.md` 已追加本批次。
+8. 上传后在 Work 标记批次号和生效日期。
+
+## 7. Work 讨论新功能的输入模板
+
+```markdown
+当前基线：WORK_SYNC_YYYY-MM-DD_Vn
+关联现状：PROJECT_STATUS_Vn
+关联领域：<领域文档>
+
+目标：
+非目标：
+业务规则：
+现有约束：
+预期用户流程：
+数据影响：
+API/队列/Provider 影响：
+成本与安全：
+验收标准：
+回滚条件：
+```
+
+## 8. 交给 Codex 的实现包
+
+Work 讨论结束后，交付内容应至少包括：
+
+- 已确认的 FEATURE/ADR 文件。
+- 关联的当前状态和领域文档版本。
+- 明确的验收标准。
+- 不允许改变的现有行为。
+- 是否允许数据库迁移、付费调用和生产重启。
+
+不要只复制一段没有上下文的聊天结论。
+
+## 9. 冲突处理
+
+### 文档与代码冲突
+
+先审计源码、迁移和运行状态；确认代码现实后更新状态快照。若代码本身是错误实现，再通过 FEATURE/修复任务改变代码，不能为了让文档“看起来一致”而掩盖差异。
+
+### Work 与最新设计冲突
+
+保留两个方案，形成 ADR，记录为什么更改。未经确认的 Work 建议不得直接覆盖当前有效文档。
+
+### 数据与文档冲突
+
+实时业务数量以数据库只读查询为准；文档快照必须标注日期。
+
+## 10. 建议节奏
+
+- 每个已上线功能：立即追加 CHANGELOG。
+- 每周或每个开发批次：更新受影响领域文档。
+- 每次结构性发布：生成新状态快照和同步清单。
+- 每月至少一次：检查备份、状态漂移、失败任务和敏感信息。
+