crm-backend-matt/.scratch/customer-e2e/e2e-report.md

# 客户模块端到端验收报告（e2e-report.md 终稿）

> **票 09 聚合产出**（20260904）· 聚合自 `report-core.md`（票 04）+ `report-heavy.md`（票 05）+ 票 08 demo 自测记录（`issues/08-webapp-testing.md` Answer）+ 票 06 Bruno 对账（`verify_a4.py`）。
> **环境**：本地后端 `localhost:8080`（verify profile，`CRM_MINIO_AK=admin`）+ 远程共享库 `8.129.84.155`（MySQL/Redis）。
> **代码基线**：HEAD `43887d3`（客户模块票 01-14 全交付）；jar 为 20260903 clean package 产物（本 effort 期间未改后端源码，D-01 修复为票 02 顺手修）。
> **数据基线**：seed 17 客户 `e2c-`（KH202609030006-0022）+ 2 商机 + 4 联系人（`seed-customer.py` 幂等可重跑，重跑方式见 §七）。
> **实测脚本**：`e2e-core.py`（F-01..F-12，112 用例）+ `e2e-heavy.py`（F-13..F-16，58 checks）+ `demo_selftest.py`（31 步 Playwright）。
> **判定纪律**：原型（蓝湖 v29 A4 页族一手拉取）> spec（D1-D29 + API-SUMMARY）> 问用户；判 ❌ 前必须核对 Controller 实际 flat 路径；孤立 401 先重试再判缺陷。
> **图例**：✅ 存在且业务可用｜⚠ 行为不符/契约差异/被缺陷阻断｜❌ 缺失或真实 bug。

---

## 一、执行摘要

| 维度 | 结论 |
|------|------|
| 流程覆盖 | **16 流程 F-01..F-16 全部实测**（spec-flows §0 全量 55 端点）+ demo 浏览器级 31 步 UI 走查 |
| 用例计数 | 112（core）+ 58（heavy）= **170 API 用例：✅ 164 / ⚠ 6 / ❌ 0**；demo 31 步 **31 PASS / 0 FAIL**（console errors=0、page errors=0）；合计 201 步全绿零阻断 |
| 端点覆盖 | 55/55 全量（specimens-core 45 + specimens-heavy 19 端点真实请求/响应留档，注入票 06 Bruno 文档） |
| 缺陷登记 | 号段 D-01..D-07 共 7 条，**有效 6 条**（D-06 撤回）：**D-01 P0 已修复**（票 02 顺手修+本 effort 复验）；**未修复 5 条 = P1×2（D-05 导入必败、D-07 assignable 超时）+ P2×3（D-02、D-03、D-04）** |
| 阻断面 | **0 个真 404、0 个 P0 活跃缺陷**——主流程全通；P1 集中在导入写入链（D-05+D-04 连锁）与交割分配辅助接口（D-07） |
| 残留 ⚠ 定性 | API 层 6 条 ⚠ **全部对应已登记缺陷**（D-02/D-03 为直接表象，D-04/D-05/D-07 的 4 条为缺陷验证证据），非缺陷性 ⚠ 为 0；已知缺口复现 3 条（API-SUMMARY §5 预登记，见 §五合并表） |

**P1 主题归纳（修复 effort 的直接输入）**：

1. **导入写入链双缺陷连锁**（D-05+D-04）：`customer.is_biz_negotiated` NOT NULL 无默认值且 createCustomer 未赋值 → 含 INSERT 行的导入任务必 FAILED（行不落库）；且 insertFail 把超长 MyBatis 异常文本写 varchar(500) 二次炸 → 失败明细 0 行全丢。导入功能对"新增"场景事实不可用（UPDATE_ONLY 正常）。
2. **交割 assignable 稳定超时**（D-07）：`GET /api/customer/transfer/{id}/assignable` 30s/60s 多轮复现超时（疑 getChildDeptIds 全树递归 + 全表扫描），前端「选择分配对象」无法加载；assign 本体（直接指定 userId）不受影响。

---

## 二、核心域 F-01..F-12（e2e-core.py · ✅110 / ⚠2 / ❌0）

