10 KiB

Raw Blame History

HANDOFF — customer-e2e 换机续跑（票 06 收尾 → 08 → 09）

交接时间：2026-09-04 凌晨。上游会话在旧电脑完成票 01-05、07，票 06 进行到「生成器修好、待重跑」。用户指令：wayfinder 把 Map 全部做完（覆盖单票/会话默认）——本 handoff 即为续跑手册。地图与全部决策细节：map.md（先读它的「范围拍板 + 环境事实 + 判定纪律」三节）；9 张票在 issues/。

1. 进度快照

票	主题	状态	交付物
01	原型重拉+流程盘点	✅ resolved	spec-flows.md（16 流程 F-01..16 + 55 端点总账）
02	起服冒烟+环境盘点	✅ resolved	env-inventory.md（64 表/字典 24 组/seed 约束 5 条）
03	seed 脚本+联调数据	✅ resolved	seed-customer.py（7/7 幂等全绿）+ seed-ids.json + seed-data-manifest.md
04	核心域实测	✅ resolved	e2e-core.py 112 用例 ✅110/⚠2/❌0 + report-core.md + specimens-core.json（45 端点）
05	重流程实测	✅ resolved	e2e-heavy.py ✅54/⚠4/❌0 + report-heavy.md + specimens-heavy.json（19 端点）
06	Bruno 文档生成	🔶 claimed，进行中	defs_a4.py + gen_a4_bru.py 已写完，main() 分组 bug 已修，尚未重跑；文档仓有第一次跑的错误产物待清理
07	单文件前端 demo	✅ resolved	demo/index.html 831 行（5 tab 全 55 端点交互面 + 缺陷角标 D-02/D-05/D-04/D-07）
08	demo 浏览器自测	⬜ open	先修 demo 联系人字段名偏差（见 §4）
09	E2E 报告聚合终稿	⬜ open	e2e-report.md 终稿 + map 收尾

缺陷台账至今：D-01（P0，已修复+复验通过）、D-02（P2 follow 过去时间未拦）、D-03（P2 缺 version 报 67001）、D-04（P2 导入 insertFail 炸 varchar(500)）、D-05（P1 导入 INSERT 行必失败）、D-07（P1 交割 assignable 超时）；D-06 撤回。只报告不修复（拍板）。

2. 换机检查清单（新电脑开工前逐项过）

workspace：e:\code\crm-backend-matt（HEAD 43887d3，客户模块实现 100% 完成，521 测试全绿——不要动源码）。
Bruno 文档仓（票 06 输出目标）：E:\code\crm-api-docs（git 仓，agent 不提交，用户审查后自行提交）。若新电脑盘符/路径不同，改 gen_a4_bru.py 顶部 DOCS = r'E:\code\crm-api-docs' 一行即可（其余路径均由它派生）。
- 根目录是裸 collection（bruno.json + collection.bru，无 workspace.yml）——已按现状跑通全部生成逻辑，不做 workspace 升级（Not-yet 挂号项的结论，写入票 06 Answer）。
远程共享库不动：DB/Redis/MinIO 凭据全部内置在 crm-app/src/main/resources/application.yml 默认值（见 map.md「环境事实」，本 handoff 不复述明文）。seed 数据仍在远程库（17 客户 KH202609030006-0022 等）——不要重跑 seed-customer.py，否则 id 全变，specimens/defs_a4.py/seed-ids.json 的实测 id 集体过期。仅当库被清才重跑，且需同步刷新 seed-ids.json + specimens + defs_a4.py。
Python 解释器：旧电脑 python 命令失败（ExitCode 1）、py -X utf8 -u 有效。新电脑先 py -X utf8 -u -c "print('ok')" 验证，两个都不行就装（.scratch 脚本全按 py 写）。
本地起服（票 08 需要）：命令与坑见 map.md「环境事实」（verify profile + MinIO env 注入；重打包前先停 8080 java 进程；fat jar 增量陷阱）。jar 不在新电脑则需要先 mvn package。
AGENTS.md 纪律照旧：.java UTF-8 无 BOM；py -c 复杂脚本必炸→一律落盘 .py；Write 出不了 workspace→文档仓用 python 直写；del 多参数报错→用 DeleteFile 工具。

