# 交接：api-docs-reorg · 票 04 执行中段（2026-08-31）

> 写给换机后的 fresh agent。票 04 已完成 9/12 步，对账全绿；剩 t10 分区 README、t11 ADR-0024 修订、t12 验收关票。

## 给新会话的一句话

继续本 effort（map.md），接手 [04 文档仓重排执行落地](issues/04-execute-reorg.md)（Status: claimed，**无需重新认领**），从 t10 开始做到关票。

## 必读工件（按序，不重复其内容）

1. [map.md](map.md) — effort 地图：目的地 + Decisions so far
2. [04 文档仓重排执行落地](issues/04-execute-reorg.md) — 当前票：Question 6 条即验收清单；Answer 段空（t12 关票时填）
3. [mapping-table.md](mapping-table.md) — 唯一执行输入与验收基线（§2 tags 重构 25 行 / §3 端点明细 / §4 git-mv 清单 / §6 基线目录树 196 文件 / §7 判断点 8 条）
4. bruno-sync 的 SKILL.md — 对账纪律与 Step 4 报告格式（铁律：结构听源码、表述听人；只碰带 `generated` 标记的 .bru）
5. [01](issues/01-mechanism-choice.md) / [02](issues/02-lead-rule-home.md) / [03](issues/03-mapping-table.md) — 已决三票（深 tag 机制选型 / LeadPool 双归属 / 映射表生成）

## 换机注意事项（本机 → 新机）

1. **两仓路径**：
   - 源码仓 `d:\code\crm-backend-matt`（agent workspace）
   - 文档仓 `D:\code\crm-api-docs`（**在源码 workspace 之外**：Write/SearchReplace 工具写不了它（45405），写它一律 Bash + python 程序化落盘，且沙箱下需权限提升）
   - 新机路径若不同：对账脚本头部 `REPO`/`DOCS` 常量、`bruno-sync.local.json` 要相应改
2. **不进 git 的文件**（源码仓 .gitignore）：
   - `tmp/` → 对账脚本已复制到本 effort 目录：[tmp_reorg_audit.py](tmp_reorg_audit.py)
   - `bruno-sync.local.json` → 内容就一行 `{ "docsRepoPath": "D:/code/crm-api-docs" }`，新机按实际路径重建
3. **源码仓大量未提交改动**：`.scratch/lanhu-latest`（staged）+ 本会话 25 个 Controller 的 tags 重构 + `bruno-sync.config.json` menuBindings 四键改名 + `.scratch/api-docs-reorg/` 全部工件。换机走 git 需用户自行 commit/push，或整目录拷贝（由用户定，agent 不要主动 commit）。
4. **文档仓大量未提交改动**：本会话的 git mv（R 记录）+ 新建 folder.bru / 空分区 / LeadPool 副本，全部未提交，同上由用户定。

## 已完成（t1-t9，不赘述细节）

- **t1 前置核查**：191 个接口 .bru 全带 `generated` 标记；folder.bru 均为 `meta{name,seq}` 格式
- **t2-t5 源码 tags 重构**：25 个 Controller 按映射表 §2 逐行落地（类级 @Tag 改全路径 / 方法级 @Operation(tags) 深路径 / LeadPool 5 端点双值 tags / SystemController 10 端点补显式 tag / Query 收敛 / Collab+Sub 分挂）。Grep 复核旧前缀零残留；`mvn compile` 通过；BOM 扫描 clean
- **t6 menuBindings**：`bruno-sync.config.json` 四键前缀 `线索管理/` → `A2 线索管理/`（viewType/scopeKey 值不动）
- **t7 文档仓 git-mv**：映射表 §4 清单全部落地；空壳（系统管理/、system/ 的 folder.bru）git rm + 目录清理；folder.bru name/seq 统一（A0=1、A2=4、A3=5、A7=9、公共依赖=10、调试=11；商机规则=1）
- **t8 LeadPool 双归属副本 + 空分区**：`A7 后台管理/线索规则/` 5 个 .bru 副本（Copy-Item）；空分区 `A1 销售工作台（首页）/A1X 工作计划/A4 客户管理/A5 项目管理/A6 数据看板` folder.bru 占位（seq 2/3/6/7/8）
- **t9 全量对账（已通过）**：运行 `python -X utf8 tmp_reorg_audit.py`（本 effort 目录副本）→ **`src keys: 196 ; doc keys: 196`，双向差集均 0**。钥匙 = (METHOD, url, tag 全路径) ↔ (METHOD, url, 文件夹相对路径)；脚本已做 url 归一化（剥 `{{baseUrl}}` / 绝对 host / `/crm-api` 子路径 / `?` 查询串）。新机复跑需先改脚本头两个路径常量

