跳转至

DIP1 Code Agent 实施指南（自包含 · 脱离 hk2026 主仓文档）

文档编号：DOC-D01-IMP / 简称：DIP1-IMP 版本：V2.0 创建日期：2026-08-09 最近更新：2026-08-09 目标读者：独立的 DIP1 Code Agent（无需阅读 hk2026 主仓的业务/制度/需求/工作日志文档）、DIP1 TL（司徒总）、SPO（曾总）跟踪子项目状态 核心承诺：按本指南 + 下方 §3 引用的 10 份 DIP1 自有文档，即可独立完成 DIP1 阶段 2 的 100% 代码交付（后端 + Web 运营后台 + React Native 双端 App）、测试、环境部署、UAT 验收，不依赖主仓的其它业务文档。

V2.0 重大变更：① 前端方案从 Next.js PWA 升级为 React Native + Expo 原生 App（wkr-app 师傅端 + cst-app 客户端，iOS+Android 双端）；② 跳过阶段 1 飞书对接（DIP1-P1 保留但标注暂不实施）；③ 新增客户端 cst-app，原 Out of Scope → In Scope；④ 工作量从 85 → 105 人天（-12 飞书 +32 RN 双端 + 移动基建）；⑤ 4 阶段路线图重排（A 基建 / B 后端 / C 前端三端 / D 集成部署）；⑥ 跟踪矩阵重写。对齐 ADR-002/006/007/008。

一、你是谁？要做什么？（DIP1 Code Agent 角色定义）

你是一名高级全栈工程师（DIP1 Code Agent），独立承接「织布鸟 WEAVELY 香港配送+安装平台」技术子项目 DIP1 的代码实施工作：

维度 你的权责（对齐 PJM RACI 的 R=执行者）
技术范围 阶段 2（一线操作系统 + 全干系方平台）全栈实施：
① 后端 DDD 4 层（6 子域：QSV/CPT/MDS/OPS/DSP/PAY）+ 65 端点 REST API + 推送服务 + 移动端认证
② 前端三端：opr-admin（Next.js Web 运营后台 15 页）+ wkr-app（React Native 师傅端 8+ 页，iOS+Android）+ cst-app（React Native 客户端 8 页，iOS+Android）
③ 基础设施：CI/CD 8 Job + EAS Build + App Store/Google Play 提审 + OTA 热更新 + 推送（APNs+FCM）
工时预算 §A 环境基建：9 人天 · §B 后端业务：49 人天 · §C 前端三端：42 人天（opr-admin 15 + wkr-app 15 + cst-app 12） · §D 集成与部署：5 人天 · 合计：105 人天（实际日历工期约 3-4 个月，含测试与 UAT）
跳过范围 阶段 1 飞书对接（DIP1-P1 文档）暂不实施——阶段 0 飞书方案（MVP-FS）实际运行后再启动；Code Agent 跳过该文档直接进入阶段 2
交付物 dip1/ 目录下完整可运行代码 + 测试报告 + 覆盖率 + CI 全绿截图 + 文档 10 份（V2.0 已交付，版本按需更新）
决策权 技术实现细节（选型/命名/模式）你 100% 决策。RN 框架细节如 Tamagui vs RN Paper 可自行微调（在 PR 中说明即可）。若与 §3 文档冲突或架构变更需提 PR，请在 PR 描述中写明「ADR-xxx 建议变更理由」，由 TL 审批
禁止决策权 报价系数、业务规则、RBAC 矩阵、品类枚举等业务内容（这些以 DIP1-SPEC §1.4 枚举定义为唯一真值，如需调整提交 DIP1-SPEC 变更 PR，BO 审批）
沟通机制 本指南无法解决的阻塞问题 → 用 Git Issue 模板（§八）assign TL；SPO 只看里程碑不看细节

二、Git 信息与协作规范（与 hk2026 项目共享同一 Git 仓库）

⚠ 重要：DIP1 代码与 hk2026 主项目文档位于同一 Git 仓库。DIP1 的代码与文档全部在 dip1/ 子目录内（代码 dip1/backend|frontend|scripts，文档 dip1/docs/，工作日志 dip1/docs/worklog/）。你不得修改 dip1/ 之外的任何文件（除非 TL 明确在 Issue 中指示）。

2.1 仓库元信息

项目 值（TL 将生产凭据填入 .env.production 后，以下地址直接可达）
Git Remote Name origin（hk2026 私有仓库，按 PJM §4.3.2 执行：主仓 hk2026 dev 分支 + hk2026-docs 公开仓；本 Git 信息已内置在主仓 .git/ 中，你无需 git init）
DIP1 工作基准分支 dev（PJM Git Flow Lite 策略：feature/ → dev → release/ → main）
DIP1 feature 分支规范 feature/dip1-p2-<scope>（Conventional Commits 前缀，scope 见下方分支清单）
DIP1 代码目录 dip1/（相对路径，禁止绝对路径硬编码）
DIP1 文档目录 dip1/docs/（与代码同目录，自包含；你可修改此目录下的 10 份自有文档版本）
DIP1 工作日志目录 dip1/docs/worklog/（Code Agent 自由写入，DWLG-YYYYMMDD-NN 编号；详见 §九）
DIP1 公共文档发布 发布/（由 PMG AI 特定行为 #1 或 #2 生成 PDF/HTML；代码暂不纳入发布范围，仅文档纳入 发布/）
PR 标题前缀（强制） dip1: · 如：dip1: wkr-app L6 原生相机拍照 + 离线缓存
Commit 规范 Conventional Commits：type(scope)!: subject（type=feat/fix/refactor/perf/test/chore/docs/ci；scope=qsv/cpt/mds/ops/dsp/infra/admin/wkr-app/cst-app/mobile-infra；! = breaking change，必须写 ADR）
PR 必填模板章节（模板见 dip1/.github/PULL_REQUEST_TEMPLATE.md MVP 占位）：
1. 关联需求（功能 ID：F-CST-001 等）
2. 实现方式摘要
3. 测试覆盖（单元 + 集成 + E2E 新增数量；RN 端 Detox 用例数）
4. 是否触发迁移：是/否，revision=000x
5. 对现有 API 兼容性：无兼容影响 / 兼容 / 破坏性（! 需 ADR）
6. 关联文档版本变更：如 DIP1-SPEC V2.0 → V2.1（若变更）
7. RN 端变更：是否影响原生模块（需 EAS Build 重建）/ 是否仅 JS Bundle（可 OTA 热更新）
Code Agent 禁止自动 Git 提交/Push ✅ 你只在本地 dip1/ 目录写代码，不得触发任何 git commit / git push / 同步（§4.3.2~4.3.6） 等写入远端的操作。Git 提交由 TL 审核后执行（对应 PJM 规则：AI 不得擅自 git 同步）

2.2 Git Flow Lite 里程碑分支（按 PJM §4.3 对齐，V2.0 调整）

main                     生产发布分支（TL 打 tag：dip1-v2.0.0）
  ↑
release/dip1-v2.0        发布候选分支（UAT 用，OL 跑 50 单 + FL 师傅 5 人内测 + CUS 客户 10 人内测）
  ↑
dev                      开发基准分支（DIP1 feature 合并目标）
  ↑
# V2.0 分支清单（移除 feature/dip1-p1-feishu-sdk；新增 RN/移动基建分支）
feature/dip1-p2-infra-bootstrap          # §A 环境基建（Docker+PG+Redis+Expo+EAS+pnpm workspace）
feature/dip1-p2-domain-qsv               # §B QSV 报价域
feature/dip1-p2-domain-cpt               # §B CPT 订单跟踪域
feature/dip1-p2-domain-mds               # §B MDS 主数据域
feature/dip1-p2-domain-ops               # §B OPS 运营域
feature/dip1-p2-domain-dsp-pay           # §B DSP 调度 + PAY 支付域
feature/dip1-p2-rbac-rls                 # §B RBAC 21 权限 + RLS 行级策略
feature/dip1-p2-mobile-auth-push         # §B 移动端认证（OTP/biometric/refresh 轮换）+ 推送服务
feature/dip1-p2-frontend-opr-admin       # §C 运营后台 Next.js Web（15 页）
feature/dip1-p2-frontend-wkr-rn          # §C 师傅端 React Native（8+ 页）
feature/dip1-p2-frontend-cst-rn          # §C 客户端 React Native（8 页）
feature/dip1-p2-mobile-infra             # §C/D 移动端基建（EAS Build + OTA + Sentry RN + 推送配置）
feature/dip1-p2-e2e-detox-playwright     # §D E2E（RN Detox + Web Playwright）

2.3 版本号 & 文档升级规则

  • 代码语义化版本：MAJOR.MINOR.PATCH（2.0.0 = 阶段 2 全栈交付 + 50 单 UAT 全绿 + App Store/Google Play 上架成功）
  • 文档版本：V主.次（V2.0 → V2.1 = 补充；V2 → V3 = 不兼容；每修改文档需：① 顶部版本号 +1 ② 底部增加修订记录行 ③ WLG DLG-xxx 增加工作日志 1 条 —— 文档 WLG 变更由 TL/听写助手执行，Code Agent 不负责，但你在 PR 中要明确标注建议的版本号）

