You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
83 lines
10 KiB
83 lines
10 KiB
3 days ago
|
# HANDOFF — customer-e2e 换机续跑（票 06 收尾 → 08 → 09）
|
||
|
|
|
||
|
|
> 交接时间：2026-09-04 凌晨。上游会话在旧电脑完成票 01-05、07，票 06 进行到「生成器修好、待重跑」。
|
||
|
|
> 用户指令：**wayfinder 把 Map 全部做完**（覆盖单票/会话默认）——本 handoff 即为续跑手册。
|
||
|
|
> 地图与全部决策细节：[map.md](map.md)（先读它的「范围拍板 + 环境事实 + 判定纪律」三节）；9 张票在 [issues/](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. 换机检查清单（新电脑开工前逐项过）
|
||
|
|
|
||
|
|
1. **workspace**：`e:\code\crm-backend-matt`（HEAD `43887d3`，客户模块实现 100% 完成，521 测试全绿——不要动源码）。
|
||
|
|
2. **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）。
|
||
|
|
3. **远程共享库不动**：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。
|
||
|
|
4. **Python 解释器**：旧电脑 `python` 命令失败（ExitCode 1）、`py -X utf8 -u` 有效。新电脑先 `py -X utf8 -u -c "print('ok')"` 验证，两个都不行就装（.scratch 脚本全按 py 写）。
|
||
|
|
5. **本地起服**（票 08 需要）：命令与坑见 map.md「环境事实」（verify profile + MinIO env 注入；重打包前先停 8080 java 进程；fat jar 增量陷阱）。jar 不在新电脑则需要先 `mvn package`。
|
||
|
|
6. **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 之后要重写）
|
||
|
|
|
||
|
|
步骤：
|
||
|
|
|
||
|
|
1. **清残留**：落盘一个 .py 用 `shutil.rmtree` 删上述两目录（Write 出不了 workspace，脚本放 `.scratch/customer-e2e/`）。
|
||
|
|
2. **重跑**：`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. **抽查 3 个文件**核对格式（金标准 = `A3 商机管理\新建商机\新建商机.bru`）：meta tags:[generated]、method 块、params/body 块、docs 四段；重点看 specimens 真值是否注入（响应示例带 `// 示例数据（E2E 实测真值）`）、Reminder JSON 端点 body:json 是否用 specimens 实测 body。
|
||
|
|
4. **对账 verify**：写 verify_a4.py——正则扫 9 个 Controller（crm-customer/controller）+ crm-rule ReminderRuleController 的 mapping 得 (METHOD, path) 钥匙集（应 57），与生成 .bru 的 docs 首行钥匙比对，全命中收口（防笔误漏端点）。
|
||
|
|
5. **重写 `A4 客户管理\README.md`**（现为占位）：9 子目录索引 + 提醒规则为何在根级（tag 原文，无 A4 前缀）+ crm-preference 6 端点**不生成副本**的说明（源码 tag 挂 A3，避免 sync 重跑孤儿；文字索引 scopeKey=customer.*）+ 维护纪律（只碰 tags:[generated]、对账钥匙行勿手改、agent 不提交 git）。
|
||
|
|
6. **关票**：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 浏览器级自测）
|
||
|
|
|
||
|
|
1. **先修 demo 联系人字段名**（源码实锤的偏差）：demo/index.html 的联系人编辑弹窗用了 `contactName`/`position`，源码 ContactDTO 实际为 `name`/`phone`/`jobTitleName`/`jobTitleId`/`jobTitleCategory`/`jobTitleLevel`/`isKeyContact`/`isInternal`/`giftRemark`/`source`（以 defs_a4.py「新增联系人」params 为准逐一对齐后再测）。
|
||
|
|
2. 认领票 08（Status: claimed）→ 起服（§2.5）→ 用 `/webapp-testing`（Playwright）打开 `demo/index.html`（file:// 静态页，登录走 `GET /api/auth/debug/token?userId=<uid>`，baseUrl 指本地 8080）。
|
||
|
|
3. 冒烟面：5 tab 各走一遍（列表三 workspace + 批量操作 / 详情 6 子页签 + 全归属动作 / 导入 / 交割 / 设置 + 查重试玩）；收集 console 错误 + 截图；重点验证三层查重 confirmSimilar 流、reminder 保存（PUT JSON）、导入页对 D-05/D-04 的展示。
|
||
|
|
4. 结果写 Answer（demo 可用性结论 + 发现的 UI 级问题按三档口径记录）→ 关票 + map 追加。
|
||
|
|
|
||
|
|
## 5. 票 09 手册（聚合终稿）
|
||
|
|
|
||
|
|
1. 汇总四路实测：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` 范本。
|
||
|
|
2. map.md 收尾：Decisions so far 追加 06/08/09；「Not yet specified」两项结转（原型歧义→无遗留则删；Bruno workspace→已在票 06 拍板不做，删除并视情况挪 Out of scope）。
|
||
|
|
3. 关票 09 → 全图关闭 → 更新 task_summary memory（收尾动作，见 §7）。
|
||
|
|
|
||
|
|
## 6. 关键文件索引（细节都在文件里，别靠记忆）
|
||
|
|
|
||
|
|
- **生成器两件**：[defs_a4.py](defs_a4.py)（57 端点定义表，含 D-02/D-05/D-04/D-07 注记与全部参数/错误码）、[gen_a4_bru.py](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（另起）引用。
|