DEV-X-01-006 图片链路重构实施规格

1. 规格边界与统一规则

2026-10-22执行范围更新：用户要求继续全平台原件改造，Drama本轮暂不修改；已启动的独立Commerce项目纳入实施。历史Drama记录保留追溯，不作为本轮继续修改Drama的授权。Commerce以最新独立仓库的素材库、图片编辑、海报、商品链接改图及视频工作流为边界，不再按冻结原型排除；Site公开发布桶仍独立。

本文是总体方案的实现补充。用户已确认的素材存储与画布规则为：图片和视频参考输入统一使用URL；导入先本地显示，随后自动后台上传并进入产品素材库；IndexedDB保存待同步内容；再次打开时结合本机草稿与云端版本恢复。 本文保留Proposed，表示整体跨仓实施及职责调整尚未完成规范落定；上述已确认交互不再列为待定，也不代表代码已上线。

不新增逐渠道传输开关，不混合URL与Base64输入，不因URL失败改Base64重发。OpenAI/Gemini等协议字段差异保留在协议实现中；同一协议采用统一字段，私有字段不兼容应整改供给。既有公开API边界适配与供应输出Base64解析不因本方案被一并删除。

单URL及历史URL＋Base64结果见真实供应验证。同一次图片请求的多URL尚未实测，混合输入通过不能替代多URL验收。 选择统一URL是产品与存储方案的收敛，不是宣称所有供应商已经兼容。

2. 分层与数据归属

Files复用现有Owner代码，作为第7.2节独立媒体实例中的逻辑模块，使用该实例的新数据库与新桶，不再额外拆分专用文件服务或新建代码仓库。MG spool只作有界执行缓冲。产品继续拥有项目、素材库及领域权限；统一文件存储不等于把各产品私有内容搬进Platform业务库。

同一导入原件进入素材库并被画布引用，只写一份文件；创建两个业务引用不再复制字节。跨产品复用仍需来源授权与目标写权限，账号相同不自动互通素材库。

3. 最小数据模型

每个内容版本有稳定上传身份，多个节点共用同一次上传；重试、重开浏览器、多标签恢复都不能另造上传意图。file_id可映射现有file_ref/revision，不为改名重写对象。客户端摘要和ID不是授权凭证；不提供跨租户摘要探测。

4. 画布本地优先与再次打开

4.1 导入、编辑和后台入库

1. 选择、拖入、粘贴后立即建立节点和local_asset_id，用File/Blob创建object URL；异步读取尺寸。不等上传、哈希、IndexedDB落盘或服务器回读。
2. 同时调度本机草稿持久化和后台上传；在线自动入库，断网暂停，恢复联网后继续。小图先采用单次流式上传，不让每个用户都承担会话/分片步骤。
3. 上传队列有界并发和退避；选择用于生成的素材优先，其余保持后台队列。禁止逐张await上传后才添加下一节点，也不以固定延迟作为唯一触发方式。
4. 文件校验就绪后，产品幂等登记素材库条目及画布引用映射，再保存匹配版本的云端画布。素材库可先显示“同步中”，完成前不能假报云端可用。
5. 移动、缩放、连线、复制节点只改元数据。裁切、重绘等确认后的像素变更产生新版本并入队；处理中的每次鼠标移动或笔画不各上传一份，也不为每个中间版本创建素材条目。

上传完成只补充对应local_asset_id/revision的file_id，不能替换后来编辑的图片、布局或连线。删除后的迟到回执不复活节点；尚未派发且无任何消费者的上传可取消。若原件已入素材库，删画布节点不等于删素材库；文件删除仍按各处绑定判断。生成已冻结、Undo仍使用的版本保留其依赖。

4.2 生成、保存和分享

例如导入20张、选2张生成：20张都可后台入库，但生成仅等待所选2张，不能被另外18张的失败或队列尾部阻塞。输入准备失败时不创建收费派发；保留可重试意图。等待期间编辑素材不静默更换被冻结输入，取消重提作为新意图处理。

4.3 IndexedDB范围与清理

