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.
145 Commits
1 Branch
0 Tags
401 MiB
 
 
 
 
 
Tree: 746b032092
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '746b032092'
${ noResults }
crm-backend-matt/.scratch/customer-rework/audit-findings.md

8.4 KiB
Raw Blame History

复核差异清单（audit-findings）— 票 08 产出

  • 日期：2026-09-04
  • 镜头一：规范镜头（代码仓扫描，依据 AGENTS.md checklist + ADR-0017/0024/0023 + spec）
  • 镜头二：原型镜头（v29-customer-pages 全 A4 + A7-3-3 两页，三列核对）
  • 基准：68 条客户相关端点（audit-api-baseline.txt）；原型 62 页（.scratch/lanhu-latest/v29-customer-pages/）

一、镜头一结论（规范镜头）

全绿项：

  • URL 风格：crm-customer + crm-rule 全部 Controller grep @PathVariable|@PutMapping|@DeleteMapping|@RequestBody 零命中；
  • 出入参：98 个端点返回类型全为 DTO/基础类型（Result<Void/Long/String/Boolean/PageResult/DTO>），无 Entity 出入参（ColumnPreference 为 record DTO，非 Entity）；
  • 分页：10 个分页端点全部 PageResult<DTO> + *PageParam（BaseParam：current/size/keyword/orderBy/asc 规范）；
  • 错误码段位：64=crm-rule / 66=opportunity / 67=customer（67001-67016 有常量表）/ 68=preference（68001），段位清晰；
  • bruno config：envelope 四段 + pageWrapper 六字段 + sourceRoots 八模块 + menuBindings 齐。

差异项：

S1 ·【能机械修】64018 错误码重复

  • 位置：crm-rule/.../constant/OpportunityRuleConstants.java
  • 事实：CODE_STAGE_TPL_SEED_PROTECTED = 64018（L99）与 CODE_SCHEME_TPL_INVALID = 64018（L139）同值不同义；前端无法区分两种失败。
  • 修法：CODE_SCHEME_TPL_INVALID 改 64022（64019-64021 已占用、64023 已被 CustomerRuleConstants 占用，64022 空缺）+ 同步引用处与测试。
  • 性质：商机规则模块既有缺陷，非客户返工引入；属"能机械修"但改动商机模块错误码契约，票 09 处理时需用户知悉。

S2 ·【观察项，不动】商机看板 Result<?>

  • OpportunityCollabController.boardStageSummary/boardCards 返回 Result<?>（通配符），接口文档结构推导歧义。商机为参照模块非本图返工对象，仅登记。

二、镜头二结论（原型镜头）

种子验证（四项全部收口）

  1. 分屏裁剪（R5 自洽） ✓：a4-1-1 实证"普通销售视角/领导视角"双态 + 角色边界段原文"普通销售可执行单条领取和批量领取；领导可执行单条分配和批量分配"——领取/分配端点后端都有，视角差异=前端按权限点裁剪，与 R5 完全一致。
  2. 交割四页覆盖度 ✓：a4-7-1 发起（preview+initiate）/ a4-7-2 分配（assign+assignable）/ a4-7-3 记录（page）/ a4-7-4 详情（detail+批量分配），六端点对四页无缺口。
  3. 详情页签族 vs detail-head ✓（主体）：8 页签中 6 个有端点（客户信息/跟进/关联商机/团队成员/操作日志/联系人）；关联项目、战略协议缺端点（见 F4/F5）；汇总卡③"进行中商机总额"占位显"--" = 票 11 既知事务（CustomerDetailHeadDTO L90 TODO 注释），非缺陷。
  4. 联系人详情 a4-5-5/5-6 △：编辑 ✓；操作日志页签无端点（见 F10）。

差异项（按处置分组）

【需决策】

  • F4 · 关联项目：a4-1-2/a4-4-4/a4-4-5 页签 + 详情快捷"新增项目"——依赖 A5 项目管理模块（本工程未建），无端点。候选：随项目模块远期划出（与范围外家族一致）。
  • F5 · 战略协议：a4-4-6 页签 + a4-4-9 新增/4-4-10 编辑 + 详情头部"新增战略协议"——无任何端点。候选：本期补（量级：单表 CRUD）or 划出。原型有完整三页，划出需用户翻案确认。
  • F6 · 批量更新工商信息：a4-3-1 弹窗"你选择了5个客户，确认要批量查询并更新工商信息吗？"——现有仅 GET /api/customer/company-lookup（单查），无批量更新写端点。
  • F7 · 内置检索视图参数缺失：a4-3-1 检索面板内置视图"我负责的客户/我协同的客户/待跟进的客户/我关注的客户"——CustomerWorkspacePageParam 无 ownerOnly/coopOnly/待跟进/focusOnly 参数（仅 archiveStatus/customerStage 等）。已归档过滤有 archiveStatus ✓；"最近访问"tab 同此家族（客户侧无 viewTouch 类端点，商机有 OpportunityCollabController.viewTouch 先例）。
  • F8 · 导入重复策略参数缺失：a4-3-2 复选框"数据重复时覆盖导入/数据重复时不导入"——import/upload 参数无对应字段。
  • F10 · 联系人操作日志：a4-5-6 页签——已核代码：CustomerContactServiceImpl 无任何 oplog 写入（grep 零命中），联系人增删改不记日志，a4-5-6 无端点可用。需决策：客户 oplog 扩操作类型（CONTACT_ADD/EDIT/DELETE，记 customerId 可过滤）vs 独立联系人日志表。
  • F9 · 导出日志：a4-4-8"导出日志（共导出 35 条，按当前筛选条件导出）"——无端点；与 D2 导出家族一并划出候选。

