科杰企业级系统（接口规范草案）

1. 文档定位

本文档给出科杰企业级系统一期接口设计的统一规范，用于后续前后端联调、移动端接入、外部协同和后续 IoT 扩展。

2. 接口风格建议

推荐一期统一采用：

RESTful JSON API 为主
文件上传下载走对象存储 + 受控接口
导出走异步任务
实时通知后续可补 WebSocket / SSE

3. 路径命名规范

建议统一前缀：

/api/admin/*：PC后台
/api/mobile/*：移动端
/api/portal/*：外部门户
/api/open/*：外部集成接口
/api/iot/*：IoT 接入接口（后续）

示例：

/api/admin/equipments
/api/admin/ledger/daily-inspections
/api/mobile/tasks/my
/api/open/export/packages/{id}

4. 统一响应格式

{
  "code": 0,
  "message": "ok",
  "data": {},
  "traceId": "xxx"
}

字段说明

code：业务状态码，0 表示成功
message：提示信息
data：业务数据
traceId：链路追踪ID

5. 分页格式建议

请求参数：

pageNo
pageSize
sortBy
sortOrder

响应格式：

{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [],
    "pageNo": 1,
    "pageSize": 20,
    "total": 120
  }
}

6. 通用鉴权建议

6.1 内部用户

JWT / Session Token
Header：Authorization: Bearer <token>

6.2 外部协同用户

独立 token 域
更短时效
更严格的数据范围控制

6.3 高敏感接口

建议增加：

二次确认
操作密码 / 验证码（按需）
操作审计日志

7. 统一错误码建议

code	含义
0	成功
40001	参数错误
40002	状态不允许当前操作
40101	未登录
40102	Token 无效
40301	无权限
40302	数据范围越权
40401	资源不存在
40901	数据冲突
40902	版本冲突
42201	审批未通过
50001	系统异常
50002	文件处理失败
50003	导出任务失败

8. 关键接口规范建议

8.1 认证与用户

获取当前用户

GET /api/admin/auth/me

获取菜单与权限

GET /api/admin/auth/menus

8.2 设备主档域

设备列表

GET /api/admin/equipments

查询参数：

equipmentCode
equipmentName
modelId
archiveStatus
operationStatus
riskLevel

创建设备主档

POST /api/admin/equipments

设备详情

GET /api/admin/equipments/{id}

更新设备主档

PUT /api/admin/equipments/{id}

查询设备档案摘要

GET /api/admin/equipments/{id}/archive-summary

查询设备版本绑定

GET /api/admin/equipments/{id}/version-bindings

8.3 标准设计资产域

机型列表

GET /api/admin/design/models

电控方案列表

GET /api/admin/design/schemes

创建电控方案

POST /api/admin/design/schemes

图纸版本列表

GET /api/admin/design/drawings/{id}/versions

上传图纸版本

POST /api/admin/design/drawings/{id}/versions

PLC 版本列表

GET /api/admin/design/plc-programs/{id}/versions

发布方案/版本

POST /api/admin/design/publish

8.4 台账域

日检任务列表

GET /api/admin/ledger/tasks/daily

日检填报

POST /api/admin/ledger/daily-inspections

月检填报

POST /api/admin/ledger/monthly-inspections

维保填报

POST /api/admin/ledger/maintenance-records

年度自检填报

POST /api/admin/ledger/annual-self-checks

查询设备台账摘要

GET /api/admin/ledger/equipments/{equipmentId}/summary

补录记录查询

GET /api/admin/ledger/backfills

8.5 整改域

问题池列表

GET /api/admin/ledger/issues

发起整改任务

POST /api/admin/ledger/rectifications

整改详情

GET /api/admin/ledger/rectifications/{id}

处理整改

PUT /api/admin/ledger/rectifications/{id}

关闭整改

POST /api/admin/ledger/rectifications/{id}/close

8.6 售后服务域

工单列表

GET /api/admin/service/work-orders

创建工单

POST /api/admin/service/work-orders

派工

POST /api/admin/service/work-orders/{id}/dispatch

填写服务记录

POST /api/admin/service/work-orders/{id}/visit-records

客户确认

POST /api/admin/service/work-orders/{id}/confirm

8.7 合规域

检验周期列表

GET /api/admin/compliance/inspection-cycles

合规风险列表

GET /api/admin/compliance/cases

关闭合规风险

POST /api/admin/compliance/cases/{id}/close

报检资料导出申请

POST /api/admin/compliance/export-packages

8.8 文件与导出域

上传附件

POST /api/admin/files/upload

查询附件列表

GET /api/admin/files

文件下载

GET /api/admin/files/{id}/download

创建导出任务

POST /api/admin/exports

查询导出任务

GET /api/admin/exports/{id}

8.9 移动端接口

我的待办

GET /api/mobile/tasks/my

设备扫码详情

GET /api/mobile/equipments/by-code/{code}

快捷日检提交

POST /api/mobile/ledger/daily-inspections

我的工单

GET /api/mobile/service/work-orders/my

工单处理提交

POST /api/mobile/service/work-orders/{id}/handle

9. 文件上传下载建议

上传方式

先调用上传接口获取文件ID
业务表单提交时引用 fileId

下载方式

走后端鉴权
返回短时效下载地址
高敏感文件必须校验设备/客户/角色权限

10. 导出设计建议

导出类接口全部异步化：

前端发起导出
返回任务ID
后端异步生成压缩包/PDF
前端轮询任务状态
成功后获取下载链接

11. 幂等与并发建议

幂等接口

建议以下接口加幂等：

登录（按需）
工单创建
日检提交
维保提交
导出任务创建

版本并发控制

建议以下接口使用版本号或更新时间判断：

图纸版本发布
PLC版本发布
BOM变更
设备主档更新
整改关闭

12. 审计与日志建议

以下接口必须记录审计：

设备主档编辑
合规状态变更
补录提交
发布/生效
导出整包资料
删除附件
关闭整改
关闭合规风险

13. 结论

接口规范的核心不是“格式统一”这么简单，而是要保证：

多端能稳定接入；
权限和数据范围能真正落地；
文件和导出不会失控；
后续 IoT 与外部接口可以平滑接入。

只要接口规范在一期就立住，后续扩展成本会低很多。

科杰企业级系统：接口规范草案