3. 票 06 续跑手册（第一步，最紧急）

现状：defs_a4.py（57 端点定义表）+ gen_a4_bru.py（生成引擎）已写完；main() 的目录重复 bug（A4 客户管理\A4 客户管理\...）已修复（剥前缀相对 BASE、根级 tag 相对 collection 根）但修后未重跑。文档仓现残留第一次跑的错误产物（已实核 2026-09-04）：

E:\code\crm-api-docs\A4 客户管理\A4 客户管理\（整个重复嵌套目录，含 9 子目录）→ 删
E:\code\crm-api-docs\A4 客户管理\客户管理\超期提醒规则\（错位：提醒规则 tag 无 A4 前缀，应建在 collection 根 E:\code\crm-api-docs\客户管理\超期提醒规则\）→ 删
保留：A4 客户管理\folder.bru、A4 客户管理\README.md（README 之后要重写）

步骤：

清残留：落盘一个 .py 用 shutil.rmtree 删上述两目录（Write 出不了 workspace，脚本放 .scratch/customer-e2e/）。
重跑：cd e:\code\crm-backend-matt\.scratch\customer-e2e; py -X utf8 -u gen_a4_bru.py。验证输出 generated 57 .bru in 10 dirs，路径形如 A4 客户管理\客户管理\新增客户.bru（10）+ 其余 8 目录 45 文件 + 根级 客户管理\超期提醒规则\（2 文件，含根级 folder.bru seq:12）。
抽查 3 个文件核对格式（金标准 = A3 商机管理\新建商机\新建商机.bru）：meta tags:[generated]、method 块、params/body 块、docs 四段；重点看 specimens 真值是否注入（响应示例带 // 示例数据（E2E 实测真值））、Reminder JSON 端点 body:json 是否用 specimens 实测 body。
对账 verify：写 verify_a4.py——正则扫 9 个 Controller（crm-customer/controller）+ crm-rule ReminderRuleController 的 mapping 得 (METHOD, path) 钥匙集（应 57），与生成 .bru 的 docs 首行钥匙比对，全命中收口（防笔误漏端点）。
重写 A4 客户管理\README.md（现为占位）：9 子目录索引 + 提醒规则为何在根级（tag 原文，无 A4 前缀）+ crm-preference 6 端点不生成副本的说明（源码 tag 挂 A3，避免 sync 重跑孤儿；文字索引 scopeKey=customer.*）+ 维护纪律（只碰 tags:[generated]、对账钥匙行勿手改、agent 不提交 git）。
关票：issues/06-bruno-docs.md 改 Status: resolved + 追加 Answer 段（沿用票 07 模式：落盘 answer06.md + append 脚本，别用花哨 py -c）——Answer 必含：生成规模（57 文件 10 目录）、分组决策（tag 原文/根级提醒规则/preference 副本划出）、对账结果、裸 collection 不升级的结论、README 索引说明。map.md「Decisions so far」追加一行。

4. 票 08 手册（demo 浏览器级自测）

