清理后端未使用代码及废弃测试

删除编辑器旧分段持久化、生成任务收尾和音频发布链路删除未使用辅助函数及其专属测试，修正受影响的现有测试边界保留现役实现，将纯退款测试辅助函数移入测试模块同步原子提交、角色生成文档和计费验证说明验证：API 全目标编译零警告，格式、编码和 diff 检查通过定向测试：391 项通过，11 项退款 outbox 测试失败，含 Windows 权限错误
2026-09-23 02:52:01 +00:00
parent 85f2831f16
commit 20b594d4f2
23 changed files with 44 additions and 2710 deletions
@@ -1123,7 +1123,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - 现象：画板生成按钮显示 `N泥点`，后端也能按模型配置计算出价格，但用户点击后钱包余额不变。
 - 原因：前端展示价和后端价格计算只证明价格能被展示 / 解析；如果 handler 没有包进 `execute_billable_asset_operation_with_cost`，或异步音频发布目标没有携带本次模型价格，外部 provider 仍会被调用但不会真实扣费。
 - 处理：新增或改造编辑器外部生成入口时，确认前端请求不携带 `priceMudPoints`，后端按运行时模型定价重新计算价格，并用该价格进入资产扣费 wrapper。音频提交 / 发布分离时，把后端计算出的价格写入 `AudioAssetBindingTarget.billing_points_cost`。
