qzl
78 lines
3.0 KiB
Markdown
78 lines
3.0 KiB
Markdown
---
|
||
description: 审查并更新 docs/protocols，确保与当前代码实现一致
|
||
---
|
||
|
||
你现在要执行一次“协议文档一致性审查与更新”，目标是让 `docs/protocols/` 成为项目协议与数据格式的最新事实来源，并与当前代码实现保持一致。
|
||
|
||
## 执行目标
|
||
|
||
1. 审查 `docs/protocols/` 下所有协议文档是否过期、缺失或与实现不一致。
|
||
2. 在发现差异时，优先更新协议文档（而不是先改代码），明确兼容策略。
|
||
3. 输出结构化审查结果：发现的问题、已更新内容、仍待确认项。
|
||
|
||
## 约束
|
||
|
||
- 审查范围优先限定在：`docs/protocols/**` 与本次协议相关代码（`backend/**`、`apps/**`）。
|
||
- 不做无关重构，不改动与协议无关模块。
|
||
- 禁止“吞错式”描述：若不确定，明确标记为待确认，不要假设正确。
|
||
- 若涉及破坏性变更，必须在文档中写明迁移与回滚策略。
|
||
|
||
## 步骤
|
||
|
||
1. **建立协议清单**
|
||
- 列出 `docs/protocols/` 中所有文档。
|
||
- 为每份文档提取：涉及的接口、事件、字段、枚举、状态码、错误结构。
|
||
|
||
2. **建立实现映射**
|
||
- 在 `backend/**`、`apps/**` 中定位对应实现与调用点。
|
||
- 对每个协议项建立“文档 -> 实现”映射（文件路径 + 关键符号/接口名）。
|
||
|
||
3. **逐项比对并分级**
|
||
- 比对以下维度：
|
||
- 请求/响应结构与字段可选性
|
||
- 字段命名、类型、默认值、约束
|
||
- 错误码/错误体格式
|
||
- 版本号、兼容说明、废弃说明
|
||
- 给每个差异打级别：
|
||
- CRITICAL：会导致客户端/服务端不兼容
|
||
- HIGH：行为偏差明显，容易引发线上错误
|
||
- MEDIUM：文档缺失或描述不完整
|
||
- LOW：措辞、示例、格式问题
|
||
|
||
4. **更新文档（优先）**
|
||
- 先更新 `docs/protocols/**`，使其反映当前真实实现。
|
||
- 每处更新都要补充“兼容策略”：
|
||
- `backward-compatible`（向后兼容）或
|
||
- `requires-migration`（需要迁移）
|
||
- 如为 `requires-migration`，补充迁移步骤与回滚注意事项。
|
||
|
||
5. **一致性复核**
|
||
- 复查所有变更是否与实现一致。
|
||
- 如仓库有协议相关测试/校验脚本，执行最小必要验证。
|
||
|
||
## 输出格式（必须）
|
||
|
||
1. **Protocol Audit Scope**
|
||
- 本次审查的文档列表
|
||
- 对应实现文件映射
|
||
|
||
2. **Findings**
|
||
- 按 CRITICAL/HIGH/MEDIUM/LOW 分组列出差异
|
||
- 每条包含：文档位置、实现位置、差异说明、影响范围
|
||
|
||
3. **Doc Updates Applied**
|
||
- 列出已更新的文档与关键修改点
|
||
- 标注每项兼容策略（`backward-compatible` / `requires-migration`）
|
||
|
||
4. **Open Questions**
|
||
- 仍需产品/后端/前端确认的点
|
||
|
||
5. **Verification**
|
||
- 列出执行的验证命令与结果（通过/失败）
|
||
|
||
## 完成标准
|
||
|
||
- `docs/protocols/` 覆盖当前实现的真实协议。
|
||
- 所有发现的关键差异（CRITICAL/HIGH）要么已修正文档，要么被明确记录为阻塞项。
|
||
- 输出报告完整，后续协作者可据此继续推进。
|