三、DIP1 自有文档独立索引（共 10 份，无需参考 hk2026 主仓其他文档）

按阅读顺序 1 → 10。Code Agent 实施时，以下文档已足够。任何需要扩展的功能都必须在 PR 中写明对应文档的变更建议。

# 简称 相对路径（dip1/docs/ 内） 核心信息 对应本指南引用位置
1 DIP1 README（子项目入口） ../README.md 项目概述 · 技术栈 · 里程碑 · 目录结构 · 角色 RACI（DIP1 简化版，自包含）· 联系方式 §4 初始化
2 DIP1 DOC 目录索引 README.md DIP1 10 份文档关系图 + 阅读顺序（本 §3 同内容） §3
3 DIP1-ARC 架构设计（必读·V2.0） DIP1-ARC-架构设计.md 4 条设计原则 · C4 容器图 11 容器（Web+RN 双引擎）· 上下文映射 DDD · 部署拓扑（含 App Store/Google Play/Expo Updates）· 10 条 ADR（V2.0 重写 ADR-002 + 新增 ADR-006/007/008） · NFR 指标（含离线/推送/启动时间） §5 实施顺序架构决策
4 DIP1-P1 阶段 1 飞书对接（⏸ 暂不实施） DIP1-P1-MVP-FS飞书对接设计.md ⚠️ V1.1 标注「暂不实施」；阶段 0 飞书方案（MVP-FS）运行后再启动；Code Agent 跳过本文档 §5.0（仅说明跳过理由）
5 DIP1-P2 阶段 2 一线操作系统（V2.0） DIP1-P2-一线操作系统设计.md 6 子域模型代码级设计 · 65 端点 REST API（V2.0 新增 CST + 移动认证 + 推送） · 22 表 SQL · RBAC 21 权限矩阵 · RLS 行级策略 · 直接实施阶段 2（跳过阶段 1） §5.2 阶段 2 后端任务
6 DIP1-P3 技术基础设施（V1.1） DIP1-P3-技术基础设施.md 环境初始化（含 Expo/EAS CLI）· Git 策略 · GitHub Actions 8 Job CI · 测试金字塔（含 RN Detox）· 部署（含 App Store/Google Play/EAS Build）+ RPO/RTO · 三支柱可观测 8 阈值（含移动端 APM/崩溃率） §4 初始化 + §5.3 部署
7 DIP1-SPEC 需求规格说明书（V2.0） DIP1-SPEC-需求规格说明书.md 自包含角色/术语/枚举定义 · 213 功能点 GWT（V2.0 新增 F-CST-001~018 + F-MOB-001~007） · NFR 18 项（V2.0 新增离线/推送/启动时间/移动兼容）· 交付 Checklist 4 × 32 条（含 RN 验收） §6 验收硬指标
8 DIP1-PROTO 功能原型设计（V2.0） DIP1-PROTO-功能原型设计.md shadcn/ui 主题 Token · 运营后台 15 页 · 师傅端 RN 8+ 页（V2.0 重写为原生交互） · 客户端 RN 8 页（V2.0 新增） · 11 条核心业务流程 Mermaid（新增 P11 客户端询价→下单） §5.4 阶段 2 前端任务
9 DIP1-API OpenAPI 规格 YAML（V2.0） 代码版：../backend/openapi.yaml
文档版：DIP1-API-OpenAPI规格.yaml		 72 operationId（V2.0 新增 CST 15 + 移动认证/推送 5；飞书 webhook 标注⏸） · 9 组 tags · 130+ Schema 组件 · 错误码与枚举完全对齐 SPEC §1.4 & 附录 A §5.2 API 实现契约
10 DIP1-SCHEMA 数据库设计 + Alembic（V1.1） 文档版：DIP1-Schema数据库详细设计.md
脚本版：../backend/alembic/versions/0001_initial_schema.py + ../backend/alembic/versions/0002_cst_mobile_push.py		 ER Mermaid 22 表（V1.1 新增 4 表：cst_sessions/cst_push_preferences/mobile_push_tokens/push_delivery_logs）· 35 枚举（+5）· 7 条 RLS 策略（+2）· 2 个 Alembic 迁移脚本（0001 初始 + 0002 移动推送） §5.2.1 先跑迁移

四、环境初始化（0→1 可运行本地开发 12 步）

参考 dip1/README.md 详细版本；以下 12 步 Code Agent 必须按顺序，每步完成确认勾号，阻塞立即 TL 报。V2.0 新增 Expo/EAS/RN workspace 配置（步骤 7、8、9）。

□ 1. 工具链版本对齐（DIP1-P3 §1.1 硬版本，V2.0 新增 Expo/EAS）：
       Python 3.12.4 · Node 20.15 LTS · pnpm 9.5 · Docker 27.1.1 · PostgreSQL 16-client · Poetry/Pipx
       + V2.0 新增：Expo CLI 0.18.x · EAS CLI 13.x · watchman 4.9 · Xcode 15.4（iOS 构建，macOS）/ Android Studio Hedgehog（Android 构建）
□ 2. 拉取仓库 hk2026：git checkout dev（TL 已给你本地工作副本）；确认路径结构：
       ls dip1/ backend frontend scripts docs
       ls dip1/docs 10 份 md/yaml + worklog/
□ 3. cd dip1 && cp .env.example .env；填 5 组本地环境变量（见 §4.1，V2.0 新增 EXPO/EAS）
□ 4. 启动依赖：`docker compose up -d`（PG 5432 / Redis 6379 / Mailpit 1025 / Jaeger 4317）
□ 5. 后端 Python：
       cd backend && python -m venv .venv && .\.venv\Scripts\activate (Windows)
       pip install -r requirements.txt -r requirements-dev.txt
□ 6. 运行 Alembic 迁移（V2.0 含 0001 + 0002 两个 revision）：
       alembic upgrade head   → 必须 22 表 + 35 枚举 + 7 RLS 全部 OK
       alembic downgrade base → 必须全部回滚无错（含 0002 → 0001 → base）
       alembic upgrade head   → 再升级 1 次（CI Job migrate-check 三循环）
□ 7. 【V2.0 新增】Expo 账户与 EAS 配置：
       npm install -g expo-cli eas-cli
       expo login（TL 提供 DIP1 Expo 账户）
       cd frontend/apps/wkr-app && eas build:configure（生成 eas.json）
       cd frontend/apps/cst-app && eas build:configure
       验证 app.json 中 expo.slug / version / ios.bundleIdentifier / android.package 唯一
□ 8. 前端 Monorepo（pnpm workspace V2.0 含 3 apps）：
       cd frontend && pnpm install && pnpm build
       → 4 包全部 OK：@weavely/ui + opr-admin (Web) + wkr-app (RN) + cst-app (RN)
□ 9. 【V2.0 新增】启动 RN 开发服务（另开 2 个终端，需物理设备或模拟器）：
       Terminal D: cd frontend/apps/wkr-app && pnpm start（→ Expo DevTools，扫码启动 wkr-app）
       Terminal E: cd frontend/apps/cst-app && pnpm start（→ Expo DevTools，扫码启动 cst-app）
       首次启动会下载 Expo Go；如需原生模块（expo-camera/expo-notifications）测试，执行 `eas build -p ios --profile development` 构建开发版
□ 10. 启动三端开发服务（另开 3 个终端）：
       Terminal A: cd dip1/backend && uvicorn app.main:create_app --factory --reload --port 8000
       Terminal B: cd dip1/frontend/apps/opr-admin && pnpm dev（→ http://localhost:3000）
       Terminal C: （wkr-app / cst-app 使用步骤 9 的 Expo 终端）
□ 11. 运行自测：
       backend:  make ci-local  →  0 失败（ruff 0 mypy 0 pytest ≥80% migrate-check）
       frontend: pnpm lint && pnpm typecheck → 0 错
       RN:       cd frontend/apps/wkr-app && pnpm test（Jest）→ 0 失败
                 cd frontend/apps/cst-app && pnpm test → 0 失败
□ 12. 手动烟测：
       ✅ http://localhost:8000/docs → Swagger UI 能打开 /health 返回 status: OK
       ✅ http://localhost:3000 → opr-admin 登录页（预留 SSO/账号登录）
       ✅ wkr-app 在 Expo Go 中启动 → 今日单 Tab 显示（mock 数据）
       ✅ cst-app 在 Expo Go 中启动 → 首页品类入口显示（mock 数据）

4.1 .env 本地产前填充（Code Agent 用开发默认值即可；生产凭据由 TL 填入 .env.production 后单独保存，禁止进入 git）

