修正音频时长缺省导出断言

更新画布素材导出测试，缺少展示字段时不再期待时长占位值。明确素材详情与 ZIP 元数据只透传 generationInputs.fields 中实际存在的时长。同步后端架构文档与共享决策记录。
2026-08-05 16:31:17 +08:00
parent 1693047fc9
commit c76d0a8835
3 changed files with 4 additions and 3 deletions
@@ -5809,7 +5809,7 @@

 - 决策：`assetKind` 是编辑器资源和素材唯一权威媒体类别；不新增或返回 `mediaType`。`character-animation` 渲染为序列帧，`video` 渲染为视频，`audio/sound-effect/background-music` 渲染为音频，其余类别渲染为图片。前端内部可保留派生的 `CanvasMediaType` 选择渲染器，但不能把它作为后端事实。
 - 持久化边界：`editor_project_resource` 与 `editor_asset` 表尾只保存 `image_sequence_frames_json` 与 `image_sequence_duration_ms`，默认均为 `None`；`editor_showcase_asset` 作为提交时冻结的审核与公开快照，同样在表尾保存这两个字段并从账号素材逐字段复制，旧行默认均为 `None`。正式帧对象和角色动作生成响应都不保存或返回 `frameIndex`，数组位置是唯一播放顺序；帧数取数组长度，FPS 由帧数和毫秒时长即时推导，不持久化 `frame_count`、`fps` 或通用 `duration_seconds`。后端处理抽帧和逐帧去背时仍保留内部 `frame_index`，仅用于乱序并发收口、OSS 命名、日志和错误定位；仓库内旧 helper 同步升级，不为它保留外部兼容字段。
- 时长口径：`image_sequence_duration_ms` 只表示角色图片序列完整播放一次的毫秒时长，与音频 / 视频生成请求中的 `durationSeconds` 完全分离。角色动作与视频生成响应仍可携带各自既有的请求 / 结果级 `frameCount/fps/durationSeconds`；通用音视频秒数不进入资源 / 素材正式列、`EditorAsset`、`CanvasLayer` 或画布 layout，只允许把上传探测值或生成请求值格式化为用户可见字符串后写入 `generation_inputs_json.fields[]` 供素材详情展示。素材放置与工程恢复不做媒体探测，也不从 layout / resource 回退；音频播放只使用媒体 `loadedmetadata.duration`。不得为音频生成响应新增 `durationSeconds`，也不得把音视频秒数写入图片序列字段。前端角色动作播放器使用 `imageSequenceDurationMs / imageSequenceFrames.length`，Spine 导出时才换算秒数并推导 FPS。
+- 时长口径：`image_sequence_duration_ms` 只表示角色图片序列完整播放一次的毫秒时长，与音频 / 视频生成请求中的 `durationSeconds` 完全分离。角色动作与视频生成响应仍可携带各自既有的请求 / 结果级 `frameCount/fps/durationSeconds`；通用音视频秒数不进入资源 / 素材正式列、`EditorAsset`、`CanvasLayer` 或画布 layout，只允许把上传探测值或生成请求值格式化为用户可见字符串后写入 `generation_inputs_json.fields[]` 供素材详情展示。素材详情和画布 ZIP 用户可见元数据只透传实际存在的 `fields[]` 时长项；缺少时直接省略，不生成 `--:--` 占位。素材放置与工程恢复不做媒体探测，也不从 layout / resource 回退；音频播放只使用媒体 `loadedmetadata.duration`。不得为音频生成响应新增 `durationSeconds`，也不得把音视频秒数写入图片序列字段。前端角色动作播放器使用 `imageSequenceDurationMs / imageSequenceFrames.length`，Spine 导出时才换算秒数并推导 FPS。
 - 写入与复用边界：`assetKind=character-animation` 必须在 SpacetimeDB storage/procedure 边界同时提供至少两帧有效数组与大于 0 的图片序列毫秒时长；其他类别不得携带图片序列字段。同项目同源同媒体资源只允许 `None → Some` 单调回填，非空冲突失败关闭，延迟重试的 `updated_at` 取请求时间与既有时间的较大值。
 - 生成关联边界：角色动作生成响应同时返回已经持久化的最终 `resource` / `asset`；带项目上下文时前端结果图层必须直接使用 `resource.resourceId` 及其预览视频来源血缘，缺少 resource 直接失败。无项目放置也必须绑定响应中的正式账号素材，不能从响应 `frames` 构造无资产真相的本地动作结果。
 - repair 幂等边界：legacy 音频 repair 不再派生或回填任何资源级通用时长，因此新列上线前已完成 repair 的重放继续按原字段精确匹配；图片序列字段在音频行上均为 `None`。
