---
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）要么已修正文档，要么被明确记录为阻塞项。
- 输出报告完整，后续协作者可据此继续推进。