# APP
APP_ENV=development
APP_VERSION=2.0.0
APP_SECRET_KEY=dev_only_insecure_key_xxxxxxxxxxxxxxxx
CORS_ORIGINS=["http://localhost:3000","http://localhost:3001"]

# POSTGRES（docker-compose.yml 定义）
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=dip1
POSTGRES_PASSWORD=dip1pass
POSTGRES_DB=dip1_dev

# REDIS
REDIS_URL=redis://localhost:6379/0

# CLOUDFLARE R2（MVP 本地可走 LocalStack 占位；阶段 2 结束前 TL 给真实凭据）
R2_ENDPOINT_URL=http://localhost:4566
R2_BUCKET=weavely-hk-dev
R2_ACCESS_KEY_ID=test
R2_SECRET_ACCESS_KEY=test

# 【V2.0 新增】EXPO / EAS（TL 提供 DIP1 Expo 账户）
EXPO_USERNAME=weavely-dip1
EXPO_PROJECT_ID_WKR=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
EXPO_PROJECT_ID_CST=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy
EAS_PROJECT_ACCOUNT=weavely-dip1

# 【V2.0 新增】推送服务（APNs + FCM via Expo）
EXPO_PUSH_AUTH_TOKEN=ExponentPushToken_dev_only_xxxxxxxxxxxxx
# 生产环境由 EAS 自动注入 Expo push 凭据；开发环境用 ExpoPushToken[xxx] 格式即可测试

# 【V2.0 新增】移动端认证
JWT_ACCESS_TTL_SECONDS=900
JWT_REFRESH_TTL_SECONDS=2592000
OTP_TTL_SECONDS=300
OTP_RATE_LIMIT_PER_HOUR=5
BIOMETRIC_REQUIRED=false

# 飞书（⏸ V2.0 暂不实施，TL 保留占位，未来阶段 0 启动时填）
# FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
# FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# ALERT（飞书机器人）
FEISHU_ALERT_WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxx

.gitignore 已排除（dip1/.env / dip1/.env.* 除了 .env.example）。

五、实施顺序路线图（V2.0：105 人天分 4 阶段，跳过阶段 1 飞书）

各阶段 有严格依赖顺序，Code Agent 必须按 §5.0 → §A → §B → §C → §D 顺序执行；不可先写业务代码（QSV recalculate）而未写 Alembic 迁移。

V2.0 重大变更：移除原 §1 飞书对接 12 人天（阶段 0 飞书方案运行后再启动），工作量从 85 → 105 人天（-12 飞书 +32 RN 双端 + 移动基建 5）。

gantt
    title DIP1 V2.0 实施甘特图（105 人天 · 4 阶段 · 跳过阶段 1 飞书）
    dateFormat  YYYY-MM-DD
    axisFormat  %m/%d
    section §A 环境基建（9 人天）
    A.1 环境初始化 12 步烟测                  :crit, a01, 2026-08-10, 1d
    A.2 Alembic 0001+0002 三循环 + 数据 seed  :crit, a02, after a01, 1d
    A.3 JWT 登录 + 移动端认证 (OTP/biometric/refresh) + RLS SET app.* :a03, after a02, 2d
    A.4 健康探针 + OTel Jaeger + Prom metrics + Sentry（含 RN SDK） :a04, after a03, 1d
    A.5 审计日志中间件（任何 write 自动留痕）   :a05, after a04, 1d
    A.6 Testcontainers 集成测试基类 + RN Jest 基类 :a06, after a05, 1d
    A.7 GitHub Actions 8 Job 本地 act 验证（含 EAS Build Job） :a07, after a06, 1d
    A.8 Expo/EAS 工程配置（eas.json/app.json 双端） :a08, after a07, 1d

    section §B 后端业务 6 子域 + 移动认证 + 推送（49 人天）
    B.1 QSV 报价域（F-QSV-001~018）+ 校准报告 Job  :crit, b01, after a08, 6d
    B.2 CPT 订单跟踪（64 功能点 8 阶段 + L6/L7/L8 3 数据表）:b02, after b01, 14d
    B.3 MDS 四库 + TSMM 标签（37 功能点 + 搜索 + 批量导入导出）:b03, after b02, 9d
    B.4 OPS 线索 + 推荐 + WOM 口碑 + 奖励（22） :b04, after b03, 6d
    B.5 DSP 派单推荐 Top3 + 负载看板 + 请假（6） :b05, after b04, 3d
    B.6 系统管理 RBAC 21 权限 + 角色/用户 + RLS 策略 + 审计查询（14）:b06, after b05, 5d
    B.7 【V2.0 新增】移动端认证（OTP/biometric/refresh 轮换/设备管理）+ 推送服务（Expo Notifications）+ CST 客户端服务 13 端点 :crit, b07, after b06, 4d
    B.8 集成测试（每域 ≥15 条）+ 越权 126 用例（21×6）+ Benchmark QSV P95<30ms + 推送送达测试 :b08, after b07, 2d

    section §C 前端三端（42 人天 · Web 15 + RN 双端 27）
    C.1 @weavely/ui 共享库（Table/KanbanCard/Timeline/StageBadge/Uploader/RBACDirective 12 组件 · V2.0 兼容 Web+RN） :crit, c01, after b08, 4d
    C.2 opr-admin 登录 + 侧栏 + DASH 2 页（Next.js 14，保留） :c02, after c01, 3d
    C.3 opr-admin OPS-01/02（线索池 Tab + 口碑推荐）:c03, after c02, 3d
    C.4 opr-admin CPT 看板 + 列表 + 订单详情（复杂 8 Tab + 侧边时间线）:c04, after c03, 4d
    C.5 opr-admin QSV 计算器 + 参数管理 2 页 :c05, after c04, 2d
    C.6 opr-admin MDS 四库（4 列表 + 画像详情 + 技能雷达）:c06, after c05, 2d
    C.7 opr-admin SYS-01/02（RBAC + 审计 + 推送服务状态）:c07, after c06, 1d
    C.8 【V2.0 重写】wkr-app React Native 8+ 页（Auth/Today/MyOrders/Profile/OrderDetail/L6SixS/L6Photos/L7Sign）+ 原生相机/推送/离线缓存/生物识别 :crit, c08, after c07, 10d
    C.9 【V2.0 新增】cst-app React Native 8 页（Auth/Home/Orders/Referral/Profile/Inquiry/OrderTrack/Review）+ WhatsApp OTP + 系统分享 :c09, after c08, 8d
    C.10 移动端基建（EAS Build 配置 + Sentry RN + 推送权限请求 + OTA 通道） :c10, after c09, 4d
    C.11 E2E：Playwright（opr-admin 11 屏基线）+ Detox（wkr-app + cst-app 各 1 条 L1→L8 主流程） :c11, after c10, 1d

    section §D 集成与部署（5 人天）
    D.1 性能压测：NFR-01~03 + 移动端启动时间 + 推送送达率（k6 + Detox 性能模式） :d01, after c11, 1d
    D.2 EAS Build 云端构建 iOS+Android 双端（wkr-app + cst-app） :crit, d02, after d01, 1d
    D.3 App Store Connect + Google Play Console 提审资料准备 + 提交审核 :d03, after d02, 1d
    D.4 香港双 AZ 后端部署（ECS + RDS PG + R2 + Cloudflare Pages）+ 蓝绿 :d04, after d03, 1d
    D.5 备份恢复演练（RPO<5min RTO<30min）+ 生产发布 v2.0.0 tag :d05, after d04, 1d

5.0 §A 环境 & 基建 & 基线细节（9 人天）

Code Agent 进入任何子域前必须全部完成。

  • §A.1：完成本指南 §4 的 12 步。
  • §A.2：alembic upgrade head 后（含 0001 + 0002），用 pg_dump -s dip1_dev 导出 Schema 与 DIP1-SCHEMA 文档的表清单 22 张进行逐项对比（SQL vs YAML Schema 字段数、类型、非空一致），写一份 alembic-vs-schema-audit.md 放在 dip1/docs/（本地 Code Agent 工作区，git ignore 但要在 PR 附件中提供这份审计）。
  • §A.3：实现 FastAPI Depends get_current_user_with_scopes(required_permission: str)（抛出 401/403 1001/1002；调用 SET app.current_role/SET app.worker_id/SET app.current_customer_id 绑定 RLS）。V2.0 新增：移动端 OTP 登录端点（/auth/otp-send + /auth/otp-verify）、生物识别绑定端点、refresh token 轮换逻辑（旧 refresh 用一次即吊销，签发新 access+refresh 对）。
  • §A.8：Expo 工程配置（V2.0 新增）：
  • frontend/apps/wkr-app/app.json：slug=wkr-app、ios.bundleIdentifier=hk.weavely.wkr、android.package=hk.weavely.wkr
  • frontend/apps/cst-app/app.json：slug=cst-app、ios.bundleIdentifier=hk.weavely.cst、android.package=hk.weavely.cst
  • eas.json（双端各一份）：3 profile（development / preview / production）；production 走 EAS Submit（App Store Connect API Key + Google Play Service Account JSON，TL 提供凭据）
  • 验证 eas build --profile development -p ios 本地能拉起（即使最终云端构建，本地配置必须先 OK）
  • §A.7：用 nektos/act 本地跑 GitHub Actions Workflow（dip1/.github/workflows/ci.yml MVP 占位），确保 8 Job 全绿（含新增的 eas-build Job 占位）。

