DIP1-P3 一线操作系统联调方案 · 接口依赖清单 + 测试数据准备

字段	值
报告编号	DWLG-20260810-09
关联文档	DWLG-20260810-08（交付总结）/ DIP1-P2 V2.0 / DIP1-API V2.0 / DIP1-SCH V2.0
覆盖范围	65 端点 × 5 业务域 × 3 客户端 联调依赖矩阵 + 50 单 UAT 测试数据方案
目标阶段	DIP1-P3 一线操作系统联调（DIP1-IMP §5.2 B.8 集成 + §D 部署）
编制人	DT（听写）
编制日期	2026-08-10
状态	📋 待 TL 审核发布

---

一、联调目标与范围

1.1 联调阶段定位

DIP1-P2 后端 5+1 域 + 前端 3 端（OPR Web + WKR RN + CST RN）已完成独立开发与 R3 UAT 验收（4 单样本），进入 P3 联调阶段后需扩展至：

• 接口层联调：65 端点 × 3 端 = 195 个端点×客户端组合全跑通
• 数据层联调：50 单真实 UAT 数据（L1→L8 完整生命周期）
• 跨域联调：QSV ↔ CPT ↔ MDS ↔ OPS ↔ DSP 数据闭环
• NFR 验证：k6 压测 + 移动端启动 + 推送送达率

1.2 联调前置条件

条件	当前状态	联调前必须达成
后端 5+1 域 API	✅ 65 端点全部可访问	保持
OPR Web 前端	✅ R3 通过	保持
WKR RN App	🟡 未启动（DIP1-IMP C-C3 10 人天）	必须先完成 C-C3
CST RN App	🟡 未启动（DIP1-IMP C-C4 8 人天）	必须先完成 C-C4
移动端认证+推送	🟡 未启动（DIP1-IMP C-B7 4 人天）	必须先完成 C-B7
50 单测试数据	🟡 当前仅 4 单	必须扩展至 50 单
OBS-01 修复	🟡 待落地	必须先落地 next.config.mjs 修复

⚠️ 关键阻塞：移动端 RN App（C-C3/C-C4/C-B7）共 22 人天未启动，建议 P3 联调分两阶段： - P3-A（立即可启动）：OPR Web × 后端 5+1 域 × 50 单 UAT - P3-B（22 人天后）：WKR/CST RN × 移动认证 × 推送

---

二、接口依赖清单（65 端点 × 5 域 × 3 端）

2.1 接口依赖矩阵总览

业务域	端点数	OPR Web	WKR RN	CST RN	联调优先级
AUTH 认证	5	✅ 必须	✅ 必须	✅ 必须	P0
QSV 报价	9	✅ 必须	❌ 不调	✅ 询价	P0
CPT 跟踪	14	✅ 必须	✅ 接单/完工	✅ Timeline/评价	P0
MDS 主数据	17	✅ 必须	🔍 只读	🔍 只读	P1
OPS 运营	10	✅ 必须	❌ 不调	✅ 推荐	P1
DSP 派单	6	✅ 必须	✅ 接单	❌ 不调	P1
CST 客户端专用	4	❌ 不调	❌ 不调	✅ 必须	P2
合计	65	61	27	36

2.2 P0 必须联调端点（28 个）

AUTH 认证域（5 端点 · 3 端共用）

#	Method	Path	OPR	WKR	CST	依赖前置	测试要点
1	POST	/auth/login	✅	✅	✅	无	admin/admin123（OPR）+ 师傅 OTP（WKR）+ 客户 WhatsApp OTP（CST）
2	POST	/auth/refresh	✅	✅	✅	#1	refresh_token 轮换 7d
3	POST	/auth/logout	✅	✅	✅	#1	token 黑名单
4	GET	/auth/me	✅	✅	✅	#1	roles/permissions 返回
5	POST	/auth/otp/send	❌	✅	✅	无	WhatsApp OTP 60s 限流

QSV 报价域（9 端点 · OPR + CST 共用）

#	Method	Path	OPR	WKR	CST	依赖前置	测试要点
6	GET	/qsv/categories	✅	❌	✅	无	6 active 品类 + base_fee
7	GET	/qsv/param-versions/current	✅	❌	❌	无	当前生效版本号
8	POST	/qsv/calculator/preview	✅	❌	✅	#6	BUG-NEW-01 回归：UUID 入参 → 380/1200
9	POST	/qsv/quotes	✅	❌	✅	#8 + customer_id	创建 DRAFT 报价
10	GET	/qsv/quotes	✅	❌	❌	#9	BUG-NEW-02 回归：category_code 字段
11	GET	/qsv/quotes/{quote_id}	✅	❌	✅	#9	详情含 factor_breakdown
12	POST	/qsv/quotes/{quote_id}/confirm	✅	❌	✅	#9	DRAFT → CONFIRMED
13	POST	/qsv/quotes/{quote_id}/reject	✅	❌	✅	#9	DRAFT → REJECTED
14	GET	/qsv/quotes/{quote_id}/pdf	✅	❌	✅	#12	PDF 下载

