luoweijian
/
crm-backend-matt
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
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.
176 Commits
1 Branch
0 Tags
461 MiB
 
 
 
 
 
Tree: 1b85082c41
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '1b85082c41'
${ noResults }
crm-backend-matt/.scratch/customer-integration-ready/integration-ready-report.md

8.9 KiB
Raw Blame History

客户模块联调就绪报告（customer-integration-ready 终验收 · 票 09）

日期：2026-09-11　图：.scratch/customer-integration-ready/map.md（十票全 resolved）　宣告：A4 客户模块达到「前端可直接联调」状态，三层证据齐备。用户验收（demo 走查）已过：8080 运行态 23/23 全绿，记录 demo-walkthrough.md。

一、结论

层 状态
E2E 回归 r3 全量 295 checks + UI 75 步，0 产品回归（票 01）；票 10 后 e2e-graph 复跑 58 checks 全绿
模块测试 crm-customer + crm-project 265 tests / 0 fail / 0 error / 0 skip（含票 10 新代码）
文档真值化 118 文件六项核验 ALL_PASS（下 §三）；「非真实返回」占位全仓清零
原型处置 票 08 四题拍板全部落地：N1/N2/N3 当轮修完（票 10），G1-G6/N4/N5 记档进移交清单

二、E2E 与测试基线

  • r3 全量回归（票 01，详见 e2e-report-r3.md）：core 113✅1⚠ / heavy 59✅1❌ / incr 61✅2⚠ / graph 57✅1⚠ + 双 demo 冒烟 35/35、40/40。4⚠1❌ 逐一取证为共享库数据态或已记档模式，0 产品回归。
  • 票 10 增量回归：e2e-graph 重跑 58 checks 全绿（0 fail 0 warn，端点 17/17，teardown 清扫）；模块测试 265/265 绿（首跑失败为本地仓 crm-dict/opportunity/rule snapshot 过期预存坑，-pl install 刷新后全绿，非代码回归）。
  • 8080 交付态：jar 2026-09-11 15:58:30 重建（含票 10 全部修复 + CodeReview 2×P3），verify profile 在跑，运行服务 = 工作树源码。

三、文档真值化与终验收核验

四票接力把 117+1 端点文档做到「不看源码就能联调」：

  1. 缺口普查（票 03）：占位示例 79 文件 / 退化 7 / 嵌套未展开 26 / 说明不清晰 10 / 错误码节回退 30 —— 产出 117 行机器可 grep worklist。
  2. 嵌套 DTO 展开（票 04）：expand_nested.py v4 写回 26 文件，五形态全覆盖（DTO-zero / 图谱 nodes·edges / type-F / DTO-flat / partial）。
  3. 真值采集（票 02 + 票 10）：23 端点交割四件套真值 + 4 条 proj-truth（关联项目页签 / detail-head×2 / 图谱悬停字段）。
  4. 真值化写回（票 05）：92 文件写回，117 端点响应示例全部 E2E 实测真值，验收 V1–V9 绿。
  5. 说明清晰化（票 06）：错误码节回捞 30 文件（全仓 78/78 = HEAD 基线，码 67001–67024 源码比对零漂移）+ createTime×9 + 引号截断 7 行重建 + jobTitleLevel 值域源码先回写再同步。

终验收六项核验（verify_integration_ready.py → verify-integration-ready.json）：

项 结果
V1 结构对账 PASS：磁盘 118 文件 ↔ 期望 118（mapping 117 + 票 10-N3 补充），双向零缺零余，对账钥匙行全一致
V2 非真实返回 PASS：全仓 0 命中
V3 四件套结构 PASS：meta / 请求块 / docs / 请求参数 / data 结构 / 响应示例 0 缺节（3 个二进制端点按票 05 口径豁免示例节）
V4 嵌套 DTO 展开 PASS：List<非原始类型> 行 0 缺子表
V5 说明质量 PASS：说明列 0 空行、0 断行残片
V6 UTF-8 无 BOM PASS：0

四、原型对照与处置落点

  • 台账（票 07，assets/prototype-parity-r3.md）：P0/P1 ×0；P2×2（N1 图谱悬停缺字段、N3 关联项目无数据源）、P3×3（N2 图谱不记日志、N4 操作日志仅单叙事列、N5 省市区无后端源）；复核翻转 G4/G5 部分残留（与 ADR-0017 防泄露口径一致）。
  • 拍板（票 08，HITL）：①N1/N2/N3 全部当轮修；②G1-G6 维持记档；③N4 记档 + N5 前端自带国标码表；④quick-create 维持七必填。
  • 落地（票 10）：
    • N1 GraphNodeDTO +isInternal/giftRemark，demo 悬停气泡切真值，图谱文档结构表同步；
    • N2 ACTION_GRAPH_EDIT + 图谱保存落 oplog（action 值域 18 种两文档同步）；
    • N3 关联项目走 port 路（ADR-0029 对称商机范式）：CustomerProjectQueryPort 三件套 + detailHead.projectCount 降级契约（失败显 "--"）+ 新端点 GET /api/customer/project/page + 关联项目页签.bru 新建。
    • CodeReview：无 P1/P2，2×P3 采纳（分页 id 兜底排序、Noop javadoc 契约措辞）。