5.1 §1 飞书对接（⏸ V2.0 暂不实施，0 人天）

Code Agent 跳过本节。阶段 0 飞书方案（MVP-FS，已在运营团队运行）后续运行情况待观察，再决定是否启动 DIP1-P1 飞书对接层。决策依据见 ADR-008。

若 TL 在未来 Issue 中指示启动飞书对接，参考 DIP1-P1 V1.1 文档。

5.2 §B 后端 6 子域 + 移动认证 + 推送（49 人天）

顺序硬依赖：QSV → CPT → MDS → OPS → DSP → 系统管理 → 移动认证/推送/CST 服务。

子域实现 5 步法（每域必须按此 5 步，否则 PR 被驳回）： 1. DDD 四层骨架（domain/entities + domain/value_objects + domain/repositories → application/services + application/dto → infrastructure/db/models → interfaces/api/router + tests） 2. 先写测试：功能 ID（F-QSV-001 等）对应 Given/When/Then（Spec §3）→ pytest 先写红 3. 实现绿：领域逻辑必须全部通过 domain_events（如 OrderCompleted 事件 → 4 条数据闭环 Job） 4. 契约对齐：API 路由与 OpenAPI YAML 第 9 份 100% 一致（用 schemathesis 对接口随机 fuzz，1000 条样本零错） 5. RLS + RBAC 越权用例：每写一个接口，必须 +21×6=126 条矩阵权限越权测试（未命中的角色/权限必须 403）；V2.0 新增：CST 客户端接口额外 +1 组（CUS 角色，对应 cst_sessions RLS 策略只看自己）

重点交付要求： - QSV recalculate 单测：pytest parametrize ≥ 32 用例（覆盖 8 品类 × 封顶/未封顶/旺季/折扣 >15% BO 审批路径）。 - CPT 8 阶段流转：状态机（FSM transitions library 或 Pydantic Literal 手动 if 链均可，但必须返回 3001 冲突码且每步校验字段齐全）。 - CPT OrderCompleted 事件：发布后必须触发 4 条 Job（Spec P10 Mermaid）；每个 Job 用 Testcontainers 的集成测试验证写入正确： - Job 1 QMD：category_avg_hours 更新 - Job 2 WPL：avg_nps 重算（≥5 单才更新） - Job 3 CPL：打 HIGH_RECOMMEND_CANDIDATE / LOW_NPS_RISK 标签 - Job 4 OPS：奖励自动生成 + WOM 候选入池 - V2.0 新增 B.7 移动端认证 + 推送 + CST 服务（4 人天）： - 移动端认证：/auth/otp-send 发 WhatsApp OTP（OTP 6 位 + 5 分钟 TTL + 5 次/小时限流）；/auth/otp-verify 验证后签发 access（15 分钟）+ refresh（30 天）token 对；refresh 轮换（每次刷新签发新 refresh，旧 refresh 写入 cst_sessions.revoked_at）；生物识别绑定（biometric_binding JSONB 存公钥，验证时对比） - 推送服务：/push/register 注册 ExpoPushToken（双端共用，区分 WKR/CST + iOS/Android）；POST /push/send（仅系统内部调用，触发 L1→L8 各阶段推送：PUSH_NEW_ORDER/PUSH_ORDER_REMINDER_1H/PUSH_WORKER_DEPARTED/PUSH_REVIEW_INVITE/PUSH_REFERRAL_REWARD/PUSH_QUOTE_READY 等 8 类）；写入 push_delivery_logs 表跟踪送达/点击 - CST 客户端服务（13 端点，对齐 F-CST-001~018）：询价（自动生成 ORD + L1→L2 流转）、报价预览（调 QSV 计算）、客户确认报价（触发 L3→L4）、订单 Timeline（L1-L8）、师傅信息展示（脱敏）、L8 评价（NPS+5星+文字+照片）、推荐码生成与分享、推荐关系自动识别（深链 referrer_id）、推荐奖励记录、个人档案、推送偏好、离线模式（AsyncStorage 缓存） - CST 服务安全：所有 CST 端点必须 RLS（CUS 只能看自己的订单/档案/评价）；询价表单上传照片 ≤ 9 张，单张 ≤ 10MB，R2 存储路径 cst-inquiries/{customer_id}/{inquiry_id}/{timestamp}-{n}.jpg

5.3 §D 部署与可观测（P3 §4 §5 §6，V2.0 含移动端）

  • 香港部署双 AZ（TL 提供阿里云 ECS + RDS PG）；你要保证 Dockerfile + docker-compose 生产 profile 正确。
  • RPO 5 分钟（PG WAL-E 归档到 R2）、RTO 30 分钟；编写 scripts/migration/pg_restore_disaster_replay.sh，在开发环境 模拟删库 1 次并恢复（录屏或截图提交 PR）。
  • 8 飞书告警（P3 §6.2）：模拟触发至少 1 次（curl -X POST 5xx 或 pytest 注入错误），确保机器人消息到达（MVP 期间可手动发测试消息留截图）。
  • V2.0 新增移动端部署：
  • EAS Build：云端构建 iOS（需 TL 提供 Apple Developer 账号 + App Store Connect API Key）+ Android（需 TL 提供 Google Play Service Account JSON）；本地不构建（避免 Xcode/Android Studio 环境依赖）
  • EAS Submit：自动提审到 App Store Connect + Google Play Console；审核被拒时记录到 DWLG（CROSS 类型 Issue 给 TL）
  • OTA 热更新（Expo Updates）：JS Bundle 变更走 OTA（无需重新提审）；原生模块变更（如新增 expo-camera 版本）必须 EAS Build 重新构建。在 eas.json 中配置 updates.url 指向 Expo Updates 服务
  • Sentry RN SDK：wkr-app + cst-app 集成 @sentry/react-native，崩溃上报到与后端同一个 Sentry 项目（区分 platform 字段）；崩溃率监控阈值 ≤ 0.5%（NFR V2.0 新增）

5.4 §C 前端三端（42 人天，V2.0 Web 15 + RN 双端 27）

5.4.1 opr-admin Web（15 人天，Next.js 14 保留）

  • UI 设计 100% 按 DIP1-PROTO §1 色板 Token；禁止自定义色值。
  • 页面数：运营后台 15 页（§3 导航清单）；E2E Playwright 录屏每个导航 1 次 + L1→L8 全流程 1 条（录屏提交 PR）。
  • RBAC 指令：<RBACDirective permission="qsv:params:edit"> 前端控制显隐；后端同时 403 双保险。
  • V2.0 微调：SYS-02 页面将"飞书同步状态"区块替换为"推送服务状态"（8 类推送 24h 送达率 + 失败重试队列）。

5.4.2 wkr-app React Native 师傅端（10 人天，V2.0 从 PWA 重写为原生）

  • 技术栈：React Native 0.74 + Expo SDK 51（managed workflow）+ React Navigation v6 + NativeWind v4 + Zustand + TanStack Query
  • 页面：8+ 页（Auth/Login/BiometricSetup + Today/MyOrders/Profile + OrderDetail/L6SixS/L6Photos/L7Sign），路由结构见 DIP1-PROTO §4.1
  • 原生能力（必须实现，否则验收不通过）：
  • expo-camera：L6 三类照片（进场/施工中/完工）原生相机拍照，禁止从相册选（保证真实性）
  • expo-image-picker：附加照片可从相册多选（≤ 9 张）
  • expo-notifications：8 类推送接收 + 点击跳转对应订单详情
  • AsyncStorage + NetInfo：L6 拍照离线缓存 ≥ 24h，弱网/无网时照片暂存本地队列，网络恢复后自动上传
  • expo-secure-store：JWT refresh token + biometric 公钥安全存储
  • expo-local-authentication：Face ID / Touch ID 生物识别登录
  • react-native-maps + Linking：订单地址展示地图预览 + 一键调起 Apple Maps / Google Maps 导航
  • UI/UX：6S 勾选改为大卡片原生动画（每个 S 一个卡片，勾选有 spring 反馈）；L7 签字用 react-native-signature-canvas 原生签字板
  • 测试：Jest 单测覆盖关键 hooks（useAuth/useOfflineQueue/usePushRouting）；Detox E2E 至少 1 条 L4→L6→L7→L8 主流程