CPT 跟踪域（14 端点 · 3 端共用）

#	Method	Path	OPR	WKR	CST	依赖前置	测试要点
15	GET	/cpt/orders/board	✅	❌	❌	无	BUG-NEW-04 回归：6 池结构
16	GET	/cpt/orders	✅	✅	✅	无	分页 + 池筛选
17	GET	/cpt/orders/{order_id}	✅	✅	✅	#16	BUG-NEW-03 回归：category_code
18	POST	/cpt/orders	✅	❌	✅	customer_id + category_id	创建订单（L1 线索池）
19	PATCH	/cpt/orders/{order_id}/stage	✅	✅	❌	#18	L1→L2→…→L8 状态机
20	POST	/cpt/orders/{order_id}/assign	✅	❌	❌	#19 + worker_id	L4 派单
21	POST	/cpt/orders/{order_id}/checkin	❌	✅	❌	#20	L6 师傅签到（GPS + 时间）
22	POST	/cpt/orders/{order_id}/checkout	❌	✅	❌	#21	L6 完工登记（CPT-F 183 字段）
23	POST	/cpt/orders/{order_id}/exception	✅	✅	❌	#19	异常池分支
24	POST	/cpt/orders/{order_id}/reopen	✅	❌	❌	#23	异常恢复
25	GET	/cpt/orders/{order_id}/timeline	✅	✅	✅	#17	时间线 8 阶段事件
26	POST	/cpt/orders/{order_id}/nps	❌	❌	✅	#19 (L8)	L8 NPS 采集（反哺 OPS）
27	GET	/cpt/orders/{order_id}/work-log	✅	✅	❌	#22	CPT-F 现场登记表
28	POST	/cpt/orders/{order_id}/work-log	❌	✅	❌	#22	提交登记表

2.3 P1 重要联调端点（27 个）

MDS 主数据域（17 端点 · OPR 管理 + WKR/CST 只读）

域	端点数	关键端点（OPR）	WKR/CST 只读端点
SCL 品类	2	GET /mds/categories（已验证）/ POST /mds/categories	GET /mds/categories
CPL 客户	4	GET/POST/PATCH/DELETE /mds/customers	GET /mds/customers/{id}
WPL 师傅	4	GET/POST/PATCH /mds/workers / PATCH /mds/workers/{id}/skills	GET /mds/workers/{id}
BPL 楼宇	4	GET/POST/PATCH /mds/buildings / GET /mds/buildings/search?q=	GET /mds/buildings/search?q=（地址联想）
TSMM 标签	3	GET /mds/tags / POST/DELETE /mds/tags/{id}/attach	不调

联调测试要点： - BPL 地址联想 2 字符响应 < 200ms（NFR-01） - 批量打标 < 1s（NFR-02） - PII 脱敏：WKR/CST 调用 GET /mds/customers 时 phone/whatsapp 应掩码

OPS 运营域（10 端点 · OPR + CST 共用）

#	端点	OPR	CST	测试要点
29	GET /ops/leads	✅	❌	线索池分页
30	POST /ops/leads	✅	✅	CST 询价自动入线索
31	PATCH /ops/leads/{id}/convert	✅	❌	线索 → 订单（关联 CPT #18）
32	GET /ops/rewards	✅	❌	奖励审批分页
33	POST /ops/rewards/{id}/approve	✅	❌	BUG-012 回归：RBAC 权限
34	POST /ops/rewards/{id}/reject	✅	❌	拒绝奖励
35	GET /ops/coupons	✅	✅	优惠券列表
36	POST /ops/coupons	✅	❌	创建优惠券
37	GET /ops/campaigns	✅	❌	营销活动
38	POST /ops/campaigns	✅	❌	创建活动

DSP 派单域（6 端点 · OPR + WKR 共用）

#	端点	OPR	WKR	测试要点
39	GET /dsp/recommendations?order_id=	✅	❌	Top3 师傅推荐
40	GET /dsp/workers/load	✅	❌	师傅负载看板
41	POST /dsp/assign	✅	❌	派单（关联 CPT #20）
42	GET /dsp/workers/me/orders	❌	✅	师傅今日工单
43	POST /dsp/orders/{id}/accept	❌	✅	师傅接单
44	POST /dsp/workers/me/leave	❌	✅	请假

