2 Commits

Author	SHA1	Message	Date
lixi	8275a04903	feat(ai): 接入 gpt-image-2 图片生成（文生图 + 图生图） ... 新增 app/providers/openai/：client 传输（JSON + multipart）、errors 错误映射、 models 厂商 DTO、capabilities 尺寸算术约束、tasks 同步→异步桥、image 图片业务。 装配与配置同步接入，缺 OPENAI_API_KEY 时跳过装配、服务仍可启动。 与火山视频的三处根本差异及其处置： - 接口同步（无任务 ID、无查询端点）→ SyncTaskRegistry 在本服务内部吸收， 对外仍是 ADR-023 §4 的两段式提交/轮询。代价：本服务从此持有状态，进程重启 丢在途任务，且横向扩容前须先解决任务 ID 只在签发进程内有效的问题。 - 产物是 base64 字节而非 URL → 无过期问题，但字节只在内存里。asset_url 放 data URI 仅为满足领域不变式，绝不能原样写进 media.assets.external_url。 - 图生图走 multipart → 先下载参考图再上传；下载失败与超限按参数错误同步拒绝， 不变成注定失败的后台任务。 两处需要记住的判断： - 尺寸上限「3840x2160」文档未说清是逐边还是按像素。逐边理解会禁掉所有高于 2160 的竖图，而 1024x1536 是文档明示的标准竖图，故必然过严。采用最长边 ≤3840 且总像素 ≤3840×2160，已在 capabilities.py 与取证页标为推断。 - 两份文档都没有错误码表，故 errors.py 以 HTTP 状态码为主、type/code 为辅， 顶部标注「未经文档证实」。429 无线索时按限流而非配额耗尽（猜成配额会把可 重试的限流判死）；400 无线索时归服务端错误而非内容被拒（错报会让用户去改 一个其实没问题的提示词）。 一处死锁已修并回归钉住：SyncTaskRegistry 原用 add_done_callback 记录完成时刻， 而快速完成的任务在注册时已 done，回调便同步地在持有非可重入锁的线程里执行。 改为首次被观察到时惰性记录。 测试 166 → 271（+105）。四道门禁逐条读退出码，全绿。 产物转存仍阻塞于存储决策（ADR-023 §7），图片模型因此未播种进 V7 目录。	2026-09-21 12:10:07 +08:00
lixi	fd23dfc0b9	feat(ai): 内部契约 openapi-internal.yaml + 像素对照表（127 测试） ... 按用户拍板的四点定型 Java↔Python 的 JSON 契约。 **① 字段命名 snake_case**（与对客户端的 camelCase 契约不同，有意为之）：本服务是 Python，snake_case 使 JSON 与领域 dataclass 字段逐一对应、无需转换层；Java 侧只需 在这一个 Feign 客户端上配置命名策略。用 camelCase 反而要在两端都加转换。 **② 两类失败分开**，判别字段是 `error.kind` 而非 HTTP 状态码： - `service`（Java↔Python）：unauthenticated / invalid_request / task_not_found / provider_unavailable / internal_error。属我方 bug 或配置问题。 - `provider`（Python↔服务商）：非 2xx + 完整分类（retry / user_facing / provider_code / message），字段与 Failure 一致，故 Java 侧可复用同一段处置 逻辑，不必为「提交时被限流」和「任务失败于限流」写两套分支。 - **任务失败是第三类，走 200 + state=failed + failure**：查询一个失败的任务， HTTP 调用本身是成功的。做成非 2xx 会让「查不到任务」与「任务失败了」难以区分。 **③ 像素对照表已实现**——此处需更正一个理解：该表**不需要查询任何东西、也不依赖 存储方案**。它是纯静态数据（官方文档「不同宽高比对应的宽高像素值」一节），厂商 查询响应已返回 ratio 与 resolution，查表即可，无需下载产物或解码。故 widthPx/heightPx 在 AI 视频产物上可零成本填真值（ADR-023 §11）。 实现上一个关键观察：**2.5 与 2.0 的 24 格里只有两格不同**（480p 的 16:9 与 9:16），其余完全一致。故写成「共享表 + 两格覆盖」，而非抄两份 24 行——后者每次 改动要改两处，迟早只改一处。另 4k 六格仅 2.0 有。 查不到时返回 None 而不猜（ratio=adaptive、未知模型族、该模型不支持的组合三种 情形）：一个错的尺寸会让客户端按错误比例渲染，且看不出是错的。 连带给 SeedanceTask 补解析响应里的 model 字段——同一适配器实例可能同时处理两个 模型族的任务，按响应里的实际模型定族才对。 **④ 路径参数用服务商任务 ID**，并在契约里写明原因：本服务不持有状态，唯一能用来 问服务商的就是这个 ID；用 job_id 就得存一份映射，「无状态」不再成立，且会多出 一个「Java 有 ID 但查不到任何东西」的中间态。你指出的那点完全对——submit 会阻塞 一次到服务商的短往返才能拿到 ID，但服务商的提交接口本身是异步的（只入队即返回）， 所以这一跳很快。契约里也如实登记了那个**无法消除的窗口**：该调用超时时 Java 拿 不到 ID 而服务商可能已创建任务，无幂等键可用，只能由 max_attempts 兜住。 测试 123 → 127：旧的「像素刻意留空」断言已作废，换成断言真实换算，并覆盖两族 差异的那两格、4k 仅 2.0、adaptive 与未知模型族的留空回退。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-09-20 16:26:49 +08:00