refactor(data): establish API contract guardrails

docs/backend/api-contract-check.md

@@ -0,0 +1,30 @@
+# 前端 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` 执行。

docs/docker-image-ci.md

@@ -8,7 +8,7 @@
 
 | Workflow | 触发时机 | 职责 |
 | --- | --- | --- |
-| `.gitea/workflows/ci.yml` | `dev`、`main`、`test` push / PR | 安装依赖、执行完整质量检查并校验 bundle 预算 |
+| `.gitea/workflows/ci.yml` | `dev`、`main`、`test` push / PR | 安装依赖、执行完整质量检查、Python 后端 OpenAPI 差异检查、移动端 smoke，并校验 bundle 预算 |
 | `.gitea/workflows/docker-image.yml` | `main`、`test` push / 手动触发 | 构建 Docker 镜像、推送到镜像仓库，并通过 SSH 部署 |
 
 这样可以避免所有开发分支都发布镜像，并确保生产镜像通过发布门禁。
@@ -33,6 +33,7 @@
 | `REGISTRY_PACKAGE_NAME` | `cozsweet-web` | 可选；Registry 镜像名不含 owner 或包名不一致时用于指定 package name |
 | `TEST_ENV_FILE` | `.env.local` 的完整内容 | 测试环境构建期环境变量 |
 | `PRODUCTION_ENV_FILE` | `.env.production` 的完整内容 | 生产环境构建期环境变量 |
+| `BACKEND_OPENAPI_SOURCE` | `https://api.example.com/openapi.json` | 可选；CI 用于检查 Python 后端是否仍公开前端依赖的 method/path |
 
 Next.js 的 `NEXT_PUBLIC_*` 会在构建期固化到产物中，因此测试环境和生产环境会分别构建镜像。