接口文档

一、通用约定

1.1 基础地址

• 管理端接口前缀：/api/admin/
• 登录/公开接口前缀：/api/
• Agent 开放接口前缀：/api/agent/
• 客户只读端前缀：/api/client/

完整示例：GET https://cert.example.com/api/admin/certificate?page=1&limit=15

1.2 请求格式

后端同时兼容 JSON 与表单。批量接口的数组参数通常写作 ids[] 或 ids，以实际页面请求为准。

1.3 响应结构

普通响应

{
  "code": 0,
  "msg": "ok",
  "data": {}
}

分页响应

{
  "code": 0,
  "msg": "ok",
  "data": {
    "list": [],
    "total": 0
  }
}

错误响应

{
  "code": 400,
  "msg": "必填项缺失：cert_no",
  "data": {}
}

判断规则：code === 0 为成功，其他均为失败。不要只判断 HTTP 200，业务错误通常也返回 HTTP 200。

1.4 鉴权

系统支持两种携带方式，任选其一：

方式 A：HttpOnly Cookie（浏览器默认）

登录成功后服务端下发 HttpOnly Cookie，浏览器自动携带。前端请求需设置：

withCredentials: true

方式 B：Bearer Token（脚本/服务端调用）

登录接口返回 data.token，后续请求携带：

Authorization: Bearer <token>

Token 默认有效期 3 小时（可在「系统管理 → 系统信息设置」调整），保存在 Redis。退出登录、改密、被管理员下线后立即失效。 code=401 表示未登录或登录已过期，需要重新登录。

1.5 权限

超级管理员 admin 不受菜单、功能权限和数据范围限制。

1.6 分页

示例：

GET /api/admin/certificate?page=2&limit=50

1.7 时间与金额

日期字段留空请传 null 或不传，不要传空字符串 ""，否则可能触发数据库严格模式错误。

1.8 错误码

1.9 文件上传

POST /api/admin/upload
Content-Type: multipart/form-data

返回示例：

{
  "code": 0,
  "msg": "ok",
  "data": {
    "path": "uploads/2026/11/xxxx.pdf",
    "name": "证书扫描件.pdf",
    "size": 123456
  }
}

上传有扩展名白名单、真实 MIME 校验、随机文件名和大小限制。生产环境上限由 upload_max_filesize、post_max_size、Nginx client_max_body_size 共同决定。

1.10 下载

导出文件名使用 RFC 5987 编码，中文名在浏览器中正常显示。

二、认证与个人中心

2.1 接口列表

2.2 获取验证码

GET /api/captcha

返回：

{
  "code": 0,
  "msg": "ok",
  "data": {
    "key": "captcha_xxx",
    "img": "data:image/png;base64,..."
  }
}

验证码默认 4 位，5 分钟有效。登录时把 key 作为 captchaKey，用户输入作为 captchaCode。

2.3 登录

POST /api/login
Content-Type: application/json

成功返回：

{
  "code": 0,
  "msg": "登录成功",
  "data": {
    "token": "xxxxx",
    "expires_in": 10800,
    "user": {
      "id": 1,
      "username": "admin",
      "real_name": "系统管理员",
      "role_code": "admin"
    }
  }
}

需要二次验证时，返回 need_totp 与 challenge（不返回 token）：

{
  "code": 0,
  "msg": "ok",
  "data": {
    "need_totp": true,
    "challenge": "totp_xxx",
    "totp_bound": false,
    "force": true
  }
}

连续输错密码 5 次会锁定 15 分钟（可在 backend/config/security.php 调整）。

2.4 二次验证

查询会话

GET /api/totp/challenge?challenge=totp_xxx&device_token=xxx&device_id=xxx

提交验证码

POST /api/totp/verify

支持腾讯身份验证器、Google Authenticator 等标准 TOTP（SHA1 / 6 位 / 30 秒）。

2.5 当前用户信息

GET /api/profile/info

返回用户、角色、菜单树、功能权限码、数据范围、可管企业等。前端据此渲染侧边栏和按钮。

2.6 修改密码

POST /api/profile/change-password

