6 Commits

Author	SHA1	Message	Date
lixi	541376e9be	fix(ai): 按官方 Error codes 页重写 OpenAI 错误映射 ... 拿到 doc_temp/gpt错误码.md 后核对，**此前猜的六个键里错了五个**： rate_limit_exceeded / moderation_blocked / content_policy_violation / invalid_api_key / image_generation_user_error 在官方文档里都不存在。真实的是 type rate_limit_error + code slow_down、type service_unavailable_error + code server_is_overloaded、四个 billing 码。唯一对的 insufficient_quota 也是宽 type 而非 code。这段历史留在 errors.py 顶部，作为凭记忆列错误码表代价的记录。 官方表的 13 条全是基础设施与计费，**没有任何内容审核/侵权码**——但图片接口确有 moderation 参数，说明审核存在、只是错误形态未文档化。直接后果：一次侵权或违规 拒绝很可能以普通 400 到达，只带一句人类可读消息。若一律归「服务端错误」，用户会 看到「服务出错了」并反复重试一个注定被拒的提示词。 故用 error.param 的有无做结构化区分（带 param = 参数错，不带 = 按内容被拒）， 三条依据：文档的 service_tier 那条明确说参数错会带 param；内容拒绝不指向任何 具体参数；我方已在调用前校验过尺寸/画质/格式，能被 400 拒掉的参数嫌疑本就不大。 这一条是推断，走到时记 WARNING——那是日后校正它的唯一素材。client.py 相应补上 param 的解析。 两处顺带收获： - 无 code 的 429 按限流处理，现在是**文档支持的默认**（六种 429 里只有「Rate limit reached for requests」没有文档化的 code），不再是猜测。 - 文档提醒视频过载已从 429 改判为 503。我们两者都归可重试，故不受影响；加了一条 测试钉住这个「无影响」。 同一张表按 code 与 type 两个字段分别查：文档把标识列在哪个字段下，不保证响应里 它就在那个字段，查错的代价是把配额耗尽降级成限流、白烧一轮重试预算。 未接 Retry-After 并记录理由：Java 侧退避基线 30 秒、上限 10 分钟，已长于服务商 通常给的值，忽略只会偏慢、不会加剧限流；接它是一次跨语言契约变更。 测试 271 → 284。四道门禁逐条读退出码，全绿。	2026-09-21 15:52:25 +08:00
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	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	4762358f54	fix(security): 凭证扫描放行依赖注入传参 + 四仓口径更正 ... `api_key=volcengine.api_key` 这类**依赖注入传参**被 KEY-ASSIGN 判为疑似凭证。 这是规则的真缺口而非代码问题：行里没有任何秘密，而做 DI 的代码到处都是这种 写法——绕过一次就得在每个调用点绕过，那等于把规则废掉。故改规则。 新增 ALLOW_REFERENCE，刻意收得很紧以免开后门： - 值必须是**未加引号**的小写起首标识符引用（真密钥要么带引号，要么不是标识符形状） - 只允许**恰好一个点且随即行尾** - 连字符不在字符集内 对抗性夹具验证（三真三假）： - 拦下 `api_key = "sk-T3Blbk…"`（OpenAI 形态） - 拦下 `secret_key: "AKID…"`（腾讯云形态） - 拦下 `auth_token=eyJ….eyJ….Sfl…`（**三段式 JWT——两个点，故不落进放行**） - 放行 `api_key=lowercase.reference` / `api_key = settings.api_key` / `api_token: config.authToken` 原 5 形态泄漏夹具复验仍 8 条命中，一条不少。 另更正口径：脚本头与 git-workflow.md 仍写「三仓同构」，实际已是四仓—— patbond-ai 是唯一持有 AI 服务商凭证的仓，漏同步它风险最大。四仓 md5 已一致 （4945940093b4b8413b7d3eec8bf6a5ec），四仓 --all 全绿。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-09-20 12:18:18 +08:00
lixi	6990709124	chore: 建仓门禁四件套——CI、防泄漏脚本与钩子、gitignore、职责边界 README ... patbond-ai 纳入发布语义（ADR-023 §12）。本仓是四仓中唯一直接持有 AI 服务商凭证的仓库，因此不得成为唯一没有防泄漏门禁的仓库——建仓即配齐， 不等代码落地。 - .gitea/workflows/ci.yml：ai-gates 作业，push(dev) + pull_request 双触发， 与另三仓同构。Secret scan 为第一个 step 且先于任何依赖安装。 pip 走腾讯云镜像（与 patbond-doc 装 mkdocs 同一策略）。 门禁命令 ruff format --check / ruff check / pytest，对应 flutter 仓的 dart format + analyze + test 三步。requirements*.txt 落地前只装工具本身， 使 CI 自建仓第一天即为绿；pytest 无测试时退出码 5 视为通过。 - scripts/check-secrets.sh：四仓同构副本，md5 640994c12bfa78b4512e872d709ed685。 已覆盖 AI 服务商密钥形态（sk-ant- / sk- / sk-proj- / sk-svcacct-）与 api_key/auth_token 实值赋值——本仓正是这些规则的主要适用对象。 - scripts/hooks/pre-commit：与另三仓同构。四仓 core.hooksPath 均已启用， ADR-023 §12 登记的「防泄漏第一层从未生效」至此闭环。 实测验证：含 5 种真实凭证形态的 .env 夹具被钩子拦下，提交未产生。 - .gitignore：Python 产物与工具缓存；凭证载体（.env / credentials* / *.pem / *.key）一律排除，占位样例走 .env.sample（对应脚本的 DENY_NAME_OK）。 - README.md：职责边界（不访问数据库、不持有对象存储凭证、对上游同步异步 一律对外呈现为异步）、与 Java 侧的接口约定（REST 非 gRPC、独立 openapi-internal.yaml、服务身份 JWT 独立密钥对、请求体不含 userId）、 本地门禁命令与凭证纪律。细节以 ADR-023 为准。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-09-18 16:42:34 +08:00
lixi	172f7d7537	first commit	2026-09-17 15:28:15 +08:00