先修 demo 联系人字段名（源码实锤的偏差）：demo/index.html 的联系人编辑弹窗用了 contactName/position，源码 ContactDTO 实际为 name/phone/jobTitleName/jobTitleId/jobTitleCategory/jobTitleLevel/isKeyContact/isInternal/giftRemark/source（以 defs_a4.py「新增联系人」params 为准逐一对齐后再测）。
认领票 08（Status: claimed）→ 起服（§2.5）→ 用 /webapp-testing（Playwright）打开 demo/index.html（file:// 静态页，登录走 GET /api/auth/debug/token?userId=<uid>，baseUrl 指本地 8080）。
冒烟面：5 tab 各走一遍（列表三 workspace + 批量操作 / 详情 6 子页签 + 全归属动作 / 导入 / 交割 / 设置 + 查重试玩）；收集 console 错误 + 截图；重点验证三层查重 confirmSimilar 流、reminder 保存（PUT JSON）、导入页对 D-05/D-04 的展示。
结果写 Answer（demo 可用性结论 + 发现的 UI 级问题按三档口径记录）→ 关票 + map 追加。

5. 票 09 手册（聚合终稿）

汇总四路实测：report-core.md（112 用例）+ report-heavy.md（54 用例 6 轮收敛）+ 票 08 demo 结论 + 票 02 冒烟 → .scratch/customer-e2e/e2e-report.md 终稿：总执行量与三档汇总、55 端点逐个结论索引、缺陷清单 D-01..D-07（P0/P1/P2 + 现象/复现/接口/原型依据）、观察点（U-01..04 / W-01 / 升级提醒链无上限）、范围外记录（API-SUMMARY §5 已知缺口）。参照 .scratch/opportunity-e2e/e2e-report.md 范本。
map.md 收尾：Decisions so far 追加 06/08/09；「Not yet specified」两项结转（原型歧义→无遗留则删；Bruno workspace→已在票 06 拍板不做，删除并视情况挪 Out of scope）。
关票 09 → 全图关闭 → 更新 task_summary memory（收尾动作，见 §7）。

6. 关键文件索引（细节都在文件里，别靠记忆）

生成器两件：defs_a4.py（57 端点定义表，含 D-02/D-05/D-04/D-07 注记与全部参数/错误码）、gen_a4_bru.py（引擎：spec_lookup 归一钥匙 / resp_struct_table 实测字段表 / trim_spec_resp 裁剪 / main 分组）
注入源：specimens-core.json（45 端点实测）+ specimens-heavy.json（19 端点）；请求/响应全真值；_capture 的 contentType 标签有噪声（is_json 判断 bug），结构听源码=form，不受影响
id 底账：seed-ids.json（admin/buddy/full 客户/公海甲/交割甲/联系人张关键/商机……全部实测 id；PATH_VARS 用它）
格式金标准：E:\code\crm-api-docs\A3 商机管理\新建商机\新建商机.bru
skill 机制：C:\Users\Administrator\.qoder\skills\bruno-sync\SKILL.md（铁律 4 条）——⚠ 新电脑若 skills 目录不在同路径，以本机安装为准，机制不变
契约速查：report-core.md「契约发现 12 条」+ defs_a4.py 头注；API-SUMMARY 笔误一处的实锤：company-lookup 参数是 companyName 不是 keyword
E2E 先例：.scratch/opportunity-e2e/（报告范本 + demo 先例）

7. Suggested skills

/bruno-sync — 票 06 动手前重读 SKILL.md 铁律（本 effort 走的是自写 gen+inject 生成器，与 skill 的 sync 流程同源，铁律「结构听源码、表述听人、只碰 generated、宁停不删」全部适用）
/webapp-testing — 票 08 Playwright 浏览器级自测
/wayfinder — 工作流约定（认领→解决→关票→map 追加；本 effort 已被用户授权「把 Map 都做完」，允许一会话多票，但仍逐票收口：关一张再开下一张）
/grilling — 仅当实测出现原型歧义需要用户拍板时（判定依据：原型 v29 > spec D1-D29 > 问用户）

8. 收尾动作（全部票关闭后）

更新 memory「客户模块E2E验收地图与换机后环境事实」（id 65cd7edb-3b9b-48e5-858f-b7fce8ca599d）：追加本 handoff 的执行结果（9 票全闭、57 .bru 落地、报告终稿路径），供后续缺陷修复 effort（另起）引用。

10 KiB Raw Blame History