crm-backend-matt/.scratch/customer-frontend-handover/gap-report.md

票 03 · A4 七页面组对照审计 gap-report（gap 汇总 + 分级台账）

审计范围：A4-1~A4-7 共 39 页（.scratch/lanhu-latest/v29-customer-pages/）× 实现（Controller 端点面 + DTO/Param + 主 demo .scratch/customer-e2e/demo/index.html）。 逐页矩阵：matrix-a4-1-a4-3.md / matrix-a4-4.md / matrix-a4-5-a4-7.md；页面→端点映射：mapping-a4-pages.md。 处置规则（chart 拍板 3）：P0/P1 当轮修复（动核心逻辑过 /code-review）；P2/P3 记档台账，用户验收可翻案。

一、结论速览

分级	数量	状态
P0（阻断联调）	0	—
P1	1（导入预检必填前移）	当轮已修复 + 单测 20/20 绿
P2（字段/数据源缺口，不阻断）	6	全部记档（G1~G6）
P3（呈现/幻影/锦上添花）	6	全部记档
豁免（前序拍板划出）	9 类	不开票，台账留痕
幻影端点 / 幻影语义	0 / 1（导入触发校验复选框）	—

端点面结论：A4 全域零缺接口（demo 59 唯一路径全部落在 API-SUMMARY 85 端点内）；缺口集中在出参字段完整性与 demo 呈现层。

二、P1 台账（当轮修复）

P1-1 导入预检必填前移（defectfix §九.2 尾巴票收口）—— ✅ 已修复

• 现象：CustomerImportAnalyzer.analyzeCustomers 仅校名称必填 + 星级格式；INSERT 行的 customerType/provinceCode/cityCode/industryCode/customerStarLevel 缺省时 preview 计 insert，执行期 createCustomer 对 NOT NULL 无默认列写 null 才行级失败——预计数与执行不同口径。
• 修复：INSERT 分支（UPSERT/APPEND_ONLY 共用）补五列必填静态校验（缺省 → 预检即 FAIL「客户类型必填/省份编码必填/城市编码必填/行业编码必填/客户星级必填」）；UPDATE 行=部分更新语义不受限、SUSPECT 行不写入不受限。
• 改动：crm-customer/.../service/impl/CustomerImportAnalyzer.java（javadoc + INSERT 分支）；CustomerImportIntegrationTest.java（5 处 INSERT 行造数补列 + 新增用例 upload_insertRowMissingRequiredColumns_failsInPreview + javadoc 覆盖清单）。
• 验证：mvn -pl crm-customer -am test -Dtest=CustomerImportIntegrationTest Tests run: 20, Failures: 0, Errors: 0（BUILD SUCCESS）；字节码含新校验常量实证；E2E 兼容性核查：heavy/heavy-r2 F-14 r1 INSERT 行五列齐全、r2~r7 均走原有 UPDATE/FAIL/SUSPECT 路径，incr I-07 纯 UPDATE 语义零 INSERT，三套件零影响。
• 契约登记：API-SUMMARY §2.12 upload 行 + §5.7 已注记。

三、P2 记档台账（用户验收可翻案）

#	缺口	位置	建议	阻塞性
G1	跟进记录缺「操作人」筛选	FollowPageParam（仅 followWay/startTime/endTime）	加 operatorUserId 筛选列（数据在 oplog/follow 行内）	低（前端可先用关键词过滤）
G2	关联商机 7 字段 vs 原型 13 列	CustomerOpportunityQueryPort.OpportunityItem	跨模块 port 增列（项目/区域/招标形式依赖 A5；下次跟进时间/甲方/意向客户 opportunity 侧取）——挂账跨模块票	低（issues-07 §C 定稿已收窄口径）
G3	团队成员缺「职务/加入时间」	CustomerMemberDTO（实体 memberRole/createTime 真源在）	DTO 补两字段直映	低
G4	客户详情缺系统信息四件套（创建/更新时间·人）	CustomerDetailDTO（BaseEntity 真源在）→ demo 系统信息区恒 "--"	DTO 补 creatorId/createTime/updaterId/updateTime	低
G5	ContactDTO 缺「联系人负责人」+ 系统信息四件套	ContactDTO（负责人可由客户 owner 快照派生）	补 ownerUserNameSnapshot 派生 + 四件套	低
G6	联系人维度操作日志无数据源	CustomerOplog 无 contact 维度列（a4-5-6 页签）	加 contactId 维度列 + 过滤参数（或前端以 CONTACT_* action + keyword 兜底）	低（页签可先空态）

