From 73848e5174c830f0b9a76371f75bee8ba402ed4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E5=BE=B7=E5=AE=87?= Date: Tue, 4 Aug 2026 10:44:08 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E8=A7=92=E8=89=B2=E5=8A=A8?= =?UTF-8?q?=E4=BD=9C=E6=AD=A3=E5=BC=8F=E5=AD=97=E6=AE=B5=E4=B8=8E=E8=BF=81?= =?UTF-8?q?=E7=A7=BB=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 记录正式图片序列数据契约、placement-only 布局边界和无运行时 fallback 约束。 补充四阶段迁移执行顺序、blocker 处理、批次哈希门禁和发布维护窗口。 同步项目记忆中的长期决策与排障经验。 --- .../shared-memory/decision-log.md | 15 ++++++ docs/project-memory/shared-memory/pitfalls.md | 28 +++++++++++ ...架构】图片画布编辑器MVP接入方案-2026-06-11.md | 3 +- ...】server-rs与SpacetimeDB数据契约-2026-05-15.md | 50 +++++++++++++++++-- ...发运维】本地开发验证与生产运维-2026-05-15.md | 4 +- ...辑器】画板角色形象生成入口设计-2026-06-15.md | 8 +-- 6 files changed, 98 insertions(+), 10 deletions(-) diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index bab05cac6..a50c1e00b 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -5638,6 +5638,21 @@ - 微信边界：小程序客户端仍只上传 `wechatPhoneCode`；`platform-auth` 必须要求微信成功响应中的 `phoneNumber`、`countryCode` 与 `purePhoneNumber` 均存在且非空，但只使用后两项执行国家码校验和 E.164 构造。腾讯官方仅说明境外 `phoneNumber` 会带区号，并未承诺 E.164 格式，中国号码示例中它与纯号码相同，因此不得校验 `phoneNumber == +{countryCode}{purePhoneNumber}`。微信字段缺失时失败关闭，不能使用普通请求的 `86` 默认值。 - 数据边界：认证投影与 SpacetimeDB 的 `phone_number_e164` 保持不变，不新增国家码或纯号码列，也不需要 schema 迁移或 bindings 生成。 +## 2026-07-28 编辑器媒体类型统一由 assetKind 判定 + +- 决策：`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`，音视频画布布局也可保留既有运行时秒数；不得为音频生成响应新增 `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`。 +- 布局边界：`editor_project_resource` 的正式字段是角色动作唯一媒体真相；动作 layout 只保存资源引用和 placement，不保存帧、时长、预览、生成输入、资源元数据或顶层 `mediaType`。前端仍可从 `assetKind` 派生内部 `CanvasMediaType`，但后端响应清洗不得把普通 layer 的旧 `mediaType` 传回前端，也不得递归删除 `generationInputs.references[*].mediaType`。 +- 迁移边界（2026-08-03 收口）：存量 `generation_inputs_json.characterAnimation`、已证明动作行的 helper 顶层 `frames/previewVideoPath/frameCount/fps/durationSeconds`、`screenColorHex`、正式帧 `frameIndex`、误标预览 MP4 和动作 layout 副本，由 `normalize_editor_character_animation_metadata_and_return` 按 `asset → project-resource → showcase → canvas` 一次性规范化。顶层字段只有先证明动作身份后才解释；普通图片 / 视频任意 JSON 中的同名字段不动。正式/旧版冲突与无法唯一补建的本地动作资源形成 blocker；apply 必须绑定同批 dry-run SHA-256，结束后全量复核零匹配、零 blocker。迁移完成后删除 api-server、admin、Web 与 helper 的 action fallback。 +- 新写入边界：`assetKind=character-animation` 的 `generationInputs` 若含旧运行字段或 `screenColorHex`，正式帧若含 `frameIndex`，api-server 和 SpacetimeDB storage 均失败关闭；门禁只对角色动作生效，不误伤其它素材的任意 generation input JSON。 +- 交互边界：角色动作素材下载导出完整序列 ZIP；点击、HTML5 拖放和指针拖放创建可移动、循环播放且可保存恢复的序列图层。`assetKind=character-animation` 但缺少有效帧时按损坏素材失败关闭，不回退首帧 PNG。 +- 精选展示边界：`/creation` 精选卡片和预览弹窗继续扩展各自现有媒体 renderer，不复用或重构画布图层组件；卡片静止时只读取首帧，hover / focus 后才加载并播放完整序列，预览弹窗提供播放暂停。后台素材查询与精选审核继续共用 `AdminEditorAssetMedia`，列表只读首帧，预览弹窗才逐帧使用管理员换签。两端均按 `imageSequenceDurationMs / imageSequenceFrames.length` 切帧，下一帧未就绪时保留上一帧且禁止淡入；损坏动作不退回普通图片。 +- 精选帧授权边界：公开换签只对当前已通过、已展示、返还完成且未删除的精选动作，按同 owner 的冻结帧 `assetObjectId` / `objectKey` 形成 exact grant；不从 `imageSrc` 或前缀推导。隐藏、拒绝、删除或快照损坏后逐帧授权随当前事务真相撤销，`read-url` 与 `read-bytes` 继续共用该判断。 + ## 2026-07-24 后台用户详情展示历史花费泥点 - 口径：`historicalConsumedPoints` 表示用户历史总消费，只累计 `profile_wallet_ledger.source_type = asset_operation_consume` 且 `amount_delta < 0` 的绝对值；`asset_operation_refund` 不冲减，充值退款追回、余额重置、赠送和退款 hold 均不计入。 diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index 47df14d11..3059ede6b 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/docs/project-memory/shared-memory/pitfalls.md @@ -3892,6 +3892,34 @@ - 处理：灰度页只能以 `/admin/api/feature-gates` 为数据源，固定目标列表只登记现役功能；新增或退役业务 target 只修改固定目标注册，不得让通用页面依赖业务列表接口。旧 `creation-entry:*` 目标、接口和页面保持退役。 - 验证：`adminRoutes` 必须包含 `gray-release`，admin-web TypeScript/ESLint/Vitest 不得排除灰度页；页面测试必须断言只请求 feature-gates，并继续覆盖现役固定 target、直接 Gate Key 保存与新 target 状态重置。 - 关联：`apps/admin-web/src/pages/AdminGrayReleaseConfigPage.tsx`、`apps/admin-web/src/app/adminRoutes.ts`、`server-rs/crates/api-server/src/modules/admin.rs`、`docs/technical/【架构下线】旧创作模板业务退役方案-2026-07-17.md`。 +## 角色动作不能靠素材主图或通用生成输入恢复 + +- 现象：角色动作在整画布导出时正常，但从素材库单项下载只得到第一帧 PNG，拖回画布也成为普通静态图片。 +- 原因：`editor_asset.image_src` 只指向首帧；若 worker 把完整帧集塞进 `generation_inputs_json`，素材 DTO、用户输入清洗或画布布局任一层丢字段，就会退化成 PNG。再增加一个 `mediaType` 只能掩盖结果字段没有落到正式资源的问题。 +- 处理：worker 只把完整帧集与图片序列毫秒时长写入 `editor_project_resource` / `editor_asset` 的 `image_sequence_frames_json`、`image_sequence_duration_ms`；数组位置是唯一帧序，不保存 `frameIndex`，帧数和 FPS 均按需派生。`assetKind=character-animation` 决定序列渲染。素材映射、单项下载和拖回画布只读取这两个正式字段，项目 resource 在保存 / 刷新后继续作为主真相；动作 layout 只保留资源引用和 placement，不再复制正式媒体结果。账号素材提交精选审核时，`editor_showcase_asset` 必须冻结复制相同字段，公开 read model 只返回正式字段。外部 helper 只调用一次动作生成接口并直接使用响应 `resource` / `asset`。 +- 画布回填：角色动作会形成“原角色资源 → 预览视频资源 → 最终序列资源”的血缘链。生成响应必须返回已经持久化的最终 resource，前端图层直接使用其 `resourceId`；不能继续构造 `local-resource-character-animation-*`，否则 `appendCanvasLayersWithResources` 会再次创建重复资源。新图层的 `sourceResourceId` 同时使用最终 resource 的直接来源（预览视频 resource），不能继续沿用请求中的原角色 resource；否则结构化保存会在已生成并计费后因血缘不一致而拒绝。修复时只替换资源关联与血缘字段，不要顺带把动作图层显示尺寸从生成占位尺寸改成原始帧分辨率。 +- 历史处理：不要再在 read mapper 增加 `generationInputs` / layout fallback。使用 migration operator procedure 按 `asset → project-resource → showcase → canvas` 迁移；只有动作身份已由 `assetKind`、正式字段、嵌套 `characterAnimation` 或权威对象证明后，才解释顶层 `frames/durationSeconds`，否则会把无关任意 JSON 误分类。正式与旧版结果冲突必须形成 blocker，不能任选一份；旧 `local-*` 动作 layer 只有唯一匹配账号动作素材时才能补建项目资源。普通 layer 顶层 `mediaType` 在迁移和响应清洗时删除，但嵌套生成参考的 `mediaType` 保留。 +- 新写入与验证：动作 `generationInputs` 出现 `characterAnimation/frames/previewVideoPath/frameCount/fps/durationSeconds/screenColorHex`，或正式帧出现 `frameIndex`，HTTP 与 storage 双层拒绝；其它 asset kind 的任意 JSON 不受该动作门禁影响。测试覆盖两种历史 JSON、无关顶层同名字段、正式/旧版相等与冲突、可选帧引用合并、screen color 和 frameIndex 清理、预览 MP4 重分类、幂等、blocker/hash apply、画布 placement 清理/资源补建、正式字段缺失失败关闭和 helper 单请求。 + +## 图片序列时长不要复用通用媒体秒数 + +- 现象：把角色动作、视频、音频和上传媒体都写进通用 `duration_seconds`，随后又尝试用持久化 `frame_count/fps/duration_seconds` 互相校验，造成取整口径、生成参数和实际播放时长彼此污染。 +- 原因：角色动作需要的是一组图片完整播放一次的精确时长；视频 / 音频的 `durationSeconds` 是生成请求或临时运行态参数。帧数已经由数组长度唯一确定，FPS 也可按需要推导，无需维护三份可冲突真相。 +- 处理：资源 / 素材只保存 `image_sequence_frames_json` 与 `image_sequence_duration_ms`，精选审核快照只冻结复制这两个正式字段。角色动作要求至少两帧且毫秒时长大于 0；播放器按 `时长毫秒 / 数组长度` 计算间隔，Spine 导出时再换算秒数并推导 FPS。音频 / 视频 `durationSeconds` 不映射到这两个字段。 +- 关联：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`src/components/image-editor/ImageCanvasWorldView.tsx`、`src/components/image-editor/ImageCanvasExportModel.ts`。 + +## 精选角色动作显示首帧还要检查前端 renderer 与逐帧授权 + +- 现象：精选接口已经返回 `imageSequenceFrames` 和正确的 5 / 6 秒成本，但创作主页或后台审核仍只显示首帧；接入播放器后又可能只有第一帧成功、后续帧换签返回 404。 +- 原因：快照字段、展示 renderer 和私有对象授权是三道独立边界。公开 `imageSrc/objectKey` 只代表首帧，不能让前端自动获得完整帧集；顶层精选 exact grant 也不会自动覆盖其它帧对象。 +- 处理：公开精选模型必须把 `assetKind=character-animation` 映射到序列 renderer，并携带完整帧与毫秒时长；后台素材查询和精选审核共同透传同一字段并复用 `AdminEditorAssetMedia`。公开授权在 SpacetimeDB 同一事务快照中只按有效精选动作的同 owner 逐帧 `assetObjectId/objectKey` 匹配，不能放宽 generated 前缀。列表未交互时只读首帧，打开或激活动作预览后才逐帧换签，避免再次制造换签突发。 +- 验证：模型 / 组件测试覆盖 4 / 5 / 6 秒动作、损坏序列不回退 PNG、后台两页共用播放器和未激活列表不逐帧请求；SpacetimeDB 测试覆盖主对象、每帧对象、无关对象、跨 owner 与取消展示后的授权撤销。真实浏览器和端到端验收由人工单独执行，不把 unit / component 结果写成 E2E PASS。 + +## 可复用资源回填必须保持时间戳单调 + +- 现象：延迟重试携带比既有行更旧的调用方时间，回填图片序列字段时若无条件写入，会使 `updated_at` 倒退，导致基于时间戳的同步看不到更新或排序错误。 +- 处理：同源图片序列字段只允许 `None → Some`，非空冲突失败关闭；发生回填时 `updated_at = max(existing.updated_at, request_timestamp)`。legacy 音频 repair 不派生资源级图片序列或通用时长，重放继续精确匹配。 + ## 历史钱包消费不能从最近流水或通用订单快照推算 - 现象：后台用户详情要展示累计花费时，直接复用只返回最近 50 条的 `list_profile_wallet_ledger`，或在充值订单每行使用的通用钱包快照里扫描该用户全部流水。 diff --git a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md index 2c169cfe6..7170da2ec 100644 --- a/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md +++ b/docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md @@ -163,7 +163,8 @@ - 上传按钮和拖拽上传都支持多文件；底部工具栏的上传入口选择文件后直接进入“上传素材”并在当前画布视口中心创建画布图层，素材栏文件夹内的上传入口只写入对应素材文件夹、不自动入画布；拖到文件夹或该文件夹内素材时进入目标文件夹；拖到画布时进入“上传素材”并在投放点创建画布图层。上传图片必须在创建占位素材、画布图层和账号级素材记录前先读取原图 Resolution，图层宽高、`originalWidth/originalHeight` 和素材库 `width/height` 都使用图片本身尺寸；上传视频同样在创建素材和图层前读取视频 metadata 宽高，保证单层下载或 ZIP 导出的真实视频文件重新导入后仍按文件自身尺寸入画布；仅在无法解析尺寸时才使用对应媒体兜底尺寸。 - 音频 / 视频素材卡和画布媒体图层必须提供稳定的非文字视觉预览：优先使用 `thumbnailSrc` / 视频 `poster`，没有真实首帧或音频封面时使用由媒体类型、素材名和地址派生的确定性视觉底图。视频图层使用原生 `