# Handoff: CRM 前端联调可用性保障（frontend-integration map 已完成）

日期：2026-08-18
工作区：`e:\code\crm-backend-matt`（Windows，PowerShell 5.1，`&&` 不可用，用 `;`）
注：按 handoff skill 本应存系统临时目录，但写入工具限定工作区内，故存于 `tmp/`。

## 一句话状态

Wayfinder map `.scratch/frontend-integration/map.md` 的 7 张票据（01-07）**全部 resolved，阻塞项清零**，map 已写入 Arrival 段落。本地验证环境在跑：crm-app :8081（新代码，verify profile，连开发库）+ demo 静态服务 :8090。**剩余只有需凭据的人工部署步骤和等待外部权限的钉钉真实同步。**

## 权威产物（先看这些，勿重复抄录）

- 地图与决策：`.scratch/frontend-integration/map.md`（Decisions so far 每票一行 + Arrival 段含交付步骤）
- 票据：`.scratch/frontend-integration/issues/01..07-*.md`（均含 Answer 段）
- 种子脚本：`.scratch/frontend-integration/seed-testdata.py`（幂等，纯 API 铺设）
- demo：`deploy/demo/index.html`（零构建单文件）
- API 回归脚本：`tmp/api-verify3.ps1`（form-urlencoded 契约验证）
- 票据 07 问题清单 G1-G7 与验证数据：见 `issues/07-api-audit-against-prototype.md` Answer 段

## 构建/运行环境（重要踩坑）

1. **mvn 不在 PATH**。可用组合：
   ```powershell
   $env:JAVA_HOME="C:\Users\Administrator\.jdks\ms-17.0.18"
   & "D:\IntelliJ IDEA 2025.1.3\plugins\maven\lib\maven3\bin\mvn.cmd" -s settings.xml clean package -DskipTests
   & "C:\Users\Administrator\.jdks\ms-17.0.18\bin\java.exe" -jar crm-app\target\crm-app-1.0.0-SNAPSHOT.jar --spring.profiles.active=verify
   ```
2. **必须全反应堆 `clean package`**。单模块 `-pl crm-app package` 会从本地仓库拉陈旧模块 jar（曾导致 sqlSessionFactory 循环依赖启动失败）。
3. 运行中的 java 进程会锁 fat jar，重打包前先 `Stop-Process`。
4. PowerShell 内联命令里 `$var`/`$_` 会被 Bash 工具转义吞掉——**一律写 .ps1 文件执行**；PS5.1 读无 BOM UTF-8 脚本中文乱码，中文字符串用 `[string]::new([char[]](0x5317,0x4EAC))` 构造。
5. BOM 要求（AGENTS.md）：批量编辑 .java 后、`mvn compile` 前扫描（参考 `tmp/bomscan.ps1`）。
6. Python 用 `py` 启动器（`python` 是坏的 WindowsApps shim）。
7. 开发库地址等连接信息见 `crm-app/src/main/resources/application*.yml` 的 verify profile，本文档不复述。

## 关键契约与决策

- **接口入参契约是 form-urlencoded 隐式绑定（不加 @RequestBody）**，ADR-0017。测试 API 时用 form 编码，JSON body 不绑定。
- 调试 token（verify profile 后门）：`GET /api/auth/debug/token?userId=<超管userId>`（ADR-0014），token 存于 `tmp/dt-token.txt`；超管 userId 可在 auth_user 表或既有脚本中查得。
- 字典读契约：`DictQueryService.getItem(groupCode, itemCode)`，分组码 `lead_source/brand/product/scene`。
- 转商机报 65008 = 设计行为（`OpportunityCreationPort` 待商机模块实现，Out of scope）。
- 数据权限启动日志"受控表扫描 0 张"为既有行为，非回归。
- 登录仅钉钉扫码；MinIO Access Key 告警为已知既有问题，不影响线索流程。

## 运行时状态（会话结束时）

- 终端 1：crm-app :8081（新 jar，verify profile）
- 终端 2：`py -m http.server 8090 --directory deploy/demo`
- 开发库种子：部门、公海池×2、线索×9（含铺设与 demo 新增）、关注×2；区划 3432 行、字典 6 组 92 项已幂等落库。

## 下一步（若用户继续）

1. **测试服务器部署**（需用户提供 SSH 凭据）：上传新 fat jar → `deploy/restart.sh`；scp `deploy/demo/index.html` → `nginx/html/demo/`。步骤已写进 map.md Arrival 段。
2. **钉钉真实同步**（待钉钉应用获得通讯录读权限）：`POST /api/system/sync/dingtalk`，随后重跑 `seed-testdata.py` 挂真实用户/部门。
3. **map "Not yet specified" 遗留**：端到端验收走查、联调问题回流机制——均待第一轮前端联调反馈后再立票，勿主动开工。
4. 若前端联调反馈新 bug：按 map Notes 的判定基准（原型标注为唯一权威、宽松优先）处理；跨模块大改才立子票。

## Suggested skills

- **wayfinder** — 若用户带着新一轮联调反馈回来，在现有 map 上续立票据并推进。
- **qa** — 前端反馈 bug 的会话式收集与立票。
- **code-review** — 部署前对 crm-lead/crm-auth 改动做标准与规格双轴审查。
- **diagnosing-bugs** — 若出现启动失败/接口异常等硬 bug（先回看上文"构建/运行环境"踩坑清单）。
- **prototype** — 若需扩展 demo 覆盖新流程。