DIP1 需求规格说明书（自包含版）¶
文档编号：DOC-D01-S / 简称：DIP1-SPEC 版本：V2.0 创建日期：2026-08-09 最近更新：2026-08-09 维护人：TL / DT 定位：DIP1 独立 Code Agent 可脱离 hk2026 主仓其他文档直接参考本规格实施交付；所有角色、术语、枚举、验收标准均在本文档内定义。 关联实现文档：DIP1-ARC 架构设计、DIP1-P2 一线操作系统设计、DIP1-API 规格、DIP1-Schema 设计、DIP1-PROTO 原型设计
V2.0 重大变更：① 跳过阶段1 飞书对接，直接实施阶段2（对齐 ADR-008）；② 前端升级为 React Native + Expo 原生 App（师傅端 wkr-app + 客户端 cst-app，iOS 14+ / Android 9+，对齐 ADR-002/006）；③ 客户端 CUS 从原 Out of Scope 纳入阶段2 In Scope（对齐 ADR-007），覆盖询价→下单→跟踪→评价→推荐全流程；④ 功能点从 193 扩展至 213（新增 CST 客户端 18 + 移动认证 2）；⑤ 新增移动端 NFR 4 项（崩溃率/冷启动/离线/推送送达率）；⑥ 飞书相关功能（F-INF-006/007/011/012）标注「⏸ 阶段1 暂不实施，未来按需启动」。
一、文档定位与使用约定¶
1.1 项目背景¶
DIP1（Delivery & Installation Platform Phase 1 + 2）是「织布鸟 WEAVELY 香港配送+安装互联网平台」的独立技术开发子项目，目标在单一 Git 仓（hk2026 主仓 dip1/ 子目录）内交付一个模块化单体后端（FastAPI + PostgreSQL）+ 三端前端应用（Next.js 运营后台 + React Native 师傅端 + React Native 客户端），覆盖业务全流程（线索→报价→派单→安装→验收→回访→口碑）。
V2.0 范围调整： - 跳过阶段1 飞书对接：原 DIP1-P1 飞书对接设计文档保留，但暂不实施，未来按需启动（ADR-008）。 - 直接实施阶段2 一线操作系统：Code Agent 全栈聚焦阶段2 目标，后端 DDD 6 子域 + 三端前端一次性交付。 - 前端升级为原生 App：师傅端从 Next.js PWA 升级为 React Native + Expo 原生 App（iOS+Android），新增客户端 cst-app 同技术栈（ADR-002/006）。 - 客户端纳入阶段2 范围：客户端从原 Out of Scope 调整为 In Scope，覆盖询价→下单→跟踪→评价→推荐完整闭环（ADR-007）。
1.2 角色与权限（5 类干系方 + 3 端用户）¶
本章节自包含，Code Agent 无需阅读 PJM 即可理解角色含义。
| 角色缩写 | 角色全称 | 系统端 | 职责简述 | 可访问页面数 |
|---|---|---|---|---|
| SPO | 项目负责人（曾总） | 运营后台 | 全局监控、里程碑确认、业务风险审批 | 只读看板 3 页 |
| BO | 业务负责人（郭总） | 运营后台 | 报价参数审批、QMD 系数校准、业务异常裁决 | 看板+报价+异常，共 6 页 |
| PO/TL | 产品/技术负责人（司徒总） | 运营后台 + 系统配置 | 技术方案、RBAC 管理、字段迭代、发布上线 | 全量 15+ 页 + 系统设置页 |
| OL | 运营负责人（成文+黄双人） | 运营后台 | 日常订单操作（L1~L8）、客户沟通、派单调度 | 订单/客户/师傅/看板，共 8 页 |
| ML | 营销负责人（洪哥，兼 BO） | 运营后台 | 线索录入、运营物料、推荐奖励发放 | 线索/营销/口碑，共 5 页 |
| FL | 一线师傅（待定） | 师傅端 App（React Native） | 看自己被派的单、填写 L6 安装记录、上传照片、提交验收、生物识别登录 | 移动端 8+ 页 |
| CUS | 客户（香港住户） | 客户端 App（React Native） | WhatsApp OTP 登录、询价、下单、订单跟踪（L1-L8 Timeline）、L8 评价、推荐有礼 | 移动端 8 页 |
V2.0 变更：CUS 从原「不在 DIP1 MVP 内」升级为「客户端 App」用户，FL 端从「H5」升级为「React Native 原生 App」。
1.3 术语表（自包含，禁止引用主仓 GLY）¶
| 术语 | 英文缩写 | 定义 |
|---|---|---|
| 订单跟踪服务 | CPT | 8 阶段订单生命周期管理（L1 线索→L8 回访） |
| 报价服务 | QSV | 基于 QMD 8 因子公式的香港家具安装报价计算与历史记录 |
| 报价模型 | QMD | 8 大类参数 × 32 项因子的报价公式，含封顶价保护机制 |
| 主数据服务 | MDS | 四库主数据：品类 SCL / 楼宇 BPL / 师傅 WPL / 客户 CPL + 标签体系 TSMM |
| 运营服务 | OPS | 6 类获客场景 + 7 组销售物料 + 口碑推荐奖励 |
| 调度服务 | DSP | 师傅派单与负载均衡（阶段 2 MVP 仅支持人工派单 + 自动推荐 3 人选） |
| 支付服务 | PAY | FPS/信用卡/现金/月结，MVP 仅支持 OL 手填状态，无真实对接 |
| 一线操作系统 | — | TND-E 阶段 2 定义的 OL/师傅日常操作平台（即 DIP1 MVP 交付物） |
| L6 6S 作业规范 | — | 穿鞋套/地面保护/工作台整洁/垃圾带走/产品清洁/前后对比照 6 个合规节点 |
| NPS | — | Net Promoter Score，0~10 分客户满意度评分（L8 回访录入） |
| RBAC | — | Role-Based Access Control，基于角色的 21 项权限矩阵 |
| RLS | — | PostgreSQL Row Level Security，物理隔离师傅行级数据（师傅只能看自己的订单） |
| ULID | — | 可排序全局唯一 ID（26 字符，前缀 ORD/QTE/WKR/CUS/CAT/BLD） |
| React Native | RN | 跨平台原生移动应用开发框架（iOS+Android），师傅端 wkr-app + 客户端 cst-app 采用 |
| Expo | — | React Native 托管工作流平台，提供 EAS Build（云端构建）/ Expo Updates（OTA 热更新）/ Expo Notifications（统一 APNs+FCM 推送） |
| OTA | — | Over-The-Air，JS Bundle 热更新机制，无需走应用商店审核 |
| NativeWind | — | React Native 版 Tailwind CSS，与运营后台 Web 端共享样式 Token |
| APNs / FCM | — | Apple Push Notification Service / Firebase Cloud Messaging，iOS / Android 官方推送通道 |
| OTP | — | One-Time Password，一次性密码（客户端 WhatsApp OTP 登录） |
| AsyncStorage | — | React Native 本地键值存储，用于离线缓存（如 L6 拍照未上传） |
1.4 枚举定义（本规格唯一真值来源，所有代码/接口/数据库以此为准）¶
1.4.1 CPT 订单 8 阶段流转顺序¶
L1 线索获取 → L2 需求确认 → L3 报价生成 → L4 签约下单 → L5 配送安排 → L6 上门安装 → L7 验收交付 → L8 售后回访 → [完成]
↘ [报价拒绝/流失] ↘ L6 异常 → 异常池 → 返回任意阶段
1.4.2 品类枚举（SCL 8 大品类 MVP 上线 6 类）¶
| 值 | 中文 | 基础费 HKD | 基础工时 h | 封顶价 HKD | 要求师傅等级 |
|---|---|---|---|---|---|
WARDROBE |
衣柜 | 380 | 2.5 | 1,200 | L2 |
KITCHEN_CABINET |
橱柜 | 520 | 4.0 | 1,800 | L2 |
BED |
床 | 220 | 1.5 | 800 | L1 |
DINING_TABLE |
餐桌 | 180 | 1.0 | 600 | L1 |
BOOKSHELF |
书柜 | 320 | 2.0 | 1,000 | L2 |
TV_CABINET |
电视柜 | 260 | 1.5 | 900 | L1 |
OFFICE_DESK |
书桌 | 280 | 1.8 | 950 | L1（MVP 第 2 迭代上线） |
COMBINATION_FURNITURE |
组合定制 | 800 | 6.0 | 3,500 | L3（MVP 第 3 迭代上线） |
1.4.3 楼宇类型（7 类 MVP 全部上线）¶
| 值 | 中文 | 基础系数 | 楼层附加规则 |
|---|---|---|---|
PUBLIC_HOUSING |
公屋 | 1.0 | 有电梯免；无电梯 2F 起每层 +5%，5F 封顶 |
HOS |
居屋 | 1.0 | 同公屋 |
PRIVATE |
私楼 | 1.1 | 有电梯免；无电梯每层 +8%，5F 封顶 |
VILLAGE_HOUSE |
村屋 | 1.2 | 无电梯每层 +10%，3F 封顶 |
COMMERCIAL |
商厦 | 1.3 | 有电梯免；货车卸货通道需额外 200 元 |
INDUSTRIAL |
工厦 | 1.25 | 有电梯免；货梯吨位 < 1.5T +100 元 |
OTHER |
其他 | 1.15 | OL 人工核定，备注必填 |
1.4.4 师傅等级 & 技能要求¶
| 等级 | 含义 | 等级系数 | 可处理品类 | 平均 NPS 门槛 |
|---|---|---|---|---|
| L1 初级 | 入职 < 3 个月，跟学中 | 0.9 | 床/餐桌/电视柜 | — |
| L2 中级 | 3-12 个月，独立作业 | 1.0 | + 衣柜/橱柜/书柜 | ≥ 7.0 |
| L3 高级 | 12+ 月，队长级 | 1.15 | 全部 8 类，可带 L1 | ≥ 8.5 |
1.4.5 订单状态 & 跟踪池¶
状态枚举：IN_PROGRESS / COMPLETED / CANCELLED / EXCEPTION_PAUSED
跟踪池枚举（用于看板）：POOL_L1_NEW_LEADS（待联系线索）/ POOL_L3_PENDING_QUOTE（待报价）/ POOL_L4_PENDING_ASSIGN（待派单）/ POOL_L6_INSTALL_TODAY（今日待安装）/ POOL_L8_PENDING_FOLLOWUP（待回访）/ POOL_EXCEPTION（异常池）
1.4.6 6 类获客场景（OPS 线索来源）¶
SCENE01_ONLINE_AD / SCENE02_PACKAGE_INSERT / SCENE03_ECOMMERCE / SCENE04_LOGISTICS_REF / SCENE05_BRAND_PARTNER / SCENE06_CAINIAO / REFERRAL / OTHER
1.4.7 推送通知场景（8 类模板，WKR + CST 双端）¶
| 推送 code | 触发节点 | 接收端 | 模板示例 |
|---|---|---|---|
PUSH_NEW_ORDER |
L4 派单成功 | WKR | "📦 您有新订单：{category}，{date} {slot}，{address}" |
PUSH_ORDER_REMINDER_1H |
L6 安装前 1 小时 | WKR + CST | "⏰ 还有 1 小时开始安装：{category}" |
PUSH_ORDER_STATUS |
L1-L8 阶段流转 | CST | "📦 订单已进入 {stage_name} 阶段" |
PUSH_WORKER_DEPARTED |
L6 师傅出发打卡 | CST | "🚗 师傅已出发，预计 {eta} 到达" |
PUSH_REVIEW_INVITE |
L7 验收完成 | CST | "✅ 订单已验收，点击评价领奖励" |
PUSH_REFERRAL_REWARD |
推荐奖励到账 | CST | "🎁 您推荐的 {name} 下单成功，奖励 {amount} HKD 已到账" |
PUSH_QUOTE_READY |
L3 报价确认 | CST | "💰 您的报价已生成：{amount} HKD，点击查看" |
PUSH_SYSTEM |
系统通知 | WKR + CST | 通用系统消息（版本升级/维护公告等） |
1.4.8 客户端订单来源（CST App 自助下单）¶
CST_APP_SELF（客户端 App 自助下单）/ OPS_REFERRAL（OPS 推荐链路转入）/ OL_MANUAL（OL 代客下单，保留旧路径）
1.5 验收方式总约定¶
所有功能采用 3 级验收：
1. Code Agent 自测：pytest 覆盖率截图 + make ci-local 全绿日志 + RN Detox E2E 录屏
2. TL 功能验收：按本章 GWT（Given/When/Then）逐条执行，通过率 100%；移动端需在 iOS Simulator + Android Emulator 双端通过
3. OL UAT 验收：跑 50 单 8 阶段全流程零阻塞；客户端 UAT 20 单跑通（含询价→下单→跟踪→评价→推荐全流程）
二、功能范围（Scope）¶
2.1 MVP 交付范围（DIP1 必须 100% 完成）¶
| 模块 | 功能点数量 | 说明 |
|---|---|---|
| QSV 报价服务 | 18 | 含 QMD 8 因子公式、参数管理、报价历史、计算器预览 |
| CPT 订单跟踪服务 | 64 | 8 阶段全流程、6 跟踪池看板、L6 6S、L7 验收、L8 NPS |
| MDS 主数据服务 | 37 | 四库 CRUD + 批量导入导出 + TSMM 标签体系（3 层 × 4 实体） |
| OPS 运营服务 | 22 | 6 场景线索池 + 推荐关系网络 + 口碑素材审批流 + 奖励计算 |
| DSP 调度（MVP 简化） | 6 | 人工派单 + 自动推荐 3 人（按负载/技能/评分） |
| 系统管理 & RBAC | 14 | 用户/角色/权限/行级策略/审计日志/系统参数 |
| 基础设施 & 可观测 | 13 | 健康检查/OpenTelemetry/飞书告警/迁移框架 |
| CST 客户端服务（V2.0 新增） | 18 | WhatsApp OTP 登录 / 询价 / 报价预览 / 下单 / 订单跟踪 / L8 评价 / 推荐有礼 / 推送接收 |
| 移动认证 & 推送（V2.0 新增） | 2 | Refresh Token 轮换 + 生物识别登录 / Expo Push Token 注册与统一推送 |
| 运营后台前端 | 15 页 | 见 DIP1-PROTO §三（Next.js 保留） |
| 师傅端 App | 8+ 页 | 见 DIP1-PROTO §四（React Native + Expo，iOS+Android） |
| 客户端 App（V2.0 新增） | 8 页 | 见 DIP1-PROTO §五（React Native + Expo，iOS+Android） |
| 合计 | 213 | （V1.0 原 193 + V2.0 新增 CST 18 + 移动认证/推送 2 = 213） |
2.2 Out of Scope（MVP 不交付，Phase 3 规划项）¶
- 真实支付网关（FPS/Stripe）对接（MVP 仅手填 PAY 状态枚举）
-
客户端 H5/小程序（MVP 仅 WhatsApp 沟通 + OL/FL 代录入）→ V2.0 已纳入 In Scope（客户端 React Native App，见 §3.8） - 飞书内嵌 AI 字段（MVP 仅听写助手外部协作接口）
- 微服务拆分（模块化单体 → 服务化，日单量 ≥ 200 后评估触发）
- 自动化派单引擎（DSP V2，当前仅 3 人推荐 + OL 手动确认）
- 多租户 / 多城市（MVP 仅香港单一租户）
- 英文 UI（MVP 仅中文界面，字段英文名保留用于 API/DB）
- 阶段1 飞书对接（⏸ V2.0 暂不实施，未来按需启动）：DIP1-P1 飞书对接设计文档保留，对应 F-INF-006/007/011/012 飞书相关功能在本期不交付，Code Agent 可跳过实施；当业务决定启动阶段0/1 时再行激活。
三、功能规格清单（213 功能点 ID 追溯）¶
3.1 QSV 报价服务（F-QSV-001 ~ 018）¶
| ID | 功能 | 角色 | 用户故事与验收标准（Given/When/Then） | 依赖 |
|---|---|---|---|---|
| F-QSV-001 | 创建报价 | OL/BO | Given OL 在订单 L3 阶段点击"新建报价"；When 输入品类/楼宇/师傅等级/尺寸参数/增项；Then 系统自动：① base_fee×8 因子 + 增项 − 折扣 = subtotal；② final = MIN(subtotal, cap_price)；③ 生成 QTE-ULID，状态=DRAFT | MDS 品类费率 |
| F-QSV-002 | 报价公式实时预览 | OL | Given 输入参数未保存；When 字段变更 < 300ms；Then 右侧预览更新 subtotal/final/factor 明细 8 条 | 无（前端计算 + 后端兜底一致） |
| F-QSV-003 | 确认报价 | OL/BO | Given 报价状态=DRAFT；When OL 点击"确认并通知客户"；Then 状态→CONFIRMED，写 quote_history，同时触发：① CPT stage=L3→L4（若客户确认）② 若 final ≥ cap_price*0.8 自动标记 BO 待阅 | 无 |
| F-QSV-004 | 拒绝报价 / 流失 | OL | Given 报价=CONFIRMED；When 点击"客户拒绝"/"流失"；Then 写 order_stage_transition 入 EXCEPTION_POOL（若 3 次拒绝 + 自动打 CPL 标签 RISK_LOST） | 无 |
| F-QSV-005 | 报价历史查询 | OL/BO/SPO | When 按订单/客户/时间段/状态过滤；Then 返回列表含 quote_id/金额/状态/操作人/确认时间 6 列 + 分页 | 无 |
| F-QSV-006 | 报价详情 + 参数快照 | TL/BO | When 打开报价详情；Then 显示 ① 最终结果 ② 8 因子展开 ③ 增项明细 ④ quote_snapshot JSON（创建时的 QMD 参数版本，确保历史不改） | F-QSV-001 存储快照 |
| F-QSV-007 | 报价参数版本管理 | TL/BO | Given 当前参数版本=V7（2026-08-01 生效）；When TL 上传新费率 CSV 并点击"生效"；Then 版本号+1，写 qsv_param_versions；新报价自动用 V8；历史报价保持 V7 | 无 |
| F-QSV-008 | 封顶价配置 | BO | When 按品类编辑 cap_price；Then 立即生效（无需等待版本）；后台报价计算结果若触发封顶，审计日志 BO 操作人 | 无 |
| F-QSV-009 | SCL 品类费率 CRUD | TL | When 增/删/改 8 大类 base_fee/base_hours/cap_price；Then 实时同步到 qsv 参数版本 + MDS 品类库 | MDS SCL |
| F-QSV-010 | QMD 反哺校准建议 | TL（AI 辅助） | Given 系统积累 ≥ 500 单；When TL 点击"生成校准报告"；Then 系统计算：① 每品类 actual_hours / base_hours 比值 ② 若 ≥1.2 自动建议 base_fee +10%；③ 生成变更 TL+BO 双审 | F-CPT-049 工时采集 |
| F-QSV-011 | 报价复制 | OL | When 对历史报价点击"复用并新建"；Then 创建 DRAFT 新报价，继承全部参数 + 新版本系数 | 无 |
| F-QSV-012 | 报价导出 PDF | OL/客户 | When 点击"导出报价单"；Then 生成 A4 PDF 含 Logo + 明细 + 盖章位 + 有效期 30 天 | 无 |
| F-QSV-013 | 多版本报价（同一订单 ≥2 次报价对比） | OL | When 同一订单 ≥2 报价；Then 提供"对比视图"：参数逐项差异高亮 + 金额差异 | 无 |
| F-QSV-014 | 折扣审批流 | BO | Given OL 申请 discount > 15%；When 提交审批；Then BO 收到飞书卡片审批；BO 通过→生效；否则保留 DRAFT | 飞书通知 |
| F-QSV-015 | 报价过期自动失效 | Cron | Given DRAFT 超过 30 天 / CONFIRMED 超过 60 天未签约；When 每日 00:05 Cron 扫描；Then 自动→EXPIRED，OL 看板提醒 | 后台 Job |
| F-QSV-016 | 旺季系数配置 | BO/TL | 可按日期范围配置 peak_factor（如国庆 1.2 / 圣诞 1.3）；自动应用到对应期望时段的报价 | 日历 UI |
| F-QSV-017 | 报价模板（大客户/渠道固定价） | BO | 可创建"渠道模板"：比如品牌 A 合作伙伴 → base_fee 9 折固定；OL 选渠道自动应用 | 无 |
| F-QSV-018 | 报价对账单（按月度导出） | BO/TL | 可按月份导出含 quote_id/订单/客户/金额/状态/操作人 CSV，用于财务对账 | 无 |
3.2 CPT 订单跟踪服务（F-CPT-001 ~ 064）¶
3.2.1 L1 线索获取（F-CPT-001~008）¶
| ID | 功能 | 角色 | 验收 GWT |
|---|---|---|---|
| 001 | 手工录入线索 | OL/ML | G：线索来源 WhatsApp/电话/随箱卡；W：填写 lead_source+客户姓名+联系方式+初步需求；T：生成 ORD-ULID，stage=L1，入 POOL_L1_NEW_LEADS |
| 002 | OPS 线索一键转订单 | ML | G：OPS 模块有已验证有效线索；W：ML 点"转 CPT 订单"；T：自动填充 L1 5 字段 + 打上首单来源标签 |
| 003 | 线索响应时效监控 | OL/TL | G：线索入池 > 2 小时未联系；W：看板红色高亮 + OL 飞书提醒；T：系统记录"响应时长分钟"指标（月度考核 OL） |
| 004 | 线索去重 | 系统 | G：相同姓名+WhatsApp 30 天内已有线索；W：保存；T：弹框提示"可能重复"（OL 可强制新建） |
| 005 | 批量线索导入（CSV/Excel） | ML/TL | 支持一次导入 ≤ 500 条线索；导入结果报告：成功 X / 格式失败 Y / 疑似重复 Z（可下载） |
| 006 | 客户画像自动补全 | 系统 | G：新客户创建；W：输入手机号/WhatsApp；T：自动查 CPL（若存在）→ 回填历史单量/标签/推荐人 |
| 007 | 3 次联系失败入流失池 | Cron | G：OL 已标注 3 次未应答；W：每日 18:00；T：自动入 EXCEPTION_POOL + 打 CPL 标签"联系失败" |
| 008 | 线索分配（多人 OL 场景） | TL | 支持手动分配 OL 跟进人 + "轮询自动分配"模式 |
3.2.2 L2 需求确认（F-CPT-009~016）¶
| ID | 功能 | 角色 | 验收 GWT |
|---|---|---|---|
| 009 | 品类+型号登记 | OL | 枚举选品类，文本填产品型号（提示：宜家 PAX / 尚品宅配定制等） |
| 010 | 安装地址 + 楼宇关联 | OL | 地址联想（BPL 匹配）→ 若命中已有楼宇 → 自动带楼宇类型/系数/电梯/停车；若新地址 → 提示 OL 创建新楼宇 BLD-ULID |
| 011 | 期望时段选择（双时段） | OL | 可选"上午 09-13" / "下午 13-18" / "周末优先" + 日期，师傅端可看见 |
| 012 | 现场条件采集 | OL | 5 个复选框：电梯可用 / 可进货车 / 有停车位 / 物业需申请 / 有楼道限制 + 自由文本备注 |
| 013 | 门框/楼道照片上传 | OL | 最多 9 张 ≤ 10MB 每张，存 R2 → 生成 URL 返回，订单详情页可见 |
| 014 | 产品参数自动提取（AI 辅助 MVP 占位） | DT 占位 | 上传产品说明书 → 未来 AI 提取尺寸/重量 → 写入 product_params（当前仅人工） |
| 015 | L2 完成 → L3 流转校验 | 系统 | 必须字段 5 项（品类/型号/地址/时段/现场条件）全部填写方可流转 |
| 016 | 客户确认信息（WhatsApp 截图） | OL | 客户确认的聊天截图，可选上传，作为后续纠纷证据 |
3.2.3 L3 报价生成（F-CPT-017~022 → 同 QSV 联动）¶
| ID | 功能 | 角色 | 验收 GWT |
|---|---|---|---|
| 017 | 订单内发起报价 | OL | 在订单详情页 L3 Tab → "发起报价" → 自动带入 L2 已采集的品类/楼宇 → 跳 QSV 新建页面带 prefill |
| 018 | 报价状态回显 | 系统 | CONFIRMED 时 → 订单主图显示绿色"已确认 ¥金额"；REJECTED → 灰色 |
| 019 | 多报价管理 | OL | 支持同一订单 2~3 版报价对比（MVP 简化版 QSV-013） |
| 020 | BO 审批异常大额报价 | BO | final_amount ≥ 2,000 HKD → 自动 BO 审批流（同 QSV-014 阈值不同） |
| 021 | 报价与订单绑定历史 | 系统 | 全部报价（含被拒绝）全部记录在 quote_history 列表，订单详情页 Tab 可见 |
| 022 | 流转到 L4 前置校验 | 系统 | 必须至少有 1 个 CONFIRMED 报价；否则提示"先确认报价" |
3.2.4 L4 签约下单（F-CPT-023~031）¶
| ID | 功能 | 角色 | 验收 GWT |
|---|---|---|---|
| 023 | 签约时间录入 | OL | 默认当前时间，可手动调整 |
| 024 | 付款方式枚举 | OL | FPS / CREDIT_CARD / CASH / MONTHLY（月结客户）4 选 1 |
| 025 | 付款状态跟踪 | OL | UNPAID / PAID / PARTIAL / REFUNDED；MVP 纯手填（无支付网关对接） |
| 026 | 首付比例记录 | OL | 如 50% 预付 / 全款 / 零首付 自定义 |
| 027 | 指派师傅（核心派单功能） | OL/DSP | 见 DSP 模块 F-DSP-001~006 |
| 028 | 合同照片/签字上传 | OL | 可选，最多 5 张 |
| 029 | 客户微信/WhatsApp 推送（MVP 占位） | 系统 | MVP 仅生成"一键复制师傅电话+安装时间到剪贴板"，OL 手动粘贴到 WhatsApp 发送 |
| 030 | 签约超时告警（>24h 未签） | Cron | 报价 CONFIRMED 后 24h 未签约 → 飞书提醒 OL |
| 031 | L4→L5 前置校验 | 系统 | signed_at + 付款方式 + assigned_worker_id 三项必填 |
3.2.5 L5 配送安排（F-CPT-032~038）¶
| ID | 功能 | 角色 | 验收 GWT |
|---|---|---|---|
| 032 | 配送方式 4 枚举 | OL | SELF_DELIVER / LOGISTICS / CUSTOMER_PICKUP / BRAND_DIRECT |
| 033 | 物流单号记录 | OL | 可选，若 = LOGISTICS 则推荐必填 |
| 034 | 配送时间/签收状态跟踪 | OL | PENDING / IN_TRANSIT / RECEIVED / EXCEPTION 4 态 |
| 035 | 配送损坏照片与备注 | OL | 可选附件，异常时必传 |
| 036 | 师傅签收确认（MVP：OL 代） | OL | 勾选"师傅已签收"→ delivery_status = RECEIVED |
| 037 | 配送时间与期望时段冲突校验 | 系统 | 若配送日期 ≥ 期望日期 +2 天 → 橙色预警"可能延期" |
| 038 | L5→L6 前置校验 | 系统 | delivery_status = RECEIVED / SELF_DELIVER / CUSTOMER_PICKUP（BRAND 可直接跳过确认） |
3.2.6 L6 上门安装 + 6S 合规（F-CPT-039~052，CPT-F 核心 183 字段主承载区）¶
| ID | 功能 | 角色 | 验收 GWT |
|---|---|---|---|
| 039 | 师傅出发打卡 | FL | 师傅端 GPS 定位（MVP 仅记录"点击出发"时间戳；阶段 3 加地理围栏） |
| 040 | 师傅到达打卡 | FL | 与上一个出发时间差 ≥ 10 分钟（防误触） |
| 041 | L6 6S 节点合规勾选（必过 6 项） | FL | 穿鞋套 / 地面保护 / 工作台整洁 / 垃圾带走 / 产品清洁 / 前后对比照：6 项 checkbox，全部√才能点"完工" |
| 042 | 现场照片分三类上传 | FL | ① 入户前（至少 1 张）② 安装过程中（至少 1 张）③ 完工后（至少 2 张：整体+细节）→ 共 ≥ 4 张才能保存 |
| 043 | 完工时间记录 | FL | 默认系统时间，可调整 ±30 分钟 |
| 044 | 实际工时自动计算 + 人工覆盖 | 系统 + FL | 自动 = (完工 - 到达) - 休息时间（若选 ≥60 分钟扣除）；FL 可手动修改（触发审计日志） |
| 045 | 增项记录（超合同范围） | FL/OL | FL 填写增项描述 + 预估金额 + 客户语音/文字确认截图 → OL 24h 内核定是否计入 final |
| 046 | 异常记录（超能力/物业拦） | FL/OL | 异常下拉枚举：产品损坏 / 零件缺失 / 安装条件不符 / 物业阻拦 / 客户改期 / 其他；严重异常直接进入 EXCEPTION_POOL |
| 047 | 安装视频（MVP 可选） | FL | 可选 ≤60s 短视频，R2 存储（未来 AI 检查 6S 合规） |
| 048 | 休息次数/时长记录 | FL | 供 TL 评估实际工时基准线 |
| 049 | 工时采集反哺 QMD（核心数据闭环） | 系统异步 Job | 订单 COMPLETED 后 10min 内：写入 worker_monthly_load / category_avg_hours / actual_vs_baseline 统计表 → QSV-010 校准报告用 |
| 050 | OL 可随时查看 L6 进度 | OL/TL | 看板实时显示："已出发/安装中/已完工/异常" + 当前照片张数 / 6S 勾选数 |
| 051 | L6 超时提醒（> 品类基础工时 × 2） | Cron | 超过基础工时 × 2 且未完工 → 自动提醒 OL 介入 |
| 052 | L6→L7 前置校验 | 系统 | 6S 全选 / 4 张照片 / 实际工时 > 0 / 完工时间必填 |
3.2.7 L7 验收交付（F-CPT-053~058）¶
| ID | 功能 | 角色 | 验收 GWT |
|---|---|---|---|
| 053 | 验收结果 3 枚举 | FL/OL | PASS / RECTIFY / COMPLAINT |
| 054 | 不合格项整改记录 | FL/OL | RECTIFY：记录问题描述 + 照片 + 预计返工日期；整改后 L7 状态重置为未验收 |
| 055 | 客户签字照上传（必传） | FL/OL | 客户在纸上签字 → 拍照 → 至少 1 张清晰照片；客户姓名与 CPL 一致（MVP 人工；AI 未来 OCR） |
| 056 | 验收时间记录 | FL/OL | 默认签字照上传时间；客诉时可精确追溯 |
| 057 | 自动生成 WOM 素材候选（口碑闭环） | 系统 | 验收 PASS 且 NPS（L8）≥ 9 → 自动进入口碑素材池（OPS-019） |
| 058 | L7→L8 前置校验 | 系统 | 验收结果 = PASS（RECTIFY 需返工完成重置；COMPLAINT 也可进 L8 作为"处理后回访"） |
3.2.8 L8 售后回访（F-CPT-059~064）¶
| ID | 功能 | 角色 | 验收 GWT |
|---|---|---|---|
| 059 | NPS 评分 0~10（必填） | OL | 滑块 0-10；颜色：≤6 红（贬损者）/ 7-8 黄（被动）/ ≥9 绿（推荐者） |
| 060 | 回访备注 5 维度模板 | OL | 5 个建议勾选：① 师傅服务态度 ② 安装质量 ③ 价格合理性 ④ 时效满意度 ⑤ 推荐意愿 + 自由文本 |
| 061 | NPS 自动打 CPL 客户标签 | 系统 | ≥9 → CPL 打标签 HIGH_RECOMMEND_CANDIDATE；≤6 → LOW_NPS_RISK 自动入 OL 跟进列表 |
| 062 | WPL 师傅评分自动更新 | 系统（异步） | 订单完成 → 重算该师傅的历史 N 单平均分（≥ 5 单才更新 avg_rating），WPL 同步更新 |
| 063 | 推荐奖励计算（OPS 联动） | OPS | 若该订单推荐关系链存在 → 按奖励规则 100-300HKD 自动生成 reward，入 OPS-022 待发放 |
| 064 | 订单完成（stage=DONE + status=COMPLETED） | 系统 | L8 保存成功 → 自动触发：OrderCompletedEvent（领域事件）→ 反哺 QMD / WPL / CPL / OPS 四条数据闭环 |
3.2.9 公共看板与统计（CPT 跨阶段，F-CPT-065~ 实际看板功能继续在 64 基础上后续补齐，总功能数按 §2.1 控制 64 条已满足）¶
3.3 MDS 主数据服务（F-MDS-001 ~ 037）¶
SCL 品类（F-MDS-001~008）¶
001 CRUD 8 大类 / 002 细分类目管理 / 003 基础费批量导入 CSV / 004 基础工时配置 / 005 封顶价 / 006 技能要求 / 007 产品参数字段模板（未来 AI 提取用）/ 008 版本化变更历史
BPL 楼宇（F-MDS-009~017）¶
009 CRUD 楼宇档案 / 010 地址输入联想（2 字符起匹配） / 011 7 类楼宇类型枚举下拉 / 012 楼层系数自动建议 / 013 电梯/停车/物业准入 / 014 师傅现场核实（打勾+坐标，MVP 仅勾选）/ 015 楼宇标签（学区房 / 豪宅 / 老破小）/ 016 批量导入 / 017 TOP 20 热门楼宇（按订单数自动榜）
WPL 师傅（F-MDS-018~027）¶
018 师傅档案 CRUD / 019 三级等级（L1/L2/L3）/ 020 技能矩阵（8 品类 × 三级熟练度）/ 021 历史单量 / 平均 NPS / 月负载小时 / 022 师傅状态（可接/忙碌/暂停）/ 023 师傅标签（细心/快手上手/粤语/普通话）/ 024 入职培训记录 / 025 客户投诉档案 / 026 工资结算月结导出（MVP 基础版）/ 027 飞书账号关联（未来飞书免登）
CPL 客户（F-MDS-028~035）¶
028 客户档案 CRUD / 029 联系方式 WhatsApp/电话/邮箱 / 030 首单来源（OPS 联动）/ 031 历史订单数 + LTV / 032 最近 NPS / 033 五维标签（价值/品类/推荐/复购/风险）/ 034 信任徽章（3 次以上好评/推荐 2 人以上）/ 035 推荐关系链可视化（graph）
TSMM 标签体系（F-MDS-036~037）¶
036 标签定义 CRUD（三层：基础属性/能力画像/场景适配 × 四实体：师傅/客户/楼宇/品类 + PDPO 隐私级别）/ 037 批量打标（运营工具，可按条件筛选后一次性打 ≤1k 条标签）
3.4 OPS 运营服务（F-OPS-001~022）¶
001 线索录入 6 场景 / 002 线索 6 分池看板 / 003 线索→CPT 订单转换（同 CPT-002）/ 004 线索阶段跟进记录（每次沟通历史）/ 005 线索转化率漏斗报表（6 场景对比）/ 006 7 组 32 项销售物料索引（对齐 OPS-M V1.0，MVP 仅存链接）/ 007 物料下载点击统计 / 008 6 场景运营手册（对齐 OPS-S V1.0，MVP 存 PDF 链接）/ 009 推荐关系新增（客户 A 推荐 B 下单自动识别 + 人工补录）/ 010 推荐关系网络图谱（2 层可视化）/ 011 推荐奖励规则（≥100 HKD / 3 级）/ 012 待发放奖励列表 / 013 奖励发放（OL 手动操作 FPS + 截图）/ 014 奖励过期自动失效（3 个月未领取）/ 015 口碑素材池（L8 NPS≥9 自动候选）/ 016 客户确认口碑（OL 通过 WhatsApp 发送确认链接，MVP 仅手动记录）/ 017 素材发布到运营库（生成下载 URL）/ 018 推荐人线索自动入池（CPL badge=推荐人 → 生日/节日自动发优惠券提示 MVP 占位）/ 019 场景 ROI 报告（月维度）/ 020 流失预警（CPL 标签 RISK_LOST → ML 工作台提醒）/ 021 口碑案例精选展示（运营后台首页）/ 022 推荐奖励发放审批（≥ 500 HKD 需 BO 审批）
3.5 DSP 调度服务（MVP 简化 F-DSP-001~006）¶
001 指派师傅弹窗（可搜姓名/品类/等级）/ 002 自动推荐 Top3 师傅（算法：技能匹配 ∧ 状态可接 ∧ 月负载最低 ∧ 平均 NPS 最高 → 综合打分）/ 003 师傅负载看板（本周已派单数 + 总工时，≥40h 标红）/ 004 改派（原师傅请假可改派他人，写入审计日志）/ 005 师傅请假登记（日期范围 + 暂停接单）/ 006 紧急单优先派（客户要求当日/次日 → 标红）
3.6 系统管理 & RBAC（F-SYS-001~014）¶
001 用户 CRUD / 002 角色定义（SPO/BO/TL/OL/ML/FL 6 角色，对齐 §1.2）/ 003 权限定义 21 条（对齐 DIP1-P2 §5.1 矩阵）/ 004 用户-角色分配 / 005 角色-权限分配 / 006 行级策略（RLS）配置页：师傅仅自己订单 / OL 全部 / ML 仅线索+客户等 （TL 可调整）/ 007 审计日志（≥1 年在线可查：全部写操作 + 敏感读）/ 008 系统参数（分页大小/超时阈值/告警阈值）/ 009 JWT Token 有效期 / 010 飞书机器人告警渠道配置 / 011 DB 备份状态查看 / 012 OpenAPI 文档（Swagger UI 访问权限）/ 013 系统健康检查仪表盘（CPU/内存/DB 连接/Redis）/ 014 字段字典（所有枚举字段字典页，便于未来新增）
3.7 基础设施 & 可观测（F-INF-001~013）¶
001 /health 健康检查端点 / 002 OpenTelemetry Trace 链路 / 003 Prometheus 指标（HTTP 4xx/5xx/P95/DB Pool/QSV 耗时）/ 004 飞书群机器人告警（8 阈值对齐 P3 §6.2）/ 005 Sentry 错误捕获 / 006 DLQ 死信队列查看页（阶段 1 飞书同步）⏸ V2.0 暂不实施 / 007 DLQ 重放 ⏸ V2.0 暂不实施 / 008 Alembic 迁移状态监控 / 009 R2 附件存储占用统计 / 010 定时任务（Cron）列表 / 011 阶段 1 飞书同步进度页（CPT/QSV/WPL/CPL/SCL/BPL 同步延迟+失败数）⏸ V2.0 暂不实施 / 012 全量同步触发按钮 ⏸ V2.0 暂不实施 / 013 数据导出（全量订单/CSV，审计日志留痕）
V2.0 说明：F-INF-006/007/011/012 飞书同步相关功能本期暂不实施（对齐 ADR-008 跳过阶段1）。Code Agent 可跳过这 4 项功能的开发，对应数据库表
feishu_sync_idempotency/sys_dlq_messages在 Alembic 0001 中仍保留结构（便于未来按需激活），但无需实现对应 API 与页面。
3.8 CST 客户端服务（F-CST-001~018，V2.0 新增）¶
对应客户端 App（cst-app，React Native + Expo）。覆盖询价→下单→跟踪→评价→推荐完整闭环，是口碑营销与推荐关系链的关键触点。详见 DIP1-PROTO §五。
| ID | 功能 | 验收 GWT |
|---|---|---|
| F-CST-001 | WhatsApp OTP 登录 | G：客户打开 cst-app；W：输入 WhatsApp 号码 → 收到 6 位 OTP → 输入验证；T：签发 JWT（refresh token + access token），写入 cst_sessions 表，登录态保持 30 天 |
| F-CST-002 | 首页品类浏览 | G：客户登录后进入首页；W：浏览 8 大品类入口 + 进行中订单卡片 + 推荐入口；T：品类数据从 SCL 实时拉取，进行中订单 ≤ 2s 加载 |
| F-CST-003 | 询价表单提交 | G：客户选择品类；W：填写型号/尺寸/地址（BPL 联想匹配）/期望时段/现场条件 + 上传门框照片 ≤ 9 张；T：生成 ORD-ULID，stage=L1，lead_source=CST_APP_SELF，自动流转 L1→L2，OL 后台收到新线索提醒 |
| F-CST-004 | 报价预览（自动计算） | G：客户提交询价后；W：系统自动调 QSV 计算（基础费 + 8 因子 + 增项 - 折扣，封顶价保护）；T：客户端展示报价明细（8 因子展开）+ 预估金额，状态=DRAFT，不自动确认（需 OL 审核或客户在 App 内确认） |
| F-CST-005 | 客户确认报价 | G：客户收到 PUSH_QUOTE_READY 推送；W：点击查看报价 → 确认/拒绝；T：确认→状态=CONFIRMED，触发 CPT L3→L4 流转；拒绝→状态=REJECTED，OL 收到拒绝通知 |
| F-CST-006 | 在线下单（确认签约） | G：报价已 CONFIRMED；W：客户在 App 内选择付款方式（FPS/信用卡/现金/月结）+ 首付比例 + 电子签字；T：订单 stage=L4，写入 contract_info，OL 后台同步显示 |
| F-CST-007 | 订单跟踪 Timeline | G：客户进入「我的订单」→ 选择订单；W：查看 L1-L8 8 阶段 Timeline；T：每个节点显示状态/时间/简要说明，当前阶段高亮，支持点击查看详情 |
| F-CST-008 | 师傅信息展示 | G：订单已派单（L4）；W：客户查看师傅卡片；T：显示师傅姓名/等级/技能徽章/历史 NPS（脱敏，不显示电话，仅展示 OL 联系方式作为中介） |
| F-CST-009 | 安装日提醒推送 | G：L6 安装前 1 小时；W：系统自动推送；T：客户端收到 PUSH_ORDER_REMINDER_1H 推送，点击跳转订单详情 |
| F-CST-010 | 师傅出发通知 | G：师傅在 wkr-app 点击「出发打卡」；W：系统推送；T：客户端收到 PUSH_WORKER_DEPARTED，显示预计到达时间 |
| F-CST-011 | L8 评价（NPS + 评分 + 文字） | G：L7 验收完成；W：客户收到 PUSH_REVIEW_INVITE → 打开评价弹窗 → 选 NPS 0-10 + 5 星评分 + 文字评价（≤ 500 字）+ 可选上传照片；T：写入 followup_record，触发 OrderCompleted 事件 → 4 链路数据闭环（QMD/WPL/CPL/OPS） |
| F-CST-012 | 历史订单查询 | G：客户进入「我的」→ 历史订单；W：按月份分组查看已完成订单；T：支持重新发起询价（一键复用历史参数） |
| F-CST-013 | 推荐码生成与分享 | G：客户进入「推荐有礼」；W：点击「生成推荐码」；T：生成唯一推荐码（CUS-ULID 后 6 位）+ 分享链接（含深链），支持系统分享（WhatsApp/微信/复制） |
| F-CST-014 | 推荐关系自动识别 | G：新客户通过推荐链接注册；W：首次 OTP 登录；T：自动绑定 referrer_id，写入 CPL 推荐关系链 |
| F-CST-015 | 推荐奖励记录 | G：被推荐人下单成功（L4）；W：系统自动计算奖励；T：推荐人 App 收到 PUSH_REFERRAL_REWARD 推送，「推荐有礼」Tab 显示奖励金额 + 状态（待发放/已发放） |
| F-CST-016 | 个人档案管理 | G：客户进入「我的」→ 个人档案；W：查看/修改姓名/联系方式/地址；T：修改写审计日志，联系方式变更触发 OTP 重新验证 |
| F-CST-017 | 推送偏好设置 | G：客户进入「设置」；W：开关 8 类推送（PUSH_NEW_ORDER 等）；T：偏好写入 cst_push_preferences 表，后端推送前过滤 |
| F-CST-018 | 离线模式（弱网降级） | G：客户在弱网/无网环境；W：浏览已加载订单/历史订单；T：AsyncStorage 缓存最近 20 条订单，网络恢复后自动同步；询价/下单等写操作提示「网络不可用，已暂存」 |
3.9 移动认证 & 推送（F-MOB-001~002，V2.0 新增）¶
| ID | 功能 | 验收 GWT |
|---|---|---|
| F-MOB-001 | Refresh Token 轮换 + 生物识别登录 | G：师傅/客户登录后 30 天内；W：access token 过期 → 自动用 refresh token 换新；T：refresh token 轮换（一次性，用后失效），旧 token 写入黑名单；生物识别（Face ID/Touch ID）绑定后可免密登录 |
| F-MOB-002 | Expo Push Token 注册与统一推送 | G：师傅/客户首次登录 App；W：请求推送权限 → 获取 ExpoPushToken → 注册到后端 mobile_push_tokens 表；T：后端按订单事件触发推送（8 类模板），通过 Expo Notifications API 统一发送至 APNs/FCM，送达率 ≥ 95% |
四、非功能性需求（可量化，交付验收硬指标）¶
| # | 类别 | 指标 | 阈值 | 验证方式 |
|---|---|---|---|---|
| NFR-01 | 性能：API P95 | 所有写接口 | ≤ 200 ms | k6 压测 50 VU |
| NFR-02 | 性能：QSV 报价计算 | 单次 recalculate | ≤ 30 ms | pytest-benchmark 10k 次均值 |
| NFR-03 | 并发 | 运营后台 | 50 并发用户无 5xx | k6 ramping VU |
| NFR-04 | 可用性（生产） | SLA | 月度 ≥ 99.9%（停机 ≤ 43 分钟） | UptimeRobot 监控 |
| NFR-05 | 数据一致性：阶段 1 飞书同步 | CPT-Lite → DB | 延迟 P95 < 10s，丢单率 0% | 对账脚本每日跑 |
| NFR-06 | RBAC 越权 | 所有接口 | 越权访问 100% 返回 403 | 越权自动化测试 21 条权限 × 6 角色 |
| NFR-07 | 安全：注入/XSS | OWASP Top 10 | 高危 0 | ZAP 被动扫描 + RLS |
| NFR-08 | 备份 RPO/ RTO | PG / Redis / R2 | RPO 5 分钟 / RTO 30 分钟（对齐 P3 §5.5） | 灾备演练脚本 |
| NFR-09 | 可维护：代码覆盖率 | 领域层 + 应用层 | ≥ 80% | Codecov 报告 |
| NFR-10 | 数据库迁移 | upgrade/downgrade 双向 | 3 轮循环零错 | CI migrate-check Job |
| NFR-11 | 响应式 UI | 运营后台 1080p / 师傅端 375px | 无横向滚动 | Playwright 视觉回归 |
| NFR-12 | 隐私合规（PDPO） | 客户/师傅联系方式 | 后台展示脱敏（中间 4 位打 *）+ ≥ L3 权限才可见完整；审计留痕 | 代码 Review + 用例 |
| NFR-13 | 国际化 | 后端字段 | 全英文 snake_case（MVP 无英文 UI，但架构预留 i18n 路径） | 命名规范 CI 检查（ruff） |
| NFR-14 | 附件上传 | 图片 ≤ 20MB / 视频 ≤ 200MB | 上传超时 ≤ 10s（香港到 R2） | 手动 + CI 模拟 |
| NFR-15 | 移动端崩溃率（V2.0 新增） | WKR/CST App iOS + Android | 崩溃率 ≤ 0.1%（按 DAU 统计） | Crashlytics / Sentry RN SDK 监控 7 天 |
| NFR-16 | 移动端冷启动（V2.0 新增） | WKR/CST App | 冷启动 ≤ 2s（中端 Android 设备） | Detox 性能测试脚本 |
| NFR-17 | 移动端离线能力（V2.0 新增） | WKR L6 拍照 / CST 订单浏览 | 弱网（3G/失联）下可继续操作，网络恢复后自动同步 | Charles 模拟弱网 + AsyncStorage 验证 |
| NFR-18 | 推送送达率（V2.0 新增） | 8 类推送模板 | 送达率 ≥ 95%（APNs + FCM via Expo Notifications） | 推送日志表 + 24h 对账脚本 |
| NFR-19 | 应用商店审核（V2.0 新增） | WKR/CST App | iOS App Store + Google Play 审核通过 | 提交审核截图 + 上架链接 |
| NFR-20 | OTA 热更新（V2.0 新增） | WKR/CST App JS Bundle | Expo Updates 推送后 24h 内 ≥ 90% 活跃用户更新 | Expo Dashboard 更新统计 |
五、Code Agent 交付 Checklist（TL 验收用，100% 通过才算 Done）¶
✅ 文档层
[1-1] 本需求规格 213 功能点 × 验收标准，每功能点对应至少 1 条自动化/手工用例
[1-2] OpenAPI spec YAML 与实现代码 100% 对齐（dredd 或 schemathesis 测试）
[1-3] DB schema 与 Alembic 迁移脚本 100% 对齐（ migra 校验，含 0001 + 0002）
[1-4] 原型与实现页面 100% 对齐（运营后台 15 页 / 师傅端 8+ 页 / 客户端 8 页，页面数/导航/按钮命名一致）
✅ 代码层
[2-1] `make ci-local` 零失败（ruff/mypy/unit 测试/迁移双向校验）
[2-2] 领域层 + 应用层覆盖率：后端报告 ≥ 80%
[2-3] 集成测试：Testcontainers PG 场景 ≥ 50 条（覆盖 6 子域）
[2-4] E2E Playwright（Web）：运营后台登录 → 创建订单 → 报价 → 派单 → L8 NPS，完整 8 阶段零报错
[2-5] RBAC 越权 21×6 = 126 条自动化用例 100% 通过
[2-6] Dockerfile + docker-compose 从零启动成功（空仓库 + .env 一条命令）
[2-7] 前后端本地启动：`make dev` 四端并行可用（:3000 运营后台 / :8081 wkr-app Metro / :8082 cst-app Metro / :8000 API）
✅ 移动端（V2.0 新增）
[M-1] wkr-app + cst-app 在 iOS Simulator + Android Emulator 双端启动零报错
[M-2] Detox E2E：师傅端 L6 打卡 → 6S 勾选 → 三类照片上传 → 完工提交全流程录屏
[M-3] Detox E2E：客户端 OTP 登录 → 询价 → 报价确认 → 下单 → 评价 → 推荐码生成全流程录屏
[M-4] 推送测试：8 类模板在 TestFlight / Internal Testing 各触发 1 次，送达截图
[M-5] 离线模式：Charles 模拟 3G 弱网，L6 拍照缓存 + 恢复后自动同步验证
[M-6] OTA 验证：Expo Updates 推送一次 JS Bundle 更新，24h 内更新率统计
✅ 部署 & 数据层
[3-1] ⏸ ~~飞书 MVP-FS → PostgreSQL 全量迁移~~（V2.0 暂不实施，阶段1 启动后再验收）
[3-2] Prometheus 4 指标集 + Grafana 仪表盘模板 JSON 交付
[3-3] 可观测告警飞书机器人 8 阈值实测触发 1 次（模拟 5xx 告警）
[3-4] DB 备份 + 恢复演练：RPO/RTO 达标（删除某订单，5 分钟内恢复）
[3-5] App Store + Google Play 双端上架成功（WKR + CST 共 4 个 App）
✅ 交付物清单
[4-1] 本规格（DIP1-SPEC V2.0）
[4-2] DIP1-ARC V2.0 / DIP1-P2 V2.0 / DIP1-P3 V1.1 架构与设计（见 §1 引用）
[4-3] DIP1-API.yaml V2.0（OpenAPI 3.0，65 端点）
[4-4] DIP1-Schema.md V1.1（字段级 ER + 迁移脚本 0001 + 0002）
[4-5] DIP1-PROTO.md V2.0（运营后台 15 页 + 师傅端 RN 8+ 页 + 客户端 RN 8 页 + 10 交互流）
[4-6] DIP1-IMP.md V2.0（实施顺序 105 人天）
[4-7] 覆盖率报告 + CI 全绿截图 + Playwright + Detox 录屏（关键流程）
[4-8] 环境变量样例 + 凭据占位清单（TL 填入生产凭据后即可上线）
[4-9] Expo 项目配置 + EAS Build 凭据 + App Store Connect / Google Play Console 配置截图
附录 A：错误码表（OpenAPI 通用返回）¶
| code | HTTP 状态 | 说明 | 触发场景示例 |
|---|---|---|---|
| 0 | 200 | 成功 | — |
| 1001 | 401 | 未登录 / Token 过期 | Authorization Header 缺失或过期 |
| 1002 | 403 | 无权限（RBAC / RLS） | OL 访问 qsv:params:edit |
| 2001 | 400 | 参数校验失败 | quote_amount 负数 / 必填字段缺失 |
| 2002 | 422 | idempotency 冲突 / 幂等重复 | 同 Idempotency-Key 二次请求 |
| 3001 | 409 | 业务规则冲突 | 订单状态流转非法（L1 直接跳到 L6）/ 报价已 CONFIRMED 不可再编辑 |
| 3002 | 409 | 资源唯一键冲突 | 相同手机号客户已存在 |
| 3010 | 422 | QSV 计算规则校验 | category_id 不存在 / building_factor 越界 0.5-2.0 |
| 3020 | 422 | CPT 阶段流转校验失败 | L6→L7 缺少签字照 / 6S 未勾选 |
| 3030 | 422 | WPL 派单冲突 | 师傅同日同时段已有 ≥ 2 单 |
| 4001 | 404 | 资源不存在 | order_id / quote_id / worker_id 找不到 |
| 4010 | 410 | 资源已删除 / 软删除 | 访问 archived 订单且无 ADMIN 权限 |
| 5001 | 500 | 系统内部错误 | DB 连接失败 / 飞书 API 连续 3 次超时 |
| 5002 | 503 | 维护中 / 功能未开启 | PAY 网关未配置 / OPS AI 提取 MVP 关闭 |
| 1003 | 401 | Refresh Token 无效或已轮换 | 移动端 refresh token 已过期/已用/已加入黑名单（V2.0 新增） |
| 1004 | 401 | OTP 验证失败 | 客户端 WhatsApp OTP 错误或超过 5 分钟有效期（V2.0 新增） |
| 1005 | 403 | 生物识别验证失败 | Face ID/Touch ID 校验未通过（V2.0 新增） |
| 3040 | 422 | 推送发送失败 | ExpoPushToken 无效或 APNs/FCM 通道异常（V2.0 新增） |
| 3050 | 422 | 客户端询价校验失败 | 询价表单缺少必填字段 / 照片张数不足（V2.0 新增） |
修订记录¶
| 版本 | 日期 | 修订人 | 修订内容 |
|---|---|---|---|
| V1.0 | 2026-08-09 | DT | 初始化：193 功能点 × 14 NFR × 6 角色 × 12 子域；自包含错误码表；3 级验收 Checklist；Next.js PWA + 飞书阶段1 范围 |
| V2.0 | 2026-08-09 | DT | 原生 App 升级：① 客户端 CUS 从 Out of Scope → In Scope，新增 F-CST-001~018 共 18 功能点；② 新增移动认证 & 推送 F-MOB-001~002；③ 功能点 193→213；④ 新增 NFR-15~20 移动端 6 项（崩溃率/冷启动/离线/推送/商店审核/OTA）；⑤ 新增 §1.4.7 推送场景 8 类模板 + §1.4.8 客户端订单来源；⑥ F-INF-006/007/011/012 飞书相关功能标注⏸暂不实施；⑦ Checklist 新增移动端 M-1~M-6 + 部署 3-5 + 交付物 4-9；⑧ 错误码新增 1003/1004/1005/3040/3050；⑨ 对齐 ADR-002/006/007/008 |
本文件为 DIP1 需求规格说明书（DOC-D01-S V2.0，自包含），Code Agent 无需阅读 hk2026 主仓其它文档即可按 §1-§5 + 关联实现文档实施交付。