2 Commits

Author	SHA1	Message	Date
lixi	062e11b1ff	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>	2026-09-20 16:59:44 +08:00
lixi	c6e8dddc8d	feat(seedance): 火山方舟视频生成客户端与错误分类（58 测试，全离线） ... 按用户提供的三份官方文档适配 Seedance 视频生成：提交 （POST /contents/generations/tasks）与查询（GET .../tasks/{id}）。 取证记录见 patbond-doc docs/development/providers/volcengine-seedance.md。 **开工前问的五项，两项与原假设不同：** 1. **不支持幂等键**。请求参数全集里没有任何幂等字段。故 ADR-023 §4 设想的 「把我方 idempotency_key 透传为厂商幂等头」对本供应商不成立，「提交超时后 不知道有没有扣费」只能由 max_attempts 兜住——如实登记，不假装解决。 两点减轻：提交是异步的（只入队即返回，超时概率低）；且厂商支持 callback_url， 孤儿任务会通过回调把 ID 送回来，故回调在此供应商上还是**孤儿回收通道**， 不只是延迟优化——这是 ADR-023 §4「回调仅预留」之外的新论据，值得复评。 2. **产物是有效期 24 小时的 URL**（2.5 另有 100 次下载上限）。因此厂商 URL **不能当存储用**：存进 media.assets.external_url 会在 24h 后变死链。 **这对挂起中的存储决策是硬约束**——无论选本地还是云，都必须在 24 小时内 把文件复制到我们自己的存储。 其余三项：查询接口只保留 7 天记录；无明确频率数值，但官方 SDK 示例用 10s 轮询 （我们的 3s/10s/30s 阶梯与之兼容）、客户端截止 30 分钟（建议据此把 ADR-023 §10 的视频客户端超时从 15~20 分钟对齐到 30 分钟）；execution_expires_after 范围 [3600, 259200]，实现取下限 1 小时（厂商默认 48h 对交互式应用过长，且无法更短）。 **两个文档自身的问题，实现按宽的那份：** - **状态枚举不一致**：查询文档列 5 个（queued/running/cancelled/succeeded/ failed），创建文档的回调一节额外列 **expired**。只按查询文档实现会让超时 任务掉进未知分支。按 6 个实现，expired 视为**可重试**失败（是超时不是内容 问题），且厂商 expired 时不一定给 error.code 故单独分类。 - **QuotaExceeded 一码两义**：同一 code 既表示「排队任务数超限」（等几秒） 又表示「额度耗尽」（等到明天或充值）。按 code 一刀切必然有一半场景的文案 和出口是错的；只能按 message 判别，两条用例都在测试里钉住。 **顺带拿到两个免费收益**：last_frame_url 可直接作视频封面（iteration-4/03 R13 把缩略图列为视频成本项，实际免费）；查询返回 ratio/resolution/framespersecond/ duration，**Worker 写产物时维度与时长都在手里、无需解码**——widthPx/heightPx 债在 AI 产物上可零成本修掉。 一处精度陷阱已处理：返回的 duration 是「帧数/24 向下取整」的约数（133 帧实际 5.54s 返回 5），且 duration 与 frames 只返回其一。故优先按 frames/fps 精确换算， 只有 duration 时退回整数秒并标注为约数，缺失时返回 None 而非编 0。 取消语义已查明：厂商**只支持取消 queued 状态**的任务，故我方取消已 running 的任务无法向厂商传导，**仍会计费**。ADR-023 §6 关于取消的说明据此可定稿。 测试 58 项（错误分类 32 + 客户端 26），全部离线用 httpx MockTransport， 夹具响应体逐字取自官方文档示例以免字段名对不上。 过程中防泄漏钩子拦下了测试夹具里的 `api_key="test-key"`——规则是对的（这正是 真实密钥最常见的泄漏形态），故改用 ALLOW 清单认可的占位词，未放宽规则。 未实现：产物转存（阻塞于存储决策）、HTTP 服务端点与 openapi-internal.yaml。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-09-20 11:51:37 +08:00