|
|
|
|
# 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 调研](issues/04-dtjava-sdk-research.md) — 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）。
|
|
|
|
|
- [行政区划全量种子导入](issues/01-region-seed.md) — china-division 2.7.0 国标三级 3432 行（34 省含港澳台/342 市/3056 区县镇街）内嵌 resources；`RegionDataInitializer`（@Order(12) CommandLineRunner）三层 batchUpsert + 回查拿 id，命中 uk_region_code 幂等；开发库两次启动实测写入与幂等通过。
|
|
|
|
|
- [字典种子对齐原型](issues/02-dict-seed-align.md) — SEED_GROUPS 对齐蓝湖 A2-1-2-2：lead_source 改名「渠道」并替换为 38 项原型渠道；新增 brand(9)/product(16)/scene(18) 共 6 组 92 项；crm-lead 分组编码常量由点号改齐 `lead_source/brand/product/scene`；「只加不删」，旧渠道项待联调库重建或手工停用。
|
|
|
|
|
- [钉钉组织同步端点与管理员角色配置接口](issues/03-dingtalk-sync-endpoint.md) — `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。
|
|
|
|
|
- [公海池与线索种子数据铺设](issues/05-testdata-seeding.md) — `seed-testdata.py`（幂等纯 API 铺设）：公海池×2（不同部门/省份/领取规则）+ 线索种子×5（待领取/已领取/跟进中）+ 关注×2，四视图均有数据；**发现项**：转商机 65008（OpportunityCreationPort 无实现，商机模块在目的地外，归票据 07 决策）、过期失效/已转商机状态无 API 可铺；全部种子挂存量单用户，待钉钉同步后补铺。
|
|
|
|
|
- [核心流程静态 demo](issues/06-static-demo.md) — `deploy/demo/index.html` 零构建单文件（原生 JS fetch 直调，每请求原文渲染 + 全量日志）；浏览器实测 7 步全通（登录签发/区划级联/字典/公海池/四列表/新增/日志）；CORS 全开 BASE 可指任意环境；部署待服务器凭据随最终交付 scp 至 nginx/html/demo/。
|
|
|
|
|
- [核心接口对照原型盘点与修复](issues/07-api-audit-against-prototype.md) — 通读 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）✓。
|
|
|
|
|
|
|
|
|
|
**交付前人工步骤**（需凭据，非阻塞）：
|
|
|
|
|
1. 更新测试服务器：全反应堆 `clean package` 产出的 `crm-app/target/crm-app-1.0.0-SNAPSHOT.jar` 上传后执行 `deploy/restart.sh`（需 SSH 凭据）；注意勿用单模块 `-pl crm-app package`（会从本地仓库拉陈旧模块 jar 导致启动失败）。
|
|
|
|
|
2. demo 部署：scp `deploy/demo/index.html` 至服务器 `nginx/html/demo/`。
|
|
|
|
|
3. 钉钉真实同步：待钉钉应用获得通讯录读权限后调 `POST /api/system/sync/dingtalk`，随后重跑 `seed-testdata.py` 把种子数据挂到真实用户/部门。
|