联调测试要点： - 同日同师傅 ≥ 2 单返回 3030 冲突（NFR） - Top3 推荐算法：技能匹配 + 负载 + 距离

2.4 P2 客户端专用端点（4 个 · CST RN 独占）

#	Method	Path	测试要点
45	POST	/cst/inquiries	客户询价（自动入 OPS leads + CPT L1）
46	GET	/cst/orders	客户自己的订单（RLS 隔离）
47	GET	/cst/orders/{id}/timeline	客户视角时间线（脱敏师傅电话）
48	POST	/cst/reviews	客户评价（关联 CPT #26 NPS）

2.5 跨域数据闭环联调（5 条关键链路）

链路 ID	流向	验证点
CL-1	CST 询价 → OPS lead → CPT L1 订单 → QSV 报价 → CPT L3 → DSP 派单 → CPT L4	询价到派单全链路
CL-2	WKR 接单 → CPT L5 → WKR 签到 → CPT L6 → WKR 完工登记 → CPT L7 → CPT L8	师傅施工全链路
CL-3	CST 评价 → CPT L8 NPS → OPS reward → OPR 审批 → DSP 结算	口碑反哺闭环
CL-4	CPT 实际工时 → MDS WPL 师傅画像 → QSV 参数校准 → QMD 系数更新	数据闭环反哺（R21）
CL-5	MDS BPL 楼宇档案 → QSV 楼宇系数 → QSV 试算 → CPT 报价快照	主数据供给（R33）

---

三、测试数据准备方案（50 单 UAT 规模）

3.1 当前数据基线 vs 联调目标

实体	当前	联调目标	缺口	扩展策略
品类（SCL）	6 active	6	0	✅ 已达标
楼宇（BPL）	2	10	8	新增 8 栋（覆盖 7 大楼宇类型）
客户（CPL）	3	30	27	新增 27（含 5 推荐关系链）
师傅（WPL）	3	10	7	新增 7（覆盖 L1/L2/L3 三级）
订单（CPT）	4	50	46	新增 46（覆盖 8 阶段 + 异常分支）
报价（QSV）	2	50	48	每订单 1 报价
线索（OPS leads）	0	20	20	新增 20（含 6 获客场景）
奖励（OPS rewards）	0	15	15	新增 15（含 ≥500 HKD BO 审批）

3.2 测试数据生成方案

方案 A：Seed CLI 扩展（推荐）

文件：dip1/backend/scripts/seed_demo.py（已有，需扩展）

扩展命令：

# 当前命令（4 单）
python scripts/seed_demo.py --scale mini

# 新增命令（50 单）
python scripts/seed_demo.py --scale uat50 --seed 20260810

实现要点：

# scripts/seed_demo.py 扩展
import argparse
import random

SCALE_PROFILES = {
    "mini": {"orders": 4, "customers": 3, "workers": 3, "buildings": 2},
    "uat50": {"orders": 50, "customers": 30, "workers": 10, "buildings": 10},
}

def seed_uat50(session, seed=20260810):
    random.seed(seed)
    profile = SCALE_PROFILES["uat50"]

    # 1. 楼宇 10 栋（覆盖 7 大类型）
    buildings = [
        ("德福花園 A 座", "PRIVATE_ESTATE", "有電梯", 1.0),
        ("大圍村南道唐樓", "VILLAGE_HOUSE", "無電梯", 1.15),
        ("沙田第一城", "PRIVATE_ESTATE", "有電梯", 1.0),
        ("黃大仙上邨", "PUBLIC_HOUSING", "有電梯", 0.95),
        ("奧運站維港灣", "PRIVATE_ESTATE", "有電梯", 1.0),
        ("元朗錦繡花園", "VILLAGE_HOUSE", "無電梯", 1.15),
        ("中環中心寫字樓", "OFFICE", "有電梯", 1.1),
        ("尖沙咀商舖", "SHOP", "有電梯", 1.05),
        ("將軍澳康城", "PRIVATE_ESTATE", "有電梯", 1.0),
        ("上水新都廣場", "PRIVATE_ESTATE", "有電梯", 1.0),
    ][:profile["buildings"]]

    # 2. 客户 30 个（含 5 推荐关系链）
    customers = generate_customers(profile["customers"], seed=seed)
    # 5 条推荐链：A→B→C→D→E（链式推荐）
    referral_chains = [["陳太", "林先生", "黃小姐", "張太", "李生"]]

    # 3. 师傅 10 个（L1×4 + L2×4 + L3×2）
    workers = [
        ("李師傅", "L1", ["WARDROBE", "BED"]),
        ("陳師傅", "L2", ["KITCHEN_CABINET", "WARDROBE"]),
        # ... 10 个
    ]

    # 4. 订单 50 单（8 阶段分布）
    stage_distribution = {
        "L1_NEW_LEADS": 8,      # 16%
        "L2_CONTACTED": 5,      # 10%
        "L3_PENDING_QUOTE": 7,  # 14%
        "L4_PENDING_ASSIGN": 6, # 12%
        "L5_ASSIGNED": 5,       # 10%
        "L6_INSTALL_TODAY": 8,  # 16%
        "L7_PENDING_ACCEPTANCE": 6, # 12%
        "L8_PENDING_FOLLOWUP": 3,   # 6%
        "EXCEPTION": 2,         # 4%
    }
    orders = generate_orders(stage_distribution, customers, workers, buildings, seed=seed)