必须保存尚未上传的Blob、尚未云同步的完整画布快照、内容版本到上传回执/file_id的映射及恢复所需意图。可按容量预算保存缩略图和近期内容缓存；不默认下载整个云端素材库作为本地镜像。object URL只是当前文档句柄，不能把它或Base64字符串当作持久原件。

数据按账号、产品、画布隔离；切换账号不得展示前一主体草稿。恢复前建立当前授权上下文；多标签用版本比较与单任务租约或等效协调，同一上传的服务端幂等仍为最终保护。

本机保存以IndexedDB事务提交为准，不能以入队或内存更新为准。配额不足、私密模式限制、浏览器清理等情况显示真实未保存/缺失状态，保留仍可用内存并提供重试或导出。可申请持久存储，但不承诺浏览器永不清理。没有云端版本且本机Blob已丢失时，保留节点信息并提示重新选择原文件，不能假造恢复成功。

未同步草稿不按固定TTL自动删除。仅当原件就绪、素材库登记和相关云端画布引用确认，且无待同步编辑、生成准备或Undo依赖时，本地原件才转为可淘汰缓存。缓存可按容量/LRU清理，上传回执映射与仍需草稿不能随缓存误删。

4.4 用户下次打开画布

恢复顺序：重新认证 → 读取本机快照用于快速展示 → 同时拉取云端最新版本 → 无本机待同步改动时采用最新云端；有改动且云端未越过基线时继续提交；双方都变更时保存本机恢复副本并提示选择/合并。不能用“最后打开的时间”无条件覆盖任一端，首期不要求完整实时协同算法。

云端保存使用base revision/CAS及稳定保存命令。回执未知先查询，避免把自己已提交的版本误判为他人修改。旧异步读取响应不得覆盖用户打开后新编辑的本机版本；旧上传响应同样按内容版本合并。

进入画布优先读取可见区域缩略图和必要元数据，视口外延迟加载；编辑、放大或下载时再取原件。云端长期只存稳定文件引用与内容版本，过期URL按当前权限续签，不重新上传。

5. 统一接口形状

以下是逻辑能力，不是已存在的HTTP路径。Owner维护版本化schema，TS/Go客户端共用合同；不要求前端理解claim或技术暂存目录。

{
  "intent_id": "client-stable-intent",
  "media_type": "image",
  "model": "published-image-model",
  "inputs": [
    {"role": "reference", "file_id": "existing-file", "revision": 1},
    {"role": "reference", "file_id": "newly-uploaded-file", "revision": 3}
  ]
}

此例中第二张已通过上传取得file_id，最终两项都是供应商可读HTTPS URL。没有local_part、Base64或blob URL的生成输入分支。服务端不信任客户端Owner/scope/摘要；并发上传允许部分成功复用，不因一个失败而重传全部。

6. 入库、同步与生成状态

上传字节校验、正式文件登记、素材库绑定、画布同步是不同确认点。文件已上传但产品事务失败时，通过持久outbox/幂等命令补登记，不重复Put/Copy；不能只靠页面回调收尾。上传未就绪前的技术暂存由Files管理，不另建面向产品的ExecutionInput资产类型。

完整云端画布只提交可解析的稳定引用；尚有本地文件时保留完整本机草稿与最后已提交云端版本，显示“本机已保存，云端同步中”。元数据自动保存可合并短时间编辑，但不能把包含本机句柄的快照标成已云保存。生成可以只等其依赖就绪，不必等待整个画布快照上云；执行保护须在首次付费派发前建立。

签名有效期覆盖供应端实际取图窗口，排队时不提前签发；派发前再核对授权、保留和地址。上游已接受后地址到期按原任务恢复协议处理，不能另发付费请求。用户取消等待不等于供应商取消、失败或退款。

7. 网关协议边界

统一字段不保证全部现有供给兼容。CookingAI的私有image字符串等保留在实测证据中，不据此增加渠道分支。HTTP 200但未采用某张参考图视为失败；多URL、顺序、角色和实际图像特征须独立核验。未验证、当前不可用、管理员停用分别记录，不自动改生产路由或启停。