四、P3 记档（呈现层/幻影/锦上添花）

#	项	说明
P3-1	主 demo 卡片/分屏视图未渲染	形态偏好存取链路已通（scopeKey 三件套），仅 demo 页面未实现卡片/分屏形态
P3-2	demo 列偏好 / saved-view 未接	同上：API 全通，demo 未挂 UI
P3-3	导入「触发校验规则后确认执行」复选框	原型控件幻影——实现语义为确认即执行（两段式 upload→confirm 已含预检）
P3-4	操作日志导出	原型含导出按钮，无端点
P3-5	「显示完整金额」开关	敏感信息三档脱敏定稿划出（§5.4），开关随之划出
P3-6	详情头部汇总卡 5 字段恒 null	DTO 字段在、装配未接（§5.3 已注明 port 扩展路径）

五、豁免台账（前序拍板，不重复开票）

豁免项	依据
A4-6 独立查重页（卡片/列表）+ 客户合并流程 + 「已被合并」客户态	customer-module chart D4/D6/D19
附件上传位（新增/编辑/协议/日志附件）	customer-module D2
OCR 快捷新增	customer-module D5
企查查真实源（company-lookup stub 恒 NO_HIT）	customer-module D2/D5 范围（F6 批量更新五态软处置已就绪）
联系人扩展档案字段（性别/生日/微信/邮件/地址）	V1 档案收窄定稿
联系人图谱节点展开折叠/跨客户人脉	原型本期暂不支持
batchEdit 空串清空语义	contact-graph D-G1（chart 拍板 2 豁免）
客户导出	API-SUMMARY §5.4 定稿划出
联系人子表导入（9.2-9）	REVIEW-HANDOFF 划出 V1（§5.5）

六、存量疑点收口（票面点名两项）

1. pool·board 白名单漂移（实测 code=0）：定性 = 契约漂移、非缺陷。实现 ViewFormServiceImpl 白名单仅全局三值、无 pool 特判；API-SUMMARY §2.14 ⚠ 已注记「前端不得依赖拒绝行为」；文档侧终稿随票 05 Bruno 对齐落实。e2e-incr I-06 记档位维持 warn 口径。
2. 导入预检 Analyzer 只校名称+星级：定性 = P1 缺陷 → 本票已修复（见 P1-1）。

七、文档漂移修复（随票顺手收口）

项	处置
API-SUMMARY §5.6 D-07 仍挂「已知缺陷」	改「已修复（customer-defectfix 2026-09-06）」+ 修复证据（ancestors 前缀 + 批量回显，0.42s/0.40s 实证）；§4 同步
API-SUMMARY §5.7 D-04/D-05 仍挂「维持原状」	改「均已修复」+ 修复口径摘要
OplogPageParam @Schema action 描述滞后（11 种）	代码侧同步为 17 种真值（注释级修改，无行为变化）；§3 ⚠ 注记解除

八、修复面回归清单（票 04 复跑时需覆盖）

• CustomerImportIntegrationTest 20 例（本票已跑 ✅）。
• E2E：heavy F-14（14.6 预检计数 insert=1/fail=5/suspect=1 不变；14.11 DONE insert=2/fail=7/suspect=1）、incr I-07（SKIP/OVERWRITE 纯 UPDATE）、demo_t02 联系人导入（不受影响）。
• heavy F-13 副作用还原口径照旧（collab owner 四字段 → owner=744842318024015872/曾偲青/dept=744841292483133440/职员）。