API 文档

TuraIDC 的接口契约分三层维护，职责不重叠：先看格式规范，再用清单导航找业务域，最后在自动生成的清单里查具体路由。

1. 三层入口

文档	回答的问题	维护方式
接口格式规范	响应结构、鉴权、分页、校验与版本边界是什么	手工维护
API 清单导航	某个业务域有哪些能力、核心业务流程映射到哪些接口	手工维护
后端 API 清单	具体路由、方法与控制器动作的完整枚举	脚本生成，禁止手工编辑

清单导航与格式规范都以重新生成后的清单为准；三者冲突时按此顺序回退到代码与测试。

2. 刷新自动清单

路由或控制器动作变化后必须重刷，产物不入手工维护范围：

php backend/scripts/export_api_inventory.php

刷新后执行文档校验，确认目录与链接仍然完整：

pnpm run docs:check

3. 接口分层约定

• 管理端接口统一落在 /api/v2/admin/*，用户端在 /api/v2/client/*，站点公开数据在 /api/v2/site/*。
• 开放 API（给外部系统调用的密钥认证接口）与魔方上游协议是独立入口，见魔方上游协议与后端规范。
• 控制器保持薄层：校验进 FormRequest，业务进 Service，第三方调用进 Driver 或插件。
• 越权与鉴权问题必须在认证授权层解决，不能靠 WAF 兜底。

关联文档

• 后端规范：控制器分层、服务边界与治理要求。
• 本地对接说明：本地联调上游接口的入口与边界。