7.1 存储角色与最终位置写入

桶分工及逐桶保留/调整以总体方案4.1为准，实际配置证据见云端只读核对。本规格不包含生产配置执行。

• 新链使用统一Files Owner及正式业务桶，新上传和生成结果写最终不可变对象键；记录接收/输出意图后写入，校验与登记成功才ready。未就绪对象不签发读取，也不能仅凭文件在正式桶就开放。
• 不把“临时Put→主桶Put→副本Put→Publish”作为正常链。先查同一上传/原执行输出回执和对象身份，未知ACK不换键重写；已就绪文件业务复用Put/Copy为0。确需临时保存的唯一恢复字节保留到正式写入确认，不进可自动到期的缓存范围。
• MG后续配置和readiness取消replica必填及强制探测；新链保存不等待副本。已有部署保持原配置，直至统一版本和Owner接线验收，不能只把环境变量清空或把三个角色填同一桶来绕过旧代码约束。
• 当前OceanWay新实例仅使用新桶，不读取或复制旧main/replica/assets/media对象；旧实例维持自身业务，不为新链提供文件读取fallback。
• 原件与预览分前缀；预览是有来源的可重建派生，失败不阻断原件下载。正式原件无年龄TTL；开发阶段上传、生成与辅助临时处理均不新增或继承7天自动删除，桶生命周期、部署模板及应用清理默认值保持一致。首期不启用新的自动物理GC；后续临时数据定时清理按实际需要另定，不作为当前开发前置条件。
• 普通读取只核当前业务权限、文件ready和首次交付资格，不重新adopt、创建长期claim或恢复原账；必要内部保留机制由Files处理。用户删除先提交解绑outbox，远端释放异步，不等待物删才更新画布，也不提前宣称释放确认。
• CORS是浏览器路径配置，供应商服务端取URL另验可达性。逐实际Origin验证预览、fetch、canvas导出、HEAD/Range；如采用直传再核PUT及签名头。保持私有访问，不把CORS与文件授权混为一谈。

7.2 独立实例、数据库副本及全新桶（最新确认）

目标地址固定为https://media.oceanway.tech。复制服务代码及数据库，数据库落入独立新库；所有新业务文件使用新建桶，开发阶段不迁移旧数据/文件、不兼容旧素材引用。这里“数据库复制”是初始化方式，不要求仅复制schema；“不迁移旧数据”指不将复制过来的旧客户任务、资金、文件引用作为新业务继续执行或提供读取。本方案不修改源库、原业务或旧桶。

原业务已受理任务由原实例自己处理；新实例不接管、重派或对账这些任务。新开发界面不恢复旧素材记录，文件缺失不触发从旧桶下载复制。此范围不要求旧新数据库持续同步或历史双读双写。

7.3 精确改动清单

身份审计已确认当前有原件直接写正式桶的图片分支，以及旧网关token100/101共用user1的问题。独立实例方向下，不再修改旧网关增加新旧客户分桶绑定，也不把证明旧token专用性作为新部署前置条件；直接为新实例签发独立身份。复用原件分支，补齐视频和全入口覆盖。

本次仅写方案，不执行生产或新环境部署。源代码定位以已核制品为依据，实施时对照目标分支并保留他人修改。复制同一代码仍可独立发布，不强制新建代码仓库；旧生产不会因新实例代码升级自动重启。

7.4 从复制到启用的顺序

1. 固定源实例/数据库及源码版本，创建独立目标部署目录、DB、空Redis和新桶；新应用/worker不启动，出站保持关闭。桶名、容器名和DB名先记录，不冒充已存在资源。
2. 只读导出源数据库一致性快照并恢复到新库；核验目标连接与schema/配置完整性。新库按清单初始化旧业务数据、文件引用、会话与后台执行状态；不复制旧文件，不对源库做清理或迁移。
3. 注入新身份、服务/存储凭据及供应配置，完成必要密文转换；配置media.oceanway.tech的DNS、证书、反代与新回调入口。初始只启用健康/元数据验证，未通过身份与资源检查不得启动任务执行。
4. 在新实例验证图片/视频、单原件写入、URL读取/续签、素材复用、重开画布及失败恢复；对旧库、旧桶访问失败作明确断言。付费生成与实际切流按具体授权执行。
5. 验收后修改Platform托管连接、File Bridge和产品文件入口，切换新业务请求。失败时暂停新业务；不回退旧桶、重派未知任务或让旧生产承担新规则。旧业务实例、数据库和桶始终维持原状。

