DIP1 技术实现文档目录索引¶
子项目编号：DIP1 文档编号：DOC-D00-D1 / DIP1-00 版本：V1.3 创建日期：2026-08-09 最近更新：2026-08-09 维护人：TL / DT 归属：TND-E V1.1 的实现层技术文档子目录（与 TND-P 的 D01-D10 对应关系见下表） 位置说明：本目录位于
dip1/docs/（代码目录内），DIP1 子项目代码+文档一体化自包含V1.3 变更（对齐 DIP1 原生 App 方案 ADR-008）：① 文档索引表全面同步最新版本（ARC V2.0 / P1 V1.1 ⏸ / P2 V2.0 / P3 V1.1 / SPEC V2.0 / PROTO V2.0 / API V2.0 / Schema V2.0 / IMP V2.0）；② 阅读顺序调整：Code Agent 跳过 P1 飞书对接，直接实施 P2 阶段 2；③ 文档关系图标注 P1 为「⏸ 暂不实施」；④ 技术栈对齐 React Native（师傅端 wkr-app + 客户端 cst-app 双 RN 原生 App）+ Expo managed workflow + EAS Build/Submit/Update。
一、定位¶
本目录（dip1/docs/）存放 DIP1 子项目的技术实现层文档，是 TND-E（6 个月演进规划）落地的开发说明书。文档与代码同在 dip1/ 目录下，实现子项目一体化自包含。
与 TND-P 规划文档的关系：
| TND-P 规划（DOC-D00-P） | → 对应本目录实现文档 | 说明 |
|---|---|---|
| D01 系统总体架构设计 | → DIP1-01 架构设计 | 落地为详细的模块划分与 DDD 分层 |
| D02 报价引擎技术方案 | → DIP1-03 §2 QSV 领域设计 | 报价引擎详细实现 |
| D09 CPT 跟踪技术方案 | → DIP1-03 §3 CPT 领域设计 | 8 阶段状态机与采集物 |
| D10 MDS 主数据技术方案 | → DIP1-03 §4 MDS 领域设计 | 四库数据模型与主数据校准 |
| D04 订单与派单系统 | → DIP1-03 §5 DSP 派单设计 | 师傅匹配与派单 |
| D07 数据安全与权限 | → DIP1-04 §5 安全设计 | 数据加密 + RBAC + PDPO |
| D08 师傅端 App | → DIP1-03 §7 前端架构 | WKR PWA 设计详情 |
| D05 B 端后台 | → DIP1-03 §7 前端架构 | OPR 后台设计详情 |
| D06 API 对接 | → DIP1-02 §3 飞书 API + DIP1-03 §8 对外 API | 飞书 + 合作方对接 |
二、文档索引¶
| # | 编号 | 文档 | 版本 | 状态 | 说明 |
|---|---|---|---|---|---|
| 1 | DIP1-01 | 架构设计 | V2.0 | ✅ | DDD 四层分层架构、限界上下文映射、模块化单体物理结构、非功能需求（性能/可用性/安全/可扩展）、V2.0：C4 容器图扩展双 RN App（wkr-app + cst-app）+ 13 条 ADR（新增 ADR-008~013 RN/Expo/NativeWind/EAS 决策） |
| 2 | DIP1-02 | 阶段 1：MVP-FS 飞书对接与迁移设计 | V1.1 | ⏸ | 飞书 Bitable API 封装层（Retry + 限流 + Token 刷新）、CSV→DB ETL 映射（6 表 88 字段）、双轨同步策略（1 周并行）、AI 数据校验规则、切换 Checklist · V1.1：ADR-008 标注「⏸ 暂不实施」——Code Agent 跳过本文档 |
| 3 | DIP1-03 | 阶段 2：一线操作系统技术设计 | V2.0 | ✅ | QSV/CPT/MDS/DSP/PAY 五大限界上下文详细设计（实体/聚合根/仓储接口）、65 REST API 端点（含 12 客户端 + 3 移动认证 + 2 推送）、22 核心数据库表 DDL（PostgreSQL 16）、RBAC 权限模型（6 角色 + 师傅行级）、前后端交互契约 · V2.0：新增 CST 客户端限界上下文 + 移动认证（refresh token 轮换）+ 推送服务（FCM/APNs via Expo） |
| 4 | DIP1-04 | 开发与基础设施设计 | V1.1 | ✅ | 本地环境一键搭建（Docker Compose + Expo/EAS CLI）、Python/Node 版本与包管理规范、Git Flow 分支策略（轻量级）、GitHub Actions CI/CD 流水线 + EAS Build/Submit/Update 三 Job（移动端 RN 云端构建）、测试金字塔（新增 Detox RN E2E + Jest RN 单测）、部署拓扑（Cloudflare Pages + 容器 API + App Store/Google Play + OTA 热更新）、SLA/监控/告警/备份 + Sentry RN SDK |
| 5 | DIP1-05 | 需求规格说明书（Code Agent 自包含） | V2.0 | ✅ | 脱离主仓文档即可独立实施：6 角色 × 12 域 × 193+ 功能点（编号 QSV-01~193）· 20+ 用户故事（US-xx 含验收标准）· 14 项 NFR 量化指标 · 统一错误码表（4xx/5xx）· MVP 范围裁剪表（P0/P1/P2）· V2.0：新增 CST 客户端 App 功能点（首页/品类/询价/订单/评价/推荐/我的）+ 移动端 NFR（启动 <2s/崩溃率 <0.1%/离线可用） |
| 6 | DIP1-06 | 功能原型设计（OPR 后台 + WKR RN + CST RN） | V2.0 | ✅ | 运营管理后台 15+ 页面（Next.js）· 师傅端 React Native 8 页面（接单/L1-L8 作业/收款/口碑，原生相机/推送/离线）· 客户端 React Native 8 页面（首页/品类/询价/订单/评价/推荐/我的）· NativeWind 主题 Token · 10 条关键交互流 Mermaid · 响应式断点规范 · V2.0：WKR 从 PWA 重写为 RN，新增 CST RN 原型 |
| 7 | DIP1-07 | OpenAPI 3.0 规格（65 端点） | V2.0 | ✅ | 可导入 Swagger/Postman/Apifox：认证 4 / 移动认证 3 / QSV 6 / CPT 14 / MDS 12 / OPS 6 / DSP 4 / CST 12 / 推送 2 / 系统 6，含请求/响应 Schema、错误码、分页规范、幂等键机制 · V2.0：新增 17 端点（CST 客户端 + 移动认证 + 推送） |
| 8 | DIP1-08 | 数据库详细设计（22 表 30 枚举） | V2.0 | ✅ | ER 图（Mermaid）· 22 张业务表字段级定义（PK/FK/默认值/CHECK 约束）· 30 枚举类型 · 5 条 RLS 行级策略（师傅数据隔离/行级审计）· 索引优化建议 · 附 alembic/versions/0001_initial_schema.py + 0002_cst_mobile_push.py 迁移脚本 · V2.0：新增 4 表（cst_customers / mobile_sessions / push_devices / push_notifications） |
| 9 | DIP1-09 | Code Agent 实施指南（含 Git 信息） | V2.0 | ✅ | 独立 Code Agent 工作说明书：Git 仓信息 + 分支规范 + 105 人天实施顺序（§0 环境基建→§2 后端→§3 前端 OPR+WKR RN+CST RN→§3 移动端基建→部署）· 跳过 §1 飞书对接 · 三级验收 Checklist（Agent自测/TL功能/OL UAT 50单）· §7.1 交付物状态跟踪矩阵（SPO/BO直接看此表即可评估进度）· V2.0：工作量 85→105 人天（+20：新增 CST + 移动基建 - 飞书），4 阶段实施计划 |
| 10 | DIP1-10 | Alembic 迁移脚本（0001 初始 + 0002 CST/推送） | V2.0 | ✅ | 与 DIP1-08 同步：0001（18 表 + 30 枚举 + 5 RLS 策略）+ 0002（4 表：cst_customers/mobile_sessions/push_devices/push_notifications），含 upgrade()/downgrade() 双向迁移，PG 扩展（pgcrypto/pg_trgm/btree_gin）、ULID 函数、updated_at 触发器 |
三、文档关系图¶
flowchart TD
TNDE["TND-E 演进方案<br/>（业务×技术双轮规划）"]
MVPFS["MVP-FS 实施方案<br/>（飞书工作台 40 字段）"]
DIP1_00["DIP1-00 目录索引<br/>（本文件，V1.3）"]
%% 第一层：架构 + 阶段设计（DIP1-01 ~ 04）
DIP1_01["DIP1-01 架构设计 V2.0<br/>DDD 四层 + 模块化单体 + 双 RN App"]
DIP1_02["DIP1-02 P1 飞书对接迁移 V1.1 ⏸<br/>【暂不实施】Bitable API + CSV→DB"]
DIP1_03["DIP1-03 P2 一线操作系统 V2.0<br/>5+1 大领域 + 65 API + 22 表 + RBAC"]
DIP1_04["DIP1-04 基础设施 V1.1<br/>Docker/CI-CD/EAS Build/测试/部署"]
%% 第二层：详细设计规格（DIP1-05 ~ 10，V2.0）
DIP1_05["DIP1-05 SPEC 需求规格 V2.0<br/>193+ 功能点 × 20 用户故事 × 14 NFR + CST"]
DIP1_06["DIP1-06 PROTO 原型设计 V2.0<br/>OPR 15+ 页 / WKR RN 8 页 / CST RN 8 页"]
DIP1_07["DIP1-07 OpenAPI 3.0 V2.0<br/>65 端点 × Swagger/Apifox 可导入"]
DIP1_08["DIP1-08 Schema 数据库 V2.0<br/>22 表 + 30 枚举 + 5 RLS"]
DIP1_09["DIP1-09 IMP Code Agent 指南 V2.0<br/>Git 信息 + 105 人天顺序 + 跟踪矩阵"]
DIP1_10["DIP1-10 Alembic 迁移脚本 V2.0<br/>0001 初始 + 0002 CST/推送"]
CODE_DOCS["📁 dip1/ 代码目录<br/>README + Makefile + docker-compose.yml + openapi.yaml"]
TNDE --> DIP1_00
MVPFS --> DIP1_00
DIP1_00 --> DIP1_01
DIP1_00 --> DIP1_02
DIP1_00 --> DIP1_03
DIP1_00 --> DIP1_04
DIP1_00 --> DIP1_05
DIP1_00 --> DIP1_06
DIP1_00 --> DIP1_07
DIP1_00 --> DIP1_08
DIP1_00 --> DIP1_09
DIP1_00 --> DIP1_10
%% 01~04 驱动代码骨架
DIP1_01 --> CODE_DOCS
DIP1_02 --> CODE_DOCS
DIP1_03 --> CODE_DOCS
DIP1_04 --> CODE_DOCS
%% 05~10 与 01~04 的支撑关系
DIP1_01 --> DIP1_05 %% 架构约束需求范围
DIP1_03 --> DIP1_05 %% 领域设计细化为功能点
DIP1_05 --> DIP1_06 %% 需求驱动原型
DIP1_05 --> DIP1_07 %% 需求驱动 API 契约
DIP1_05 --> DIP1_08 %% 需求驱动数据模型
DIP1_03 --> DIP1_07 %% 领域服务 → REST API
DIP1_03 --> DIP1_08 %% 实体聚合 → 表结构
DIP1_08 --> DIP1_10 %% Schema 设计 → Alembic 代码
DIP1_07 --> CODE_DOCS %% OpenAPI → FastAPI 路由骨架
DIP1_08 --> CODE_DOCS %% Schema → SQLAlchemy 模型
DIP1_09 --> CODE_DOCS %% 实施指南 → 代码执行顺序
style TNDE fill:#D4AF78,stroke:#004046,color:#004046
style DIP1_00 fill:#D4AF78,stroke:#004046,color:#004046
style DIP1_01 fill:#2a9d8f,stroke:#004046,color:#fff
style DIP1_02 fill:#2a9d8f,stroke:#004046,color:#fff
style DIP1_03 fill:#457b9d,stroke:#004046,color:#fff
style DIP1_04 fill:#457b9d,stroke:#004046,color:#fff
style DIP1_05 fill:#e76f51,stroke:#004046,color:#fff
style DIP1_06 fill:#e76f51,stroke:#004046,color:#fff
style DIP1_07 fill:#e76f51,stroke:#004046,color:#fff
style DIP1_08 fill:#e76f51,stroke:#004046,color:#fff
style DIP1_09 fill:#e76f51,stroke:#004046,color:#fff
style DIP1_10 fill:#e76f51,stroke:#004046,color:#fff四、阅读顺序（给新加入的开发人员 / DIP1 Code Agent）¶
4.1 独立 Code Agent（脱离主仓文档，仅看本目录即可）¶
⚠️ V2.0 关键决策（ADR-008）：跳过阶段 1 飞书对接（DIP1-02），直接实施阶段 2（DIP1-03）。 Code Agent 全栈聚焦阶段 2 目标：后端业务 + OPR 后台（Web）+ WKR 师傅端（RN）+ CST 客户端（RN）+ 移动端基建。
👉 必读顺序（最短路径，保证 100% 信息完整）：
1. DIP1-09 IMP 实施指南 V2.0 §1-§3 → 获取 Git 仓信息、环境搭建、分支规范、105 人天 4 阶段实施计划
2. DIP1-05 SPEC 需求规格 V2.0 §1-§6 → 理解 193+ 功能点（含 CST 客户端）、用户故事、验收标准、错误码、移动端 NFR
3. DIP1-01 ARC 架构设计 V2.0 §2-§5 → DDD 四层架构 + 限界上下文（含 CST）+ 13 条 ADR（RN/Expo/NativeWind/EAS 决策）
4. DIP1-07 OpenAPI YAML V2.0（导入 Swagger/Apifox）→ 前后端契约真值（65 端点含 CST/移动认证/推送）
5. DIP1-08 Schema 数据库 V2.0 + DIP1-10 Alembic 脚本 → 数据模型真值（22 表，含 0001+0002 迁移）
6. DIP1-06 PROTO 原型 V2.0 → 页面结构（OPR Web + WKR RN + CST RN）与 10 条交互流
7. DIP1-02 P1 飞书对接 → ⏸ 跳过（暂不实施）——如未来 TL 在 Issue 中明确启动，再阅读
8. DIP1-03 P2 一线操作系统 V2.0 → 阶段 2 实施核心（5+1 大领域 + 65 API + 移动认证 + 推送）
9. DIP1-04 P3 基础设施 V1.1 → CI/CD（含 EAS Build/Submit/Update）+ 测试（含 Detox RN E2E）+ 部署（含 App Store/Google Play）
10. DIP1-09 IMP §6 三级验收 Checklist + §7.1 跟踪矩阵 → 提交前自查与状态更新
4.2 人类开发人员（有主仓背景）¶
- 必读：先读 TND-E 了解业务阶段划分和目标 → 再读本索引 DIP1-00 → 读 DIP1-01 架构设计 V2.0 理解整体分层（含双 RN App）
- BE 后端：DIP1-01 → DIP1-04 §开发环境 V1.1 → DIP1-05 SPEC → DIP1-08 Schema → DIP1-03 五大领域设计 + CST/移动认证/推送 →
DIP1-02 对接迁移（跳过） - FE 前端（OPR Web）：DIP1-01 §前端架构 → DIP1-04 §开发环境 → DIP1-05 SPEC → DIP1-07 OpenAPI → DIP1-06 PROTO §OPR 章节 → DIP1-03 §7 前后端契约
- FE 前端（WKR/CST RN）：DIP1-01 §前端架构（RN 部分）+ ADR-008~013 → DIP1-04 §Expo/EAS → DIP1-06 PROTO §WKR/§CST 章节 → DIP1-07 OpenAPI（移动认证 + CST 端点）→ DIP1-03 §移动认证 + §推送
- TL/DevOps：DIP1-01 → DIP1-04（全章，含 EAS）→ DIP1-09 §2 Git 信息 → 搭建 CI/CD（含 EAS Build）+ 生产环境 + App Store/Google Play 凭据
- SPO/BO 进度评估：直接打开 DIP1-09 §7.1 交付物状态跟踪矩阵，无需阅读其他任何文档
- 工作日志：Code Agent 开发过程记录在 worklog/（DWLG-YYYYMMDD-NN 编号），TL 定期同步至主仓 WLG
修订记录¶
| 版本 | 日期 | 修订人 | 修订内容 |
|---|---|---|---|
| V1.0 | 2026-08-09 | DT | 初始化：DIP1 子项目目录索引，注册 4 份技术设计文档 |
| V1.1 | 2026-08-09 | DT | 注册新增 6 份详细设计文档（DIP1-05 SPEC / DIP1-06 PROTO / DIP1-07 OpenAPI / DIP1-08 Schema / DIP1-09 IMP 实施指南 / DIP1-10 Alembic 脚本）；文档关系图扩展为两层 10 节点；新增「4.1 独立 Code Agent 脱离主仓阅读顺序」与「4.2 SPO/BO 进度快速入口」；索引表从 4 条扩展至 10 条（DIP1 自有文档全部注册完毕，Code Agent 仅看本目录即可实施） |
| V1.2 | 2026-08-09 | DT | 目录合并：从 docs/技术文档/dip1/ 迁移至 dip1/docs/（代码目录内），实现 DIP1 子项目「代码+文档」一体化自包含；修正 Alembic 脚本相对路径 ../../dip1/backend/ → ../backend/；TND-E 引用路径更新为 ../../../docs/技术文档/技术平台演进方案.md；§4.2 新增第 6 条工作日志指引（指向 worklog/ 子目录）；主仓 docs/技术文档/dip1/ 保留轻量跳转索引 |
| V1.3 | 2026-08-09 | DT | 原生 App 方案升级（对齐 DIP1-ARC V2.0 ADR-008）：① 文档索引表全面同步最新版本（ARC V2.0 / P1 V1.1 ⏸ / P2 V2.0 / P3 V1.1 / SPEC V2.0 / PROTO V2.0 / API V2.0 / Schema V2.0 / IMP V2.0 / Alembic V2.0）；② DIP1-02 P1 飞书对接状态改为 ⏸ 暂不实施；③ DIP1-03 P2 端点数 52→65、表数 18→22；④ DIP1-06 PROTO 从「OPR + WKR H5」改为「OPR Web + WKR RN + CST RN」；⑤ DIP1-09 IMP 工作量 85→105 人天，4 阶段实施计划；⑥ 文档关系图各节点标注 V2.0 版本号与状态；⑦ §4.1 阅读顺序调整：Code Agent 跳过 P1 直接实施 P2，新增 WKR/CST RN 前端阅读路径；⑧ 技术栈对齐 React Native（wkr-app + cst-app 双 RN 原生 App）+ Expo managed workflow + EAS Build/Submit/Update |