AiDOPWarehouse/tools/integration-simulator

Ai-DOP 第三方对接模拟器（第一阶段初版）

独立运行的本地第三方系统模拟器，用同一套可追踪业务样例分别模拟三种入站方式：

通道	模拟端	Ai-DOP 真实执行链
DB_SYNC	providers/mock_db.py → 独立 MySQL schema aidop_integration_sim	MdpSourcePullDispatcher → MdpDbPullExecutor
API_PULL	providers/mock_api.py → 本地 GET Mock（默认 8018）	MdpSourcePullDispatcher → MdpApiPullExecutor
API_INBOUND	clients/inbound_client.py → HMAC 签名推数	MdpInboundController → 接收服务

派生文档：建设方案 · 初步执行任务书

本工具不写 Ai-DOP 贴源/标准/KPI 表，不修改 Ai-DOP 配置，不进入 Ai-DOP 菜单。

---

1. 环境要求

• Python 3.11+（Windows 需真实解释器，非 Microsoft Store 别名占位）
• 独立 MySQL 测试实例，具备建库建表权限；不得使用 Ai-DOP 库或其账号

• 可访问的 Ai-DOP 开发/UAT 地址，且已准备测试租户与测试 AccessKey

  cd d:\DEMONET
  python -m venv .venv-sim
  .venv-sim\Scripts\pip install -r tools/integration-simulator/requirements.txt
  

2. 配置

Copy-Item tools/integration-simulator/config.example.json tools/integration-simulator/config.json
# 按本机修改 aidopBaseUrl / mockApiPort / allowedTargetHosts

config.json 已加入 .gitignore，且只放非敏感项。凭据一律走环境变量：

$env:AIDOP_SIM_MYSQL_HOST      = "127.0.0.1"
$env:AIDOP_SIM_MYSQL_PORT      = "3306"
$env:AIDOP_SIM_MYSQL_USER      = "sim_user"          # 专用账号，勿用 Ai-DOP 主库账号
$env:AIDOP_SIM_MYSQL_PASSWORD  = "<模拟库密码>"
$env:AIDOP_SIM_MYSQL_DATABASE  = "aidop_integration_sim"
$env:AIDOP_SIM_INBOUND_ACCESS_KEY = "<测试 AccessKey>"
$env:AIDOP_SIM_INBOUND_SECRET     = "<测试 Secret>"
$env:AIDOP_SIM_ADMIN_TOKEN        = "<可选：只读管理 API 用>"

缺任何一项时，页面顶部横幅会明确提示缺哪个变量；Secret 永远不由页面输入、不回显、不落盘。

3. 启动

.venv-sim\Scripts\python tools/integration-simulator/app.py
# 控制台：http://127.0.0.1:8017/

服务只绑定 127.0.0.1。目标 Ai-DOP host 必须命中 allowedTargetHosts，否则硬阻断。

4. 页面用法

页签	用途
对象测试	选对象 → 选通道 → 加载/编辑适配样例 → 预检 → 执行 → 看三层结论与核验 SQL
业务场景	三组跨对象链路（订单制造链 / 采购执行链 / 库存与成品链）；不支持的节点标红「该通道不支持」
Mock API	启停 8018；切换 NONE/TOKEN/BASIC/APIKEY；注入延迟与 401/403/429/500；改响应路径；看脱敏审计
模拟 MySQL	建库建表 / 装载样例 / 重置单表 / 行数与最大增量 / 生成 Ai-DOP 配置清单
API_INBOUND	26 契约 schema 批量预检；七类操作与必测用例
运行记录	最近运行（自动脱敏）
环境安全	凭据加载状态、白名单、隔离约束说明

5. Ai-DOP 侧登记（人工执行）

模拟器只生成建议配置（GET /api/db/aidop-config/{objectCode}），不自动写库。需在 Ai-DOP 配置页登记：