【能机械修 / 低优先】

  • F3 · import 端点 tag 归属：a4-1-1（公海）工具条也有"导入"气泡——import/* 端点 tag 目前只挂"我的客户/客户导入"。若公海页真实可发起导入，按 ADR-0024 应多值挂公海；若仅布局复用则维持。建议对照交互流确认后补 tag（一行注解）。

【范围外确认（只登记，不审）】

  • 客户列表导出（a4-1-1/a4-2-1/a4-3-1 工具条气泡，D2）
  • OCR 快捷新增（a4-3-3-3/4、a4-4-2、a4-5-1）
  • 客户查重/合并（a4-4-6/1/2/3，维持划出）
  • 联系人导入（a4-5-4，D5）
  • 查看完整联系电话（a4-4-2"查看完整联系电话"）——脱敏三档家族，维持划出

三、建议归并（回填 09 号票）

  • 机械修：S1（64022 改码）、F3（tag 补挂，确认后）、F10（oplog 参数或记账）
  • 需用户拍板（grill）：F5（战略协议补 or 划出，唯一有完整原型三页的缺口）、F6（批量工商更新）、F7（内置视图过滤参数）、F8（导入重复策略）
  • 划出候选确认：F4（关联项目→A5 依赖）、F9（日志导出→导出家族）

四、处置状态（票 09 收尾回填，2026-09-05）

条目 处置 说明
S1 已修 实改方向与上节建议相反（64022 已被 CODE_SCHEME_TPL_FIELD_INVALID 占用）：CODE_SCHEME_TPL_INVALID 保 64018（64018-64022 归方案卡模板段），CODE_STAGE_TPL_SEED_PROTECTED 64018→64024 顺延补位；段位 javadoc + 引用处 + 测试同步
F3 已修 六个 import 端点双 tag 增挂「客户公海」（a4-1-1 工具条实证导入入口，ADR-0024 多值）
F4 划出 随 A5 项目域：本工程无项目管理模块，端点与页签随项目模块建立时一并落（用户 2026-09-05 拍板）
F5 已单开票 12 战略协议单表 CRUD（原型三页完整）；全栈实现+测试+bruno 移交 12 号票
F6 已修 POST /api/customer/company-lookup/batch-update（ids 查询参数表单绑定；逐个单查→guardCreditCodeForWrite→§C2 只补空缺不覆盖→SKIPPED/UPDATED/NO_HIT/CONFLICT/NOT_FOUND 软处置；单批上限 100）；port 为 stub 恒 NO_HIT，真实企查查 Bean 接入自动激活；+4 集成用例
F7 部分误报 + 已修 审计口径偏差：viewType 单参数已承载五内置视图（ASSIGNED/COLLABORATING/FOLLOW_UP_DUE/FOCUSED/RECENT，SQL 与测试俱全），无需新增过滤参数；真缺口=customer_view_log 生产侧零写入（RECENT 死视图，票 04 建壳挂账未兑现）→ detailHead 聚合时自动 upsert touchViewLog（实体 javadoc 明文设计意图），零新端点；+1 upsert 集成用例
F8 已修 import/upload 加 duplicateStrategy 参数（SKIP 缺省 / OVERWRITE；非法值 67013；D24 冻结语义：作用面仅文件内重复组，overwrite=组内自上而下最后一条通过校验的行 UPDATE 生效；不触名称相似 SUSPECT——D16 独立规则）；task 实体加列 duplicate_strategy、analyzer 穿参、preview DTO、executor、+3 集成用例
F9 划出 随 D2 导出家族：导出端点族整体未建，先行项不存在（用户 2026-09-05 拍板）
F10 已修（轻方案） 客户 oplog 扩 CONTACT_ADD/EDIT/DELETE 三操作类型；联系人 create/update/delete 三处 oplogWriter.write（detail=「新增/修改/删除联系人【名】」）；独立联系人日志表方案否决（用户拍板轻方案）；+1 集成用例断言三行日志

bruno 侧 F6/F8 新参数与 F7 行为的示例同步未在本票内做，随票 10 bruno 对账步统一核补（文档仓本机 D:\code\crm-api-docs）。