12 流程全部走通：三 workspace 列表/看板/saved-view、新增+三层查重、编辑、联系人、详情头部+页签、跟进、关注/重点、团队成员、归属动作、商机侧硬依赖三端点。

| 流程 | 用例 | 结论 | 要点 |
|---|---|---|---|
| F-01 三 workspace 列表 | 12 | ✅ | overview/mine(三视图)/pool 分页字段齐；keyword/阶段/归档过滤；D19 默认排除已归档；公海 enterPoolTime 有值 |
| F-02 看板三分组 | 7 | ✅ | stage 三列齐（stage2/3 经 DB 直拨样例覆盖）；summary 与 page total 自洽；越界 groupColumn 静默 |
| F-03 saved-view | 10 | ✅ | 三 scope 互不影响；save(JSON)/应用/set-default/delete；删除后应用不炸（静默按无视图） |
| F-04 新增+三层查重 | 9 | ✅ | L1 check-name/credit-code 提示；L2 needConfirm（未落库）→ confirmSimilar=true 落库；L3 67003 硬拦；编号 KH+yyyyMMdd+4 位 |
| F-05 编辑 | 5 | ⚠ D-03 | 回显/oplog 旧→新叙事 ✅；缺 version → **67001（spec 约定 67005，偏差）**；改信用代码撞 simA 67003 |
| F-06 联系人 | 9 | ✅ | 非法手机号 67001；67002；page/search 电话命中；check-phone 跨客户；PUT/DELETE /{id} |
| F-07 详情头部+页签 | 8 | ✅ | 头部项齐；**汇总卡 5 字段恒 null（已知缺口 §5.3 预登记）**；D-01 复验 opportunityCount==1；oplog 值域 11 种白名单 |
| F-08 跟进 | 12 | ⚠ D-02 | 空 content 67009 / 30s 防重 ✅；**nextFollowTime 早于当前未拦（D-02）**；写入+D25 锚点刷新；append-only 无编辑口 |
| F-09 关注/重点 | 7 | ✅ | focus 幂等；star/unstar 保行置位；focus-batch；FOCUSED 视图命中；unfocus 物理删连带清标；不写 oplog |
| F-10 团队成员 | 10 | ✅ | OWNER 在前；重复 67016 整批拒；软删 delete_key=id 复用键；MEMBER_ADD/REMOVE 留痕 |
| F-11 归属动作 | 17 | ✅ | claim+D25 锚点；重复领 67004；assign 67012 四连拦；67007/67006 阻断；抛公海清 owner 保部门锚点；archive-batch 整批预检整体拒 |
| F-12 商机侧硬依赖 | 7 | ✅ | quick-create 七必填+默认值；search 三维过滤；contacts 带出；已知缺口复现（见 §五） |

**核心契约发现 12 条**（全文见 `report-core.md` §四，前端联调高发）：LocalDateTime form 绑定 ISO `T` 分隔（空格 400）；Long→String 序列化（id/total/cnt 均字符串数字）；board summary 计数字段名=`cnt`；**PUT 编辑=全量覆盖语义**（部分提交清空未提交可空字段）；assign 的 oplog action=`TRANSFER`；team_member 软删 delete_key=id；公海生命周期写 enter_pool_time；**archive-batch 整批预检整体拒绝**（claim/assign/release 批量为逐条独立事务）；归属校验顺序（67004 先于权限语义）；debug token 瞬时 500 需重试；saved-view 应用=过滤叠加不改 DataScope；名称相似算法对纯数字尾巴敏感（造名避开）。

明细证据：`report-core.md` + `e2e-core-checks.json`；示例请求/响应 `specimens-core.json`（45 端点）。

---

## 三、重流程 F-13..F-16（e2e-heavy.py · ✅54 / ⚠4 / ❌0）

