# 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。
- 每周或每个开发批次：更新受影响领域文档。
- 每次结构性发布：生成新状态快照和同步清单。
- 每月至少一次：检查备份、状态漂移、失败任务和敏感信息。