前端 API 契约检查

本仓库只包含 Next.js 前端，Python 后端仍在独立项目中维护。前端实际调用的 HTTP method 与 path 统一记录在 src/data/services/api/api_contract.json，ApiPath 与 OpenAPI 检查共同消费这份清单。

本地检查

传入 Python 后端生成的 OpenAPI JSON 文件或 URL：

pnpm contract:check ../backend/openapi.json
pnpm contract:check https://backend.example.com/openapi.json

也可以使用环境变量：

BACKEND_OPENAPI_SOURCE=https://backend.example.com/openapi.json pnpm contract:check

检查会验证前端依赖的每个 method/path 是否仍由后端公开。路径参数名称不同（例如 {albumId} 与 {album_id}）不会产生误报。字段级兼容仍由前端 Zod Schema Model 测试负责，避免仅凭 OpenAPI 生成代码覆盖现有防御性解析规则。

在 Gitea Actions Secrets 中配置 BACKEND_OPENAPI_SOURCE 后，CI 会比较目标 Python 后端的实时 OpenAPI。未配置时 CI 会明确记录跳过原因，本地的比较器测试仍会随 pnpm quality 执行。