| 流程 | 结果 | 关键结论 |
|---|---|---|
| F-13 客户交割（A4-7） | **18/18 ✅** | preview 圈定=名下全量；initiate 必填/范围 67011；resign 自动推导接收总监（D22）；重入 67010；**整批原子 owner→总监 + 商机三列联动**（经 opportunity_customer 反查）；oplog 交接编号叙事；detail/assignable/page/续号当日不重号；assign 序列（67012 四连拦+批量）；D23 自动完成（assignedCount==totalCount → status=1）；已完成单再分配失败行收口。**⚠ D-07(P1)：assignable 辅助接口稳定超时**（见 §五） |
| F-14 客户导入（A4-3-2） | 10 ✅ + 4 ⚠ | 模板下载（RFC 5987+xlsx 魔数）；67013 三连；APPEND_ONLY 预检（t=7 i=1 f=5 s=1）；行级判定（已存在 FAIL/文件内重复组 FAIL/相似 SUSPECT）；UPDATE_ONLY 按编号 u=1；**UPSERT 同名新编号→SUSPECT（不按名称匹配，U-01 映射口径实测收口）**；confirm 状态机重复 67014；creator 过滤（admin 有/buddy 无）。**⚠ D-05(P1) 含 INSERT 行必失败 + ⚠ D-04(P2) 失败明细全丢**（连锁，见 §五） |
| F-15 提醒规则族（a7-3-3-1） | **11/11 ✅** | GET 回显/PUT 全量覆盖（唯一 JSON 端点）/64023 两连/校验失败不落库/开关缺省=0；**Job 实测**（env 注入 */30 cron，U-02 拍板收口）：落表 plan=锚点+first(1)、status=0、type=FOLLOW_OVERDUE、target=owner、payload 快照全对；未到期/公海/归档排除；**幂等=同 plan 不重写（每轮补下一条升级链，remindSeq 0..29 严格连续）**；follow 刷新锚点后旧未发 30 条全置 INVALID。测后服务/规则均已还原（30/7 全开+默认 cron） |
| F-16 查重消费侧（a7-3-3-2） | **7/7 ✅** | check-credit-code 命中/创建撞码 67003 硬拦/check-name 相似命中（出厂 80）/创建相似名 needConfirm 未落库/check-phone 跨客户软提示/导入 SUSPECT 消费引证。**单例未落地**（customer_dedup_rule 表不存在）→ DefaultCustomerDedupSettingProvider 出厂默认生效；D26 关闭路径因此无法实测（挂观察点） |

明细证据：`report-heavy.md` + `e2e-heavy-checks.json`；`specimens-heavy.json`（19 端点）。

**口径修正记录**（证据链在 checks JSON note 字段）：15.7/15.9 首测按「恒 1 条」判 fail → DB 取证证明语义=「每轮补下一条」修正后 pass；D-06「导入分页恒空」经取证**撤回**（脚本取 records 而 PageResult 序列化 content，非产品缺陷）。

---

## 四、demo 浏览器级测试（票 08 · 31 步全绿）

`demo/index.html`（file:// 直开，AJAX 经 API_BASE 直连 8080，debug token 登录）以 Playwright chromium headless 自测：**31 PASS / 0 FAIL，console errors=0、page errors=0**，截图 30 张 `shots08/`（shot-01..30 按步骤号对应）。

| 面板 | 覆盖 |
|---|---|
| 客户列表 | 三 workspace 切换、关键字检索、汇总卡渲染、勾选+批量关注、详情入口 |
| 客户详情 | 6 子页签渲染（info/contacts/follow/opps/members/oplog）、写跟进（follow_way_01 契约值）、联系人建/编/删全链（PUT/DELETE /{id}）、关注/取关/重点/取消重点四连击（`POST /{id}/focus` 路径变量）、L2 needConfirm / L3 67003 两路查重 |
| 客户导入 | 任务列表、上传预检 DRAFT、确认执行→终态 DONE、失败明细弹窗 |
| 客户交割 | 列表（5 条真单）、发起前预览、交接单详情（进度 3/3） |
| 设置 | 提醒规则读改写（PUT JSON 全量覆盖）、64023 负路径、基线还原、查重试玩三端点 |

**自测前修复的 6 处 demo 契约偏差**：联系人字段名（→ name/jobTitleName/isKeyContact/isInternal/giftRemark/source）、联系人 PUT/DELETE 路径（→ /{id}）、导入失败明细路径（→ /{taskId}/failures）、API_BASE（file:// 跨源）、unifiedCreditCode 字段名、follow_way 字典值。