8. 结果、读取与复用

生成完成即捕获短期URL或解码Base64输出，按原执行＋output_index幂等登记原始文件字节。原件保持格式、透明通道及原始信息；缩略图和旋转展示由派生承担。保存回执未知查询原登记，输出不可恢复时如实标记，不重新生成；批次部分失败不能重做已完成输出。

普通下载只核验当前业务权限/交付资格和读授权，不再次采用原件或恢复账务。签名并发续签可合并，权限撤销不无限重试；旧签名URL不承诺立即失效，需即时撤销的场景采用受控读取。私有缓存隔离账号与权限，Site公开资源沿独立发布流程。

同一文件进入素材库、画布、对话或剧集，只新增获准Binding；裁切、重绘等内容变化创建有来源关系的新文件。删除只解除本处绑定，其它引用和执行保护继续有效，首期不新增自动物理GC。

9. 错误与用户动作

前端不暴露claim、namespace或数据库术语；内部用upload_id、file_id、canvas revision、operation_id、binding_id关联诊断。

10. 分阶段工作包与责任

下列编号是提案逻辑拆分，尚未注册正式WP；详细映射见总体方案。

按ADR-0024不恢复旧测试数据迁移、双读双写、跨版本回退、开发备份或联合灾备门禁。本机草稿恢复属于编辑可靠性，不是新增跨服务灾备项目。

10.1 Commerce的统一原件接入

Commerce维持独立部署和既有工作流。当前宿主仍为单用户、仅loopback的开发网关；File Owner接线不能代替中央身份与逐用户授权，也不能据此公开网关。

• 素材上传由产品服务登记稳定命令；查询仅接收UUID、SHA-256、字节长度和MIME，命令指纹绑定当前宿主/File Owner作用域。并发、丢失响应和刷新继续使用同一命令，元数据查询恢复后不重传原件。命令冲突、未知状态或回收站中的素材拒绝继续，不以新命令自动兜底。
• 最新用户决定：Commerce不再使用本地媒体存储。 编辑器、品牌、批处理、AI工具不向IndexedDB写入媒体Blob或上传回执。File/Blob只作当前页面的内存预览；成功后设计和任务保存稳定素材ID与同源读取入口。浏览器仍可保存项目/设计元数据；未成功提交的文件不承诺关闭页面后恢复。本轮不自动清除既有浏览器数据，旧媒体表不再读取/写入。
• 素材库进入工具、结果进入编辑器直接复用产品素材ID；结果入口可返回原件元数据，不能先下载再作为新素材登记。切换编辑模式保留URL中的素材ID，刷新恢复相同原件。
• File Owner为必需配置，只使用专用服务身份与可信subject，产品域为commerce。缺配置、部分配置、Owner拒绝或回执不一致均拦截；不得启用本地文件或限时relay兜底。宿主仍单用户loopback，不能据此公开服务。
• 上传素材、图片/海报/商品链接各镜头成品、最终视频和换装raw结果都先获得Owner回执再发布可用状态。结果入同一素材目录，只有稳定原件证明持久化；图片多参考角色按顺序映射为HTTPS URL，视觉文本请求和Seedance同样使用URL。未验证URL映射的视频协议在收费前拒绝。
• 原件grant和签名URL仅在当前调用内使用。预览跳转到当前授权地址，下载有界临时读取并校验长度/SHA/MIME，不向对象服务转发宿主凭据。下载后清理临时字节；无常驻原件缓存。历史项目读取仍可访问移入回收站的原件，新的素材选择/生成拒绝回收站引用。
• 产品SQLite保存素材分类、任务、稳定引用及JSON/SRT文本元数据；不将媒体字节或Base64写进业务库。FFmpeg/Pillow输入、合成帧与输出仅在任务临时目录中处理，正常/异常结束清理，父进程在取消/终止worker后清理其目录。整机硬崩溃可能遗留OS临时文件，宿主清理即可，不得作为正式读取来源。
• 图片/视频上传25MiB，音频15MiB，不能把Owner更低的音频上限留到付费任务之后才发现。File Owner上传契约按真实容器字节识别WAV常见MIME别名、Ogg音频和Matroska；保持旧客户Asset API不变，不将扩展名当内容证据。
• Owner保存失败不能假报完成、落盘兜底或自动重发付费生成。若模型结果仅存在worker内存而Owner不可用或worker在确认前退出，当前候选无法跨进程恢复该结果；供应商结果采用/故障恢复仍须另行闭合。中央用户接线、真实新实例/桶联调、跨域画布导出和生产切换也不以本机测试代验。

