From 413b3645c21d464accc5c6965760abfb871255ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= Date: Sat, 3 Oct 2026 16:39:01 +0800 Subject: [PATCH] =?UTF-8?q?docs(=E4=BC=9A=E5=91=98):=20=E8=A1=A5=E6=A8=A1?= =?UTF-8?q?=E5=9E=8B=E6=9D=83=E9=99=90=E4=B8=8E=E5=B9=B6=E5=8F=91=E4=B8=8A?= =?UTF-8?q?=E9=99=90=E7=9A=84=E5=AE=9E=E7=8E=B0=E7=8A=B6=E6=80=81=E4=B8=8E?= =?UTF-8?q?=E5=A5=91=E7=BA=A6=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 数据契约 external_generation_job 增补 2026-10-03 会员并发上限：新增 (owner_user_id, status) 索引、认领只算 running、过期回收豁免、缺行失败关闭到 Normal - 设计文档 §11.4 增补落地状态与提交号，并标注账号档位轻量读与客户端 403 重选提示为后续可选项 - decision-log 追加落地实现条目：实现拆分、Basic/Full 与 Normal 的失败语义、验证结论与边界 TODO --- docs/project-memory/shared-memory/decision-log.md | 11 +++++++++++ ...技术设计】泥点三池与会员计费后端设计-2026-10-02.md | 1 + ...端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md | 1 + 3 files changed, 13 insertions(+) diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 6d0c7a9d0..cafcb0a0e 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -9631,6 +9631,17 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在 - 影响范围：`docs/technical/【技术设计】泥点三池与会员计费后端设计-2026-10-02.md`（新增 §11，修订 §9/§10）、`CONTEXT.md`（并发上限 / 新增「独立生成任务」）、`docs/adr/【ADR】模型权限与并发上限的强制边界-2026-10-03.md`、`docs/README.md`。未改代码。 - 验证：`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`。 +## 2026-10-03 模型权限与并发上限落地实现 + +- 背景：承接同日「模型权限与并发上限的强制边界（拷问定案）」，把定案按 §11.4 编码约定落地；本文记实现拆分与验证，不再重复决策理由。 +- 实现（`module-runtime`，`b78003143`）：新增 `agc_model_access.rs`（`AgcModelAccess::Basic/Full`、`MODEL_NOT_AVAILABLE_FOR_PLAN`、`AgcModelResolveError::{Unavailable, NotAvailableForPlan}`、`RuntimeProfileMembershipModelAccess → AgcModelAccess`）；`AgcModel` 末位追加 `#[serde(default)] access`（存量 JSON 缺字段即 `Basic`，失败开放）；`AgcModelCatalog` 增加 `available_models_for / default_model_id_for / resolve_requested_for`，默认模型优先取登记项、不在档内则回退目录顺序首个可用项、无可用项返回 `Unavailable`。 +- 实现（`spacetime-module`，`db8d467b8`）：`external_generation_job` 追加 btree 组合索引 `(owner_user_id, status)`；`claim_external_generation_jobs_tx` 在 `pending → running` 前按 owner 现算 `running` 行数并过滤，达上限留在 `pending`；只算 `running`（含过期待回收），自身过期 `running` 回收豁免，`pending` 不占名额；`effective_profile_concurrent_job_limit` 走 `profile_membership.plan → concurrent_job_limit`，缺行失败关闭到 `Normal`（=1），`128` 为不限；抽取纯函数 `external_generation_claim_within_concurrency_limit` 并补单测。 +- 实现（后台，`919b4b01d`）：`AdminAgcModel` 新增 `access`（缺省 `basic`），api-server 保存时只接受 `basic/full`，`GET` 回读 / `PUT` 写入；后台「AGC 模型」页新增「权限档」列与选择器，fake API 与页面用例覆盖。 +- 实现（`api-server`，`9b1a538d2`）：新增 `llm/model_access.rs`，用现有 `get_profile_recharge_center` 解析账号档位到 `AgcModelAccess`，缺会员行 / 缺目录行 / 读失败统一失败关闭到 `Basic`；`GET /api/llm/models` 按档过滤且默认项取该档可用集合；`/api/llm/responses`、`/api/llm/chat/completions`、`/api/llm/anthropic/*` 全改按档解析；越权映射 403 + `MODEL_NOT_AVAILABLE_FOR_PLAN`，目录外 / 停用仍为 422。 +- 术语口径：`Basic` / `Full` 是模型对会员档的要求，`Normal` 等是会员档位；缺省语义统一「失败开放到基础档、失败关闭到 1 并发」——模型档缺省 `Basic` 是失败开放（不拦），并发上限缺行失败关闭到 `Normal`（=1）。 +- 验证：`cargo check -p api-server`、`cargo check -p api-server --tests`；`cargo test -p api-server llm` 49 passed、`model_catalog_tests` 3 passed（含 Basic 档过滤 Full 模型、403 错误码映射）；`npm run check:spacetime-schema` 的失败项全部是分支既有 `profile_membership` / `profile_recharge_product_config` 字段变更（对照 `origin/master` merge-base `25beb3ad5`），与本次仅新增 btree 索引无关，guard 不比较索引；`npm run check:encoding`、`git diff --check`。 +- 边界 / TODO：账号档位仍复用带周期刷新写入的 `get_profile_recharge_center`，后续替换为轻量专用读；AGC 客户端仍靠「目录按档过滤 + 本地选择对账回退默认项」，未加专门的 403 重选提示；统一「账号在飞生成」口径（含无 job 行的同步生成）仍为后续 TODO。 + ## 2026-10-03 会员链路错误分类改为机器可读错误码（typed error） - 背景：`api-server/src/runtime_profile.rs` 的 `is_runtime_profile_membership_domain_error` 用中文 `error_message` 前缀 / 精确匹配决定返回 400 还是 502；文案一改（或新增拒绝点）就静默退化，且分类逻辑与 module 的错误文案跨层重复。 diff --git a/docs/technical/【技术设计】泥点三池与会员计费后端设计-2026-10-02.md b/docs/technical/【技术设计】泥点三池与会员计费后端设计-2026-10-02.md index 46cc93b20..182072df7 100644 --- a/docs/technical/【技术设计】泥点三池与会员计费后端设计-2026-10-02.md +++ b/docs/technical/【技术设计】泥点三池与会员计费后端设计-2026-10-02.md @@ -609,6 +609,7 @@ flowchart TD - **`api-server`**：新增 `llm/model_access.rs`，用现有 `get_profile_recharge_center` 读出账号 `membership.plan` 与目录行 `model_access` 并映射到 `AgcModelAccess`；`GET /api/llm/models` 按档过滤，`/api/llm/responses`、`/api/llm/chat/completions`、`/api/llm/anthropic/*` 全部按档解析，越权返回 403 + 错误码 `MODEL_NOT_AVAILABLE_FOR_PLAN`。 - **后台**：`AdminAgcModel` 与后台「AGC 模型」页新增 `access` 字段（`basic` / `full`，缺省 `basic`），GET 回读、PUT 写入；**不做**自动播种或代码内清单。 - **性能说明**：本期账号档位复用现有 `get_profile_recharge_center` 读模型，它带幂等的周期刷新写入；后续可替换为更轻的专用读（TODO）。 +- **落地状态（2026-10-03）**：`module-runtime` 权限档与目录解析 `b78003143`；`spacetime-module` 并发索引与认领过滤 `db8d467b8`；后台 `access` 标注与页面 `919b4b01d`；`api-server` 按档过滤 / 校验 `9b1a538d2`。AGC 客户端侧仍以「目录按档过滤 + 本地选择对账回退默认项」为主，未额外新增针对 403 `MODEL_NOT_AVAILABLE_FOR_PLAN` 的专门提示，作为后续可选项。 --- diff --git a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md index f51a57277..9cd812614 100644 --- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md +++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md @@ -286,6 +286,7 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复 - Rust 结构体：`ExternalGenerationJob` - 源码：`server-rs/crates/spacetime-module/src/external_generation.rs` - 现役覆盖：worker claim 只允许 `source_module = editor-canvas`；任务领取、续租、阶段更新和结果完成必须携带并校验同一 `worker_id + lease_token`。 +- 2026-10-03 会员并发上限：新增 btree 组合索引 `by_external_generation_job_owner_status (owner_user_id, status)`。`claim_external_generation_jobs_tx` 在 `pending → running` 前按任务 owner 的 `profile_membership.plan → profile_membership_plan.concurrent_job_limit` 现算该 owner `status = running` 的行数（含租约过期待回收的 `expired_running`），达上限的 pending 保持排队；账号自身过期的 running 回收豁免上限，避免超限账号的卡死任务无法回收。`pending` 不占名额，失败退回 `pending` 会自然释放名额；不新增计数表。缺会员行按 `Normal`（上限 1）失败关闭，目录行缺失同样按 1；`128` 哨兵由 `is_unlimited_concurrency` 解释为不限。 - 用途：外部生成 worker 的内部持久任务队列；`GENARRATIVE_EXTERNAL_GENERATION_MODE=queue` 时，`api-server` HTTP 角色只入队，`external-generation-worker` 角色通过 claim lease 领取、续租、执行，并用 `lease_token` 栅栏回写阶段、完成 / 失败。队列行继续保存 worker 执行、计费与滚动发布兼容所需字段，末尾可选 `phase` 只取 `generating / processing`；claim 写 `generating`，真实进入抠图处理时由受 `job_id + worker_id + lease_token` 保护的 procedure 写 `processing`。phase procedure 以结构化结果区分 `LeaseFencingRejected` 与 `OtherRejected`；`LeaseFencingRejected` 立即终止，`OtherRejected` 以及 SDK 的 `Procedure` / `Runtime` 错误不重试，只有 `Build` / `ConnectDropped` / `Timeout` 在同一个 job attempt 内重试一次。该重试只重新上报 phase，不把任务写回 `pending`，也不重新调用 provider；编辑器 job 入队固定 `max_attempts=1`，第二次传输失败后任务进入 `failed`，不会回到 `pending` 或从 provider 生成起点重跑。用户可见任务列表、价格、状态、阶段、未确认终态数量和通知确认时间的正式读取事实源已经迁到 `external_generation_job_summary`；BFF 不得再为列表 / 详情 / acknowledge 读取该大表。图片画布编辑器的 `editor_image_generation`、`editor_image_edit`、`editor_background_removal`、`editor_icon_spritesheet_generation`、`editor_ui_design_asset_extraction`、`editor_character_animation_generation`、`editor_video_generation`、`editor_sound_effect_generation` 和 `editor_background_music_generation` 复用同一队列表。结构化 canvas 激活后，当前 worker completion 先以读取时 canvas revision 执行 CAS，并发冲突时拒绝覆盖并保留可诊断失败；目标是进一步收口为受 lease 栅栏保护的单事务幂等写入 `editor_project_resource`、结果 `editor_canvas_layer`、`editor_canvas_generation_dialog` 终态和 canvas revision。未激活 canvas 在 2 MiB 上限内继续走 `editor_canvas.layers_json` 兼容写回。前端只通过 BFF job 状态轮询和项目快照读取恢复完成态。`GENARRATIVE_EXTERNAL_GENERATION_MODE=inline` 时不创建该队列行，三个 external generation guard 字段必须同时为空才允许 api-server 受控同步写回，半空 guard 仍会拒绝。worker 成功写回业务事实后才能 complete job；业务失败态写回成功后才能 fail job，失败态未写回时保留租约等待后续重领。 - 2026-08-06 收口覆盖：上一条用途描述中“当前先 CAS、单事务仍是目标”的旧句已作废。现役编辑器生成不再组合调用 object confirm、resource create、asset create、canvas save 和 job complete。`api-server` 只准备稳定候选，再经 `spacetime-client` 调用 `persist_editor_generation_result_and_return`；procedure 在同一 `try_with_tx` 内写入可选 `asset_object`、全部 `editor_project_resource`、`editor_asset`、可选 `asset_entity_binding`、可选 canvas V2 CAS、queue job 终态和 `editor_generation_operation` receipt。结构化 canvas 的 layer / dialog / revision 与未激活 canvas 的 legacy `layers_json` 仍经既有 V2 布局验证分流，前端不直接发明正式完成态。queue 首次提交在同一快照验证 owner、job kind、request fingerprint 和有效 `job_id + worker_id + lease_token`；统一 procedure 已完成 job 后 worker 不得再单独 complete。 - 载荷约束：本次先对 `source_module = editor-canvas` 的 `request_payload_json` / `result_payload_json` 实施有限大小合法 JSON、任意层级禁止 `data:` / `blob:` 的双层门禁，只保存 worker 执行必需的普通参数和已登记媒体引用。画布 Agent 来源的任务可在 `result_payload_json.editor-agent-tool-call-result` 中保存有界的轻量结果和已登记媒体引用，供后端按已有 `externalJobId + owner_user_id` 定向懒回填；其它编辑器任务保持元数据结果，并可保存有界的 `warning.code/reason`。未登记的 source module 不由本次门禁静默改变既有请求契约。该主表只供 worker claim / 执行、受控维护以及画布 Agent 的定向结果回填读取；正式用户任务列表、单任务状态、队列概览与 acknowledge 不得返回或解析这两个 payload。画布 Agent 懒回填必须经对应工具 formatter 归一为有界轻量媒体引用后写入 OSS 会话，不能把原始 payload 直接透传前端。