# 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`

> ✅ 示例表结构（简化）：
> ```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 不主导该流程 |