API 契约

后端为 Express + SQLite（node:sqlite），所有业务接口遵循同一套响应契约。本文由 ai-drafts/2026-10-20-api-contract/gen-api-routes.mjs 从路由源码与权限表生成清单部分，新增接口后重跑该脚本即可同步；契约规则与示例为手写维护。

统一响应结构

所有业务 JSON 响应统一走 success() / failed()，结构为：

interface ApiResponse<T> {
  code: number      // 与 HTTP status 一致：200 成功，4xx/5xx 为错误码
  message: string   // 人类可读提示；校验失败时为「字段路径: 原因」
  data: T           // 业务数据，失败时为 null
  requestId?: string // 请求追踪 ID，与 X-Request-Id 响应头一致
}

requestId 由 requestId 中间件统一注入响应体，同时保留 X-Request-Id 响应头（CORS 已暴露给浏览器），前端异常日志据此与后端日志串联。
健康探针（/health/*）与 MCP 传输层不走该结构。

错误码表

HTTP status 与业务 code 保持一致，不额外设计 0/1 成功码：

code	语义	抛出来源
400	请求参数校验失败 / 非法 JSON	validate 中间件、BadRequestError
401	未登录或 token 失效	authMiddleware、UnauthorizedError
403	无权限 / 初始密码未修改	permissionMiddleware、ForbiddenError
404	资源不存在	NotFoundError
409	业务冲突（用户名/角色名重复等）	ConflictError
413	请求体超过 256KB 上限	body-parser
428	需要先完成滑块验证码	PreconditionRequiredError
429	尝试过于频繁	TooManyRequestsError
500	服务器内部错误（对外只暴露统一文案，堆栈只进服务端日志）	errorHandler 兜底

分页结构

所有分页接口的 data 统一为：

interface PageResult<T> {
  list: T[]      // 当前页数据
  total: number  // 过滤条件下的总条数
  page: number   // 页码，默认 1，最小 1
  pageSize: number // 每页数量，默认 10，最小 1，最大 100
}

例外：监控日志列表 / 增量轮询为流式读取，pageSize 上限单独放宽（5000 / 2000），代码内有注释标注。

认证方式

登录后持 Bearer <token> 请求（Authorization 头）；token 由 POST /admin/login 签发，默认 2h，前端静默续期。
权限模型：RBAC。会话每次请求实时解析角色权限码；超级管理员持有 *。
员工首次登录未改密期间仅放行会话类接口（/admin/info、/admin/updatePassword 等），其余返回 403。

接口清单

「认证」列：公开 = 无需登录；登录 = 需 Bearer token。「权限标识」列即 RBAC 权限码，超级管理员通配；登录即可表示仅要求会话。

健康检查（部署探针）

方法	路径	认证	权限标识
GET	`/health/live`	公开	—
GET	`/health/ready`	公开	—
GET	`/health/info`	公开	—

认证与会话

方法	路径	认证	权限标识
GET	`/admin/login/state`	公开	—
GET	`/admin/captcha`	公开	—
POST	`/admin/captcha/verify`	公开	—
POST	`/admin/login`	公开	—
GET	`/admin/refreshToken`	登录	—（登录即可）
GET	`/admin/info`	登录	—（登录即可）
POST	`/admin/logout`	登录	—（登录即可）
POST	`/admin/updatePassword`	登录	—（登录即可）

用户管理

方法	路径	认证	权限标识
POST	`/admin/register`	登录	system:user:add
GET	`/admin/list`	登录	system:user:list
GET	`/admin/:id`	登录	system:user:list
POST	`/admin/update/:id`	登录	system:user:edit
POST	`/admin/delete/:id`	登录	system:user:delete
POST	`/admin/updateStatus/:id`	登录	system:user:edit
POST	`/admin/role/update`	登录	system:user:assignRole
GET	`/admin/role/:adminId`	登录	system:user:list / system:user:assignRole

角色管理

方法	路径	认证	权限标识
GET	`/role/list`	登录	system:role:list
POST	`/role/create`	登录	system:role:add
GET	`/role/all`	登录	system:role:list / system:user:assignRole / org:employee:assignRole
GET	`/role/menu/:roleId`	登录	system:role:list / system:role:assignMenu
POST	`/role/menu/update`	登录	system:role:assignMenu
GET	`/role/:id`	登录	system:role:list
POST	`/role/update/:id`	登录	system:role:edit
POST	`/role/delete/:id`	登录	system:role:delete

菜单管理

方法	路径	认证	权限标识
GET	`/menu/list`	登录	system:menu:list
GET	`/menu/tree`	登录	system:menu:list / system:role:assignMenu
GET	`/menu/all`	登录	system:menu:list / system:role:assignMenu
GET	`/menu/permissions`	登录	system:menu:list
POST	`/menu/create`	登录	system:menu:add
GET	`/menu/:id`	登录	system:menu:list
POST	`/menu/update/:id`	登录	system:menu:edit
POST	`/menu/delete/:id`	登录	system:menu:delete

系统架构

方法	路径	认证	权限标识
GET	`/system/architecture`	登录	system:architecture:list

元数据

方法	路径	认证	权限标识
GET	`/metadata/sets/page`	登录	metadata:set:list
GET	`/metadata/sets/code/:setCode/items`	登录	—（登录即可）
GET	`/metadata/sets/:id`	登录	metadata:set:list
POST	`/metadata/sets/add`	登录	metadata:set:add
POST	`/metadata/sets/:id/update`	登录	metadata:set:edit
POST	`/metadata/sets/:id/status`	登录	metadata:set:edit
POST	`/metadata/sets/:id/delete`	登录	metadata:set:delete
POST	`/metadata/items/add`	登录	metadata:item:add
POST	`/metadata/items/batch`	登录	metadata:item:add
POST	`/metadata/items/:id/update`	登录	metadata:item:edit
POST	`/metadata/items/:id/status`	登录	metadata:item:edit
POST	`/metadata/items/:id/delete`	登录	metadata:item:delete

组织架构

方法	路径	认证	权限标识
GET	`/org/profile`	登录	—（登录即可）
POST	`/org/profile/update`	登录	—（登录即可）
GET	`/org/summary`	登录	org:read
GET	`/org/dept-tree`	登录	org:read
GET	`/org/employees`	登录	org:read
GET	`/org/employees/detail`	登录	org:read
POST	`/org/employees/create`	登录	org:employee:create
POST	`/org/employees/:id/update`	登录	org:employee:edit
POST	`/org/employees/:id/status`	登录	org:employee:edit
POST	`/org/employees/:id/grantAccount`	登录	org:employee:account
POST	`/org/employees/:id/resetPassword`	登录	org:employee:account
POST	`/org/employees/:id/accountStatus`	登录	org:employee:account
GET	`/org/employees/:id/roles`	登录	org:employee:assignRole
POST	`/org/employees/:id/roles`	登录	org:employee:assignRole
GET	`/org/roles/:id/permissions`	登录	org:employee:assignRole
GET	`/org/roles`	登录	org:read
GET	`/org/positions`	登录	org:read
GET	`/org/functional-orgs`	登录	org:read

表单

方法	路径	认证	权限标识
GET	`/form/list`	登录	form:form:list
GET	`/form/detail`	登录	form:form:list / form:data:list
GET	`/form/versions`	登录	form:form:list
GET	`/form/categories/tree`	登录	form:form:list
POST	`/form/categories/create`	登录	form:form:edit
POST	`/form/categories/reorder`	登录	form:form:edit
POST	`/form/categories/:id/update`	登录	form:form:edit
POST	`/form/categories/:id/status`	登录	form:form:edit
POST	`/form/categories/:id/delete`	登录	form:form:edit
POST	`/form/create`	登录	form:form:add
POST	`/form/copy`	登录	form:form:add
POST	`/form/update`	登录	form:form:edit
POST	`/form/draft`	登录	form:form:edit
POST	`/form/publish`	登录	form:form:edit
POST	`/form/retire`	登录	form:form:edit
POST	`/form/revive`	登录	form:form:edit
POST	`/form/delete`	登录	form:form:delete
POST	`/form/render`	登录	form:form:list / form:data:list / form:data:submit

表单数据

方法	路径	认证	权限标识
POST	`/form/data/submit`	登录	form:data:submit
GET	`/form/data/list`	登录	form:data:list
GET	`/form/data/detail`	登录	form:data:list
POST	`/form/data/update`	登录	form:data:edit
POST	`/form/data/updateStatus`	登录	form:data:edit
POST	`/form/data/delete`	登录	form:data:delete

监控

方法	路径	认证	权限标识
POST	`/monitor/collect`	公开	—
GET	`/monitor/meta`	登录	—（登录即可）
GET	`/monitor/apps`	登录	monitor:app:list
POST	`/monitor/apps/create`	登录	monitor:app:add
POST	`/monitor/apps/update`	登录	monitor:app:edit
POST	`/monitor/apps/:appId/channels/test`	登录	monitor:app:edit
GET	`/monitor/apps/:appId/channels/tests`	登录	monitor:app:list
GET	`/monitor/apps/:appId`	登录	monitor:app:list
POST	`/monitor/apps/:appId/archive`	登录	monitor:app:edit
POST	`/monitor/apps/:appId/unarchive`	登录	monitor:app:edit
GET	`/monitor/apps/:appId/queue-stats`	登录	monitor:app:list
POST	`/monitor/apps/:appId/queue/start`	登录	monitor:app:edit
POST	`/monitor/apps/:appId/queue/stop`	登录	monitor:app:edit
GET	`/monitor/logs`	登录	monitor:log:list
GET	`/monitor/logs/export`	登录	monitor:log:list
GET	`/monitor/audit/stats`	登录	monitor:log:list
GET	`/monitor/logs/incremental`	登录	monitor:log:list
GET	`/monitor/stats/workbench`	登录	monitor:stats:list
GET	`/monitor/stats/perf`	登录	monitor:stats:list
GET	`/monitor/stats/api`	登录	monitor:stats:list
GET	`/monitor/stats/behavior`	登录	monitor:stats:list
GET	`/monitor/stats/error`	登录	monitor:stats:list
GET	`/monitor/stats/biz-error`	登录	monitor:stats:list
GET	`/monitor/alerts/history`	登录	monitor:alert:list
GET	`/monitor/alerts/health`	登录	monitor:alert:list
POST	`/monitor/alerts/status/batch`	登录	monitor:alert:handle
POST	`/monitor/alerts/:id/status`	登录	monitor:alert:handle
POST	`/monitor/alerts/retry`	登录	monitor:alert:retry
GET	`/monitor/maintenance/status`	登录	monitor:maintenance:prune
POST	`/monitor/maintenance/prune`	登录	monitor:maintenance:prune

MCP

方法	路径	认证	权限标识
POST	`/mcp`	公开	—
GET	`/mcp`	公开	—
DELETE	`/mcp`	公开	—
GET	`/mcp/health`	公开	—

API 契约 ​

统一响应结构 ​

错误码表 ​

分页结构 ​

认证方式 ​

接口清单 ​

健康检查（部署探针） ​

认证与会话 ​

用户管理 ​

角色管理 ​

菜单管理 ​

系统架构 ​

元数据 ​

组织架构 ​

表单 ​

表单数据 ​

监控 ​

MCP ​