方案 B：JSON 数据导入

文件：dip1/backend/scripts/seed_uat50.json

预生成 50 单完整数据（含客户/师傅/楼宇/订单/报价/线索/奖励），通过 psql \copy 或 SQLAlchemy bulk insert 导入。

优点：可重复、可版本控制、可审计 缺点：维护成本高（schema 变更需同步）

方案 C：Faker 库生成（Python）

# scripts/seed_faker.py
from faker import Faker
fake = Faker("zh_CN")

def generate_customers(n=30):
    return [
        {
            "name_zh": fake.name(),
            "phone": fake.phone_number(),
            "whatsapp": fake.phone_number(),
            "district": fake.random_element(["九龍", "新界", "港島"]),
        }
        for _ in range(n)
    ]

优点：数据多样性高，接近真实 缺点：手机号格式可能不符合 HK 规则

推荐组合方案

阶段	方案	用途
立即	方案 A 扩展	主流场景 50 单
补充	方案 C	边界场景（异常地址、特殊尺寸）
归档	方案 B	50 单完整快照入版本控制

3.3 测试数据覆盖矩阵

3.3.1 订单阶段覆盖（50 单）

阶段	单数	占比	关键测试点
L1 新线索	8	16%	CST 询价 → OPS lead → CPT 转换
L2 已联系	5	10%	OPR 跟进记录
L3 待报价	7	14%	QSV 试算 + 报价创建
L4 待派单	6	12%	DSP Top3 推荐 + 派单
L5 已派单	5	10%	WKR 接单
L6 今日安装	8	16%	WKR 签到 + 完工登记（CPT-F）
L7 待验收	6	12%	CST 验收
L8 待回访	3	6%	NPS 采集 + 推荐反哺
异常池	2	4%	异常分支 + 恢复
合计	50	100%

3.3.2 品类覆盖（50 单）

品类	单数	测试要点
衣柜 WARDROBE	10	基础品类，base_fee 380
橱柜 KITCHEN_CABINET	8	高客单价，base_fee 520
床 BED	8	短工期，base_fee 220
餐桌 DINING_TABLE	6	中等
书柜 BOOKSHELF	6	中等
电视柜 TV_CABINET	6	中等
组合定制 COMBINATION	6	复杂场景，需 BO 审批

3.3.3 异常场景覆盖（2 单 + 边界）

异常类型	单数	触发条件
客户取消	1	L3/L4 阶段客户取消
师傅请假	1	L5/L6 阶段师傅请假，需重新派单
边界场景
折扣 > 15%	2	触发 BO 审批
同日同师傅 ≥ 2 单	2	触发 3030 冲突
楼宇无电梯 + 大件	3	楼宇系数 1.15
推荐链 ≥ 3 层	1	A→B→C→D 推荐反哺

3.4 数据生成执行步骤

# 1. 备份当前 4 单数据
docker exec dip1-postgres-1 pg_dump -U dip1 dip1_dev > backup_4orders.sql

# 2. 清空业务数据（保留品类/楼宇/师傅/客户主数据）
docker exec dip1-postgres-1 psql -U dip1 dip1_dev -c "
TRUNCATE qsv_quotes, cpt_orders, ops_leads, ops_rewards CASCADE;
"

# 3. 执行 50 单 seed
cd dip1/backend
python scripts/seed_demo.py --scale uat50 --seed 20260810

# 4. 验证数据
python scripts/verify_seed.py --expected-orders 50

# 5. 跑 R3 复测脚本（确保数据扩展后无回归）
pytest tests/smoke/ -v

---

四、联调执行计划