## 待做（从这里开始）

### t10 分区索引 README（票 04 第 3 条）

- 11 个一级目录：`A0 登录界面`、`A1 销售工作台（首页）`、`A1X 工作计划`、`A2 线索管理`、`A3 商机管理`、`A4 客户管理`、`A5 项目管理`、`A6 数据看板`、`A7 后台管理`、`公共依赖`、`调试(验证专用)`
- 每分区 README：已落地接口清单（按二级目录列 .bru 名）→ 空缺标注 → 对接工程师示位
- 生成方式票面留给落地时定：**推荐手写**（README 是给对接工程师的叙述性导航，脚本产出生硬；一次性 11 个文件）。空分区 README 只写占位说明（该分区无接口落地，对应原型 A 区页面）
- 注意：bruno-sync 不生成 README（只管 .bru）；README 放分区一级目录下

### t11 ADR-0024 修订（票 04 第 4 条）

`docs/adr/0024-bruno-docs-grouping-by-menu.md` 文末追加修订段，六要点照票面：一级目录对齐原型 A 区（引用 [lanhu-tree-v29.md](lanhu-tree-v29.md)）；深 tag 纪律（一级=分区原文，二级=页面，更深=页面内分组）；商机规则归 A7 裁决（票 02）；URL 回退通道关闭；双归属=方法级多值 tags；新接口挂载纪律（新 Controller 按页面全路径挂 tag）

### t12 验收 + 关票（票 04 第 6 条）

- 对照 mapping-table.md §6 基线目录树逐项核对文档仓（196 个接口 .bru = 191 + 5 副本；folder.bru 不计）
- knife4j 抽查：起 crm-app 后看 swagger 分组 = 深路径 tag 原文（抽查 3-4 组即可，如 `A0 登录界面` / `A3 商机管理/商机详情/客户` / `A7 后台管理/权限管理/角色管理` / `公共依赖/文件`）
- **补跑单测**：票 04 第 1 条要求"回归编译与单测"，本会话只跑了 `mvn compile`（tags 是注解字符串、逻辑零变化，风险低，但票面要求补上）
- 关票：票 04 写 Answer（六条逐项结果）+ Status: claimed → resolved；map.md Decisions so far 加指针行

## 本会话踩坑实录（省新会话时间）

1. **SearchReplace 假失败**：对源码路径报 "save file failed, reason: unknown" 但实际已写入——报错 ≠ 失败，必须 Grep/Test-Path 复核文件系统实际状态再决定下一步
2. **workspace 外写入**：Write/SearchReplace 写不了文档仓（45405）；一律 Bash（需权限提升）+ python 程序化落盘。PowerShell 5.1 `Set-Content -Encoding UTF8` 会写 BOM → 用 `[IO.File]::WriteAllText(path, content, [Text.UTF8Encoding]::new($false))`，且 .NET 方法要绝对路径（PS Set-Location 不影响 .NET 当前目录）
3. **git mv 对 untracked 报 fatal** → 用 Move-Item；git rm 后空目录壳用 Remove-Item 清理
4. **Java 注解扫描五个盲区**（对账脚本 v3 已全修）：@PreAuthorize 嵌套括号断链、裸字符串 tags、无括号 @PostMapping、@Operation 位于 @PostMapping 之后（注解顺序）、**方法级 `tags = {"..."}` 数组闭括号把"注解区下界"切坏**（v3 方案：mapping 前 800 字符窗口 + findall 取最后一个 @Operation）
5. **文档仓历史残留**：`A7 后台管理/权限点管理/资源树列表.bru` 的 url 行是绝对地址 `https://ai.itc.vip/crm-api/api/resources/list`——对账脚本已归一化识别；bruno-sync 真跑时会以源码为准把它修正为 `{{baseUrl}}` 形式（结构听源码，合法 patch），验收时留意
6. **大块 CJK+Markdown 过 edit/Write 有非确定性丢载荷风险**：单发重试 → python 程序化落盘；`.scratch/` 与 `tmp/` 下尤甚

## Suggested skills

- **wayfinder**（Work through the map 模式）：t12 关票 + map.md 更新按其第 4/5 步执行
- **bruno-sync**：若需向用户出正式同步报告，按其 SKILL.md Step 4 格式——本次对账预期全绿：新增 0 / 更新 0 / 删除 0 / 全部不动
- 若 t10/t11 落地中冒出需要用户裁决的点，用 **grilling** 一次一问