d3i-szct/docs/communication.md

D3I（数字化三方系统集成）系统与 OA、DCM 系统集成需求说明书

1. 项目背景

D3I（Digital 3-Directional Integration，数字化三方系统集成） 系统作为 DCM（Digital City Management，数字城管系统） 与办公自动化（OA）系统之间的核心枢纽，需实现双向数据流转：

• 正向流程：D3I 从 DCM 服务器抓取数据 → 存储至中间表 → 调用 OA 接口推送数据 → OA 完成业务流程。
• 反向流程：OA 完成流程后，调用 D3I 接口将处理结果回传至 DCM 系统（体外循环）。

本需求旨在明确 D3I 系统在该流程中需暴露和调用的接口，以及数据表结构设计，为开发、测试与对接提供权威依据。

---

2. 总体工作目标

1. 梳理并标准化 D3I 系统对外（DCM）等平台与对内（OA）的接口清单；
2. 明确 D3I 系统内部数据表结构，建立测试用镜像数据库；
3. 为后续接口开发、联调测试、文档编写提供完整、一致的依据。

---

3. 详细作业步骤

第1步：梳理 D3I 暴露给 OA 系统的 API 清单

目标：列出 D3I 当前已提供和需新增的所有供 OA 系统调用的接口，形成统一 API 文档。

内容要求：

• 接口名称（英文/中文）
• 请求方法（POST/GET）
• 请求路径（URL）
• 请求参数（JSON Schema）
• 响应格式（成功/失败示例）
• 认证方式（如 Token、OAuth、IP 白名单）
• 业务含义（如“提交案件数据”、“更新处理状态”）
• 当前状态（已上线 / 待开发）

输出物：
docs/api/d3i_to_oa_api_v1.md
（建议使用 OpenAPI/Swagger 格式维护）

✅ 示例接口（供参考）：

• POST /api/v1/case/submit：提交案件数据至 OA
• GET /api/v1/case/status/{id}：查询案件在 OA 中的处理状态

---

第2步：梳理 D3I 调用 DCM 系统的接口清单

目标：明确 D3I 从 DCM 获取数据和提交数据所需的全部接口。

内容要求：

• 接口用途（登录认证 / 获取数据 / 提交数据）
• 请求方式与地址
• 认证机制（用户名/密码、Token、证书）
• 数据格式（XML/JSON）
• 请求频率限制
• 错误码与重试策略
• 是否支持分页/增量拉取

输出物：
docs/api/d3i_to_dcm_api_v1.md

✅ 示例接口（供参考）：

• POST /api/login：获取 DCM 登录 Token
• GET /api/cases?status=new&limit=100：拉取待处理案件
• POST /api/cases/submit：向 DCM 提交处理结果

---

第3步：梳理 D3I 调用 OA 系统的接口清单（补充）

目标：确认 D3I 主动调用 OA 的接口，用于推送数据（与第1步区分，此为“主动调用”视角）

⚠️ 注意：第1步是“OA 调用 D3I”，本步是“D3I 调用 OA”。两者可能有重叠，需明确方向。

内容要求：

• 接口用途（如“推送案件”、“通知流程完成”）
• 请求方式、URL、Header、Body
• 是否需要异步回调机制
• 超时与重试策略
• 是否需记录调用日志

输出物：
docs/api/d3i_calling_oa_api_v1.md

✅ 示例接口：

• POST https://oa.example.com/api/v1/case/create：创建案件工单
• PUT https://oa.example.com/api/v1/case/update/{id}：更新案件状态

---

第4步：设计并建立 D3I 内部数据表镜像（测试环境）

目标：在 D3I 数据库中建立与 DCM 和 OA 交互所需的数据表结构镜像，用于开发与测试。

内容要求：

• 列出所有 D3I 使用的数据表（至少包括）：
  • dcm_data_cache：缓存从 DCM 拉取的原始数据
  • oa_case_submission：待推送给 OA 的案件队列
  • oa_callback_log：记录 OA 回调的响应日志
  • sync_status：记录同步状态（成功/失败/重试次数/时间戳）
• 每张表需定义：
  • 字段名、类型、约束（主键、外键、非空）
  • 索引设计
  • 数据保留策略（如 7 天自动清理）
• 建议使用 SQL 脚本定义结构，便于部署

输出物：
sql/schema/d3i_test_tables.sql

✅ 示例表结构（简化）：

CREATE TABLE dcm_data_cache (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  dcm_case_id VARCHAR(50) UNIQUE NOT NULL,
  raw_data JSON NOT NULL,
  received_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  processed BOOLEAN DEFAULT FALSE
);

---

4. 后续建议

• 所有接口文档建议使用 Swagger / Postman Collection 维护，便于测试；
• 数据表设计需与 DBA 审核，确保符合公司数据规范；
• 建议为每个接口编写集成测试用例（如使用 pytest + requests）；
• 建立数据流转图（流程图），标注每个环节的数据来源与去向。

---

5. 附录：术语说明

术语	说明
D3I	Digital 3-Directional Integration，数字化三方系统集成
DCM	Digital City Management，数字城管系统
OA	办公自动化系统（Office Automation）
体外循环	指数据由 OA 调用 D3I 回传至 DCM，D3I 不主导该流程