7.6 KiB

Raw Blame History

Wayfinder Map: 前端联调可用性保障（frontend-integration）

Label: wayfinder:map

Destination

前端按接口文档 + 蓝湖原型能走通核心流程（认证登录 → 公共依赖[省市区/字典] → 线索主流程[新增/四列表/流转/公海池]），期间发现的阻塞项全部清零，并以静态 demo 作为正确性参照交付。

Notes

本 effort 携带执行（覆盖 Wayfinder 默认的 plan-don't-do）：数据初始化、bug 修复、demo、测试数据铺设均作为地图内票据推进。
必填/非必填判定基准（已与用户对齐）：
- 蓝湖原型表单标注为唯一权威来源；接口文档与原型冲突时，以原型为准改后端。
- 原型含糊/未标注时宽松优先：服务端不做强制校验，仅对「数据库 NOT NULL 且无默认值」字段做最小校验；宁可放过，不可误拦。
- 回显规则：详情接口返回字段必须覆盖新建表单全部字段（含字典编码 + 名称快照、区划 ID + 名称）。
钉钉同步方案（已与用户对齐）：application.yml 的钉钉配置可用；引入 com.github.tingyugetc520:dt-java:0.1.2；只拉部门树 + 用户；部门负责人是钉钉字段随部门存下，不是系统角色；另写管理员角色配置接口。
字典种子（已与用户对齐，票据 02 落地时以原型实际清单校正）：lead_source 选项替换为原型渠道清单（38 项）；新增 brand（9 项，非最初记录的仅 itc）/ product（16 项）/ scene（18 项）三个内置分组；customer_status / industry 保留不动；联调库直接重建或手工清理「只加不删」seeder 的残留。
行政区划（已与用户对齐）：全量国标三级（约 3200 行），seeder 幂等导入（与 DictDataInitializer 同款模式），非 SQL 脚本。
测试数据（已与用户对齐）：用户/组织走钉钉同步端点拉全量真实数据；角色用管理员角色配置接口手工配；公海池 ×2 + 各状态线索种子走后端 API 铺设。
环境流转（已与用户对齐）：本地 :8081（连 8.129.84.155 开发库）验证 → 打包 → deploy/restart.sh 更新测试服务器（nginx 80）交付前端；demo 部署至 nginx/html/demo/。
相关技能：demo 票据用 /prototype；修复票据酌情用 /tdd。
原型文本位置：.scratch/lanhu-text/（新增线索表单见 a2-1-2-2____.txt）；Bruno 集合：.scratch/bruno-coldstart/。

Decisions so far

