# 前端 API 契约检查

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

## 本地检查

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

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

也可以使用环境变量：

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

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

## CI 配置

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