4.1 P3-A 阶段（立即可启动 · OPR Web × 后端）

工作日	任务	负责人	交付物
D1	OBS-01 修复（next.config.mjs） + 测试脚本归档	Code Agent	next.config.mjs / tests/smoke/
D2	50 单 seed 数据生成 + 验证	Code Agent	seed_uat50.json
D3-D4	P0 端点联调（28 个）	Code Agent + TL	联调报告 P0
D5-D6	P1 端点联调（27 个）	Code Agent + TL	联调报告 P1
D7	5 条跨域闭环联调	Code Agent + TL	闭环验证报告
D8	k6 压测 NFR-01~03	Code Agent	压测报告

P3-A 验收标准： - 28 P0 + 27 P1 = 55 端点 100% 通过 - 5 条跨域闭环全通 - 50 单 UAT 数据 L1→L8 全生命周期 0 阻塞 - k6 NFR-01（地址联想 < 200ms）/ NFR-02（批量打标 < 1s）/ NFR-03（试算 P95 < 30ms）达标

4.2 P3-B 阶段（22 人天后 · RN 双端 × 移动认证）

📖 配套操作手册：DWLG-20260811-01 《P3-B 移动端联调操作指南》（师傅端 8 页 + 客户端 8 页 + 移动认证 + 推送，共 54 项 Checklist）

工作日	任务	依赖	交付物
D1-D4	C-B7 移动认证+推送+CST 后端（4 人天）	P3-A 完成	OTP + 推送 + CST 4 端点
D5-D14	C-C3 WKR RN 8 页（10 人天）	C-B7 完成	wkr-app RN App
D15-D22	C-C4 CST RN 8 页（8 人天）	C-B7 完成	cst-app RN App
D23	C-C5 移动基建 + EAS Build（4 人天，并行）	C-C3/C-C4	EAS Build 4 端
D24	C-C6 E2E（Detox 双端各 1 主流程）	C-C3/C-C4	E2E 报告

P3-B 验收标准： - WKR RN 8 页 + CST RN 8 页 100% 可用 - OTP / 推送送达率 ≥ 95% - EAS Build 4 端 artifact 生成 - Detox E2E 双端各 1 主流程通过

4.3 P3-C 阶段（UAT 50 单 + 部署）

工作日	任务	负责人	交付物
D1-D7	OL UAT 50 单（DPL-04）	OL + TL	UAT 报告
D8-D14	FL 5 人 wkr-app 内测（DPL-05）	FL + TL	内测报告
D15-D21	CUS 10 人 cst-app 内测（DPL-06）	CUS + TL	内测报告
D22-D28	生产部署 + 蓝绿（DPL-03）	TL	部署报告
D29-D30	App Store + Google Play 提审（DPL-02）	TL + 听写	上架凭证

---

五、风险与缓解

风险	概率	影响	缓解措施
RN App 开发延期（22 人天）	中	高	P3-A/B 分阶段，OPR Web 先联调不阻塞
50 单数据生成不规范	中	中	seed 脚本版本控制 + verify_seed 校验
推送送达率不达标	中	高	移动基建阶段提前压测（≥ 95%）
App Store 审核被拒	中	高	提前准备审核资料（DPL-02 并行）
OBS-01 未修复影响联调	低	中	P3-A D1 立即落地修复

---

六、联调验收 Checklist

6.1 一级：代码层（Code Agent 自检）

• OBS-01 修复落地（next.config.mjs webpack.cache=false）
• 测试脚本归档至 dip1/backend/tests/smoke/
• 50 单 seed 数据生成 + verify 通过
• 65 端点 100% 联调通过（P0+P1+P2）
• 5 条跨域闭环验证通过
• k6 NFR-01~03 达标

6.2 二级：TL 验收

• P3-A 55 端点联调报告审核
• P3-B RN 双端 16 页验收
• EAS Build 4 端 artifact 验收
• Detox E2E 双端主流程通过

6.3 三级：UAT 验收

• OL 50 单 UAT 0 Critical 阻塞
• FL 5 人 7 天 0 Critical 崩溃
• CUS 10 人 7 天 0 Critical 阻塞
• 推送送达率 ≥ 95%
• App Store + Google Play 上架

---

七、附录：联调工具清单

工具	用途	版本
pytest	Python 测试框架	8.x
k6	压测工具	0.50+
Detox	RN E2E	20.x
Apifox / Postman	API 联调	最新
EAS CLI	RN 构建	12.x
Sentry	错误监控	8.x

---

— 听写 DT，2026-08-10。本方案为 AI 辅助草案，TL（司徒总）需终审后发布执行。