5.4.3 cst-app React Native 客户端（8 人天，V2.0 新增）

  • 技术栈：与 wkr-app 一致（RN + Expo + React Navigation + NativeWind）
  • 页面：8 页（Splash/OtpSend/OtpVerify + Home/Orders/Referral/Profile + InquiryForm/QuotePreview/OrderTrack/ReviewModal），路由结构见 DIP1-PROTO §5.1
  • 核心功能：
  • WhatsApp OTP 登录：与 wkr-app 账密登录不同，客户端用 WhatsApp OTP（香港客户 WhatsApp 渗透率高）
  • 询价表单：品类选择 + 尺寸输入 + 地址联想（BPL pg_trgm 2 字符 autocomplete）+ 期望时段 + 现场条件 + 门框照片 ≤ 9 张（expo-image-picker）
  • 报价预览：调 QSV 自动计算 8 因子 + 封顶价保护，展示明细但不自动确认
  • 订单 Timeline：L1-L8 8 阶段进度条 + 当前阶段高亮 + 师傅信息卡片（脱敏，仅显示等级/技能徽章/NPS）
  • L8 评价：NPS 0-10 滑块 + 5 星评分 + 文字（≤ 500 字）+ 可选照片；触发 OrderCompleted 4 链路数据闭环
  • 推荐有礼：生成推荐码（CUS-ULID 后 6 位）+ 系统分享（expo-sharing：WhatsApp/微信/复制链接）；推荐关系通过深链自动绑定
  • 离线模式：AsyncStorage 缓存最近 20 条订单；询价/下单等写操作暂存队列
  • 测试：Jest 单测 + Detox E2E 至少 1 条 询价→报价→下单→L8 评价主流程

5.4.4 移动端基建（4 人天，C.10）

  • EAS Build 配置：eas.json 3 profile（development / preview / production）；双端各自独立 build profile
  • Sentry RN：@sentry/react-native 初始化 + 错误边界 + 性能监控（启动时间 / 屏幕 FPS）
  • 推送权限请求：首次启动弹出 iOS 授权弹窗（expo-notifications Android 自动授权）；用户拒绝后引导到设置页
  • OTA 通道：expo-updates 配置；JS Bundle 变更自动检查更新（启动时 + 每 30 分钟一次）；原生模块变更需重新 EAS Build

六、3 级交付验收 Checklist（100% 通过才算 DIP1 Done）

6.1 一级：Code Agent 自测（你必须本地全绿）

文档层 4 项
  □ 1-1 213 功能点 × GWT 至少 1 条自动化/手工用例映射表（tests/gwt_mapping.csv）
  □ 1-2 OpenAPI 实现与 YAML 100% 对齐（schemathesis 1000 samples PASS，72 operationId）
  □ 1-3 migra 0001+0002 ↔ SCHEMA 文档 22 表字段类型完全一致（§0.2 审计报告）
  □ 1-4 原型页 × 实现页 100% 页面数 + 导航数一致（E2E 菜单遍历脚本 PASS，含 RN 双端）

代码层 9 项（V2.0 新增 RN 相关）
  □ 2-1 make ci-local 零失败（ruff + mypy 0 错）
  □ 2-2 领域+应用层覆盖率报告 ≥ 80%（Codecov XML 报告提交 PR）
  □ 2-3 Testcontainers 集成测试总数 ≥ 7×15 = 105 条（含 CST/推送/移动认证）
  □ 2-4 RBAC 越权测试 126 + 18 条（CUS CST 端 RLS）= 144 条 100% 通过
  □ 2-5 Dockerfile + docker-compose 空仓库从零启动成功（git clean 后重复 §4 12 步）
  □ 2-6 `make dev` 三端并行：3000（opr-admin）/ 8000（backend）/ Expo Go（wkr+cst）同时健康
  □ 2-7 Idempotency 测试：重复 POST 报价 10 次 → 只生成 1 条 DRAFT
  □ 2-8 【V2.0 新增】RN Jest 单测：wkr-app + cst-app 关键 hooks 覆盖率 ≥ 70%
  □ 2-9 【V2.0 新增】推送送达测试：本地 ExpoPushToken 收到 8 类推送各 1 次

部署&数据层 6 项（V2.0 新增移动端部署）
  □ 3-1 MVP-FS → PG 迁移脚本（scripts/migration/mvpfs_to_pg.py）跑 50 单历史数据：一致性 ≥ 99.99%（若 TL 决定启动飞书对接，否则跳过）
  □ 3-2 Prometheus metrics 4 组（HTTP/QSV/DB/推送）可抓取
  □ 3-3 飞书告警机器人 8 阈值 × 1 次模拟触发 100% 成功
  □ 3-4 DB 备份+恢复演练脚本执行成功（RPO<5min，RTO<30min）
  □ 3-5 【V2.0 新增】EAS Build 云端构建 wkr-app + cst-app 各 iOS+Android 双端成功（4 个 build artifact）
  □ 3-6 【V2.0 新增】OTA 热更新演练：发布 v2.0.1 JS Bundle → App 自动检测并热更新（不重新安装）

6.2 二级：TL 功能验收（司徒总按 DIP1-SPEC §3 逐条执行）

  □ 4-1 F-QSV-001~018 全部跑通（报价/参数/校准）· 覆盖率 100%
  □ 4-2 F-CPT-001~064 L1→L8 8 阶段 50 条完整订单（无阻塞/无 5xx）
  □ 4-3 F-MDS-001~037 + TSMM 标签打标/查询/批量
  □ 4-4 F-OPS-001~022 线索/推荐/奖励/WOM 素材
  □ 4-5 F-DSP-001~006 Top3 推荐（手动构造 3 个师傅匹配场景）
  □ 4-6 F-SYS-001~014 6 角色权限 × 21 条开关
  □ 4-7 F-INF-001~013 健康/DLQ/备份/可观测
  □ 4-8 【V2.0 新增】F-CST-001~018 客户端 18 功能点全跑通（WhatsApp OTP / 询价 / 报价 / 下单 / Timeline / 评价 / 推荐 / 离线）
  □ 4-9 【V2.0 新增】F-MOB-001~007 移动端 7 功能点全跑通（OTP / 生物识别 / 推送 / 相机 / 离线 / OTA / 崩溃监控）
  □ 4-10 性能压测：NFR-01~03 + 移动端启动时间（冷启 ≤ 2s 热启 ≤ 0.5s）+ 推送送达率 ≥ 95%（k6 + Detox 性能模式报告）

6.3 三级：OL/FL/CUS UAT（成文/黄双人 + 5 位师傅 + 10 位客户真单 8 阶段全流程）

  □ 5-1 50 单 8 阶段全流程 OL 主观阻塞点 = 0
  □ 5-2 飞书旧数据 50 单与新 PG 对照一致性 ≥ 99.99%（若启动飞书对接，否则跳过）
  □ 5-3 【V2.0 调整】FL 师傅 wkr-app RN 8+ 页在真实 iPhone SE + Android 低端机（红米 Note）运行无卡顿/上传失败/崩溃
  □ 5-4 运营后台 1080p/1440p/1920p 三分辨率零横向滚动
  □ 5-5 备份后随机删 1 条订单 + 恢复演练成功（RPO/RTO 验证）
  □ 5-6 客户敏感信息 PDPO 脱敏：默认显示 9123****，TL 切 `mds:pii:view_full` 权限可见完整
  □ 5-7 【V2.0 新增】CUS 客户 cst-app RN 8 页在真实 iPhone SE + Android 低端机运行：WhatsApp OTP 登录 → 询价 → 报价预览 → 下单 → Timeline 跟踪 → L8 评价 → 推荐分享全流程 0 阻塞
  □ 5-8 【V2.0 新增】App Store + Google Play 双端审核通过并上架（TL 提交，OL/FL/CUS 各角色至少 1 人 TestFlight / 内部测试轨道 7 天无 Critical 崩溃）
  □ 5-9 【V2.0 新增】推送送达率 UAT：50 单 L1-L8 各阶段推送实际送达率 ≥ 95%（按 `push_delivery_logs` 表统计）
  □ 5-10 【V2.0 新增】离线模式 UAT：师傅端 L6 拍照在无网环境拍 3 张 → 网络恢复后自动上传成功；客户端在无网环境浏览历史订单 → 网络恢复自动同步

七、DIP1 状态追踪（供 SPO/BO/TL 直接评估子项目状态，无需深入代码）

任何干系人（SPO/BO/TL）无需阅读 hk2026 主仓的 PJM/WLG/TND-E 等任何文档；直接看本 §7 三张表的 3 项红黄绿状态即可。

7.1 DIP1 交付物状态跟踪矩阵（SPO/BO/TL 唯一真值跟踪视图 · V2.0 重写）