**自测中发现并修复的 2 处 demo 真缺陷**：① oneBy() focus 族 URL 形态错误（查询参数 → `POST /{id}/{op}` 路径变量；ownership 族 claim/release-pool/archive/restore 实为 flat `?id=` 形态保持不变）；② 交割 tab 初次加载 `transferPage(1)` 误用"下一页" dir 语义导致第 2 页空态（→ `transferPage(0)`）。demo 为验证工具非交付产品，缺陷即修即验，不新增 D-xx 台账项。

**经验沉淀**：404 响应无 CORS 头 → 浏览器 console 误报 CORS block（判 CORS 先看请求 URL 对不对）；`tableHtml` 空态也渲染 1 个 tr（Playwright 行计数须排除空态行）；`IMP_ST` 状态文案是英文（DRAFT/RUNNING/DONE/FAILED）；DELETE 后 switchSub 异步重载需轮询等待。

---

## 五、缺陷清单（有效 6 条 + 撤回 1 条）与已知缺口合并

> 复现基线：`python .scratch/customer-e2e/seed-customer.py` → 对应脚本。**本次只报告不修复**（map 范围拍板）；修复另起 effort。

### 缺陷表（D-01..D-07，原型依据 = 蓝湖 v29 A4 页族）

| 编号 | 级别 | 现象（期望 vs 实际） | 复现 | 接口/位置 | 原型/spec 依据 | 状态 |
|---|---|---|---|---|---|---|
| D-01 | P0 | 公海列表 pool/page 500（期望 200） | F-01/F-07 | `POST /api/customer/workspace/pool/page` | A4-2 公海列表页 | ✅ **已修复**（票 02 顺手修，用户拍板；本 effort 复验通过：公海 200 + 交割-甲 opportunityCount==1） |
| D-02 | P2 | 跟进 nextFollowTime 早于当前未拦截（期望 67009）；客户进入 FOLLOW_UP_DUE 视图且 append-only 无改删口 → 提醒永远无法消除 | f08 负路径 | `POST /api/customer/{id}/follow` | spec F-08（67009 语义含"早于本次"）；demo 角标 D-02 | ⚠ 未修复（建议 addFollow 入口补 `nextFollowTime > now`，对称 content 空校验位置） |
| D-03 | P2 | 编辑缺 version 报 **67001**「缺少乐观锁版本号」，spec 约定 **67005**（CAS 冲突）——可达但码不对，前端按 code 分流提示会踩坑 | f05 负路径 | `PUT /api/customer/{id}` | spec 决策 D-06（customer-module map） | ⚠ 未修复（补 67005 或文档按 67001 口径修正，二选一对齐） |
| D-04 | P2 | 导入失败明细全丢：insertFail 将完整 MyBatis 异常文本写 `fail_reason` varchar(500) → Data too long 二次异常 → fail 表 0 行 | F-14 任意失败行 | `CustomerImportExecutor.insertFail` | A4-3-2 导入页失败明细列 | ⚠ 未修复（建议异常文本截断/摘要化入库） |
| D-05 | P1 | **含 INSERT 行的导入任务必 FAILED**：`customer.is_biz_negotiated` tinyint NOT NULL 无默认值且 createCustomer 未赋值 → `Field 'is_biz_negotiated' doesn't have a default value`；UPDATE_ONLY 正常 | F-14 APPEND_ONLY/UPSERT | `CustomerImportExecutor.createCustomer` | A4-3-2 导入页（模板 V1 双 sheet） | ⚠ 未修复（补赋值或列默认 '0'，对照 is_child 有默认） |
| D-06 | — | 「导入分页恒空」首判缺陷 | F-14 page | `GET /api/customer/import/page` | — | ❌ **撤回**（脚本取 `records` 而 PageResult 序列化字段为 `content`，非产品缺陷） |
| D-07 | P1 | 交割 **assignable 辅助接口稳定超时**（E2E 30s×2、probe 60s×2，三轮复现）；assign 本体不受影响 | F-13 详情页点分配 | `GET /api/customer/transfer/{id}/assignable` | A4-7 交割页「选择分配对象」下拉 | ⚠ 未修复（建议：部门树缓存/子部门查询收窄；前端临时兜底=直接填 userId） |

### 已知缺口合并去重（API-SUMMARY §5 预登记 × 实测确认，均不算新缺陷）

