技术文档（Technical Documentation - TND）¶
文档编号：DOC-D00 / TND 版本：V3.2（TND V2.0 阶段三启动） 维护人：TL / DT（听写负责编写，听码负责消费实施；听云负责部署拓扑相关章节评审） 关联文档：PMG、PJM §5.8/§5.9 阶段三 TND V2.0 里程碑、BAS V1.0 五服务限界上下文、QSV、CPT、DIS
阶段三启动声明（TND V2.0 · 2026-08-21 开启）¶
按 PJM §5.9 下一里程碑定义，阶段三 = 技术设计准备（TND V2.0），为听码 WDE 编码阶段提供唯一权威技术依据。交付范围：
- D01-D10 共 10 份技术设计文档（D01 总体架构 → D10 主数据技术方案），对齐 DIS/QSV/CPT/MDS/OPS 5 服务 + B 端（MFR/LGP）+ 对外 API 对接
- 5 服务 OpenAPI 3.0 YAML 契约：约 200 条路由（覆盖 V3.3.0 OpenAPI 136 路由扩展版），与业务用例 56 UCL 一一对应
- 技术选型 ADR：微服务基础设施（Docker Compose → K8s 演进）、PostgreSQL 仓储（主/从/只读副本）、NATS JetStream 领域事件总线、Drools/JSON-Rules 报价规则引擎、鉴权（Keycloak OIDC + JWT）
- 原型补齐：11 页 V3.3 缺口页（OPS5/CST2/WKR2/LGP2）的子元素级 data-* 二次注入（PJM §2.3 原注记：顶层✅ + 子元素⏸ → 阶段三补齐 🟢）
治理约束：技术选型变更须遵循 PJM §2.5 变更管理流程（三级评审：技术负责人 TL → 业务负责人 BO → 决策人 SPO 审批）；10 份设计文档按 BAS V1.0 §六 DDD 实施规范 8 要素统一模板产出。
目录索引¶
一、规划与总纲（DOC-D00-*）¶
| 文档 | 编号 | 版本 | 状态 | 说明 |
|---|---|---|---|---|
| 技术规划 | TND-P | V1.1 | 🟢 已挂，V2.0 阶段三随 D01-D10 同步更新 | 定位、规划文档清单（D01-D10）、MVP 优先 + 规则引擎先行 + 渐进智能化 6 大技术原则 |
| MVP 实施方案 | DOC-D00-M | V1.0 | 🟢 已发布（V3.3.0 P3d 阶段飞书多维表格+AI 听写助手） | 极简 MVP 方案：40 字段 CPT-Lite/QSV-Lite/MDS-Lite 数据模型；8 阶段操作手册；AI 协同规范；四阶段演进路径 |
| templates/ | — | — | 🟢 已挂 | MVP 配套 Excel 模板（CPT-Lite / QSV-Lite / MDS-Lite）+ Python 生成脚本 |
| 技术平台演进方案 | DOC-D00-E | V1.0 | 🟢 已挂（飞书→DIP1→S2G1 三阶段演进） | 与 MVP-D00-M 对接的四阶段技术演进路线（P1 飞书双轨 → P2 dip1 → P3 云原生） |
二、D01-D10 详细技术设计（阶段三 TND V2.0 核心交付 · 全部挂表）¶
| 编号 | 文档（简称） | 英文简称 | 版本 | 状态 | 对应业务服务 | 关键章节 |
|---|---|---|---|---|---|---|
| D01 | 系统总体架构设计 | TND-ARC | V1.0 | 🟡 阶段三编写 | 全局 5 服务 + 3 端 + 基础设施 | 分层架构；五服务限界上下文拆分；DDD 战术映射 → 服务/聚合/仓储接口；Docker Compose dev → K8s prod 部署拓扑；NATS JetStream 事件总线 Topic 规划；ADR 选型记录（PostgreSQL 16 + NATS 2.10 + Keycloak 25 + Kong API GW） |
| D02 | 报价引擎技术方案 | TND-QSVE | V1.0 | 🟡 阶段三编写 | QSV 报价服务 | PricingEngine 伪代码→实际 TypeScript 算法 + 32 因子加权；DME 运输模型（M1/M2/M3 三模式）；规则引擎选型（JSON-Rules → Drools 渐进）；封顶价与品牌溢价（1.2/1.4）代码实现；报价版本快照存储；CPT L8 反哺校准接口 |
| D03 | 楼宇库技术实现方案 | TND-BPL | V1.0 | 🟡 阶段三编写 | MDS-BPL 楼宇特征库 | 业务设计已在 MDS/BPL 挂（DOC-P51-B）；本方案：PostgreSQL 25+10 扩展字段表结构 + PostGIS 几何索引；采集接口（LGP 司机 GPS 围栏 + CPT 师傅现场核实双写）；楼宇系数映射 SQL View |
| D04 | 订单与派单系统技术设计 | TND-DIS | V1.0 | 🟡 阶段三编写 | CPT 客户跟踪 + DIS 派单 | CPT CustomerProject 8 阶段状态机（Java/Spring Statemachine 或 TS XState）；DIS 派单决策引擎（运输分×0.55 + 安装分×0.45 三模式候选池加权排序）；C7 保险赔付 4 档流程；L5 → DIS 领域事件 NATS 触发链路；异常订单升级（L7 客诉）SAGA 补偿 |
| D05 | B 端后台技术设计 | TND-B2B | V1.0 | 🟡 阶段三编写 | MFR 生产商 + LGP 物流商 | MFR 品牌商 20 产品 + 批量订单接口；LGP 物流商运单分配 + 跨境 8800 投保；对账结算（MFR 月度 / LGP 按趟）；B2B RBAC 6 角色；开放报价 MFR→QSV API 桥 |
| D06 | API 对接方案 | TND-INT | V1.0 | 🟡 阶段三编写 | 外部集成 | 菜鸟裹裹香港 + 淘宝/京东/拼多多电商平台 + 中港物流专线对接方案；Webhook + 轮询双模式；幂等性设计（Idempotency-Key Header）；沙盒环境清单；HS 编码跨境报关字段接口 |
| D07 | 数据安全与权限设计 | TND-SEC | V1.0 | 🟡 阶段三编写 | 全局 | PDPO 合规（CPL 客户 5 级字段加密 AES-256）；师傅隐私字段（手机号/WhatsApp/证件号）脱敏展示；RBAC 12 角色 + RLS 行级权限（PostgreSQL row level security）；Keycloak OIDC + JWT 方案；审计日志；API GW 限流（Kong Rate Limiting） |
| D08 | 师傅端 App/小程序技术设计 | TND-WKR | V1.0 | 🟡 阶段三编写 | WKR 师傅端 + CPT 采集 | React Native / Expo 工程选型（与原型 WKR RN 100% UI 对应）；GPS 围栏 + L6 节点打卡（摄像头水印 + 时间戳 + 位置三重校验）；电子签字（signature_pad → NAS 归档）；WPL 等级 + 技能矩阵本地缓存；拒单处罚扣分解禁 |
| D09 | 客户项目跟踪表技术方案 | TND-CPT | V1.0 | 🟡 阶段三编写 | CPT 客户项目跟踪服务 | 183 字段 PostgreSQL 数据模型（对应 CPT-F DOC-P41-F 5 类干系方 7 类采集物）；多端信息采集（CST/WKR/OPR/MFR/LGP）写入聚合根；8 阶段状态机 → Timeline UI；NPS 星级采集（9 档）与 OPS 口碑推荐 REF 生成接口 |
| D10 | MDS 主数据服务技术方案 | TND-MDS | V1.0 | 🟡 阶段三编写 | MDS 6 库（SCL/BPL/WPL/CPL/PPL/DLV） | 四库→六库升级（新增 PPL 生产商 + DLV 物流商）；6 库数据模型 + PostgreSQL 表结构；主数据读写 API（MDS-D DOC-P51-D 供给表 1:1 对齐）；校准引擎（CPT L8 实际数据 → WPL 师傅画像 / SCL 费率 / BPL 系数 自动校准 3 通道）；MDM 数据治理 + 版本号 + 审批流 |
三、OpenAPI 契约与 Schema（阶段三 TND V2.0 交付）¶
| 文档 | 编号 | 版本 | 状态 | 说明 |
|---|---|---|---|---|
| openapi/ | TND-API | V3.0 | 🟡 阶段三编写（YAML，OpenAPI 3.0.3） | 5 服务契约：QSV 报价 + CPT 跟踪 + MDS 主数据 + DIS 派单 + OPS 运营；约 200 operationId；兼容 V3.3.0 dip1 OpenAPI 136 路由（向上扩展不破坏） |
| schemas/ | TND-SCH | V3.0 | 🟡 阶段三编写（JSON Schema + PostgreSQL DDL） | 22 表 + 30 枚举 → SQL DDL 脚本（对齐 V3.3.0 Alembic 0001/0002）；JSON Schema 前端表单校验 |
目录说明¶
本子目录存放平台技术方案、系统架构、模块设计等技术文档。阶段三起，从"规划态"正式进入"可编码态"：
- 消费方：听码 WDE（dip1/ 代码实现按 TND V2.0 设计文档执行，不再以业务文档为唯一依据）
- 评审方：听云 OCM（§D01 部署拓扑 / §D07 安全 / §D06 第三方对接 由 OCM 加签后才可下发编码）
- 治理约束：技术选型变更须遵循 PJM §2.5 变更管理流程（三级评审 TL → BO → SPO）
原型缺口阶段三补齐：11 页原型缺口页（OPS5/CST2/WKR2/LGP2）顶层 div 已注入 6 data-，子元素（按钮 / 卡片内层 / 输入框）的二次 data- 注入在阶段三 TND-8 任务完成，完成后 PJM §5.5.2 状态从「顶层✅ 子元素⏸」更新为「全量✅」。
修订记录¶
| 版本 | 日期 | 修订人 | 修订内容 |
|---|---|---|---|
| V1.0 | 2026-08-04 | DT | 创建 |
| V2.0 | 2026-08-04 | DT | 添加编号与英文简称 |
| V3.0 | 2026-08-04 | DT | README.md 改为目录索引；主内容迁移至 技术规划.md |
| V3.1 | 2026-08-06 | DT | 新增 MVP 实施方案（DOC-D00-M V1.0）及配套 Excel 模板目录；索引表新增版本列 |
| V3.2 | 2026-08-21 | DT | 阶段三 TND V2.0 启动：① 新增 §阶段三启动声明；② 目录拆分为三分区：规划总纲（DOC-D00-）/ D01-D10 详细技术设计（10 份挂表）/ OpenAPI 契约（TND-API / TND-SCH）；③ 为 D01-D10 每份文档补写「版本」「状态」「对应业务服务」「关键章节」4 列元数据；④ 技术平台演进方案（DOC-D00-E V1.0）入索引；⑤ 新增原型缺口阶段三补齐说明（11 页子元素 data- 二次注入） |