组 交付物 负责人 验收标准 状态 🔴🟡🟢 证据链接/路径 完成度
文档 10 份（V2.0 已交付：🟢）
D-01 子项目 README DT+TL 角色/里程碑/目录清晰 🟢 V2.0 完成 dip1/README.md 100%
D-02 DOC 索引 README DT+TL 10 份文档关系图正确 🟢 V1.3 dip1/docs/README.md 100%
D-03 ARC 架构 DT+TL 10 ADR / NFR 量化（含 RN/离线/推送） 🟢 V2.0 DIP1-ARC V2.0 100%
D-04 P1 飞书对接设计 DT+TL ⏸ V1.1 标注暂不实施 🟢 V1.1（跳过） DIP1-P1 V1.1 100%
D-05 P2 一线操作系统设计 DT+TL 6 子域 / 65 端点 / 直接阶段 2 🟢 V2.0 DIP1-P2 V2.0 100%
D-06 P3 技术基础设施 DT+TL 8 CI Job / RPO RTO / EAS Build / Detox 🟢 V1.1 DIP1-P3 V1.1 100%
D-07 SPEC 需求规格 213 功能 DT+TL 枚举/GWT/NFR 自包含（含 CST/MOB） 🟢 V2.0 DIP1-SPEC V2.0 100%
D-08 PROTO 原型 15+8+8 页 DT+TL 色板 Token / 导航矩阵 / RN 原生交互 🟢 V2.0 DIP1-PROTO V2.0 100%
D-09 API OpenAPI 3.0 YAML DT+TL 72 operation / 130+ Schema / CST+推送 🟢 V2.0 openapi.yaml V2.0 100%
D-10 SCHEMA DB 设计 + Alembic V1.1 DT+TL 22 表 / 35 枚举 / 7 RLS / 0001+0002 迁移 🟢 V1.1 0001 + 0002 脚本 100%
代码 105 人天（Code Agent 实施中）
C-A0 §A 环境 9 项基线 Code Agent / TL 本指南 §4 12 步 + A.1-A.8 任务全绿 🟡 待执行 dip1/Makefile ci-local target 0%
C-B1 §B QSV 报价域（6 人天） Code Agent / TL recalculate P95 < 30ms，32 用例全绿 🟡 待执行 QSV 集成测试报告 0%
C-B2 §B CPT 跟踪（14 人天） Code Agent / TL L1→L8 状态机 0 越权，4 条反哺 Job 正确写库 🟡 待执行 0%
C-B3 §B MDS 四库（9 人天） Code Agent / TL 地址联想 2 字符响应 < 200ms / 批量打标 < 1s 🟡 待执行 0%
C-B4 §B OPS（6 人天） Code Agent / TL 奖励 ≥500 HKD BO 审批走通 🟡 待执行 0%
C-B5 §B DSP（3 人天） Code Agent / TL 同日同师傅 ≥ 2 单返回 3030 冲突 🟡 待执行 0%
C-B6 §B 系统管理（5 人天） Code Agent / TL 144 RBAC+RLS 越权测试 100% 通过 🟡 待执行 0%
C-B7 §B 移动认证+推送+CST（4 人天） Code Agent / TL OTP/refresh 轮换/8 类推送/CST 13 端点全通 🟡 待执行 0%
C-B8 §B 集成+压测（2 人天） Code Agent/TL k6 NFR-01~03 + 移动端启动 + 推送送达率 🟡 待执行 0%
C-C1 §C @weavely/ui（4 人天） Code Agent 12 共享组件 Web+RN 双引擎 Storybook 全 render OK 🟡 待执行 0%
C-C2 §C opr-admin Web 15 页（15 人天） Code Agent / OL 导航矩阵 100% 页可达；SYS-02 推送状态替换飞书状态 🟡 待执行 0%
C-C3 §C wkr-app RN 8+ 页（10 人天） Code Agent / FL 原生相机/推送/离线/生物识别/地图全通；6S 必须勾 6 项才能完工 🟡 待执行 0%
C-C4 §C cst-app RN 8 页（8 人天） Code Agent / CUS WhatsApp OTP/询价/报价/Timeline/L8 评价/推荐分享全通 🟡 待执行 0%
C-C5 §C 移动端基建（4 人天） Code Agent EAS Build 配置 + Sentry RN + 推送权限 + OTA 通道 🟡 待执行 0%
C-C6 §C E2E（1 人天） Code Agent Playwright 11 屏 + Detox 双端各 1 条主流程 🟡 待执行 0%
部署 & UAT 验收（TL / OL / FL / CUS 真实跑）
DPL-01 EAS Build 云端构建 4 端 TL wkr-app + cst-app 各 iOS+Android build artifact 4 份 🟡 0%
DPL-02 App Store + Google Play 提审 TL + 听写 双端审核通过并上架（含审核资料准备） 🟡 0%
DPL-03 后端生产部署（香港双 AZ + 蓝绿） TL ECS/RDS/R2 TL 凭据 + Cloudflare Pages 前端 🟡 0%
DPL-04 OL UAT 50 单 100% 通过 TL + OL L1→L8 完整零阻塞 🟡 0%
DPL-05 FL 师傅 5 人 wkr-app 内测 7 天 TL + FL 0 Critical 崩溃；推送送达率 ≥ 95% 🟡 0%
DPL-06 CUS 客户 10 人 cst-app 内测 7 天 TL + CUS 询价→下单→评价→推荐全流程 0 阻塞 🟡 0%
DPL-07 文档发布 PDF（AI 特定行为 #1） TL + 听写助手 10 份 DIP1 文档 → 合并 PDF 供评审 🟡 （TL 指令触发） 发布/ 0%
总完成度（加权：文档 10 份=10%；代码 105 人天=60%；部署+UAT=30%） 🟢 当前 10% 完成（文档 10/10 🟢 V2.0）；后续 Code Agent 代码推进 10%

7.2 里程碑红黄绿标准

  • 🟢 绿灯：所有前置任务完成 + 当前里程碑完成 ≥ 90% + 0 个 Critical 阻塞；TL 可推进下一阶段
  • 🟡 黄灯：当前里程碑 30-89% 完成，或存在 ≥1 Major 阻塞但有方案；SPO 知道风险即可，无需亲自介入
  • 🔴 红灯：当前里程碑 < 30% 或存在 Critical 阻塞 72 小时；必须在 SPO 每周一 10:00 项目例会专项汇报

7.3 DIP1 问题升级路径

Code Agent 遇到问题
    ↓（24h 内自行尝试 + Issue 描述 + 报错截图）
TL 介入（司徒总）→ 24h 内给答复
    ↓（技术问题 48h 未解决；或业务规则变更）
BO 介入（郭总）→ 业务规则/报价系数裁决
    ↓（架构变更 ADR 或预算影响）
SPO 裁决（曾总）→ 最终决策

八、反馈与阻塞问题 Git Issue 模板（SFM 通用版 · Code Agent 必须严格按此模板提交）

升级说明（V1.2）：原 §八 仅支持阻塞型 Issue，已升级为 PJM §4.4 SFM（子项目反馈机制）通用 Issue 模板。任何需要主项目介入的内容都必须用此模板，覆盖 5 类反馈（INFO/REQ/ESCAL/CROSS/RISK × 3 严重级别），并同步写入 DWLG 工作日志（§九 9.3 场景 4/5/6）。Issue + DWLG 双轨留痕缺一不可。

建议落地位置：dip1/.github/ISSUE_TEMPLATE/sfm-feedback.yml（TL 或听写助手配置 frontmatter 自动解析与打标签）。

---
# ====== 必填 Frontmatter（听写助手/自动化工具解析字段）======
subproject: dip1                    # 子项目标识：dip1 / dip2 / dip3
type: REQ                           # 反馈类型：INFO / REQ / ESCAL / CROSS / RISK
severity: Major                     # 严重级别：Critical / Major / Minor
milestone: C-B7                     # 关联 §7.1 矩阵代码组 ID：C-A0~C-C6 / D-01~D-10 / DPL-01~07
cross-project: none                 # 跨项目协作（CROSS 必填）：none / dip2 / dip1,dip3
expected-response: 48h              # 期望响应时间：4h / 24h / 48h / 72h / 7d
---

## DIP1 Issue：<一句话标题>
> 建议标题格式：`[dip1][REQ][C-B7] WhatsApp OTP 限流策略需 BO 确认`

### 背景与复现步骤
1. <step 1>
2. <step 2>
3. <step 3>

### 实际结果与期望结果
- 实际：<pytest 失败日志或 curl 返回 JSON；尽量附 Traceback>
- 期望：<引用本指南哪条文档或 SPEC 哪个 F-ID 应该的结果>

### 你尝试过的 3 种方案（**ESCAL / CROSS 必填 3 种**；INFO/RISK 可写 N/A）
1. <尝试 1 + 失败原因>
2. <尝试 2 + 失败原因>
3. <尝试 3 + 失败原因>

### 你建议的方向（如可行）
<如果有，请写；如果没有，留空 "待 TL 决策">

### 关联反馈型 DWLG 日志（**必须**，反馈双轨留痕）
> 同步提交的反馈型工作日志编号：`DWLG-YYYYMMDD-NN`
> 日志路径：`dip1/docs/worklog/YYYYMMDD_<主题>.md`

### 附件（ESCAL / Critical 必填）
- 报错截图或日志
- 相关 pytest -vv -s 输出
- （可选）小范围复现 Minimal Reproducible Example