@@ -429,7 +429,7 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复

 - `asset_kind` 是资源 / 素材唯一权威媒体类别，不新增或返回 `media_type` / `mediaType`。角色动作预览 MP4 使用 `asset_kind = video`，最终透明帧集使用 `asset_kind = character-animation`；前端据此派生具体渲染器。
 - `editor_project_resource` 与 `editor_asset` 表尾只追加 `image_sequence_frames_json: Option<String>` 和 `image_sequence_duration_ms: Option<u64>`；`editor_showcase_asset` 作为提交时冻结的审核与公开快照，也在表尾追加并从账号素材复制相同两字段。前者保存完整有效帧数组，数组位置是唯一播放顺序，正式帧对象不保存或返回 `frameIndex`；后者只表示该图片序列完整播放一次的毫秒时长。帧数始终取数组长度，FPS 在播放或导出时即时推导，不持久化 `frame_count` 或 `fps`。
- 图片序列时长不能复用音频 / 视频生成请求的 `durationSeconds`，资源和素材也不保存通用 `duration_seconds`。角色动作与视频生成响应保留各自既有的请求 / 结果级秒数；音频 / 视频的用户可见时长只作为字符串展示项写入 `generation_inputs_json.fields[]`，上传媒体使用本次上传探测值，带时长选项的生成任务使用用户提交值，不再复制到 `EditorAsset`、`CanvasLayer` 或画布 layout，也不在素材放置 / 工程恢复时探测或从 layout、resource 做双来源回退。音频播放控件只信任 `<audio>` 的 `loadedmetadata.duration`，展示字段不得参与播放、裁切或变速。音频生成响应不得新增 `durationSeconds`，这些展示值也不得映射到资源、素材正式列或图片序列字段。
+- 图片序列时长不能复用音频 / 视频生成请求的 `durationSeconds`，资源和素材也不保存通用 `duration_seconds`。角色动作与视频生成响应保留各自既有的请求 / 结果级秒数；音频 / 视频的用户可见时长只作为字符串展示项写入 `generation_inputs_json.fields[]`，上传媒体使用本次上传探测值，带时长选项的生成任务使用用户提交值，不再复制到 `EditorAsset`、`CanvasLayer` 或画布 layout，也不在素材放置 / 工程恢复时探测或从 layout、resource 做双来源回退。素材详情和画布 ZIP 用户可见元数据只透传实际存在的 `fields[]` 时长项；缺少该项时省略时长，不生成 `--:--` 等占位值。音频播放控件只信任 `<audio>` 的 `loadedmetadata.duration`，展示字段不得参与播放、裁切或变速。音频生成响应不得新增 `durationSeconds`，这些展示值也不得映射到资源、素材正式列或图片序列字段。
 - 角色动作 worker 在透明帧全部持久化后创建最终项目资源与账号素材，并写入帧数组与 `image_sequence_duration_ms`；生成响应可继续返回请求 / 结果层面的 `frameCount`、`fps`、`durationSeconds`，但它们不是持久化真相。预览视频仍作为独立 `asset_kind = video` 中间素材保留并承担生成成本，最终派生素材成本为 0。
 - `create_editor_project_resource`、`create_editor_asset` 和同源资源回填必须在 procedure/storage 边界验证最终状态：`asset_kind = character-animation` 必须同时包含至少两帧的有效数组和大于 0 的 `image_sequence_duration_ms`；其他类别不得携带任一图片序列字段。同源资源只允许从 `None` 单调补齐字段，非空冲突失败关闭，补写后的 `updated_at` 不得早于既有时间。
 - `generation_inputs_json` 只保存用户生成 / 重放输入，例如 `fields`、`references`、`artSpec`；动作输出和内部背景决策色不得再写入该 JSON。背景决策审计继续走独立审计链路。
@@ -293,7 +293,8 @@ describe('useImageCanvasAssetExportWorkflow', () => {
      expect(metadata.layers[3].visible.type).toBe('生成视频');
      expect(metadata.layers[4].file).toBe('media/004-胜利音效.wav');
      expect(metadata.layers[4].visible.type).toBe('生成音频');
-      expect(metadata.layers[4].visible.duration).toBe('--:--');
+      expect(metadata.layers[4].visible.duration).toBeUndefined();
+      expect(metadata.layers[4].visible.generationInputs).toBeNull();
      expect(metadata.layers[5].file).toBe(
        'sequences/005-角色动作/manifest.txt',
      );