11. 验收矩阵

12. 性能验证与完成定义

同设备、网络、文件、模型参数对照，区分冷/热缓存。先做本地与隔离测试，真实供应只在明确额度内验证；历史异构渠道耗时不做速度排名。

覆盖小图、大图、多图、透明PNG、EXIF JPEG及高像素样本。浏览器测试报告样本量与p50/p95，付费小样本只报告逐次结果。节点先显示改善操作等待，后台上传减少后续等待，缩略图改善加载；均须实测，不承诺加速倍数。

完成须具备逐仓版本、测试及用户流程证据、实际协议、未闭合项与有效数据保护说明。文档更新、代码合并、真实供应验证和生产切换分别记录。

13. 异步图片和视频的本批实施边界

依据ADR-0026，Media拥有结果归档，Platform拥有原任务与稳定输出引用，Studio拥有业务素材绑定，Runtime仅编排和送达。本节优先于本文早期将执行中保留、文件后端或生命周期交给Runtime的安排；文件SDK可被产品复用，Runtime服务不持有Files凭据。Drama、旧客户服务和桶、同步图片保持原状。

13.1 完成与恢复

Media将新异步任务的归档策略在派发前冻结；视频任务和必需归档意图共同持久化，并由后台幂等补齐已受理但缺失的保存意图。图片持久保存供应商已返回结果后仅重试归档。结果文件通过大小、MIME、摘要和对象回执校验后才可交付；未知存储结果核验同一对象，禁止重复模型派发、重复计费或另存副本。

13.2 稳定引用与下载续签

完成任务持久保存文件ID、版本、摘要、大小及MIME，不持久保存签名URL或访问grant。Platform API返回图片data[].url、视频content_url及稳定输出元数据；地址是短期签名HTTPS，可无Platform Bearer直接GET。重新查询同一任务只续签同一文件。首次交付和下载授权均须检查当前客户归属及已完成的交付资格；未完成归档、结算或已丢弃结果不能暴露下载地址。

13.3 Studio绑定与Runtime退出

Studio根据Platform原任务的稳定输出回执建立产品自身绑定，Files只登记技术保留，不复制对象。绑定意图先持久化，远端未知结果通过相同命令恢复；普通读取直接按产品已存绑定向Files续签。Runtime接收不含claim、grant、桶位置或签名URL的产品保存回执，Artifact仅记录元数据并幂等送达；新异步输出没有Runtime原件采用、文件版本和保留链。缺少新合同接线时明确失败，禁止静默退回下载再上传。

13.4 必须分别验证

真实异步图片与视频各验证一次生成归档、无Bearer直接下载、续签前后ID和SHA一致、已有素材复用不增加正式原件。覆盖视频归档意图登记中断、存储回执丢失、重启恢复和业务绑定重试。停止Runtime后，API生成归档和已有Studio文件读取仍正常。受控夹具不替代真实供应与云桶证据；独立Media部署验证通过也不等于已切换共享Platform连接。

本批代码、独立部署和真实联调的时点证据见PROC-02-021。该记录不代表共享Platform或Studio已切流，也不替代完整画布浏览器验收。