dt-java SDK 部门与用户拉取 API 调研 — dt-java 0.1.2 存在于中央仓库（旧版 oapi 封装）；实测校正：初始化只需 appKey/appSecret（无需 corp-id/agent-id）；部门树 list(null,true) 可用；发布版 jar 的 DtUser 无 isLeaderInDeparts 字段（tmp 源码是更新版），用户链路改 HTTP 直调 /topapi/user/listbypage 自行解析负责人；传递依赖旧需 exclusions（xstream）。
行政区划全量种子导入 — china-division 2.7.0 国标三级 3432 行（34 省含港澳台/342 市/3056 区县镇街）内嵌 resources；RegionDataInitializer（@Order(12) CommandLineRunner）三层 batchUpsert + 回查拿 id，命中 uk_region_code 幂等；开发库两次启动实测写入与幂等通过。
字典种子对齐原型 — SEED_GROUPS 对齐蓝湖 A2-1-2-2：lead_source 改名「渠道」并替换为 38 项原型渠道；新增 brand(9)/product(16)/scene(18) 共 6 组 92 项；crm-lead 分组编码常量由点号改齐 lead_source/brand/product/scene；「只加不删」，旧渠道项待联调库重建或手工停用。
钉钉组织同步端点与管理员角色配置接口 — POST /api/system/sync/dingtalk（超管）：部门走 dt-java SDK、用户因 0.1.2 缺 isLeaderInDeparts 改 HTTP 直调 listbypage；幂等键 sys_dept.dt_dept_id（新增唯一索引）与 account=钉钉 userid；负责人是部门字段反写 leader_user_id 不映射角色；POST /api/system/users/admin-role（超管）增量授予/回收角色，缺省 ROLE_ADMIN；错误码 61017。
公海池与线索种子数据铺设 — seed-testdata.py（幂等纯 API 铺设）：公海池×2（不同部门/省份/领取规则）+ 线索种子×5（待领取/已领取/跟进中）+ 关注×2，四视图均有数据；发现项：转商机 65008（OpportunityCreationPort 无实现，商机模块在目的地外，归票据 07 决策）、过期失效/已转商机状态无 API 可铺；全部种子挂存量单用户，待钉钉同步后补铺。
核心流程静态 demo — deploy/demo/index.html 零构建单文件（原生 JS fetch 直调，每请求原文渲染 + 全量日志）；浏览器实测 7 步全通（登录签发/区划级联/字典/公海池/四列表/新增/日志）；CORS 全开 BASE 可指任意环境；部署待服务器凭据随最终交付 scp 至 nginx/html/demo/。
核心接口对照原型盘点与修复 — 通读 12 段蓝湖规格逐一对照：端点覆盖齐全，差距集中在出参回显与查询口径，G1-G7 全部在 crm-lead 内修复（字典/部门/反馈人/新增人名称回显、统计卡 waiting+feedback 四项、keyword 三路搜索含区划名反查、历史操作人姓名）；转商机 65008 判定为设计行为（商机模块 out of scope）不修；70 单测全绿 + 本地真实库 API 回归通过。

Not yet specified

~~盘点产出的具体 bug 修复票据~~：已在票据 07 内清点完毕——差距均为出参回显/查询口径小修，未拆子票直接修复关闭；若第一轮联调反馈出现跨模块大改，再立票。
端到端验收走查：数据、demo、修复齐备后，全流程点击验收 + 前端确认的最终票据，待前置完成后再立。
联调问题回流机制：前端联调期间新反馈的 bug 如何归类进本地图（还是单开 issue），待第一轮联调反馈到来时再定。

Out of scope

系统管理页面（用户/组织/角色管理页）本身的完整联调——本 effort 只做钉钉同步与管理员角色配置接口，管理页 UI 联调不在目的地内。
数据字典管理页联调——只保证读路径可用 + 内置字典齐全，管理页本身的联调 bug 非阻塞。
文件/附件模块联调——线索表单如无附件场景则整体不进核心。
客户/商机/项目管理等后续模块——目的地之外，另起 effort。

Arrival（票据全部清零，2026-08-18）

7 张票据（01-07）全部 resolved；阻塞项清零。目的地达成情况：认证登录（钉钉扫码 + verify 调试 token）✓；公共依赖（区划 3432 行 + 6 组 92 项字典）✓；线索主流程（17+8 端点对照原型修复 G1-G7）✓；静态 demo（deploy/demo/index.html，本地 :8090 已验证）✓；测试数据（公海池×2 + 线索×5 + 关注×2）✓。

交付前人工步骤（需凭据，非阻塞）：

更新测试服务器：全反应堆 clean package 产出的 crm-app/target/crm-app-1.0.0-SNAPSHOT.jar 上传后执行 deploy/restart.sh（需 SSH 凭据）；注意勿用单模块 -pl crm-app package（会从本地仓库拉陈旧模块 jar 导致启动失败）。
demo 部署：scp deploy/demo/index.html 至服务器 nginx/html/demo/。
钉钉真实同步：待钉钉应用获得通讯录读权限后调 POST /api/system/sync/dingtalk，随后重跑 seed-testdata.py 把种子数据挂到真实用户/部门。

7.6 KiB Raw Blame History