修改成功后当前登录态失效，需要重新登录。

2.7 登录设备

三、工作台、报表与查询

3.1 工作台

GET /api/admin/dashboard/stat

常用参数：

返回通常包含：

• todo：8 类待办与风险数量；
• resource：证书利用率、闲置、借调中；
• base：企业数、人员数、证书数、合同数；
• expiring：近期到期证书列表；
• alerts：未读提醒列表。

3.2 统计报表

GET /api/admin/report/summary?period=6&company_id=0
GET /api/admin/report/overview?period=6&company_id=0

返回覆盖：到期趋势、证书状态结构、费用收支、结算进度、企业排行、借调分布、证书类型分布、企业明细。

3.3 一键查询中心

GET /api/admin/search?keyword=张三&scope=all&page=1&limit=15

详情：

GET /api/admin/search/detail?type=staff&id=1

type 支持 staff / company / certificate。

四、客户企业

4.1 接口列表

4.2 列表参数

GET /api/admin/company?page=1&limit=15&company_name=建筑&status=1&owner_user_id=0&mine=0

4.3 保存企业

POST /api/admin/company/save

新增时负责人自动为当前用户；变更负责人请调用 CRM 移交接口，不要直接改。

4.4 平台补全

POST /api/admin/company/complete-basic

平台单次请求有最小间隔与 10 分钟缓存，批量时逐家返回结果。

4.5 资质采集流程

1. POST /api/admin/company/fetch-qualification：返回是否需要验证码；
2. 如需要，POST /api/admin/company/qualification-captcha 获取图片；
3. 人工识别后，POST /api/admin/company/fetch-qualification-detail 提交验证码；
4. 识别错误可 POST /api/admin/company/qualification-captcha-refresh 换图；
5. 确认后 POST /api/admin/company/import-qualification 入库。

系统不内置 OCR、不绕过平台校验，验证码由业务人员人工识别。

五、企业证书（资质 / 安许）

5.1 列表参数

5.2 保存

六、人员档案

6.1 接口列表

6.2 列表参数

6.3 保存人员

OCR 接口接收图片文件或图片地址，返回识别出的姓名、身份证号、住址、毕业学校、毕业证编号、毕业日期等，供表单回填。

6.4 全景档案

GET /api/admin/staff/profile?id=1

返回：

• 基本信息、证件利用率；
• certificates：名下证书与占用状态；
• social：社保信息；
• projects：借调记录；
• follows：本人 + 名下证书的跟进；
• fees：合同与费用；
• conflicts：合规与冲突；
• attachments：附件。

七、证照台账

7.1 接口列表

7.2 列表参数

7.3 保存证书

POST /api/admin/certificate/save

重复校验

新增时按「同人员 + 同证书编号」和「同人员 + 同证书专业」查重。命中返回 409：

{
  "code": 409,
  "msg": "证书编号与该人员名下已有证书重复，请确认是否强制保存",
  "data": {
    "duplicate_cert": {
      "id": 12,
      "cert_name": "建筑工程",
      "cert_no": "豫********1234",
      "expire_date": "2027-06-30",
      "fields": ["cert_no"]
    }
  }
}

前端展示确认框，用户确认后带 force=1 重新提交。

7.4 变更状态

POST /api/admin/certificate/status

会写入状态变更日志与操作日志。

7.5 一键采集

POST /api/admin/certificate/person-collect

采集受平台频控，失败会返回可读原因；验证码由人工识别。

八、证书延续与状态日志

8.1 新增延续

保存后会回写证书的新到期日；如果原状态为「已过期」，会恢复为「正常」，并写状态变更日志。

8.2 状态变更日志

GET /api/admin/cert-status-log?biz_type=certificate&page=1&limit=15

九、证书借调

9.1 接口列表

9.2 列表参数

9.3 保存借调

冲突返回

保存前会做冲突检测。默认「证书占用」为阻断级，返回：