标签自动应用规则（基于 frontmatter，听写助手或 TL 配置后自动）： - subproject:dip1 · type:req · severity:major · milestone:c-b7 - Critical 自动追加：priority:P0 + 飞书机器人 @mention TL（司徒总） - CROSS 自动追加：cross-project + @mention 对方子项目 TL

九、工作日志规范（Code Agent 必须执行，对齐主仓 WLG §三/§四）

完整规范见：worklog/README.md（DIP1-WLG V1.0） 对齐主仓：主仓 WLG §三 记录规范 + §四 整理要求

9.1 为什么需要工作日志？

DIP1 定位为独立子项目，但你（Code Agent）的开发过程必须可追溯：

维度 要求
过程可追溯 每个功能点的实现思路、遇到的问题、解决方案都要记录
决策有依据 技术选型/架构调整的理由须留痕，供 TL 审查与后续复盘
状态可评估 §7.1 矩阵的红黄绿变更须在日志中说明触发原因
越权防护 你仅在 dip1/docs/worklog/ 写日志，严禁修改主仓 docs/工作日志/（WLG）——后者由 TL/听写助手执行

9.2 记录编号与命名

  • DIP1 工作日志编号：DWLG-YYYYMMDD-NN
  • D = DIP1 子项目标识
  • YYYYMMDD = 日期
  • NN = 当日序号（01 开始）
  • 示例：DWLG-20260810-01（DIP1 当日第 1 条日志）
  • 文件命名：YYYYMMDD_主题.md，存放在 dip1/docs/worklog/
  • 同日多份：追加序号 20260810_01_xxx、20260810_02_xxx

9.3 记录时机（必须记录的 6 种场景）

# 场景 触发时机 记录内容
1 功能实现完成 每个功能 ID（F-xxx）代码 + 测试写完 实现思路 · 产出文件 · 测试覆盖率 · 关联 F-ID
2 PR 提交 PR 描述中附 DWLG 编号 PR 标题 · 变更摘要 · 测试新增数 · DWLG 编号
3 里程碑达成 §7.1 矩阵某项 🟡→🟢 里程碑 ID · 验收结果 · 矩阵状态变更
4 问题排查 Issue 提交后 24h 内 问题现象 · 根因分析 · 尝试方案 · 解决结果
5 技术决策 ADR 变更或架构调整 决策内容 · 理由 · 影响 · 关联 ADR-xxx
6 阻塞升级 §7.3 升级路径触发 阻塞描述 · 已尝试 · 升级到哪一级 · TL/BO/SPO 回复

9.4 记录模板（每次复制此模板填充）

# DIP1 工作日志 — <主题简述>

> **DWLG 编号**：DWLG-YYYYMMDD-NN
> **日期**：YYYY-MM-DD
> **参与方**：DIP1 Code Agent / TL
> **关联文档**：DIP1-0x（§y.z）
> **关联 Issue**：ISSUE-YYYYMMDD-NN（如有）

---

## 一、工作内容

<本次做了什么：功能实现 / Bug 修复 / 文档更新 / 测试验收>

## 二、产出物

| 类型 | 路径 | 说明 |
|------|------|------|
| 代码 | `dip1/backend/app/domain/qsv/xxx.py` | QSV 报价计算核心逻辑 |
| 测试 | `dip1/backend/tests/domain/test_xxx.py` | 单元测试 8 例，覆盖率 85% |
| 文档 | `dip1/docs/DIP1-0x.md` | §y.z 更新 |

## 三、关键决策（如有）

<技术选型/架构调整的理由>

## 四、问题与待办（如有）

| # | 问题 | 状态 | 负责人 | 截止 |
|---|------|------|--------|------|
| 1 | WhatsApp OTP 限流策略 | 🟡 已定位 | TL | YYYY-MM-DD |

## 五、状态矩阵更新（如有）

DIP1-IMP §7.1 矩阵变更：
- C-B7（移动认证+推送+CST）：🟡 → 🟢（100%，单测覆盖率 85%）

9.5 整理要求（对齐主仓 WLG §四）

  1. 及时性：每个开发节点完成后即时记录（当日完成当日记录，不跨日积压）
  2. 客观如实：记录须如实反映开发过程，问题与决策归属性清晰
  3. 涉密脱敏：涉及客户隐私、师傅信息、生产凭据的内容严禁记录（Token/密码/密钥/Apple Developer 账号等）
  4. 索引同步：新增记录后，即时更新 worklog/README.md §三 记录索引
  5. PR 关联：每条 DWLG 须关联对应的 PR 描述（由 TL 提交时附上 DWLG 编号）

9.6 TL 同步至主仓 WLG 的规则（扩展至 8 项 · 对齐 PJM §4.4.5）

你（Code Agent）不执行主仓 WLG 同步，仅在 dip1/docs/worklog/ 维护 DWLG 日志。TL 审核后按以下触发条件同步至主仓 WLG（DLG 编号）：

同步触发条件 主仓 WLG 编号 执行人
§A 环境基建（9 人天）完成 DLG-xx TL / 听写
§B 后端业务（49 人天）完成 DLG-xx TL / 听写
§C 前端三端（42 人天）完成 DLG-xx TL / 听写
App Store + Google Play 上架成功 DLG-xx TL / 听写
UAT 50 单 + FL 5 人 + CUS 10 人验收完成 DLG-xx TL / 听写
重大 Issue 升级（Critical 72h） DLG-xx TL
生产发布 V2.0 DLG-xx TL / 听写
周反馈简报（每周一 10:00） DLG-xx 听写（草稿）→ TL（审核）
Critical 升级闭环 DLG-xx TL（根因+决策+整改）

详细 SFM 反馈机制（5 类型 × 3 级别 / 7 状态双向确认 / 超时升级）见主仓 PJM §4.4。

十、反馈处理确认状态机执行细则（7 状态 · 双向确认 · 对齐 PJM §4.4.4）

本节是你（Code Agent）与 TL 之间的反馈双向确认契约。每个状态必须按要求评论动作 + 同步 DWLG，不得跳步、不得忽略超时。

10.1 状态流转图（Code Agent 必须熟记）

stateDiagram-v2
    [*] --> SUBMITTED : Code Agent 提交 Issue + DWLG
    SUBMITTED --> RECEIVED : TL 评论"已接收，预计 Xh 回复"（≤4h）
    RECEIVED --> IN_REVIEW : TL 评审中（可 @BO/@PO 咨询）
    IN_REVIEW --> DECIDED : TL/BO 给出可执行决策（≤24h）
    DECIDED --> IMPLEMENTED : Code Agent 评论"已实施，请验证"
    IMPLEMENTED --> CONFIRMED : TL 验证通过（≤24h）
    IMPLEMENTED --> IN_REVIEW : TL 验证不通过，退回（REOPENED）
    CONFIRMED --> CLOSED : 自动关闭
    CLOSED --> [*]

10.2 你的强制动作清单（逐状态）

状态 你（Code Agent）必须做 禁止 SLA
SUBMITTED ① 按 §八 frontmatter 模板严格填写 Issue ② 同步写 DWLG（§九 9.3 场景 4/5/6），DWLG 中引用 Issue #NN ③ 在 DWLG 中记录 状态：SUBMITTED → RECEIVED 漏填 frontmatter / 忘记同步 DWLG T0（提交时一次性）
RECEIVED → IN_REVIEW 观察期，无需主动动作。若 TL @你要求补充信息，4h 内回复具体证据 沉默不补充 被动等待
DECIDED ① 收到 TL 决策后 8h 内，Issue 评论：✅ 已理解，按 <X 方案简述> 执行 ② DWLG 追加「反馈处理记录」小节（见 worklog/README §六）：填入决策内容、决策时间、确认状态 ③ 若对决策有异议，不得自行拒绝，须在评论中写明理由 + 开 REQ 升 ESCAL（引用原 Issue） 8h 内不回复 / 质疑决策却不开 Issue T_DECISION + 8h
IMPLEMENTED ① 按决策实施完毕 + 所有自测通过（§6.1 一级 Checklist 相关项） ② Issue 评论：已实施，请验证。关联 DWLG：DWLG-YYYYMMDD-NN，关联 PR #XX ③ DWLG 更新状态：DECIDED → IMPLEMENTED，附实施结果摘要 未自测通过就说已实施 决策后合理工期
CONFIRMED / CLOSED ① 收到 TL "验证通过"评论后，DWLG 标记状态 CONFIRMED → CLOSED ② 若本反馈触发 §7.1 矩阵变更，更新矩阵状态 ③ 若 TL 24h 未验证，DWLG 标注"超时默认通过" 并推进状态到 CLOSED TL 未回复就认为通过 TL_VERIFY + 24h
REOPENED ① 收到 TL "验证不通过"评论后，DWLG 状态回退：IMPLEMENTED → IN_REVIEW ② 按 TL 退回意见修改，完成后回到 IMPLEMENTED 重走 ③ 若退回 ≥2 次，自动升 severity：Minor → Major → Critical 无视退回意见 被动响应

