lixi
0b0317415b
CI / docs-build (push) Successful in 39s
记录从官方文档实际读到的事实，供实现与排查引用，并把开工时「待服务商文档确认 的五项」逐条落定。实现在 patbond-ai（58 测试）。 要点（详见正文）： - **不支持幂等键**：ADR-023 §4 设想的「透传为厂商幂等头」对本供应商不成立， 风险窗口只能由 max_attempts 兜住。但厂商支持 callback_url，孤儿任务会通过 回调把 ID 送回——回调在此供应商上是**孤儿回收通道**而非仅延迟优化， §4「M4 只做轮询」值得据此复评。 - **产物 URL 仅 24 小时有效**（2.5 另有 100 次下载上限）：厂商 URL 不能当存储 用，存成 external_url 会变死链。**这对挂起中的存储决策是硬约束**——无论选 本地还是云，都必须在 24 小时内把文件复制到我们自己的存储。 - **两处文档自身的矛盾**已登记并按宽实现：状态枚举在查询文档与回调说明里 不一致（后者多一个 expired）；QuotaExceeded 一码两义（排队超限 vs 额度耗尽， 只能按 message 判别）。 - 两个免费收益：last_frame_url 可直接作视频封面（R13 把缩略图列为视频成本项， 实际免费）；查询返回 ratio/resolution/fps/duration，Worker 写产物时维度与 时长在手、无需解码，widthPx/heightPx 债在 AI 产物上零成本可修。 - 取消语义：厂商只支持取消 queued 状态，已 running 的任务取消后仍计费。 - 用户提供的两份文档**文件名与内容装反了**（火山错误码.md 里是查询 API）， 已按实际内容归档并注明，避免他人按文件名读错。 另：V7 目录种子仍待确认账号实际开通的 model ID——文档里的示例值不能直接当种子， 否则 provider_model_name 会指向无权访问的模型（InvalidEndpointOrModel.NotFound）。 验证：secret-scan exit 0；mkdocs build --strict exit 0（已挂导航）。 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Patbond Doc
Patbond 的契约、架构决策与开发过程文档。用 MkDocs 构建成站点。
本仓是四仓中唯一的「正典」所在：契约、数据模型、架构决策以此为准。其余仓库中的同类内容都是副本或实现，冲突时以本仓为准。
权威文档在哪
| 文档 | 位置 | 说明 |
|---|---|---|
| 对外契约 | docs/api/openapi.yaml |
客户端可见的全部端点。升版须与 patbond-api 内的四份快照同步 |
| 数据模型正典 | docs/database/patbond_postgresql.sql |
已评审的目标模型。Flyway 迁移从中逐列摘取，任何偏离都必须在迁移文件头写明原因 |
| 架构决策 | docs/architecture/decisions.md |
ADR-001 起累积。改动实现前先读相关 ADR |
| 后端模块结构 | docs/architecture/backend-modules.md |
各模块职责与边界 |
| 发布记录 | docs/development/releases.md |
每次发布追加一条，含门禁结果与生效的流程纪律 |
| 功能清单 | docs/development/feature-checklist.md |
逐条功能的完成状态 |
| Git 与门禁 | docs/development/git-workflow.md |
分支、提交、CI 门禁与凭证防泄漏规范 |
| 真机验证清单 | docs/development/device-verification.md |
桌面不可替代的验证项，含逐项步骤与通过标准 |
| 服务器暴露面 | docs/development/server-exposure.md |
生产主机的端口、常驻服务与处置记录 |
| 迭代报告 | docs/development/iterations/ |
按迭代归档。存档不回改，结论失效时追加带日期的修正注记 |
本地构建
pip install mkdocs
mkdocs serve # http://127.0.0.1:8000
本地门禁
与 CI 同一套命令（.gitea/workflows/ci.yml）：
sh scripts/check-secrets.sh --all # 凭证防泄漏（ADR-021）
mkdocs build --strict # 必须 exit 0 且零 warning
--strict 会把死链和未挂导航的孤立文档判为失败，所以新增文档必须同时挂进 mkdocs.yml 的 nav。
每人每仓启用一次 pre-commit 钩子：
git config core.hooksPath scripts/hooks
scripts/check-secrets.sh 是四仓同构副本，调整规则时四仓同步提交。
写作纪律
- 常设文档不写死本机绝对路径，用
<你的工作区>/patbond-xxx之类的参数化写法；迭代报告存档豁免。 - 迭代报告是时点存档，不回改。结论后来被推翻时，在原文下方追加带日期的修正注记并指向新依据——改掉原文等于销毁历史记录，而追加注记同样能掐断转述链。
- 不要引用别的报告的转述结论。本项目已多次因此误判：某报告写「无 nickname 字段」实指「契约未暴露」，被下游当成「缺列需迁移」，规模预估高估一整档。凡「XX 不存在 / XX 缺失」的判断，请打开原始 SQL、原始契约、原始源码确认，并注明核实的文件与行号。
site/是构建产物，已被.gitignore排除，不要提交。
相关仓库
| 仓库 | 内容 |
|---|---|
patbond-api |
Spring Boot 多模块后端 |
patbond-flutter |
Flutter 客户端 |
patbond-ai |
AI 生成服务（Python），只调服务商 API |