zwf
141 lines
5.0 KiB
Markdown
141 lines
5.0 KiB
Markdown
# 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 不主导该流程 | |