五、联调移交注意事项（前端）

  1. 鉴权：请求头 Authorization: Bearer {{token}}；联调环境（verify profile）取 token：GET /api/auth/debug/token?userId=<用户id>（如 admin = 739564171091247104 罗伟健）。
  2. URL 与出入参约定（ADR-0017）：扁平动作动词 + 查询参数传 id（POST /edit?id=、GET /detail?id=）；写端点一律 POST + 表单绑定（非 JSON body）；读端点 GET。
  3. id 与数值形态：雪花 id / total / size 等长整型一律字符串出参（防 JS 精度丢失），前端按字符串处理。
  4. 脱敏口径：联系人列表/详情出参 phone 字段即脱敏值（前 3 + **** + 后 4），图谱节点出参字段名为 phoneMasked；明文一律走 reveal 端点（电话明文查看，留痕）。（demo 走查实测修正）
  5. 乐观锁错误码：编辑客户 version 必传，CAS 不符报 67005；图谱保存 version 比对不符报 67018（提示用户刷新后重试）。
  6. 二进制端点（3 个，文档为文字说明、非 JSON 示例，Axios 需 responseType:'blob'）：GET /api/customer/import/template（客户公海 / 我的客户两分区同 URL）、GET /api/customer/contact/import/template。
  7. N5 注记：省市区级联无后端数据源（票 08 拍板）——前端自带国标码表，存 provinceCode / cityCode 编码值。
  8. 记档项（不阻塞联调，均见台账）：G1-G6（六处字段级缺口，G4/G5 与 ADR-0017 防泄露口径一致）、N4（操作日志三结构化列缺）、batchEdit 空串清空语义表单绑定下不可达（D-G1 豁免）。
  9. 字典驱动：customer_type / job_title（两级档位 level 1–10）/ 项目阶段别名等全部走 /api/dict/*，文档示例值即字典真值。
  10. 参考实现：crm-customer demo .scratch/customer-e2e/demo/index.html（E2E 同款调用姿势，含图谱编辑器）。

六、双仓未提交变更清单（均待用户审查提交）

后端仓 d:\code\crm-backend-matt（git status 为准，此处列代码增量，.scratch 产物与 logs 不列）：

  • 票 10（本图）：改 7（CustomerConstants / CustomerDetailController / GraphNodeDTO / OplogPageParam / ICustomerDetailService / CustomerContactGraphServiceImpl / CustomerDetailServiceImpl）+ 新 3（customer port 接口与 Noop、crm-project port 真实现）+ 测试适配 4（Enhance / Graph / Members / Follow）+ demo index.html。
  • 前置轮基线：@Schema 注解 8 文件（BaseDTO / BaseEntity / ContactDTO / CustomerFollow / CustomerOplog / CompanyLookupPort / CustomerOpportunityQueryPort / ColumnPreference——含票 06 jobTitleLevel 源码回写）。
  • demo/E2E 运行产物（.scratch 下截图 / checks / xlsx）随审查取舍。

文档仓 D:\code\crm-api-docs：A4 分区约 100 个 .bru 修改（票 04 展开 / 票 05 真值化 / 票 06 回捞 / 票 10 同步叠加）+ 新目录 A4 客户管理/客户详情/关联项目/（关联项目页签.bru）。

七、环境与复跑指南

  • 起服（PowerShell）：$env:SPRING_PROFILES_ACTIVE='verify'; $env:CRM_MINIO_AK='admin'; $env:CRM_MINIO_SK='Itc@123456'; java -jar crm-app\target\crm-app-1.0.0-SNAPSHOT.jar
  • 远程共享库：8.129.84.155（db crm）；夹具纪律 e2c- 前缀 + 正门清扫。
  • 文档核验：py -X utf8 .scratch/customer-integration-ready/verify_integration_ready.py（期望 ALL_PASS，VERIFY_EXIT=0）。
  • E2E 复跑：py -X utf8 跑 .scratch/customer-e2e/{e2e-core-r2,e2e-heavy-r2,e2e-incr}.py + .scratch/customer-contact-graph/e2e-graph.py；Playwright venv .scratch/customer-e2e/.venv10。
  • 模块测试：mvn -s settings.xml -pl crm-customer,crm-project test；若遇 NoClassDefFound/NoSuchMethod 先 mvn -pl <依赖模块> install -DskipTests 刷新本地仓 snapshot（本图三次应验）。
  • 发版部署：需用户 SSH 凭据（移交清单见 .scratch/customer-contact-graph/e2e-report.md §八）。

八、产物索引

  • 核验：verify_integration_ready.py + verify-integration-ready.json（本目录）
  • 报告：e2e-report-r3.md（票 01）+ assets/prototype-parity-r3.md（票 07）+ assets/doc-gap-worklist.md（票 03）
  • specimens：specimens-{core,heavy,incr,graph}-r3.json + specimens-doc-truth.json（23 端点）+ specimens-proj-truth.json（4 条）
  • 日志：{core,heavy,incr,graph,demo-t04,demo-graph}-r3-run.log、compile-n3.log、package-n3.log、e2e-graph-n3.log、test-n3-r3.log、server-final.log
  • 票据：issues/01…10（十票全 resolved，Answer 各附细节）