{
  "code": 409,
  "msg": "检测到阻断级冲突：证书已被占用",
  "data": {
    "conflicts": [
      {
        "type": "occupy",
        "level": 2,
        "title": "证书已被占用",
        "detail": "该证书已被 XX 建筑有限公司占用，区间 2026-01-01 ~ 2026-12-31"
      }
    ]
  }
}

用户确认后带 force=1 可强制保存。

9.4 归还

POST /api/admin/secondment/return

9.5 续借

POST /api/admin/secondment/renew

续借会把状态恢复为「借调中」，写状态变更日志，并触发「借调续借」场景推送。

十、项目配证

10.1 列表参数

10.2 保存项目

reqs 每项：

十一、配证任务

11.1 列表参数

11.2 保存任务

11.3 更新进度

POST /api/admin/cert-task/update-item

十二、智能匹配

12.1 推荐

GET /api/admin/match/recommend?project_id=1&req_id=3&limit=20

返回每人的总分与五维得分：

12.2 选用

POST /api/admin/match/select

选用成功会自动生成借调记录并留痕。存在阻断冲突时返回 409，确认后可强制提交。

十三、冲突中心

13.1 冲突类型

13.2 规则级别

{
  "occupy":     { "enabled": 1, "level": 2 },
  "person":     { "enabled": 1, "level": 1 },
  "exclusive":  { "enabled": 1, "level": 1 },
  "policy":     { "enabled": 1, "level": 1 }
}

十四、属地政策

14.1 规则类型

14.2 保存规则

14.3 试算

GET /api/admin/policy-rule/evaluate?cert_id=1&project_id=2

返回命中的规则、违规级别与说明。

十五、政务网进度

15.1 列表参数

15.2 保存申报

编辑时 password 留空表示不修改。

15.3 同步

POST /api/admin/gov-progress/sync

批量：

POST /api/admin/gov-progress/sync-all

同步后会：

• 解析平台 FLOWXML 环节，完整落库；
• 检测到「签发」环节完成即标记办结并自动归档；
• 状态字段变化时触发 gov_progress 场景推送；
• 写入执行记录。

15.4 归档

POST /api/admin/gov-progress/archive

15.5 查看密码

详情接口默认返回掩码。查看明文需要 gov:reveal 权限，调用：

GET /api/admin/gov-progress/detail?id=1&reveal=1

查看明文会写入操作日志，请按最小权限分配。

十六、账号密码库

16.1 列表参数

16.2 保存

16.3 查看密码

GET /api/admin/credential-vault/reveal?id=1

密码使用 AES-256-GCM 加密存储，列表与导出均不返回明文。查看动作会写操作日志。

十七、考试报名

17.1 证书类目

17.2 业务配置

默认业务动作：

默认状态流：待提交 → 待审核 → 已审核 → 已报名 → 已排考 → 已完成。

17.3 批次与考点

17.4 报名工单

列表参数：

工单保存关键字段：

提交时会做报名条件校验（年龄、学历、工作年限、证书有效期等），不符合会返回 400 与具体原因。

十八、学历报名

18.1 报名工单

列表参数：

工单保存关键字段：

默认流程：

• 电中（中专）：待报名 → 已报名 → 已入籍 → 已毕业
• 成考：待报名 → 已报名 → 待考试 → 待录取 → 已录取

18.2 报名机构

18.3 流程配置

十九、费用、收款账户、合同

19.1 费用台账

列表参数：

保存字段：

结算：

POST /api/admin/fee/settle

结算金额累计后：未结清 > 0 为「部分结算」，未结清 = 0 为「已结算」。

19.2 收款账户

字段：account_name、account_type、bank_name、bank_branch、account_no、init_balance、currency、contact、contact_phone、is_default、sort、status、remark。

当前余额 = 初始余额 + 已收 − 已付。被费用引用的账户不允许删除。

19.3 服务合同

字段：company_id、contract_no、contract_name、contract_type、party_a、party_b、sign_date、start_date、end_date、amount、status、secondment_id、remark、attachments。

二十、CRM 跟进

20.1 移交

POST /api/admin/crm/transfer

移交会写移交历史与操作日志；负责人不接受直接编辑。

20.2 新增跟进

POST /api/admin/crm/follow

