feat(ai): 内部 HTTP 端点 + 服务票校验 + 契约漂移守卫（166 测试）

按 openapi-internal.yaml 落地两个端点与鉴权，全部离线可测。

**鉴权（app/api/auth.py）**是这一层的安全边界，三条纪律各有测试：
- **强制校验 aud 与 iss**（交给 pyjwt 强制，不解出来自己比——自己比容易漏掉
  「claim 不存在」那一路）。这是独立密钥对方案唯一的意义所在：Java 侧现有的
  JwtVerifier 只验签名、不校验 aud，正因如此才必须独立密钥；若本服务也只验签名，
  那对独立密钥就白搭了。
- **额外强制 typ=service**，作为「有人误把用户密钥配到这里」的第二道防线。
- **缺公钥时全拒而非全过**。配置缺失必须立刻暴露，而不是变成一扇敞开的门；
  与 Java 侧 InternalAuthFilter 未配置 internal-token 时全拒 /internal/** 一致。
- 失败一律返回同一个笼统原因，**不告诉调用方是签名错/过期/aud 不符**——对方是
  我们自己的服务，真正原因在日志里；细节回给调用方只会在将来某天变成提示。

**三类失败分开**（契约核心）。第三类「任务失败」走 200 + state=failed + failure，
因为那种情况下 HTTP 调用是成功的；做成非 2xx 会让「查不到任务」与「任务失败了」
难以区分。另外两处刻意选择：
- 服务商 429 **不透传**，一律 502 + provider 信封。429 既可能是「等几秒」也可能是
  「等到明天」，状态码表达不了这个区别，retry 才是权威信号。
- 超出模型限制的请求归 service/invalid_request 而非 provider——请求**根本没发出去**，
  归到 provider 会让调用方以为是上游问题而去退避重试，而重试同样的参数永远不会变好。
- 服务商 404（含超出其 7 天保留期）归 service/task_not_found：调用方要做的是
  **停止轮询**，不是退避重试。
- 接管 FastAPI 默认的 {"detail": [...]} 校验错误，否则调用方要处理三种形状，
  而第三种还是框架实现细节。

**契约漂移守卫（tests/api/test_contract_drift.py，14 项）**：本项目开工审计已证明
「没有门禁的契约必然漂移」——四模块快照锁实际不存在，白名单 42/41 之误四份文档
一路不可见整整一个迭代。内部契约同样需要门禁。比对路径/方法/字段集/枚举/必填项，
**不比对字节**（永远不会相同，只会制造一个天天红然后被 skip 绕过的门禁）。

写这个守卫时它立刻抓到一处问题，但**问题在我的内省方式而不在应用**：本版本
FastAPI 的 include_router 会包一层内部 wrapper，路由并不平铺在 app.routes 上。
已改用 app.openapi()——它是「究竟暴露了什么」的权威视图，且不依赖框架内部结构，
否则这个门禁会在升级框架时莫名失效，而一个悄悄失效的门禁比没有门禁更糟。

**新增 pyproject.toml**：`Depends()` 放在参数默认值里正是 FastAPI 的标准写法，
ruff 的 B008 在此是误报。按 ruff 正规方式声明这些调用可安全求值，而不是在每个
端点上撒 noqa——后者迟早被用来压制真正的问题。

schemas 用 extra="forbid"：拼错的字段应当立刻报错而非被静默忽略，后者表现为
「我传了 durationSec 却没生效」这类极难查的问题。测试覆盖了 camelCase 与
user_id（契约刻意不含它）两种被拒情形。

新增依赖 fastapi / uvicorn / pyjwt[crypto]；测试 127 → 166。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

README.md

@@ -26,6 +26,49 @@ Patbond 的 AI 生成服务（Python）。负责调用 AI 服务商 API 完成
 - Java 主动轮询本服务查询进度；回调是将来的可选优化，当前不启用。
 - 请求体**不含 `userId`**（数据最小化）：完成工作只需 `jobId`、生成参数与预签名上传地址。
 
+## 运行
+
+```bash
+cp .env.sample .env      # 填入实际值；.env 已被 gitignore
+python -m app            # 默认 127.0.0.1:8000
+```
+
+**只监听回环**是默认：本服务只接受来自 `patbond-creation` 的内部调用，不该对外
+可达（与项目「默认拒绝、需要外部访问时经 nginx 反代」的纪律一致）。
+
+探活：`GET /health`（**在 `/internal` 之外，不需要服务票**）。它会报出实际装配了
+哪些适配器——缺服务商凭证时适配器不装配，而那个症状（任务永远排队）离根因很远，
+让探活直接说出来能省很多排查时间。
+
+## 接口
+
+| 端点 | 说明 |
+| --- | --- |
+| `POST /internal/generation/tasks` | 提交任务，返回**服务商**任务 ID |
+| `GET /internal/generation/tasks/{provider_request_id}` | 查询任务 |
+| `GET /health` | 探活，无需服务票 |
+
+**权威契约是仓库根目录的 `openapi-internal.yaml`**（手写），不是 FastAPI 自动生成
+的 `/openapi.json`（后者仅供调试，交互文档已关闭）。两者的一致性由
+`tests/api/test_contract_drift.py` 守着——比对路径、方法、字段集、枚举取值与必填项，
+**不比对字节**（那永远不会相同，只会制造一个天天红然后被 skip 绕过的门禁）。
+
+### 三类失败必须分开
+
+| 类别 | 形态 | 调用方该做什么 |
+| --- | --- | --- |
+| `service` | 非 2xx + `error.kind = "service"` | 我方 bug 或配置问题。除 `internal_error`/`provider_unavailable` 外不该重试 |
+| `provider` | 非 2xx + `error.kind = "provider"` + 完整分类 | **一律以 `retry` 字段为准**，不要自己解读厂商码 |
+| 任务失败 | **200** + `state = "failed"` + `failure` | 同上看 `retry` |
+
+第三类刻意不走错误通道：查询一个失败的任务，**HTTP 调用是成功的**，失败的是任务。
+做成非 2xx 会让「查不到任务」与「任务失败了」难以区分。
+
+判别字段是 `error.kind`，**不是 HTTP 状态码**——状态码在两类之间会撞。
+
+`provider` 信封与 `failure` 的分类字段**故意完全一致**，故调用方可复用同一段处置
+逻辑，不必为「提交时被限流」与「任务失败于限流」写两套分支。
+
 ## 代码结构
 
 分四层，依赖**单向**向内（`config` → `providers` → `domain`），由
@@ -98,7 +141,9 @@ app/
 
 ## 本地门禁
 
-与 CI 同一套命令（`.gitea/workflows/ci.yml`）：
+与 CI 同一套命令（`.gitea/workflows/ci.yml`）。**逐条分开跑并读各自的退出码**——
+`ruff check . | tail -1; echo $?` 读到的是 `tail` 的退出码，会把一次真实的 lint
+失败读成通过（本仓已因此红过一次）：
 
 ```bash
 sh scripts/check-secrets.sh --all   # 凭证防泄漏全量自查