|
|
@@ -0,0 +1,280 @@
|
|
|
+# Ai-DOP 第三方系统模拟器人工操作手册
|
|
|
+
|
|
|
+> 配套文档：[`分阶段完整执行任务书`](./Ai-DOP第三方系统模拟器分阶段完整执行任务书.md)（阶段与验收依据）· [`README`](../../../tools/integration-simulator/README.md)（环境准备、安装、配置、启动、故障排查）
|
|
|
+
|
|
|
+本手册按《分阶段完整执行任务书》§23 要求，分别给出三种对接方式的人工全链路操作步骤（模拟器准备 → Ai-DOP 配置 → 人工触发 → 模拟器证据 → Ai-DOP 流水 → 结果核验 → 异常恢复 → 数据清理），并补充异常测试（N1-N4）、压力测试（§16-§21）与报告脱敏（§24）操作。
|
|
|
+
|
|
|
+**安全边界（全文有效）**：模拟器只模拟第三方一侧——不写 Ai-DOP 贴源/标准/KPI 表，不修改 Ai-DOP 配置，不进入 Ai-DOP 菜单；凭据一律走环境变量、Secret 不落盘不进浏览器；Ai-DOP 侧登记全部由人工按模拟器生成的清单执行。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 0. 阅读前提（模拟器准备，三方式通用）
|
|
|
+
|
|
|
+1. **环境**：Python 3.11+（Windows 用真实解释器）、独立 MySQL 测试实例、可访问的 Ai-DOP 开发/UAT 地址与测试租户。详见 README §1。
|
|
|
+2. **安装**：
|
|
|
+
|
|
|
+ ```powershell
|
|
|
+ cd d:\DEMONET
|
|
|
+ python -m venv .venv-sim
|
|
|
+ .venv-sim\Scripts\pip install -r tools/integration-simulator/requirements.txt
|
|
|
+ ```
|
|
|
+
|
|
|
+3. **配置**：
|
|
|
+
|
|
|
+ ```powershell
|
|
|
+ Copy-Item tools/integration-simulator/config.example.json tools/integration-simulator/config.json
|
|
|
+ ```
|
|
|
+
|
|
|
+ 按本机修改 `aidopBaseUrl` / `mockApiPort` / `allowedTargetHosts`（config.json 只放非敏感项，已 gitignore）。
|
|
|
+
|
|
|
+4. **凭据**（环境变量，进程启动时注入，改后须重启模拟器）：
|
|
|
+
|
|
|
+ | 变量 | 用途 | 必填 |
|
|
|
+ |---|---|---|
|
|
|
+ | `AIDOP_SIM_MYSQL_HOST` / `PORT` / `USER` / `PASSWORD` / `DATABASE` | 方式甲模拟库连接 | 方式甲必填 |
|
|
|
+ | `AIDOP_SIM_INBOUND_ACCESS_KEY` / `AIDOP_SIM_INBOUND_SECRET` | 方式丙 HMAC 签名凭据 | 方式丙必填 |
|
|
|
+ | `AIDOP_SIM_ADMIN_TOKEN` | 只读管理 API（可选） | 否 |
|
|
|
+
|
|
|
+ 仅测方式乙（API_PULL）可全不设。
|
|
|
+
|
|
|
+5. **启动**：
|
|
|
+
|
|
|
+ ```powershell
|
|
|
+ .venv-sim\Scripts\python tools/integration-simulator/app.py
|
|
|
+ ```
|
|
|
+
|
|
|
+ 控制台 `http://127.0.0.1:8017/`；Mock API 由控制台启停（默认 8018）。服务只绑 127.0.0.1，目标 host 受 `allowedTargetHosts` 白名单硬阻断。
|
|
|
+
|
|
|
+## 1. 控制台页签总览
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+| 页签 | 用途 | 对应方式 |
|
|
|
+|---|---|---|
|
|
|
+| 对象测试 | 选对象/通道 → 加载适配样例 → 预检 → 执行 → 三层结论与人工核验 SQL | 甲/乙/丙通用 |
|
|
|
+| 业务场景 | 三组跨对象链路；不支持节点标红 | 演示 |
|
|
|
+| Mock API（API_PULL） | 启停 8018、鉴权切换、异常注入、脱敏审计 | 方式乙 |
|
|
|
+| 模拟 MySQL（DB_SYNC） | 建库建表、装载样例、行数/增量、配置清单、档位生成 | 方式甲 |
|
|
|
+| API_INBOUND | 26 契约预检、七类操作与必测用例 | 方式丙 |
|
|
|
+| 异常测试 | 三通道异常场景目录（10/16/17）+ N4 报告 | 甲/乙/丙 |
|
|
|
+| 压力测试 | 计划十项 + 开始/停止 + 实时指标 + 报告 | 甲/乙/丙 |
|
|
|
+| 全链路报告 | 基础打通报告（§24 三类报告之一） | 通用 |
|
|
|
+| 运行记录 | 最近运行（自动脱敏） | 通用 |
|
|
|
+| 环境安全 | 凭据加载状态、白名单、隔离约束 | 通用 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 2. 方式甲 DB_SYNC（数据库同步）人工全链路
|
|
|
+
|
|
|
+**链路**：模拟器 `mock_db.py` → 独立 MySQL schema `aidop_integration_sim` →（Ai-DOP 拉取）`MdpSourcePullDispatcher` → `MdpDbPullExecutor` → 贴源表。
|
|
|
+
|
|
|
+### 2.1 模拟器准备
|
|
|
+
|
|
|
+1. 打开「模拟 MySQL（DB_SYNC）」页签：
|
|
|
+
|
|
|
+ 
|
|
|
+
|
|
|
+2. 填「库名/主机」（默认 `aidop_integration_sim` / `127.0.0.1`），点 **建库建表**——内部执行 DDL（幂等），库名经硬闸门校验（非 `aidop_integration_sim` 前缀直接拒绝，防误写 Ai-DOP 主库）。
|
|
|
+3. 点 **装载样例**——按目录样例装载可追踪业务数据（业务键 `SIM-{runId}-`，增量列 `sourceUpdatedAt` 递增）。
|
|
|
+4. 在「行数与最大增量」区确认装载行数与当前最大增量值，作为后续核验基准。
|
|
|
+
|
|
|
+### 2.2 Ai-DOP 配置（人工执行）
|
|
|
+
|
|
|
+1. 点 **生成 Ai-DOP 配置清单**（`GET /api/db/aidop-config/{objectCode}`），得到建议登记项。
|
|
|
+2. 在 Ai-DOP 配置页人工登记：
|
|
|
+ - `mdp_source`：`SIM_MODE3_DB`（`system_code=SIM_MODE3`，与另两通道**不得共用 source_code**）；
|
|
|
+ - `mdp_entity`：源表 `sim_{objectCode}`、目标贴源表、业务键、增量列 `sourceUpdatedAt`。
|
|
|
+3. 确认不抢占现有 T8/165/自建单等生产权威来源。
|
|
|
+
|
|
|
+### 2.3 Ai-DOP 人工触发
|
|
|
+
|
|
|
+在 Ai-DOP「数据源管理」对 `SIM_MODE3_DB` 执行拉取（或按既定调度触发）。
|
|
|
+
|
|
|
+### 2.4 模拟器证据查看
|
|
|
+
|
|
|
+- 「行数与最大增量」区查看拉取后增量是否推进；
|
|
|
+- 「运行记录」页签查看最近运行与三层结论。
|
|
|
+
|
|
|
+### 2.5 Ai-DOP 流水查看
|
|
|
+
|
|
|
+- Ai-DOP 拉取调度流水（`MdpSourcePullDispatcher` 运行日志）；
|
|
|
+- 模拟库侧可用核验 SQL 直接查行数：
|
|
|
+
|
|
|
+ ```sql
|
|
|
+ SELECT COUNT(*), MAX(sourceUpdatedAt) FROM aidop_integration_sim.sim_item;
|
|
|
+ ```
|
|
|
+
|
|
|
+### 2.6 目标结果核验
|
|
|
+
|
|
|
+按「对象测试」页签执行后给出的**人工核验 SQL**，在 Ai-DOP 贴源表核对行数与业务键。三层结论不得混为一谈：HTTP 202 不代表业务全链路跑通，贴源写入与否以核验 SQL 为准。
|
|
|
+
|
|
|
+### 2.7 异常恢复
|
|
|
+
|
|
|
+「异常测试」页签 → 方式甲分组（10 个场景），每个 auto 场景带 **恢复** 按钮一键还原（重建表/重载样例）；guide 场景只出指引文本。
|
|
|
+
|
|
|
+### 2.8 测试数据清理
|
|
|
+
|
|
|
+- 模拟库侧：页签「重置单表」清空对应 `sim_*` 表；
|
|
|
+- Ai-DOP 侧贴源数据按运行编号（runId）核验 SQL 人工清理——删除不由模拟器执行。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 3. 方式乙 API_PULL（我方拉取）人工全链路
|
|
|
+
|
|
|
+**链路**：模拟器 `mock_api.py` 本地 GET Mock（默认 8018）→（Ai-DOP 拉取）`MdpSourcePullDispatcher` → `MdpApiPullExecutor` → 贴源表。
|
|
|
+
|
|
|
+### 3.1 模拟器准备
|
|
|
+
|
|
|
+1. 打开「Mock API（API_PULL）」页签：
|
|
|
+
|
|
|
+ 
|
|
|
+
|
|
|
+2. 点 **启动**，Mock API 监听 `:8018`（真实端口绑定，失败如实报错）。
|
|
|
+3. 默认鉴权 `TOKEN`、令牌 `sim-mock-token`；按需切换 NONE/TOKEN/BASIC/APIKEY。
|
|
|
+4. 确认样例响应路径（默认挂载目录样例）。
|
|
|
+
|
|
|
+### 3.2 Ai-DOP 配置（人工执行）
|
|
|
+
|
|
|
+- `mdp_source`：`SIM_MODE3_API`；
|
|
|
+- `mdp_entity`：源 API path（如 `/api/item`）、鉴权方式与凭据（与模拟器设置一致）、目标贴源表、cursor 语义增量。
|
|
|
+
|
|
|
+### 3.3 Ai-DOP 人工触发
|
|
|
+
|
|
|
+Ai-DOP「数据源管理」对 `SIM_MODE3_API` 拉取。
|
|
|
+
|
|
|
+### 3.4 模拟器证据查看
|
|
|
+
|
|
|
+- 页签审计区查看最近请求（**自动脱敏**：Bearer/Secret 只留后四位）；
|
|
|
+- 未拉取时审计为空——先查鉴权设置是否与 Ai-DOP 侧一致。
|
|
|
+
|
|
|
+### 3.5 Ai-DOP 流水查看
|
|
|
+
|
|
|
+Ai-DOP 拉取调度流水 + 响应状态码（401=鉴权不匹配、429=限流注入、500=错误注入）。
|
|
|
+
|
|
|
+### 3.6 目标结果核验
|
|
|
+
|
|
|
+同 2.6，以「对象测试」页签人工核验 SQL 在贴源表核对。
|
|
|
+
|
|
|
+### 3.7 异常恢复
|
|
|
+
|
|
|
+「异常测试」页签 → 方式乙分组（16 个场景）：超时/空响应/坏 JSON/错误 Content-Type/忽略 cursor/不排序/强制状态码等，auto 场景一键预置与恢复。
|
|
|
+
|
|
|
+### 3.8 测试数据清理
|
|
|
+
|
|
|
+- Mock 侧：审计为内存态，**停止 Mock API** 即清；
|
|
|
+- Ai-DOP 侧贴源数据按 runId 人工清理。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 4. 方式丙 API_INBOUND（第三方推送）人工全链路
|
|
|
+
|
|
|
+**链路**：模拟器 `clients/inbound_client.py` HMAC 签名推数 → Ai-DOP `MdpInboundController` → 接收服务 → 贴源表。
|
|
|
+
|
|
|
+### 4.1 模拟器准备
|
|
|
+
|
|
|
+1. 启动模拟器进程前注入 `AIDOP_SIM_INBOUND_ACCESS_KEY` / `AIDOP_SIM_INBOUND_SECRET`（**进程启动后无法热更新**）。
|
|
|
+2. 打开「API_INBOUND」页签：
|
|
|
+
|
|
|
+ 
|
|
|
+
|
|
|
+3. 先跑 **26 契约 schema 批量预检**：逐实体 GET schema 探测，状态分类（READY / 授权缺失 / 实体未注册 / 源不可达）。
|
|
|
+
|
|
|
+### 4.2 Ai-DOP 配置（人工执行）
|
|
|
+
|
|
|
+- `mdp_inbound_grant` + `SysOpenAccess`：为测试 AccessKey 授权目标 entityCode 并绑定测试租户；
|
|
|
+- `mdp_entity.inbound_enabled=1`。
|
|
|
+
|
|
|
+> 未授权实体入站会返回 403 `entity not authorized`（凭据有效但未授权）。「压力测试」页签实体下拉只显示已授权实体，可点「刷新授权」重探测（探测为 GET schema，只读无副作用，Secret 不出后端）。
|
|
|
+
|
|
|
+### 4.3 模拟器触发（方式丙由模拟器发数，非 Ai-DOP 触发）
|
|
|
+
|
|
|
+「对象测试」页签选 API_INBOUND → 加载适配样例 → 预检 → 执行（七类操作：单条/批量/快照等）。
|
|
|
+
|
|
|
+### 4.4 模拟器证据查看
|
|
|
+
|
|
|
+「运行记录」页签：请求/响应预览（脱敏）、HTTP 状态、三层结论。
|
|
|
+
|
|
|
+### 4.5 Ai-DOP 流水查看
|
|
|
+
|
|
|
+Ai-DOP `mdp_inbound_request` 入站流水（含 syncBatchId，按 runId 检索）。
|
|
|
+
|
|
|
+### 4.6 目标结果核验
|
|
|
+
|
|
|
+按核验 SQL 查 Ai-DOP 贴源表（如 `mdp_stg_item`），核对业务键与行数。
|
|
|
+
|
|
|
+### 4.7 异常恢复
|
|
|
+
|
|
|
+「异常测试」页签 → 方式丙分组（17 个场景）：错/缺 AccessKey、缺必填字段、错误字段类型、陈旧行、未知实体、批量部分失败、快照提交失败、实体未开启等；auto 场景一键恢复。**注意区分「工具自身失败」与「被测系统正确拒绝」**：Ai-DOP 预检拦截（409）记为 expectedReject，模拟器自身问题如实透传。
|
|
|
+
|
|
|
+### 4.8 测试数据清理
|
|
|
+
|
|
|
+- 按 syncBatchId/runId 在 Ai-DOP 入站流水与贴源表人工清理；
|
|
|
+- 模拟器不执行删除，只提供运行编号与核验 SQL。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 5. 异常测试操作（第二阶段 N1-N4）
|
|
|
+
|
|
|
+打开「异常测试」页签：
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+1. **场景目录**：按通道分组——方式甲 10 项 / 方式乙 16 项 / 方式丙 17 项，每场景含 id、标题、类型（`auto` 可一键预置/恢复；`guide` 只出指引，不自动改配置）、模拟行为、预期结果、恢复方式。
|
|
|
+2. **预置**：auto 场景点「预置」→ 按场景执行（如方式乙注入 500、方式丙缺必填字段推数）。
|
|
|
+3. **恢复**：点「恢复」还原；或 Mock 设置区一键 reset。
|
|
|
+4. **N4 异常报告**（八列）：选场景自动带入模拟行为与预期结果，填写后保存/导出 Markdown/列表管理；同场景重复保存为原位更新。
|
|
|
+
|
|
|
+## 6. 压力测试操作（第三阶段 §16-§21）
|
|
|
+
|
|
|
+打开「压力测试」页签：
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+1. **安全前提**：压测默认关闭，须测试人员显式开启；执行前填满十项（压测方式/对象/实体/环境/测试租户/负责人/时间窗口/最大数据量/最大并发/清理方案），**不允许生产**；共享开发/UAT 环境须负责人确认。
|
|
|
+2. **提交计划（校验）**：前端校验十项必填与上限，后端二次校验（双层上限：共享上限 + 指定值），失败列出错误项。
|
|
|
+3. **开始压测**：
|
|
|
+ - 方式甲：S/M/L 档批量生成（可一键停止）；
|
|
|
+ - 方式乙：Mock 压力模式（page_size/total_rows_limit/随机延迟/错误比例/限流）；
|
|
|
+ - 方式丙：模拟器发压（并发/QPS/阶梯升压/预热/错误数据比例/幂等键策略/超时/三类自动停止阈值）。
|
|
|
+4. **实时指标**：2 秒轮询 19 项指标（QPS、行吞吐、成功率、P50/P95/P99 等）；停止后指标**定格**在停止时刻。
|
|
|
+5. **立即停止**：随时可停；触发「连续错误/超时/429」自动停止阈值也会自动收尾（无后台残留负载）。
|
|
|
+6. **报告**：压测结束保存报告并导出 Markdown（自动脱敏）。
|
|
|
+
|
|
|
+## 7. 报告与脱敏（§24）
|
|
|
+
|
|
|
+三类报告：
|
|
|
+
|
|
|
+| 报告 | 入口 | 内容 |
|
|
|
+|---|---|---|
|
|
|
+| 基础打通报告 | 「全链路报告」页签 | 对象/通道/三层结论/核验 SQL |
|
|
|
+| 异常测试报告 | 「异常测试」页签 N4 | 八列：场景/模拟行为/预期/实际/符合/证据/恢复/备注 |
|
|
|
+| 压力测试报告 | 「压力测试」页签 | 计划十项 + 19 项指标快照 + 停止原因 |
|
|
|
+
|
|
|
+脱敏规则（保存前统一处理）：
|
|
|
+
|
|
|
+- 不出现 AccessSecret、数据库密码、JWT、完整 Authorization、完整连接串；
|
|
|
+- AccessKey 仅保留后四位；
|
|
|
+- 不出现真实客户敏感数据。
|
|
|
+
|
|
|
+## 8. 测试数据清理总表
|
|
|
+
|
|
|
+| 位置 | 清理方式 |
|
|
|
+|---|---|
|
|
|
+| 模拟 MySQL（`aidop_integration_sim`） | 页签「重置单表」；或按核验 SQL 人工删 |
|
|
|
+| Mock API 审计 | 内存态，停止即清 |
|
|
|
+| 模拟器运行记录 | 自动脱敏 + 容量限制 |
|
|
|
+| Ai-DOP 贴源/入站流水 | 按 runId / syncBatchId 核验 SQL 人工清理（模拟器不执行删除） |
|
|
|
+
|
|
|
+测试数据以 `SIM-{runId}-` 业务键与 syncBatchId 全程可追踪。
|
|
|
+
|
|
|
+## 附录 A：本手册截图清单
|
|
|
+
|
|
|
+| 截图 | 对应页签 |
|
|
|
+|---|---|
|
|
|
+| `sim-manual-img/tab_run_对象测试.png` | 对象测试 |
|
|
|
+| `sim-manual-img/tab_mockapi_MockAPI.png` | Mock API（API_PULL） |
|
|
|
+| `sim-manual-img/tab_db_模拟MySQL.png` | 模拟 MySQL（DB_SYNC） |
|
|
|
+| `sim-manual-img/tab_inbound_API入站.png` | API_INBOUND |
|
|
|
+| `sim-manual-img/tab_fault_异常测试.png` | 异常测试 |
|
|
|
+| `sim-manual-img/tab_load_压力测试.png` | 压力测试 |
|
|
|
+| `sim-manual-img/tab_runs_运行记录.png` | 运行记录 |
|
