增加文档

2026-06-02 17:55:33 +08:00
parent da41723e99
commit ac449b0134
4 changed files with 1820 additions and 0 deletions
@@ -0,0 +1,141 @@
+# 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 不主导该流程 |