• mdp_source：三个专用测试来源 SIM_MODE3_DB / SIM_MODE3_API / SIM_MODE3_INBOUND，共用 system_code=SIM_MODE3；
• mdp_entity：源表/源 API path、目标贴源表、业务键、增量列（DB_SYNC 用 sourceUpdatedAt，API_PULL 用 cursor 语义）；
• mdp_inbound_grant + SysOpenAccess：测试 AccessKey 授权目标 entityCode 并绑定测试租户；
• mdp_entity.inbound_enabled=1。

三通道不得共用 source_code，且不得抢占现有 T8/165/自建单等生产权威来源。

6. 结果分层（不得混为一谈）

代码层：SUPPORTED / UNSUPPORTED
配置层：READY / CONFIG_NOT_REGISTERED / CONFIG_NOT_ENABLED / GRANT_MISSING / SOURCE_UNREACHABLE
数据层：NOT_RUN / ACCEPTED / STAGING_WRITTEN / TRANSFORM_PENDING / RUN_FAILED

第一阶段无安全的只读管理 API 核对贴源结果时，报告 TRANSFORM_PENDING 并给出人工核验 SQL， 不把 HTTP 202 说成业务全链路跑通，不把配置未开通说成代码未实现。

7. 测试

.venv-sim\Scripts\pytest tools/integration-simulator/tests -v

文件	覆盖
tests/test_inbound_signature.py	签名金标向量（与独立实现交叉验证）、SHA256/HMAC、签名头不外泄
tests/test_sample_adapters.py	目录三通道完整性、26 契约覆盖、样例路径存在、SIM-{runId}- 业务键、契约字段名、缺必填如实上报
tests/test_mock_api.py	cursor 过滤、四种鉴权、401/403/429/500 注入、响应路径切换、样例挂载、审计脱敏
tests/test_mock_db.py	DDL 与类型推断、幂等 upsert、库名硬阻断、配置清单；真实 MySQL 用例无密码时跳过并标注未实测
tests/test_guard.py	非白名单目标阻断、预检状态分类、运行记录脱敏与容量
tests/test_redaction.py	Secret/连接串/Bearer/AccessKey 后四位脱敏

tests/test_guard.py 是任务书初始清单外新增的一份守卫测试（安全闸门与三层判定），其余文件名与任务书一致。

8. 目录

tools/integration-simulator/
├─ app.py                     # 本地控制服务（只绑 127.0.0.1）+ 三层报告 + 运行记录
├─ requirements.txt
├─ config.example.json        # 仅非敏感默认项；复制为 config.json（已 gitignore）
├─ clients/
│  ├─ inbound_client.py       # HMAC 签名与七类推数操作
│  ├─ aidop_probe.py          # 只读预检与白名单闸门
│  └─ redaction.py            # 脱敏
├─ providers/
│  ├─ mock_api.py             # API_PULL 对端
│  └─ mock_db.py              # MySQL 建表/装载/清理 + 配置清单生成
├─ catalog/
│  ├─ entities.json           # 42 个对象 × 三通道能力矩阵
│  ├─ scenarios.json          # 三组跨对象基础场景
│  └─ sample_adapters.py      # canonical 样例 → 三通道适配
├─ static/                    # 本地页面
└─ tests/

复用但不迁移、不修改的既有资产：

doc/db/mdp/mock_api/endpoints.json
doc/db/mdp/mock_api/samples/*.json
tools/mock/inbound/push_demo.py

9. 第一阶段边界

• 只做 MySQL 方言；SQL Server、故障注入编排、全链路自动对账、CLI/CI/容器化属第二阶段；
• 不做高并发压测，默认低频单批；
• 不为无契约对象伪造 API_INBOUND 接口（销售订单头、合同评审、发货计划/发货单、工序计划、MRP、采购申请、交货计划、现存量、过程检验、成品入库）；
• 删除测试数据不由模拟器执行，只提供运行编号与核验 SQL 清单。