update:优化个人训练图片

doc.md

@@ -113,4 +113,134 @@ git push origin test
 2. **每次合并前先拉取最新代码**，避免覆盖他人改动
 3. **体验版发布前确认代码已提交**，避免遗漏
 4. **开发分支命名建议**：`feature/姓名-功能名`，如 `feature/zhangsan-login`
-5. **删除已合并的开发分支**：`git branch -d feature/your-name-work`
+5. **删除已合并的开发分支**：`git branch -d feature/your-name-work`
+
+---
+
+## 六、比赛服 Proto 更新流程
+
+### 1. 新开发人员快速接手
+
+首次拉取项目后，先安装依赖并确认当前协议与运行时解码器一致：
+
+```bash
+npm install
+npm run proto:check
+npm run build
+```
+
+如果 `proto:check` 提示协议不同步，先执行 `npm run proto:generate`，不要直接修改生成区块。
+
+### 2. 相关文件职责
+
+| 文件 | 职责 | 修改规则 |
+|------|------|----------|
+| `src/utils/match.min.js` | 后端比赛服协议描述，是生成字段表的输入文件 | 后端协议更新时整体替换；禁止在小程序运行时代码中导入 |
+| `scripts/generate-match-schema.mjs` | 解析协议、校验字段并生成运行时字段表 | 只有新增通用协议能力时才修改 |
+| `src/utils/matchProtocol.js` | 小程序实际使用的 protobuf 编解码器 | `<match-schema-generated>` 标记区间内禁止手动修改 |
+| `src/matchWebsocket.js` | 服务端消息路由、ACK 和业务事件分发 | 新增消息业务行为时人工接入 |
+| `src/utils/matchAdapter.js` | 将解码结果从 snake_case 统一转换为 camelCase | 页面继续使用适配后的字段名 |
+
+`match.min.js` 不是小程序运行时解码器。运行时仍使用 `protobufjs/minimal.js` 的 `Reader/Writer`，`int64` 字段统一保留为字符串，避免大整数精度丢失。
+
+### 3. 日常协议更新步骤
+
+```text
+替换 src/utils/match.min.js
+        ↓
+执行 npm run proto:update
+        ↓
+检查生成差异和业务接入范围
+        ↓
+执行 git diff --check
+        ↓
+微信开发者工具检查包体并上传
+```
+
+具体操作：
+
+1. 从后端获取最新的 `match.min.js`，整体覆盖 `src/utils/match.min.js`。
+2. 执行推荐命令：
+
+```bash
+npm run proto:update
+```
+
+3. 该命令会依次完成：
+   - 解析 `match.min.js`
+   - 更新 `matchProtocol.js` 内的生成区块
+   - 校验生成区块与协议源文件一致
+   - 执行微信小程序正式构建
+4. 检查 Git 差异。普通字段更新通常只应涉及：
+   - `src/utils/match.min.js`
+   - `src/utils/matchProtocol.js` 的生成区块
+5. 如果新增了消息业务行为，再单独检查 `src/matchWebsocket.js`、页面或组件的接入改动。
+6. 执行空白和换行检查：
+
+```bash
+git diff --check
+```
+
+7. 打开微信开发者工具，导入 `dist/build/mp-weixin`，检查代码依赖分析和主包体积后再上传。
+
+### 4. Proto 命令说明
+
+| 命令 | 用途 | 是否修改文件 |
+|------|------|--------------|
+| `npm run proto:generate` | 根据 `match.min.js` 更新生成区块 | 是 |
+| `npm run proto:check` | 检查生成区块是否与协议同步 | 否 |
+| `npm run proto:update` | 执行生成，然后运行正式构建 | 是，日常更新推荐使用 |
+| `npm run dev` | 启动开发构建，启动前自动执行 `proto:check` | 协议不同步时直接中止 |
+| `npm run build` | 执行正式构建，构建前自动执行 `proto:check` | 协议不同步时直接中止 |
+
+`npm run dev` 和 `npm run build` 只负责检查，不会自动改写协议；发现不同步时应执行 `npm run proto:generate` 或 `npm run proto:update`。
+
+### 5. 自动生成与人工接入边界
+
+以下内容由生成器自动处理：
+
+- 服务端和客户端消息枚举
+- 普通 scalar 字段
+- 嵌套 message
+- repeated message
+- 当前解码器支持的 map
+- snake_case 字段名和 oneof 兼容信息
+
+以下情况仍需人工处理：
+
+- **新增服务端消息类型**：枚举会自动生成，但 `matchWebsocket.js` 的路由、ACK、音频或页面事件仍需接入。
+- **新增客户端指令**：枚举会自动生成，但发送函数、字段编码和业务调用入口仍需接入。
+- **修改既有字段编号或类型**：属于协议兼容性变更，必须先与后端确认，不能只看构建是否通过。
+- **新增解码器不支持的类型**：生成器会直接报错，需要同时扩展生成器和 `matchProtocol.js` 的通用解码能力。
+
+当前生成器会拒绝不支持的 scalar、map key、字段规则以及 packed scalar repeated，避免继续构建后静默丢字段。
+
+### 6. 常见报错处理
+
+| 报错或现象 | 原因 | 处理方式 |
+|------------|------|----------|
+| 生成区块与 `match.min.js` 不同步 | 替换协议后没有重新生成 | 执行 `npm run proto:update` |
+| 找不到 `Root.create(...)` | 后端提供的文件格式发生变化或文件不完整 | 停止更新，确认协议文件来源和生成格式 |
+| 使用了不支持的类型、规则或 map key | 新协议超出当前通用解码器能力 | 不要手补生成区块，先扩展生成器和解码器并补充验证 |
+| packed scalar repeated 不支持 | protobuf 默认可能使用 packed 编码，当前通用解码器未覆盖 | 增加 packed 解码能力后再重新生成 |
+| `matchProtocol.js` 缺少生成区块标记 | 标记被误删或生成区块被手改 | 恢复 `<match-schema-generated>` 标记，重新执行生成 |
+| 协议生成成功但构建失败 | 问题位于项目构建或业务代码，不是字段表同步 | 保留生成结果，按构建错误继续定位 |
+
+### 7. 禁止事项与验收清单
+
+禁止：
+
+- 禁止在运行时代码中导入 `match.min.js`。
+- 禁止手动修改 `<match-schema-generated>` 与 `</match-schema-generated>` 之间的内容。
+- 禁止绕过 `proto:check` 后直接上传。
+- 禁止把 `int64` 字段直接转换为普通 `Number`。
+- 禁止把“枚举已经生成”等同于“业务消息已经完成接入”。
+
+每次协议更新至少确认：
+
+1. `npm run proto:check` 通过。
+2. `npm run build` 通过，或直接确认 `npm run proto:update` 已完整通过。
+3. `git diff --check` 通过。
+4. 生成区块之外没有意外改动。
+5. 新消息已完成必要的 WebSocket 路由和页面验证。
+6. 微信开发者工具中的主包、分包体积符合上传限制。