GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(puzzle): record reference asset upload flow

Browse Source
This commit is contained in:
kdletters
2026-05-21 19:22:51 +08:00
parent 5834a99107
commit fda916ac63
6 changed files with 24 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
.hermes/shared-memory/decision-log.md
View File

@@ -25,10 +25,19 @@
- 验证方式：执行 `cargo test -p api-server external_api_audit --manifest-path server-rs/Cargo.toml -- --nocapture`、`cargo test -p api-server openai_image_generation --manifest-path server-rs/Cargo.toml -- --nocapture`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`。
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
## 2026-05-21 拼图参考图主链改为 OSS assetObjectId 与只读签名 URL
- 背景：release 上拼图图生图生成草稿时，旧链路把上传图转成 Data URL/base64 放进创作 action JSON body，容易先触发 Nginx `413 Request Entity Too Large`，也让外部模型调用前的 HTTP body 过大。
- 决策：浏览器参考图先通过资产直传票据上传 OSS，并确认 `asset_object`；拼图 action 主链只提交 `referenceImageAssetObjectId(s)`。`api-server` 按当前登录用户校验 asset owner、bucket、kind、图片 MIME 和大小后签发 OSS 只读 URL，传给 VectorEngine 的 generation fallback 使用；需要 edits multipart 时由后端用该签名 URL 拉取字节，不再让前端把图片塞进 JSON body。
- 兼容边界：旧 `referenceImageSrc(s)` Data URL 与历史 `/generated-*` 路径仅保留给旧草稿、旧入口和迁移期请求；调大 Nginx `client_max_body_size` 只作为兼容兜底，不是长期创作主链。
- 影响范围：拼图创作前端、`packages/shared` / `shared-contracts` action DTO、`api-server` 拼图 VectorEngine 编排、资产确认和 `spacetime-client` 资产读取 facade。
- 验证方式：前端 payload 中 AI 重绘优先出现 `referenceImageAssetObjectId(s)` 且 `referenceImageSrc(s)` 不再携带 Data URL；后端 `puzzle_vector_engine_generation_prefers_signed_reference_url`、`puzzle_reference_image_sources_prefer_asset_object_ids`、`puzzle_asset_object_reference_requires_matching_owner` 通过。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
## 2026-05-21 Nginx 通用 API 入口放行创作参考图请求体
- 背景：release 上拼图结果页重绘动作携带参考图 Data URL 时，Nginx access log 出现 `413`、`request_time=0.000`、`upstream_status=-`，说明请求被反代层默认 1 MiB 上限拦截，未进入 `api-server`。
- 决策：发布、开发服和容器 Nginx 模板的通用 `location ~ ^/api(?:/|$)` 统一设置 `client_max_body_size 64m`。该值只作为反代放行上限，具体业务请求体和图片字节上限继续由 `api-server` 路由 `DefaultBodyLimit` 与业务校验控制，不能替代接口级限制。
- 决策：发布、开发服和容器 Nginx 模板的通用 `location ~ ^/api(?:/|$)` 统一设置 `client_max_body_size 64m`。该值只作为反代放行和旧 Data URL 请求兼容兜底，具体业务请求体和图片字节上限继续由 `api-server` 路由 `DefaultBodyLimit`、OSS asset 确认和业务校验控制，不能替代接口级限制；拼图参考图长期主链见同日 `OSS assetObjectId` 决策。
- 影响范围：`deploy/nginx/genarrative.conf`、`deploy/nginx/genarrative-dev-http.conf`、`deploy/container/nginx.conf`、Nginx README、生产运维文档和 release 排障口径。
- 验证方式：目标机 `nginx -T 2>/dev/null | grep client_max_body_size` 应看到 `client_max_body_size 64m;`；大于 1 MiB 的参考图请求不再在 Nginx 层直接 413，access log 应出现有效 `upstream_status`。
- 关联文档：`deploy/nginx/README.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。