10.3 超时自动升级规则（Code Agent 自助执行）

若 TL 未按时响应，你不得空等，必须按以下规则自助升级（同步写入 DWLG）：

超时条件 你的自动动作
SUBMITTED → TL 4h 未接收（无"已接收"评论） Issue 评论：PJM §4.4.4 超时检测：TL 4h 未接收，请求人工介入 + DWLG 记录
IN_REVIEW → TL 24h 未决策 ① 自动把 frontmatter 注释 severity: Major → Critical（在 Issue 正文中写明，标签由 TL 手动更新）② Issue 评论：PJM §4.4.4 超时升级：24h 未决策，已升 Critical，请 BO 介入 ③ DWLG 同步记录状态变更
DECIDED → 你 8h 内未确认理解（你自己的 SLA，避免 TL 误判） 若你看到决策在 8h 内，立即评论"已理解"；若超过 8h 才看到，评论：抱歉延迟确认，已理解并执行
IMPLEMENTED → TL 24h 未验证 Issue 评论：PJM §4.4.4 超时默认通过：24h 未验证，按规则视为 CONFIRMED + DWLG 标注"超时默认通过" + 状态推进 CLOSED
REOPENED ≥ 2 次 severity 自动升一级（Minor→Major→Critical）+ Issue 评论：PJM §十 退回累计≥2次，severity 升级

10.4 越权防护红线（Feedback 版）

在 SFM 反馈与状态机流程中，你严禁以下行为（违反即触发 PJM §3.4.4 越权防护）：

# 禁止事项 理由
1 修改 docs/工作日志/ 下任何文件（含 DLG、WLG README） 主仓 WLG 写入权仅 TL/听写持有
2 关闭 / Reopen 任何 Issue（仅 TL 有权） 状态确认闭环必须由 TL 触发最终 CLOSED
3 擅自更改 Issue frontmatter 字段（尤其是 severity / type） 严重级别变更必须按 §10.3 规则；你仅可在正文中写明建议值
4 用非 Issue 渠道向 TL 提反馈（微信/邮件等） 反馈必须 100% 进入 Git + DWLG 双轨留痕
5 在跨子项目 CROSS Issue 中直接修改其他子项目 dip2/ / dip3/ 文件 PJM §4.5.4 禁止；提契约 PR 走 contracts/ 仓
6 severity=Critical 时不标记 @TL P0 请飞书机器人触发告警 确保 Critical 即时触达 TL（通道由 TL 维护）

修订记录

版本 日期 修订人 修订内容
V1.0 2026-08-09 DT 初始版本：Git 信息 · 85 人天甘特 · §7.1 状态跟踪矩阵 · 三级验收 Checklist · Issue 模板
V1.1 2026-08-09 DT 目录合并 + 工作日志接入：文档路径从 docs/技术文档/dip1/ 迁移至 dip1/docs/（代码目录内，自包含）；§2.1 新增「DIP1 工作日志目录」条目；§3 文档索引全部改为 dip1/docs/ 相对路径；§4 环境初始化路径同步；新增 §九 工作日志规范（DWLG-YYYYMMDD-NN 编号 · 6 种记录场景 · 记录模板 · TL 同步规则 · 对齐主仓 WLG §三/§四）
V1.2 2026-08-09 DT SFM 子项目反馈机制落地：版本号 V1.1→V1.2；§八 从"阻塞问题 Issue 模板"升级为 PJM §4.4 SFM 通用 Issue 模板（新增 Frontmatter 6 字段：subproject/type/severity/milestone/cross-project/expected-response，扩展支持 5 类型 × 3 严重级别 × 跨项目协作，DWLG 关联字段必填，ESCAL/CROSS 强制 3 种尝试方案，Critical 自动 P0 + 飞书告警，CROSS 自动跨子项目标签）；§九 9.6 TL 同步主仓 WLG 触发条件从 6 项扩展为 8 项（新增「周反馈简报」+「Critical 升级闭环」，对齐 PJM §4.4.5）；新增 §十 反馈处理确认状态机执行细则：10.1 stateDiagram 7 状态流转图 · 10.2 逐状态强制动作清单（SUBMITTED/RECEIVED→IN_REVIEW/DECIDED/IMPLEMENTED/CONFIRMED→CLOSED/REOPENED）+ 明确 SLA + 禁止项 · 10.3 5 条超时自动升级规则（TL 4h/24h未响应、Agent 8h未确认、TL 24h未验证、REOPENED≥2次 severity 升级）· 10.4 6 条 Feedback 版越权防护红线（禁改主仓WLG、禁开关Issue、禁改 severity、禁非Issue渠道反馈、禁跨子项目改文件、Critical 必标记告警）
V2.0 2026-08-09 DT 原生 App 方案升级重写（对齐 ADR-002/006/007/008）：① §一 角色定义：移除阶段 1 飞书对接范围，改为「直接阶段 2 全栈」；工时预算 85 → 105 人天（-12 飞书 +32 RN 双端 + 移动基建）；新增 cst-app 客户端 RN App；② §2.2 Git 分支：移除 feature/dip1-p1-feishu-sdk，新增 feature/dip1-p2-frontend-wkr-rn / feature/dip1-p2-frontend-cst-rn / feature/dip1-p2-mobile-auth-push / feature/dip1-p2-mobile-infra；Commit scope 新增 wkr-app/cst-app/mobile-infra；PR 模板新增第 7 项「RN 端变更」字段；③ §3 文档索引：10 份文档版本号全面同步至 V2.0/V1.1（ARC V2.0 / P1 V1.1 标注暂不实施 / P2 V2.0 / P3 V1.1 / SPEC V2.0 213 功能 / PROTO V2.0 15+8+8 页 / API V2.0 72 operationId / SCHEMA V1.1 22 表 + 0001+0002 迁移脚本）；④ §4 环境初始化：从 10 步扩展为 12 步（新增步骤 7 Expo/EAS 配置 + 步骤 9 RN 开发服务启动）；.env 新增 EXPO/EAS/推送/移动端认证 4 组变量；飞书变量注释为「⏸ 暂不实施」；⑤ §五 实施顺序路线图：从「85 人天 4 阶段含飞书」重写为「105 人天 4 阶段（A 基建/B 后端/C 前端三端/D 集成部署）跳过飞书」；甘特图重排（移除 §1 飞书 12 人天，新增 B.7 移动认证+推送+CST 4 人天 + C.3-C.6 RN 双端 + C.10 移动基建 + D.1-D.5 含 EAS Build/提审）；⑥ §5.2 新增 B.7 移动认证+推送+CST 服务实现要求（OTP/refresh 轮换/8 类推送/CST 13 端点 + RLS + R2 存储路径）；§5.3 部署新增 EAS Build + EAS Submit + OTA + Sentry RN；§5.4 前端从「27 人天双端」重写为「42 人天三端」（opr-admin Web 15 + wkr-app RN 10 + cst-app RN 8 + 移动基建 4 + E2E 1）；⑦ §6 验收 Checklist：一级代码层 7→9 项（新增 RN Jest + 推送送达测试）；部署层 4→6 项（新增 EAS Build + OTA 演练）；二级 TL 验收新增 F-CST/F-MOB 2 组功能点；三级 UAT 新增 FL wkr-app/CUS cst-app RN 测试 + App Store/Google Play 上架 + 推送送达率 + 离线模式 UAT；⑧ §7.1 跟踪矩阵：移除 C-01 飞书 12 人天；新增 C-B7 移动认证+推送+CST 4 人天 / C-C3 wkr-app RN 10 人天 / C-C4 cst-app RN 8 人天 / C-C5 移动基建 4 人天；部署项从 4 项扩展为 7 项（新增 EAS Build + App Store/Google Play 提审 + FL 5 人内测 + CUS 10 人内测）；文档组 10 份全部更新至 V2.0；⑨ §八 SFM Issue 模板：milestone 示例从 C-03 调整为 C-B7（反映新矩阵 ID）；⑩ §九 9.6 TL 同步 WLG 触发条件：从「阶段 1/2 后端/2 前端/UAT/发布」调整为「§A/§B/§C/App Store 上架/UAT 50 单+FL 5 人+CUS 10 人/发布 V2.0」；⑪ 修订记录新增 V2.0 行

本文件为 DIP1 Code Agent 实施指南（DOC-D01-IMP V2.0，自包含 · 原生 App 方案）。Code Agent 必须严格按 §3 文档索引 + §4 初始化 + §5 实施顺序（4 阶段 105 人天，跳过阶段 1 飞书）+ §6 Checklist + §7 状态矩阵 + §八 SFM Issue 模板 + §九 工作日志 + §十 7 状态反馈确认机执行。任何与 hk2026 主仓交互（Git 提交、发布文档 PDF、WLG 更新）由 TL/SPO 或听写助手按 PJM 和 PMG 规则执行，Code Agent 不得越权。