| §5 预登记 | 实测确认 |
|---|---|
| 1. QuickCreateDTO 无 confirmSimilar | ✅ f12 复现：命中相似 needConfirm=true，带 confirmSimilar=true 重发仍 needConfirm（表单字段不存在被忽略）→ 商机弹窗快创遇相似名无解，只能改名 |
| 2. 查重设置页无对外端点 | ✅ F-16：customer_dedup_rule 表不存在 → 出厂默认全开生效（名称 80/信用码硬拦/电话软提示）；D26 关闭路径无法实测（挂观察点） |
| 3. 详情页签 5/6 与汇总卡 5 字段恒 null | ✅ f07 复现：wonProjectAmount/planEstimateAmount/ongoingOpportunityAmount/contractAmount/paidAmount 全 null（不符④拍板 A 占位） |
| 4. 三档脱敏+查看日志/合并客户/客户导出 | 范围外（定稿划出），未测 |
| 5. 联系人子表导入 | 范围外（REVIEW-HANDOFF 划出），未测 |

### 观察点收口（票 01 挂号 U-01..04 + W-01）

| 挂号 | 收口结论 |
|---|---|
| U-01 导入双控件 vs 单参数 importMode | ✅ 销号：F-14 实测映射语义（UPDATE_ONLY 按编号/UPSERT 同名→SUSPECT 不按名称匹配），与原型偏离但实现自洽，按判定纪律不视为缺陷 |
| U-02 提醒 Job 触发方式 | ✅ 销号：票 05 拍板 env 注入 cron（`restart_service()`），测后还原默认 `0 0 4 * * ?` |
| U-03 公海分配按钮角色可见性 | ✅ 销号：按口径 E2E 用 admin 统一视角验端点行为；环境仅 ROLE_ADMIN 一个角色，BUDDY（无角色）已确认走业务校验路径（67004），完整越权矩阵留联调环境 |
| U-04 看板 groupColumn 白名单 | ✅ 销号（票 01 已实锤：stage/star/relation 与原型三分组对应） |
| W-01 contact_source 字典组缺失 | ⚠ **维持挂账**（联调观察点）：dict_group 24 组无 contact_source，但联系人创建不校验 source（回显原值 contact_source_01）——前端下拉将无数据源，等字典补种或口径拍板 |
| 升级提醒链无上限 | ⚠ 维持挂账（产品口径复核）：客户永不跟进时提醒逐轮堆积（30 轮=30 条待发），建议复核是否需「存在未发提醒时暂停推进」 |

---

## 六、与票 12 静态对齐的差异（静态核对 vs 动态实测增量）

票 12 十页静态对齐（spec 对照，不符②③④⑤修复后同步版）核对的是**存在性与契约文本**；本 effort 实测新增的是**运行时行为**维度，以下均为静态核对无法触达、由动态实测暴露的发现：

| 类别 | 动态实测增量（静态对齐看不到） |
|---|---|
| 校验逻辑缺口 | D-02（nextFollowTime 过去未拦——静态只见参数声明，不见"缺失的 if"）；D-05（is_biz_negotiated 缺省列——需 DB SHOW COLUMNS 对照 INSERT 路径）；D-04（异常文本超长二次炸——需真实失败触发异常链） |
| 错误码语义偏差 | D-03（67001 vs 67005——静态对齐只核对了"有 CAS"，未触发缺 version 的真实响应码） |
| 性能问题 | D-07（assignable 超时——静态无法发现，需真实调用计时） |
| 序列化/绑定形态 | 12 条契约发现（ISO T 分隔、Long→String、cnt 字段名、PUT 全量覆盖、oplog action=TRANSFER、PageResult content 等）——静态看 DTO 注解推断不出 Spring 实际绑定/序列化行为 |
| 事务与批量语义 | archive-batch 整批预检整体拒 vs claim/assign/release 逐条独立事务——需对含阻断户的批量请求实测 |
| 状态机副作用 | D25 锚点赋值时序、enter_pool_time 生命周期、D23 自动完成、INVALID 置无效链——需按状态流转序列触发 |

