契约与版本

两份文件

	主契约 `openapi.yaml`	BaaS `baas-app-v1.yaml`
角色	仓库实现清单	下游接入合同
内容	Admin + 已落地的 App 路径	App/BaaS 全量能力地图
质量门槛	有路径就必须已实现（零 stub）	可以先于实现冻结
变更	随代码合入	v1 只增不改；破坏性开 v2

合流方式：某波 BaaS 落地后，路径进入主契约并带实现；baas-app-v1.yaml 仍作为下游目录保留摘要。

一致性测试

platform/server/internal/contracttest 核对：

OpenAPI 声明的路径
internal/transport/router.go 实际挂载
skeleton manifest（若该路径受清单管理）

改路由或改契约必须让这组测试通过，CI 会阻断不一致。

版本策略

BaaS v1 已评审冻结；路径与字段以 docs/openapi/baas-app-v1.yaml 为准。
新增字段、新路径：additive，不改旧语义。
改路径、改必填、改错误码语义：新开 baas-app-v2，与 v1 并行。
主契约 info.version 随仓库迭代，以文件为准。

本站怎么维护

文档站只写分组与约定，不抄全量 schema。路径数量会变，页面用「以仓库 YAML 为准」，避免过期数字。