docs(mdp): 新增连T8场景数据流说明（直连T8表 vs MDP双模式对照）

- 说明 S5-S7 早期直连 T8 表的问题与正确的双模式做法
- 含数据流对照图、6 条问题、7 维对照表、现状与迁移建议

Co-authored-by: Cursor <cursoragent@cursor.com>

doc/plan/AIDOP双模式T8对接数据流说明.md

@@ -0,0 +1,112 @@
+# AIDOP 双模式｜连 T8 场景数据流说明（直连 T8 表 ❌ vs MDP 双模式 ✅）
+
+> 目的：用一张图 + 对照表说清「S5–S7 早期直连 T8 表」为什么是错的，以及正确的双模式（经 MDP 贴源层/标准层）应该长什么样。
+> 适用：所有需要对接 T8 / 第三方系统（MES、WMS、QMS、ERP）取数与回写的模块。
+
+---
+
+## 1. 一句话结论
+
+**旧做法**把「取数逻辑 + T8 表结构」焊死在业务代码里；**正确做法**是把 T8 当成一个可插拔的 `mdp_source`，数据先进 `mdp_stg`（贴源层）、再转 `mdp_std`（标准层），业务/KPI 只认标准层——这样 **DB 路线和 API 路线才能等价互换**，也才能做契约一致校验、换源、多租户。
+
+---
+
+## 2. 数据流对照图
+
+```mermaid
+flowchart LR
+    subgraph WRONG["❌ 旧做法：S5-S7 直连 T8 表"]
+        direction LR
+        T8a[(T8 库<br/>业务表)]
+        S57a[S5/S6/S7<br/>TransformService<br/>硬编码连接·直算]
+        DWDa[(dwd_t8_* / KPI)]
+        T8a -->|直接 SELECT T8 原表| S57a --> DWDa
+    end
+
+    subgraph RIGHT["✅ 正确：双模式经 MDP 贴源+标准层"]
+        direction LR
+        T8b[(T8 库<br/>业务表)]
+        APIb[[T8 / 三方 API]]
+        SRC[mdp_source<br/>+ mdp_entity 配置]
+        DISP{MdpSourcePullDispatcher}
+        DBEX[MdpDbPullExecutor]
+        APIEX[MdpApiPullExecutor]
+        STG[(mdp_stg_*<br/>贴源层)]
+        STD[(mdp_std_*<br/>标准层)]
+        OUT[(dwd_* / KPI / 看板)]
+
+        T8b --> DBEX
+        APIb --> APIEX
+        SRC --> DISP
+        DISP --> DBEX
+        DISP --> APIEX
+        DBEX --> STG
+        APIEX --> STG
+        STG -->|transform| STD --> OUT
+    end
+
+    WRONG -. 重构为 .-> RIGHT
+```
+
+---
+
+## 3. 为什么"直连 T8 表"是错的
+
+早期 S5/S6/S7 的实现（见 `S5/S6/S7MdpSyncTransformService.cs` 头部注释：「一期不做 `mdp_stg_t8_*` 贴源层；结果直接落 `dwd_t8_*` 与 `ado_s9_kpi_value_l1_day`」）存在以下问题：
+
+1. **连接硬编码**：T8 连接信息写死在业务 Service 里，换库/换环境要改代码。
+2. **强耦合 T8 表结构**：SQL 直接 `SELECT` T8 原表字段，T8 一改表结构，S5-S7 就崩。
+3. **无分层**：没有贴源层（原样落地）与标准层（口径统一），数据口径散落在各 Service 的直算 SQL 里，难维护、难复用。
+4. **只能 DB、无法切 API**：一旦第三方只给 API（或反过来），必须重写业务代码，谈不上"双模式"。
+5. **无契约一致性**：DB 路线和 API 路线是否取到同一份数据，无法自动校验。
+6. **多租户/换源难**：租户隔离、切换数据源都要改代码而非改配置。
+
+---
+
+## 4. 正确的双模式做法
+
+### 4.1 配置化数据源
+- 每个外部系统登记为一条 **`mdp_source`**（`source_type=DB` 或 `API`，含连接/鉴权信息）。
+- 每个业务对象登记为一条 **`mdp_entity`**（源表名、目标贴源表、增量列、批量、同步窗口）。
+
+### 4.2 分发 + 执行（入站）
+- **`MdpSourcePullDispatcher`** 按实体配置分发到对应执行器：
+  - **`MdpDbPullExecutor`**（`SupportedType=DB_SYNC`）：连 DB 源抽数，含增量游标、SQLServer/MySQL 分页、防注入。
+  - **`MdpApiPullExecutor`**（`SupportedType=API_PULL`）：调 API 源，按分页/游标取数。
+- 两条路都把数据**原样**写入 **`mdp_stg_*`（贴源层）**。
+
+### 4.3 转标准层
+- `transform` 把贴源数据按统一口径转成 **`mdp_std_*`（标准层）**。
+- 业务、KPI、看板**只认标准层**，与"数据来自 DB 还是 API"解耦。
+
+### 4.4 双模式等价（契约测试）
+- 同一对象的 DB 路线与 API 路线，落到 `mdp_std_*` 后应**逐字段等价**；用契约脚本（`doc/db/mdp/contract_tests/`）断言 `A ≡ B`，保证两模式可互换。
+
+---
+
+## 5. 对照速查表
+
+| 维度 | ❌ 旧：直连 T8 表 | ✅ 正确：双模式经 MDP |
+|------|------------------|----------------------|
+| 连接 | Service 里**硬编码** T8 连接 | `mdp_source` 统一登记，动态连接 |
+| 取数 | 直接 `SELECT` T8 原表，**耦合表结构** | `mdp_entity` 配置化，`Dispatcher` 分发 |
+| 数据分层 | 无贴源/标准层，**直算落 dwd** | `mdp_stg`(贴源) → `mdp_std`(标准) → dwd/KPI |
+| 模式切换 | **只能 DB**，换 API 要改代码 | **DB / API 两条路等价**，配置即切 |
+| 一致性 | 无法契约校验 | DB 路 ≡ API 路（契约测试保证） |
+| 换源/多租户 | 改代码 | 改配置（源、租户映射） |
+| 抗变更 | T8 改表即崩 | 变更收敛在贴源层映射 |
+
+---
+
+## 6. 现状与迁移建议
+
+- **现状**：目前走 `mdp_stg/std` 标准层的只有 **S1（`mdp_stg_so/mdp_std_so`）** 和后补的 **`S6_REPORT`（`mdp_stg_s6_report/mdp_std_s6_report`）**；**S5/S6/S7 主体仍是旧做法**——从 T8 直算落 `dwd_t8_*`。
+- **迁移方向**：按 `S6_REPORT` 模式，为 S5/S6/S7 的各入站对象补 `mdp_source/mdp_entity + mdp_stg_* + mdp_std_* + transform`，让业务/KPI 改读标准层；旧的直算链保留为过渡，逐对象切换并用契约脚本验证等价后下线。
+- **回写方向**：见 [`AIDOP双模式S5-S7独立SQLServer跨库回写方案与任务书.md`](AIDOP双模式S5-S7独立SQLServer跨库回写方案与任务书.md)（`mdp_outbox` + 执行器，DB 型走 `MdpDbPushExecutor`、API 型走 `MdpApiPushExecutor`）。
+
+---
+
+## 7. 关联文档
+- 入站/回写落地任务书：[`AIDOP双模式S5-S7独立SQLServer跨库回写方案与任务书.md`](AIDOP双模式S5-S7独立SQLServer跨库回写方案与任务书.md)
+- UAT 对接配置操作指南：[`AIDOP双模式S5-S7对接UAT配置操作指南.md`](AIDOP双模式S5-S7对接UAT配置操作指南.md)
+- 全模块对接总任务书：[`AIDOP双模式全模块对接交付级任务书.md`](AIDOP双模式全模块对接交付级任务书.md)