静态对齐已核项（本 effort 不再重复质疑、实测全部确认）：公海列表（不符①已修）、总览身份筛选、详情 8 页签（不符③④已修）、操作日志 action 筛选（不符⑤已修，值域 11 种实测白名单吻合）、交割（整批原子+D22/D23）、导入三方式两段式、规则两页、归属弹窗守卫码、新增三层查重（不符②成员写端点已修）。

---

## 七、测试数据指引（前端联调）+ Bruno 交付核对

### seed 指引

- **完整清单**：`seed-data-manifest.md`（人读）+ `seed-ids.json`（机读，消费方**一律从 json 取 id，禁止硬编码**——重跑后 id 全变）。
- **账号矩阵**（debug token = `GET /api/auth/debug/token?userId=`）：管理员罗伟健 `739564171091247104`（ROLE_ADMIN data_scope=4）/ BUDDY 曾偲青 `744842318024015872`（无任何角色，走业务校验路径）。
- **数据矩阵**：17 客户 `e2c-` 前缀（阶段 1/2/3 三档、星级、相似对 A/B、跟进待办/超期、协同、成员、交割甲乙丙、公海甲乙、已归档）+ 2 商机（交割/67007 拦截绑定）+ 4 联系人（含同号 check-phone 样例王重复）。
- **重跑方式**：
  - `python .scratch/customer-e2e/seed-customer.py` —— 先清后造（幂等；物理清 e2c- 命名空间再重建，KH 编号只前进）
  - `python .scratch/customer-e2e/e2e-core.py` —— 核心域全量（F-11/F-12 自还原归属态/自清快创，可重复跑）
  - `python .scratch/customer-e2e/e2e-heavy.py` —— 重流程全量（F-15 会临时注入 */30 cron 并还原；F-13 交割前提搭建含 leader 设置 teardown 还原）
  - `python .scratch/customer-e2e/demo_selftest.py` —— demo 浏览器级 31 步（需 8080 在线；每轮自清联系人甲）
- **联调注意**：① `Result<Void>` data=null 非失败，判 code 即可；② 写端点全 form 绑定，唯一 JSON = PUT /api/rule/customer/reminder；③ PUT 编辑全量覆盖（编辑页必须全量回显提交）；④ 导入含 INSERT 行当前必 FAILED（D-05），联调导入请用 UPDATE_ONLY；⑤ 本 effort 测试残留：demo 自测轮次的导入任务记录（DONE/suspect）与已归档的 KH202609040001（清理验证产物），均无碍复用。

### Bruno 交付核对（票 06）

- **位置**：`D:\code\crm-api-docs\A4 客户管理\`（D 盘文档仓，git 仓 **agent 不提交，用户审查后自行提交**）。
- **规模**：**57 .bru / 10 目录**（55 端点 + 归属 flat 与批量双形态）；目录 = Controller @Tag 原文（客户管理 10/workspace 3/归属流转 9/详情页 8/联系人 7/关注 5/交割 6/导入 6/健康 1 + 根级 `客户管理\超期提醒规则\` 2）。
- **分组决策**：crm-preference 6 端点不生成副本（tag 挂 A3，README 文字索引 scopeKey=customer.*）；根级提醒规则 2 端点按 tag 归位根级目录。
- **对账**：`verify_a4.py` 对源码 57 钥匙（METHOD+路径）与生成物双向比对 **PASS（0 差异）**；请求示例 = specimens 实测真值注入（64 端点形态覆盖）。
- **结构**：裸 collection 不升级（bruno.json + collection.bru，Bruno 3.x 可打开，Not-yet 结案）；README 已重写（9 子目录索引 + 归位说明 + 维护纪律）。

---

## 八、交付确认（两件套 + 配套资产）

| 交付物 | 状态 |
|---|---|
| ① Bruno 接口文档集合 | ✅ `D:\code\crm-api-docs\A4 客户管理\` 57 .bru / 10 目录 + 对账 PASS |
| ② E2E 测试报告（本文档） | ✅ `.scratch/customer-e2e/e2e-report.md` |
| 配套：前端 demo | ✅ `demo/index.html`（票 07 交付 831 行 + 票 08 修复 8 处）+ 31 步自测全绿 |
| 配套：seed 联调数据 | ✅ `seed-customer.py` ALL GREEN 7/7 + manifest + seed-ids.json |