Переглянути джерело

docs(data-platform): add stage 1 V2 review feedback

Co-authored-by: Cursor <cursoragent@cursor.com>
YY968XX 16 годин тому
батько
коміт
7f64280b18

+ 450 - 0
doc/plan/系统集成/数据中台/Ai-DOP数据中台阶段1任务书V2.0审查反馈.md

@@ -0,0 +1,450 @@
+# Ai-DOP 数据中台阶段 1 任务书 V2.0 审查反馈
+
+> 审查日期:2026-11-19
+>
+> 审查对象:`Ai-DOP 数据中台一期·阶段1(模块化安全底座)执行任务书 V2.0`
+>
+> 审查基线:仓库 `master` 提交 `f296f764d` 及本目录现行总体方案、实施验收计划、研发测试工作计划和项目进度管理表
+>
+> 审查结论:**修改后复审;完成本反馈 P0 项前,不得标记为“可派发实施”**
+
+## 1. 总体评价
+
+V2.0 已正确采用“Ai-DOP 内置数据中台模块”的产品定位,并基本覆盖以下硬性架构原则:
+
+- 与 Ai-DOP 共用登录、租户、工厂、权限、菜单、部署和运维体系;
+- 数据中台核心保持模块隔离,禁止直接依赖 S1–S9、看板、诊断和 KPI 实现;
+- 复用现有 `mdp_stg_* → mdp_std_* → DWD/KPI` 三层链路,不重复建设业务标准层;
+- 通过版本化二级包和 `IAidopPackageHandoff` 交接;
+- 保留未来替换为进程外交接实现的能力;
+- 阶段 1 与后续数据库接入、完整 API 推送和拉取、接入助手及完整治理能力已有基本边界。
+
+当前主要问题不是总体方向错误,而是任务书尚未成为能直接纳入项目进度管理的执行计划:
+
+1. 第 3 章大量开工输入仍为“待补充”,阶段 0 实际没有签出;
+2. DP1-00~DP1-08 没有映射现有三级 WBS、责任人、日期、人日和周门禁;
+3. 一个研发、一个 QA 的现有项目资源与“26 组必测、云端和私有化分别全量验证”的工作量没有核算;
+4. 现网固定入站链路与新 Raw/Handoff 链路缺少并行、迁移和退出设计;
+5. 部分待建接口、表和 Worker 被放在“复用”语境中,容易被误判为现网已有能力。
+
+因此,V2.0 当前应按“阶段 1 详细执行设计审查稿”管理,完成 P0 修订并复审后,才能作为开发派工依据。
+
+## 2. 项目进度管理对齐要求
+
+### 2.1 唯一计划基线
+
+修订任务书必须与以下文件保持一致,不得另起一套人员、日期或进度口径:
+
+- [`Ai-DOP数据中台一期研发与测试工作计划.md`](./Ai-DOP数据中台一期研发与测试工作计划.md)
+- [`Ai-DOP数据中台一期项目进度管理.xlsx`](./Ai-DOP数据中台一期项目进度管理.xlsx)
+
+现行责任人:
+
+- 研发负责人:小刘;
+- QA 负责人:小彭;
+- 架构、产品、DBA、安全和运维作为评审或配合角色时,必须写明实际人员、投入日期和所需人日,不能只写角色名称。
+
+现行关键门禁:
+
+- 11 月 18 日:任务书通过审查;
+- 11 月 27 日:第三方接入研发完成;
+- 11 月 30 日:模拟器对接测试启动;
+- 12 月 9 日:数据中台处理研发完成;
+- 12 月 16 日:全部功能研发和模块单元测试完成;
+- 12 月 17 日—23 日:整体联测;
+- 12 月 23 日:发布候选版本通过;
+- 12 月 28 日:完成内部交付。
+
+如果修订后的阶段 1 工作量无法满足上述门禁,必须明确列出:
+
+- 冲突的任务和门禁;
+- 需要增加的人员、环境或预算;
+- 建议调整的日期;
+- 不调整时无法完成的验收项。
+
+禁止在任务书中保留完整范围,却不核算人日和环境,默认由现有一个研发、一个 QA 在原日期内完成。
+
+### 2.2 DP1 工作包必须增加的字段
+
+DP1-00~DP1-08 每个工作包必须增加:
+
+1. 对应的项目三级 WBS 编号;
+2. 完整三级任务名称;
+3. 研发责任人;
+4. QA 验证责任人;
+5. 配合人员或角色;
+6. 计划开始日期;
+7. 计划完成日期;
+8. 计划人日;
+9. 前置 WBS;
+10. QA 验证内容和日期;
+11. 所属 W1—W7;
+12. 对应周门禁和项目关键门禁;
+13. 交付证据位置;
+14. 延期时影响的后续任务和门禁。
+
+任务书不得只写“执行 Bxx 测试”或“由测试负责”,必须写清测试对象、输入、期望结果、执行日期和责任人。
+
+### 2.3 建议的 DP1 与项目 WBS 对应关系
+
+以下映射作为修订起点,最终日期和人日须与项目进度管理表逐项核对:
+
+- **DP1-00 契约与开工签出**
+  - `0.1 需求确认`
+  - `0.2 任务书`
+  - 完成阶段 0 交付物签出、实际分工、环境和样本确认。
+- **DP1-01 工程、模块边界与扩展契约**
+  - `1.1 接入公共基础`
+  - `3.1 现有能力复用与边界`
+  - 包含七类接口骨架、独立 Worker 入口、模块目录和禁止依赖守卫。
+- **DP1-02 Raw、接收待办和迁移**
+  - `2.1.2 Raw批次和原始事件存储`
+  - `2.1.3 Raw与Outbox原子写入`
+  - 包含表域、迁移、权限、保留、清理和容量实测。
+- **DP1-03 最小安全接收**
+  - `1.1.4 凭据、认证、幂等、限流和接收回执`
+  - `2.1.1 接入网关和统一接收服务`
+  - 仅实现阶段 1 受控 JSON 样本所需最小入口。
+- **DP1-04 Worker、隔离和交接**
+  - `2.1.4 Worker租约、心跳、重试和故障恢复`
+  - `2.3.4 数据隔离和问题原因分类`
+  - `3.2 二级包与贴源层交接`
+- **DP1-05 追溯、重放和内置页面**
+  - `2.1.5 数据追溯和运行时间线`
+  - `2.1.6 原版本重放基础能力`
+  - `2.5.1 纳入Ai-DOP的接入、治理、运行、对账和交接页面`
+- **DP1-06 运行保障**
+  - `2.5.5 同地域高可用、基础备份和监控告警`
+  - `5.2 部署运维文档`
+- **DP1-07 QA 验证**
+  - `4.1 单元测试`
+  - `4.2 模拟器对接测试`
+  - `4.3 整体联测`
+- **DP1-08 阶段签出和交付**
+  - `5.1 技术文档`
+  - `5.2 部署运维文档`
+  - `5.3 使用及交付文档`
+  - `5.4 交付包`
+
+同一 DP1 工作包跨多个周次时,应拆成可单独完成和验收的三级任务,不得用一个跨月大任务代替每日进度跟踪。
+
+### 2.4 QA 安排必须符合现行分工
+
+QA 只安排:
+
+1. 模块单元测试验证;
+2. 模拟器对接测试;
+3. 整体联测。
+
+相应修订要求:
+
+- DP1-04 等研发包不得把 QA 写成共同研发主责;
+- 小刘完成一个可独立验证的模块后,小彭立即执行对应单元测试,不等待全部研发结束;
+- 第三方接入完成后,11 月 30 日立即启动模拟器测试;
+- 12 月 17 日—23 日执行跨模块、安全、恢复和全链路整体联测;
+- 26 组测试必须逐组映射到上述三类测试及具体日期;
+- 无法在现有日期安排的测试必须登记为进度冲突,不能默认为“最后统一完成”。
+
+### 2.5 Excel 进度跟踪要求
+
+任务书修订后,应能直接映射进项目进度管理表:
+
+- 任务书的三级 WBS、责任人、日期和计划人日与 Excel 左侧项目进度一致;
+- 人员日历“计划”行来自任务书计划;
+- 日常只人工填写“实际”和“备注”;
+- 备注以“风险:”或“阻塞:”开头时,能够进入延期和风险区域;
+- 阶段 0 未完成输入必须作为阻塞或风险登记,不能继续留在正文中而不进入项目管理;
+- 周门禁和项目关键门禁使用同一完成口径。
+
+## 3. P0:复审前必须关闭
+
+### P0-01 阶段 0 未签出,阶段 1 不能开工
+
+任务书第 3 章仍有大量待补充项,包括:
+
+- 首个二级包和标准对象;
+- 来源、Raw、二级包三层 Schema;
+- 七类接口签名和评审记录;
+- Manifest 和 SDK 规范;
+- 配置包、状态机、权限和审批;
+- 安全基线、限额、错误码和幂等期限;
+- Worker 租约和重试参数;
+- 云端、私有化环境和恢复条件;
+- 受控样本和下游回归场景;
+- 禁止依赖自动检查;
+- 进程外替换演练方式。
+
+这些内容多数属于实施验收计划的阶段 0 交付物。修订时必须:
+
+1. 已完成项填写实际版本、评审记录和证据位置;
+2. 未完成但阻塞开工的项登记责任人、计划日期及项目风险;
+3. 非阶段 1 必需项移入后续阶段,不得全部塞入 DP1-00;
+4. DP1-00 只负责签出核验,不重复进行一轮未估算的阶段 0 设计。
+
+### P0-02 缺少人日、日期和实际责任人
+
+当前 DP1-00~DP1-08 仅列角色,没有人日、日期和小刘/小彭的实际分工,无法判断阶段 1 对整个 30 个工作日计划的占用。
+
+修订时必须提交:
+
+- DP1 包级和三级任务人日;
+- 小刘、小彭逐日计划;
+- 配合角色投入;
+- 关键路径;
+- 可并行任务;
+- 与 W1—W7 及关键门禁的对应关系。
+
+### P0-03 现网固定入站链路与新链路缺少迁移方案
+
+代码层现状:
+
+- 现网入口为 `api/mdp/inbound/{entityCode}`;
+- `MdpInboundReceiveService` 直接依赖 `MdpStagingWriter`;
+- `MdpInboundModuleTrigger` 直接触发业务模块重建;
+- 新方案目标是 `Raw → Worker → IAidopPackageHandoff → 现有贴源/标准层`。
+
+两条链路职责不同。任务书必须补充:
+
+1. 哪些鉴权、签名、幂等组件可以抽取复用;
+2. 哪些现网服务不能被数据中台核心直接调用;
+3. 新旧链路如何并行对账;
+4. 按数据集切换和回退的条件;
+5. 旧入口的兼容期限和退出条件;
+6. 如何避免双 Raw、双映射、双写贴源和重复业务结果。
+
+不得把整个 `MdpInboundReceiveService` 直接视为可复用的通用入站服务。
+
+### P0-04 接收待办不得与现有出站 Outbox 混用
+
+`MdpOutboxEnqueueService` 和 `mdp_outbox` 的现有职责是出站回写和推送。阶段 1 的接收待办用于保证 Raw 与后台处理任务原子登记,语义、权限、状态和恢复方式不同。
+
+任务书应明确:
+
+- 可以复用 Outbox 设计模式和基础工具;
+- 不默认复用现有出站表和业务服务;
+- 接收待办使用独立表域、状态机、迁移和最小权限;
+- 出站队列和接收待办分别测试、监控和恢复。
+
+### P0-05 新增能力与现有能力必须分栏
+
+以下现有能力已在代码中找到:
+
+- `SysAuthService`、`SysTenantService`、`SysOrgService`、`SysRoleService`、`SysMenuService`;
+- `MdpSourceConfigService`、`MdpSourceMappingService`、`MdpSyncTaskConfigService`、`MdpSyncLogService`;
+- `MdpInboundController`、`MdpOutboxEnqueueService`、`MdpInboundModuleTrigger`;
+- `MdpStdObjectCatalog`、现有 `mdp_stg_*` 和 `mdp_std_*`;
+- 数据中台现有五个管理页面。
+
+以下能力在当前代码中尚未实现,属于本阶段待交付:
+
+- `IRawStorage`;
+- `IAidopPackageHandoff`;
+- `IStandardStore`;
+- `IEventBus`;
+- `ITransformEngine`;
+- `IConnector`;
+- `ISchemaRegistry`;
+- `MySqlRawStorage`;
+- `MySqlOutboxEventBus`;
+- `ISecretStore`;
+- 独立运行的 Worker 工程或进程入口;
+- `raw_batch`、`raw_event` 或 `mdp_ingest_*` 表域;
+- `DataPlatform/UnifiedIngress/` 和 `DataPlatform/AiDOPHandoff/` 目录。
+
+复用清单必须拆成:
+
+1. 现网直接复用;
+2. 现网改造或抽取;
+3. 本阶段新增;
+4. 后续阶段实现。
+
+### P0-06 双部署形态必须进入资源和进度计划
+
+任务书要求云端和私有化分别完成安装、升级、回滚、双实例、主备、整库恢复、PITR 和 Raw 重放,但现有项目进度计划没有为两套完整环境单独分配人日和资源。
+
+修订时必须二选一:
+
+1. 阶段 1 代码和制品兼容两种部署,以当前已具备的环境完成主验收,另一形态完成约定的兼容和冒烟验证;
+2. 两种环境均执行全量验收,并同步调整项目进度表、资源、人日、预算和风险。
+
+不得在任务书中要求双环境全量验收,却仍沿用原有一个研发、一个 QA 和原日期。
+
+## 4. P1:重要修订项
+
+### P1-01 明确阶段 1 最小 API 与阶段 3 完整 API 的边界
+
+阶段 1 可以保留 `POST /api/v1/ingest/{datasetKey}`,但必须明确它只用于:
+
+- 受控 JSON 样本;
+- 最小来源和数据集授权;
+- Raw 与接收待办同事务;
+- 最小幂等、限额、错误码和回执;
+- 阶段 1 安全和故障恢复验收。
+
+NDJSON、OAuth2、mTLS、完整第三方开发者材料、完整批次查询和正式第三方联调体验仍属于后续完整 API 推送阶段。
+
+### P1-02 统一路由与兼容策略
+
+现网路由是 `api/mdp/inbound/{entityCode}`,目标路由是 `/api/v1/ingest/{datasetKey}`。必须明确:
+
+- 两者是并存、适配还是替换关系;
+- `entityCode` 与 `datasetKey` 如何映射;
+- 签名串是否变化;
+- 旧客户端兼容期限;
+- 切换和回退方式;
+- 对应 WBS、日期和测试任务。
+
+### P1-03 明确 `ISecretStore` 的现网落点
+
+当前代码没有统一 `ISecretStore` 实现。任务书应说明:
+
+- 是在阶段 1 新建统一接口;
+- 还是适配现有密码解析和环境秘密机制;
+- 云端和私有化分别如何保存、轮换、撤销和恢复;
+- 如何做到凭据只写不回显;
+- 对应开发、测试和交付人日。
+
+### P1-04 明确独立 Worker 的交付形态
+
+当前仓库有宿主内后台服务,但没有任务书所述独立 Worker 工程。必须冻结:
+
+- 是否为独立进程;
+- 工程和启动入口;
+- 构建制品;
+- 运行账号和权限;
+- 部署、升级和回滚方式;
+- 与 Ai-DOP API 的配置和版本兼容;
+- 在项目计划中的研发与运维日期。
+
+### P1-05 落实禁止依赖自动检查
+
+任务书 B24 要求流水线阻断以下行为:
+
+- 数据中台核心引用 S1–S9、看板、诊断或 KPI;
+- S1–S9 读取 Raw、连接器内部表或第三方源库;
+- 跨模块外键和隐式同库关联;
+- 绕过 `IAidopPackageHandoff` 写入贴源或标准层。
+
+当前仓库尚未找到对应自动检查。修订时必须写明:
+
+- 检查规则的实际代码位置;
+- 由谁开发;
+- 计划日期和人日;
+- 违规样例;
+- CI 执行位置;
+- QA 如何验证规则确实能够拦截违规代码。
+
+### P1-06 统一 Raw 表名
+
+任务书同时使用 `raw_batch`、`raw_event` 和 `mdp_ingest_*`。开工前必须冻结:
+
+- 实际物理表名;
+- 实体类;
+- 迁移脚本位置;
+- 表归属;
+- API、Worker、恢复账号权限;
+- 测试 SQL 和验收证据。
+
+### P1-07 收敛门户骨架
+
+阶段 1 应完成实施验收计划要求的管理页面骨架,但必须区分:
+
+- 本阶段必交:项目登记、受控试跑、批次时间线、Raw/隔离/交接/贴源/标准追溯、最小权限和审计;
+- 后续增强:完整新手/专家体验、复杂配置比较、完整审批与晋级体验、AI 辅助和大规模运营能力。
+
+每项页面能力必须映射到 `2.5.1` 等三级 WBS、具体日期和前后端人日。
+
+## 5. P2:文档质量问题
+
+1. 将第 7 章标题“环境资源与容量估算??”改为“环境资源与容量估算”。
+2. 将“双 API”统一改为“API 双实例”,避免被理解为两个不同业务接口。
+3. 将“操作审计服务”落实到具体服务、表和权限。
+4. 在文首明确本文只覆盖实施验收计划的工程阶段 1,不代表产品一期全部完成。
+5. 所有计划路径和计划服务标注“本阶段拟新增”,不得写成现网已有。
+6. 旧版审查反馈只作为历史记录,新任务书不得引用其中已经失效的独立平台结论。
+
+## 6. 代码、配置、数据三层核查结果
+
+### 6.1 代码层
+
+已存在:
+
+- Admin.NET 登录、租户、组织、角色、菜单和审计基础服务;
+- Ai-DOP 来源、映射、同步任务和同步日志服务;
+- 固定 `entityCode` 入站控制器及鉴权、幂等、映射链路;
+- 出站 `mdp_outbox` 服务;
+- `MdpStdObjectCatalog`、贴源层、标准层和现有转换;
+- 数据中台现有管理页面。
+
+尚未存在:
+
+- 七类扩展接口的代码定义和实现;
+- `ISecretStore`;
+- 通用 Raw 表域和存储实现;
+- 接收待办实现;
+- 独立 Worker 工程;
+- `IAidopPackageHandoff` 真实实现;
+- B24 禁止依赖自动检查。
+
+结论:现网可以提供基础复用条件,但阶段 1 目标能力尚未实现,任务书不得将“有现网基础”表述为“阶段 1 能力已经具备”。
+
+### 6.2 配置层
+
+已存在:
+
+- 数据中台菜单和页面路由种子;
+- `mdp_source`、`mdp_entity`、`mdp_field_mapping`、同步任务、入站授权和运行日志相关迁移;
+- 固定入站接口授权和来源配置基础。
+
+尚未开通:
+
+- 通用 Raw 表域;
+- `mdp_ingest_*` 配置;
+- 二级包交接契约登记;
+- 独立 Worker 配置;
+- 禁止依赖流水线规则。
+
+### 6.3 数据层
+
+开发库抽样结果:
+
+- `mdp_source`:16 行;
+- `mdp_entity`:227 行;
+- `mdp_field_mapping`:218 行;
+- `mdp_sync_log`:469,618 行;
+- `mdp_outbox`:7,546 行;
+- 已存在大量 `mdp_stg_*` 和 `mdp_std_*` 表;
+- 尚无 `raw_batch`、`raw_event` 或 `mdp_ingest_*` 表。
+
+结论:现有数据源、同步、出站和三层数据链路已有真实运行基础;新方案的通用 Raw、接收待办和二级包交接尚无运行数据,符合“待研发”状态。
+
+## 7. 修订后的交付格式
+
+修订稿至少应包含以下附表:
+
+1. 阶段 0 签出证据表;
+2. 现网复用、改造、新增和后续能力四分类表;
+3. 旧入站链路与新链路并行、迁移和退出表;
+4. DP1 工作包与项目三级 WBS 映射表;
+5. 小刘、小彭逐日计划及人日表;
+6. 26 组测试与单元测试、模拟器测试、整体联测的日期映射表;
+7. 云端和私有化环境范围、资源、人日及验收差异表;
+8. 风险、阻塞、影响门禁和调整措施表;
+9. 代码、配置、数据三层验收证据索引。
+
+## 8. 复审通过条件
+
+同时满足以下条件后,任务书才能改为“可派发实施”:
+
+- 阶段 0 阻塞项全部关闭或已形成经批准的例外;
+- 首个二级包、受控样本和真实贴源/标准落点已经冻结;
+- 新旧入站链路的迁移与退出方式明确;
+- 接收待办与出站 Outbox 职责彻底分开;
+- 七类接口、独立 Worker、Raw 表域和交接实现的新增范围明确;
+- DP1-00~DP1-08 全部映射到项目三级 WBS;
+- 每项任务具备责任人、日期、人日、QA 和门禁;
+- 双部署形态的范围与现有资源、进度和预算相符;
+- 项目进度管理 Excel 能按任务书计划自动跟踪;
+- P0 问题关闭,并提交更新后的代码、配置、数据三层证据。
+
+在上述条件完成前,任务书可继续用于详细设计和范围评审,但不得作为已经完成资源核算的直接开发派工单。

+ 4 - 0
doc/plan/系统集成/数据中台/README.md

@@ -26,6 +26,10 @@
    - 按第三方接入、数据中台处理、Ai-DOP三层整合和QA验证组织三级WBS。
 4. [Ai-DOP数据中台一期项目进度管理.xlsx](./Ai-DOP数据中台一期项目进度管理.xlsx)
    - 用于实际进度跟踪,并提供面向业务人员的总体业务功能架构和三期规划。
+5. [Ai-DOP数据中台阶段1任务书V2.0审查反馈.md](./Ai-DOP数据中台阶段1任务书V2.0审查反馈.md)
+   - 审查阶段 1 任务书 V2.0 的架构、现网复用和可执行性,重点要求 DP1 工作包与项目三级 WBS、人员、日期、人日、QA 及 W1—W7 门禁逐项对应。
+
+旧版阶段 1 任务书审查反馈仅保留为历史过程记录,不再作为当前任务书的修订基线。
 
 ## 与既有系统集成方案的关系