20.3 跟进台账

GET /api/admin/crm/ledger?page=1&limit=15

二十一、提醒与推送

21.1 提醒中心

列表参数：

补发：

POST /api/admin/alert/resend

21.2 推送渠道

渠道类型：

测试推送参数：id（渠道 ID）、target（接收目标）、content（消息内容，留空用示例）。

21.3 消息模板

字段：scene（场景）、template_type（渠道）、template_name、content、status。

场景包括：证书到期、借调临期、借调到期、借调续借、政务网进度等。

21.4 企业接收人

字段：company_id（0 = 全局）、receiver_name、mobile、email、wecom_userid、receiver_type、status。

21.5 推送日志

参数：company_id、status（0 待发送 / 1 成功 / 2 失败）、source（正式/测试）、cert_id、channel、keyword、日期范围。

21.6 推送体检与手动检测

POST /api/admin/push/run-check

21.7 提醒规则

字段：company_id（0 = 全局）、alert_nodes（如 1year,6month,3month,2month,1month,15day,7day,3day,1day）、alert_ways（站内信/短信/邮件/企微等）、default_priority。

二十二、字典与自定义字段

22.1 字典

保存类型字段：type_code、type_name、module、remark、status。 保存字典项字段：type_code、dict_value、dict_label、parent_value、sort、status、remark。

22.2 证书类型与专业

专业若已登记字典，必须归属所选类型；类型为空且专业归属唯一时自动补全。

22.3 自定义字段

字段：module、field_key、field_label、field_type、options、default_value、is_required、sort、status、remark。

支持模块：人员、企业、证书、合同、借调、项目、配证任务等。

二十三、组织、账号、角色、菜单

23.1 部门

23.2 账号

保存字段：id、username、password、real_name、dept_ids、role_id、data_scope（all/dept_tree/dept/self）、company_ids、phone、email、status。

23.3 角色

字段：role_name、role_code、menu_ids、perms、remark、status。

23.4 菜单

23.5 企微通讯录与审批

二十四、系统配置、日志、回收站

24.1 系统信息

24.2 日志

24.3 回收站

参数：id 或 ids、module。

24.4 在线升级

二十五、导入导出与附件

25.1 通用导入

预览参数：

提交参数：

预览会校验必填、日期、身份证、手机号、邮箱、信用代码格式；失败行可下载失败名单。

25.2 各模块模板与导出

25.3 附件下载

GET /api/attach/download?path=uploads/2026/11/xxx.pdf

需要登录态；WebDAV 附件走带 HMAC 签名、1 小时有效的代理下载。

二十六、Agent 开放接口

26.1 认证

密钥明文只在创建时显示一次，库内只存 SHA-256 哈希与前缀。

26.2 接口

26.3 证书列表参数

26.4 写接口参数

更新证书状态

追加跟进

26.5 MCP

POST /api/agent/mcp
Content-Type: application/json
Authorization: Bearer <API_KEY>

支持 MCP Streamable HTTP 协议，工具清单与 REST 能力一致。适合 Claude Desktop、Cherry Studio 等支持 MCP 的客户端。

二十七、企业微信回调

智能机器人支持在「Agent 接入 → 企业微信机器人」中生成 Token、查看回调 URL，并配置到企业微信后台。支持查询类指令与受控写入指令。

二十八、客户企业只读端

客户角色只能读本企业数据，写操作一律 403。数据范围由 user_company_rel 决定。

二十九、附录

29.1 证书状态

29.2 社保状态

29.3 借调状态与方向

29.4 项目状态

29.5 项目社保要求

29.6 匹配状态

29.7 提醒节点

1year, 6month, 3month, 2month, 1month, 15day, 7day, 3day, 1day

支持自定义节点。

29.8 费用结算

29.9 数据范围

29.10 版本与兼容

• 新增字段遵循向后兼容，旧客户端可忽略未知字段。
• 枚举值以字典管理为准，界面优先显示字典标签，字典缺失时回退内置常量。
• 接口路径如遇调整，会保留旧路径兼容或在下个版本说明中标注。