7.7 KiB

Raw Permalink Blame History

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

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

给新会话的一句话

继续本 effort（map.md），接手 04 文档仓重排执行落地（Status: claimed，无需重新认领），从 t10 开始做到关票。

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

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

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

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

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

SearchReplace 假失败：对源码路径报 "save file failed, reason: unknown" 但实际已写入——报错 ≠ 失败，必须 Grep/Test-Path 复核文件系统实际状态再决定下一步
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 当前目录）
git mv 对 untracked 报 fatal → 用 Move-Item；git rm 后空目录壳用 Remove-Item 清理
Java 注解扫描五个盲区（对账脚本 v3 已全修）：@PreAuthorize 嵌套括号断链、裸字符串 tags、无括号 @PostMapping、@Operation 位于 @PostMapping 之后（注解顺序）、方法级 tags = {"..."} 数组闭括号把"注解区下界"切坏（v3 方案：mapping 前 800 字符窗口 + findall 取最后一个 @Operation）
文档仓历史残留：A7 后台管理/权限点管理/资源树列表.bru 的 url 行是绝对地址 https://ai.itc.vip/crm-api/api/resources/list——对账脚本已归一化识别；bruno-sync 真跑时会以源码为准把它修正为 {{baseUrl}} 形式（结构听源码，合法 patch），验收时留意
大块 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 一次一问

7.7 KiB Raw Permalink Blame History