API 参考

当前 API 参考入口仍未接入正式 OpenAPI，但以下控制面对外表面已经冻结，可作为实现与联调前的最小依据。

当前冻结的最小控制面接口

路径	方法	作用	当前冻结语义
`/api/v1/system/info`	`GET`	平台聚合状态入口	返回平台级状态摘要与 runtime 持久化能力摘要，不替代 `/healthz` / `/readyz`
`/api/v1/authn/status`	`GET`	AuthN wiring/status 可见性	只报告认证面状态，不泄露 token 或 session 明细
`/api/v1/authz/status`	`GET`	AuthZ wiring/status 可见性	只报告授权面状态，不暴露原始策略或实时授权结果
`/api/v1/approvals`	`POST`	approval ticket 创建入口	repository 已配置且请求有效时返回 `201 Created`；未配置时返回结构化 `503 Service Unavailable`
`/api/v1/compose/import`	`POST`	Compose 导入预检与报告	当前冻结为字段矩阵评估与导入报告入口，不直接承接完整 AppSpec/部署流程
`/api/v1/installer/actions`	`POST`	安装器执行入口	当前冻结为 installer run intent 入口，收敛到 step event 写入，不接管 task/deploy authority
`/api/v1/databases`	`GET`	数据库可见性	当前冻结为只读 visibility surface，可返回 `placeholder` 与空列表
`/api/v1/storage/objects`	`GET`	对象存储可见性	当前冻结为只读 visibility surface，可返回 `placeholder` 与空列表
`/api/v1/aidb/query`	`POST`	历史 AI DB 兼容壳层	当前冻结为 legacy-only 迁移提示面，不再扩展新长期能力

三个 status surface 的目标行为都是 200 OK + JSON 状态对象，并显式区分 placeholder / ready / degraded。
/api/v1/system/info 可以额外暴露 runtime 摘要字段，用于说明当前运行模式与持久化能力边界，但不能泄露 DSN、token 或其它敏感配置。
POST /api/v1/approvals 当前已交付为 approval ticket 创建接口；在 approval repository 已配置时成功返回 201 Created，未配置时返回结构化 503 Service Unavailable。
approval binding 语义仍冻结为围绕 subject_id、env、resource、action 建立；command_hash 继续作为 CLI/Agent 推荐绑定字段保留。
POST /api/v1/compose/import 当前最小输入是归一化后的 Compose fields 与可选 strict；生成报告成功时即使 passed=false 也返回 200 OK。
POST /api/v1/installer/actions 当前最小输入包含 task_id、action、resource、env；action 冻结为 installer.run.execute。correlation_id 可显式传入，也可缺省为当前请求上下文的 correlation ID。
/api/v1/databases 与 /api/v1/storage/objects 当前只承担只读可见性，不执行 query、上传、删除或 provider 管理。
/api/v1/aidb/query 当前应返回结构化 legacy-only / migration-needed 响应，而不是 raw 501。