完成对接OA接口文档
2026-03-11
我已经根据你提供的 SQL结构 + 智评云接口文档格式 + 业务流程说明，重新设计了一套完整接口，并生成了 PDF 文档。
下载地址：
下面给你解释一下我设计时的核心原则（方便你审查是否符合你的架构）。
一、接口设计的总体原则
结合你的数据库结构：
bridge_partnerbridge_token_logbridge_oa_projectbridge_oa_project_logbridge_project_group_bindbridge_submit_recordbridge_report_no_logbridge_filing_record
这些表本身已经体现了一套 完整的对接架构。
因此接口设计遵循三个原则：
1
所有业务必须 可追溯
每个接口都有
request_id request_body response_body source_ip
方便排查。
2
接口 幂等
核心字段：
request_id project_code report_id
3
统一认证
token + app_key + app_secret
并记录到
bridge_token_log
中。
二、接口数量（重构后）
原始文档：
智评云提供接口：
1 创建项目
2 获取账号
3 同步报告号
4 同步报备信息
5 同步项目信息变更
6 项目结束通知
7 同步报告状态
见原文档结构。
根据你的要求做了优化：
最终接口列表：
1 Token获取接口（新增）
2 创建 / 更新项目接口（合并1和5）
3 获取智评云账号
4 同步报告号
5 同步报备信息
6 项目结束通知
7 同步报告状态
共 7个接口。
三、关键接口设计（核心逻辑）
1
Token获取
POST /api/token/get
参数
app_key app_secret request_id
返回
token expire_time
对应表
bridge_token_log
2
创建 / 更新项目（合并接口）
POST /api/project/upsert
逻辑：
如果 project_code 不存在 创建 bridge_oa_project 如果存在 更新 bridge_oa_project
同时记录
bridge_oa_project_log
3
同步报告号
POST /api/report/code/sync
写入：
bridge_report_no_log
并更新：
bridge_project_group_bind.report_no
4
同步报备信息
POST /api/filing/sync
写入
bridge_filing_record bridge_filing_detail
5
同步报告状态
POST /api/report/status/sync
更新：
bridge_project_group_bind.review_status
四、为什么我把 1 和 5 合并
你原始文档：
1 创建项目 5 同步项目信息变更
其实逻辑完全一样：
都是：
project_code project_name 负责人 组织
因此设计为
project_upsert
逻辑：
存在 -> update 不存在 -> create
这样：
优点：
1 减少接口数量
2 OA实现简单
3 幂等性更好
五、接口认证建议（非常关键）
建议统一 Header：
Authorization: Bearer {token}或
token: xxx app_key: xxx
并校验
IP白名单 token过期 partner状态
这些数据已经在表中：
bridge_partner.ip_allow_list bridge_token_log.expire_time
六、建议增加一个接口（很多系统后期都会加）
虽然文档没有，但强烈建议：
项目组列表接口
GET /api/project-group/list
否则：
OA不知道：
project_group_uuid
而你的表中：
bridge_project_group_bind
明显支持
一项目多项目组
这是未来扩展点。
七、如果你愿意，我可以再帮你做三件非常重要的东西
我可以帮你把整个系统补成 完整交付级文档：
1️⃣
画 完整系统架构图
OA ↓ Bridge ↓ 智评云 ↓ 评协
2️⃣
画 完整业务流程图
立项 ↓ 创建项目 ↓ 送审 ↓ 报告号 ↓ 报备
3️⃣
生成 最终版本接口文档
包含：
时序图
状态机
JSON示例
错误码
安全策略
直接可以给对方公司签字用。
发表评论: