# patbond-ai

Patbond 的 AI 生成服务（Python）。负责调用 AI 服务商 API 完成图片与视频生成，
是四仓中唯一直接持有 AI 服务商凭证的仓库。

架构与边界的完整决策见 **patbond-doc `docs/architecture/decisions.md` ADR-023**。
以下为要点，改动前请以 ADR 原文为准。

## 职责边界

- **只负责调用 AI 服务商 API。** 不访问数据库——生成任务状态的唯一事实来源是
  Java 侧的 `creation.generation_jobs`。
- **不持有对象存储凭证。** 产物由 Java 下发预签名 PUT 地址，本服务直传后回报，
  再由 Java 核实并建 `media.assets` 行（即客户端两步上传，本服务站在客户端位置）。
- **对上游同步或异步一律对外呈现为异步**：`submit` 立即返回任务 id，同步型
  服务商（长连接等待返回）在本服务内部以后台任务承载。这样 Java 侧无长连接占线程，
  且 `provider_request_id` 立即可得，超时不再产生「是否已扣费」的歧义。

## 与 Java 侧的接口

- 传输为 **REST（JSON）**，非 gRPC（理由见 ADR-023 §4：避免引入第二套无门禁契约体系）。
- 契约为本仓内独立的 **`openapi-internal.yaml`**，独立版本号，
  **不进** patbond-api 的四模块快照锁，**也不写入**面向客户端的 `openapi.yaml`。
- 鉴权为 **服务身份 JWT**（独立密钥对，非用户 token 转发）：本服务强制校验
  `aud=patbond-ai` 与 `typ=service`。
- Java 主动轮询本服务查询进度；回调是将来的可选优化，当前不启用。
- 请求体**不含 `userId`**（数据最小化）：完成工作只需 `jobId`、生成参数与预签名上传地址。

## 本地门禁

与 CI 同一套命令（`.gitea/workflows/ci.yml`）：

```bash
sh scripts/check-secrets.sh --all   # 凭证防泄漏全量自查
ruff format --check .
ruff check .
pytest -q
```

**每人每仓启用一次** pre-commit 防泄漏钩子：

```bash
git config core.hooksPath scripts/hooks
```

`scripts/check-secrets.sh` 是四仓同构副本，**调整规则时四仓同步提交**。
它覆盖 AI 服务商密钥形态（`sk-ant-`、`sk-`/`sk-proj-`/`sk-svcacct-`）与
`api_key`/`auth_token` 实值赋值——本仓正是这些规则的主要适用对象。

## 凭证纪律

真实密钥**只允许存在于被 gitignore 的文件中**（`.env`），占位样例进 `.env.sample`。
拦下真实凭证时的第一动作是**去服务商控制台轮换/禁用该密钥**，然后才是清理提交。

## 分支与发布

`dev` 直推 + CI 绿，`main` 经 PR 合并。本仓纳入四仓 tag 同步与发布回归
（ADR-023 §12）。发布流程见 patbond-doc `docs/development/releases.md`。