- 验证：结构性测试覆盖对应 handler 包含 `execute_billable_asset_operation_with_cost` 和价格变量；音频测试覆盖 `resolve_creation_audio_points_cost` 优先读取 editor target 的 `billing_points_cost`。
+- 验证：结构性测试覆盖对应 handler 包含 `execute_billable_asset_operation_with_cost` 和价格变量；`worker_billing_context_freezes_charge_and_preserves_job_metadata` 与 `logged_in_background_music_queue_preparation_uses_canonical_prompt_and_frozen_price` 覆盖现役队列冻结价格，原子计费测试覆盖提交失败与结果未知时的退款边界。
 - 关联：`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、`server-rs/crates/api-server/src/vector_engine_audio_generation/`、`src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts`。

 ## 本地 dev 启动日志先看成功锚点，不要把非阻断 warning 当失败
@@ -77,6 +77,7 @@ EditorGenerationResultPersistInput {

 ## api-server 接入

+- 旧分段持久化、worker 独立完成及其重复结果序列化实现，在失去现役调用方后直接删除；不保留只供旧测试调用的生产副本。废弃实现的专属测试随实现删除，不因清理而将旧用例改接到现役函数；现有现役行为测试保持原有覆盖。手动拆分、上传等现役路径使用的底层 helper 继续保留，HTTP / DTO、inline 模式和历史任务解析兼容不受清理影响。
 - 通用持久化改为 `prepare -> build canvas candidate -> atomic commit`。prepare 阶段只生成稳定 ID、上传/验证对象和构造候选 DTO，不创建 resource/asset。
 - api-server 继续复用现有画布 completion / replacement 逻辑计算候选 `layers_json` 和 `expected_revision`；统一 procedure 在最终事务内重新执行既有 layout 校验和 CAS。
 - CAS 冲突只刷新当前 project、重新计算 layout 并重试 prepared commit；相同 operation、slot、对象和记录候选保持不变，禁止重跑 Provider。
@@ -65,7 +65,7 @@

 - 角色面板增加紧凑的 `像素艺术` 勾选项，请求使用可选字符串字段 `style`：未勾选传 `"none"`，勾选传 `"pixelArt"`。该选择可以随现有生成器快照和队列 payload 保存，但不写入用户可见 `generationInputs`、素材元数据或新建的持久化记录。
 - `style` 省略、为 `null`、空字符串或 `"none"` 时按内部 `None` 处理且不告警；`"pixelArt"` 在 `kind="character"` 时启用像素规整。未知字符串按 `None` 继续生成，并通过既有通用 `warning` 返回 `unsupported-image-style`；非字符串 JSON 仍返回 `400`。同一图片生成请求 DTO 被其它 `kind` 复用时，只有普通图片和 `character` 支持 `"pixelArt"`，其它 `kind` 收到该值也按不支持风格降级。
- 2026-08-01 修订：`"pixelArt"` 不再只是后处理，同时向提交给 provider 的提示词末尾追加独立一行约束。角色链路使用「角色主体为像素风格」，**不得**使用「画面为像素风格」——角色生成后要按纯色抠像，绿幕底必须保持平整，同一段提示词里已写死「纯色背景必须平整无纹理、无渐变」，画面级像素化要求会与之互相拆台；且该提示词已禁止出现角色以外的场景内容，因此只需点名角色本身。注入发生在 `build_editor_character_image_prompt` 返回之后，该函数签名和输出契约不变。约束句**不会**进入角色链路的任何 `editor_project_resource`：原图 resource 的 prompt 列存的是 `role_setting`（用户原文），透明结果的 `output_prompt` 在抠图成功后被无条件覆盖为 `"去除纯色背景"`；完整提交提示词是否留存取决于 provider：`persist_editor_provider_source_image` 写原图 asset object 元数据时用的是 `actual_prompt.unwrap_or(prompt)`，provider 未回 `actualPrompt` 时才存 `submitted_prompt`（含约束句），此时排障可按 `object_key` 查；provider 回了 `actualPrompt` 就存 provider 改写后的文本，该次生成的 `submitted_prompt` 在系统内一处都不落——外部 API 审计的 `request_payload` 只记 `promptChars` 字符数，没有提示词原文。响应体返回的是用户原文，前端显示不变。以上 prompt 列写入与 asset object 元数据规则都是既有行为，与 `web/master` 逐行一致，本次未改动。角色提示词里既有的「严格基于图1的角色美术视觉规范的美术风格」与像素约束存在潜在冲突，本次未改写，等实测。
+- 2026-08-01 修订：`"pixelArt"` 不再只是后处理，同时向提交给 provider 的提示词末尾追加独立一行约束。角色链路使用「角色主体为像素风格」，**不得**使用「画面为像素风格」——角色生成后要按纯色抠像，绿幕底必须保持平整，同一段提示词里已写死「纯色背景必须平整无纹理、无渐变」，画面级像素化要求会与之互相拆台；且该提示词已禁止出现角色以外的场景内容，因此只需点名角色本身。注入发生在 `build_editor_character_image_prompt` 返回之后，该函数签名和输出契约不变。约束句**不会**进入角色链路的任何 `editor_project_resource`：原图 resource 的 prompt 列存的是 `role_setting`（用户原文），透明结果的 `output_prompt` 在抠图成功后被无条件覆盖为 `"去除纯色背景"`；原图 asset object 元数据由现役 `prepare_editor_generated_image` / upload-only helper 按传入的 `prompt` 构造，resource / asset 的 `actualPrompt` 由原子提交候选单独保存；排障应核对现役调用参数与记录，不能再按已退役的 provider-source 分步持久化函数推断提示词来源。角色提示词里既有的「严格基于图1的角色美术视觉规范的美术风格」与像素约束存在潜在冲突，本次未改写，等实测。
 - 角色 provider 回图先按统一业务像素矩阵执行交付尺寸归一：允许无放大恢复时使用 Lanczos 重采样并居中裁切，无法安全恢复时保留 provider 实际尺寸并返回非阻断告警。归一后的带纯色背景图先持久化并作为 BgFilter 输入；BgFilter 正常成功后，把 Alpha 蒙版回贴到这张同尺寸平底原图，再执行像素规整并上传透明主图。网格分析源使用已收口到实际交付尺寸的平底原图，RGBA 采样源使用 Alpha 已回贴的透明图；软 Alpha 只参与单格覆盖率和 Alpha 加权 RGB 计算，输出 Alpha 硬化为 `0 / 255`。
 - 首版参数固定为分析色数 `16`、Alpha 覆盖阈值 `0.375`、像素格尺寸自动检测、固定色板关闭、K-means 最大采样 `262144`。单格覆盖率 `Σ(A / 255) / N >= 0.375` 且 `ΣA > 0` 时输出 `A=255`，颜色按 `Σ(A × RGB) / ΣA` 计算；否则输出 `[0,0,0,0]`。分析色数不限制最终输出色数。
 - 像素规整 CPU 工作使用进程级最大并发 `2`；取得并发许可的排队时间与实际处理时间共享最多 `30` 秒预算，同时不得晚于当前请求 deadline，最终以两者中更早者为准。输入图片任一边不得超过 `10000` 像素，总像素不得超过 `8294400`；超限、排队超时或处理超时均保留 Alpha 已回贴的透明图并走非致命降级。