MG-02-010 历史数据迁移
2026-09-30 用户已确认所有历史记录保留，并要求支持迁移旧 new-api-new-oceanway 数据。本章是迁移设计；本轮只读源码，没有连接业务库、导出实际记录、迁移文件或停用旧清理器。
范围与保留原则
保留目标服务现有全部历史；迁入旧平台历史生成任务、使用/错误/费用日志、输入快照、测试证据、结果/素材索引及必要的旧渠道/模型/身份元数据。不能仅迁成功、最近若干天或当前启用渠道的记录。缺失/无法转换项目必须保留去向并报告，不能静默丢弃。
视频历史在统一“生成记录”可查询；无法投影到视频详情的非视频、账务/系统等历史以管理端只读档案保留，按类型查询，不恢复图片/文字生成、客户钱包或旧用户登录。源未知字段保留受限原始归档及摘要，投影不能代替完整迁移留档。
历史记录永久保留，无按天数自动删除。已经取得并绑定记录的结果与有价值的输入/证据不默认清理；未引用临时上传仍可按独立租约规则回收。源端已丢失的文件只能保留记录及缺失原因，不承诺从一个过期 URL 复原。旧平台原件和旧桶保持，不在本任务删除或移动。
此前“旧 6 个归档渠道原地保留”的决定继续适用于运行配置/凭据；它们相关历史不能因此从迁移统计排除。新系统可保存只读来源渠道快照来解释历史，不自动启用或重复迁移这 6 个旧渠道的凭据。
已核对源码与尚未核对的运行数据
Schema/结果来源见 history-source-map.json，固定旧提交 6484b5971ccb6c9c76ed78b6dfa2fe338bd992b0，14 个文件已记 SHA-256。
| 来源代码 | 已知字段或行为 | 迁移要求 |
|---|---|---|
| model/task.go | request_id、内部主键、task_id、上游 ID、渠道/供给、用户/组、状态、时间、Properties、PrivateData、Data | 身份/时间/状态原样保留；敏感执行上下文分离加密 |
| Properties.Request / service/task_request_snapshot.go | method/path/content type、正文编码/大小、SHA-256、截断标记，源码限 1 MiB | 不把截断视为完整输入；缺失/编码区别显示 |
| model/log.go | 消费/退款/错误/管理/系统/登录等类型、request/upstream request ID、模型/渠道、quota、Other | 日志关联主任务，同时保留孤立记录、原单位和类型 |
| model/main.go | 主库与 LOG_SQL_DSN 日志库可能独立，代码支持多种数据库 | 实施时盘点实际主库/日志库；不能只导出主库就称全部完成 |
| model/seedance_v2_archive.go | task/媒体 ID、对象及媒体元数据、封存状态、到期/错误/租约 | 对照真实对象可读性，保留生成与交付各自状态 |
| model/asset_library.go | 素材/分组、来源用户/项目、存储 provider/bucket/object key/原链接 | 保留授权来源和引用，旧账号不成为新登录 |
| service/media_storage.go、seedance_v2_archive* | 本地/S3 读取、签名、封存/清理；源码有 7 天媒体保留默认值 | 不继承该自动删除默认值；运行策略和现存文件须另核对 |
| controller/task.go、log.go、video_proxy.go | 管理与用户投影/授权、媒体代理 | 复用映射依据，迁移管理读取不能依赖旧登录 |
源码目录不是数据库备份。实际旧实例、数据库类型/位置、日志库、存储方式、数据规模、保留/清理策略和可恢复媒体都尚未盘点；不能把源码审计写成“所有数据已可迁完”。盘点由后续迁移任务只读执行，敏感连接资料不进入公开证据。
映射与唯一身份
每条迁移记录带 source_instance / source_store / source_table / source_primary_key / snapshot_id；目标使用独立稳定 ID 并保留所有源 request/task/provider ID。重跑同一导入只能更新对应历史来源版本或补文件，不增加重复记录。
不同实例可能同 ID，不全局按 task_id 去重。日志缺可靠原主键时用持久来源快照行标识、原始内容摘要及重复次数保留重数；不能把内容相同的多条事件当一条。以明确 request/Provider/关联字段建立任务与日志关系；按时间/模型相近的猜测只能标记候选，不自动合并。
| 历史内容 | 目标投影 | 缺失/不确定处理 |
|---|---|---|
| task、原 request/task ID、原状态/时间 | 一条已迁移生成记录及源映射 | 保留原状态与映射依据；不改变原完成时间 |
| 旧渠道/供给/模型/用户标识 | 只读来源快照，与当前配置区分 | 源实体已删除也保留旧 ID，不假造活跃实体 |
| 提示词、参数、请求快照 | 受限详情及安全摘要 | 未记录/截断/不能解析明确标记 |
| 原日志/费用上下文/扣费退款 | 关联历史事件和只读档案 | quota 保留原单位，不自动转换为采购 CNY/美元 |
| 已封存结果/本地文件/S3 对象 | 授权平台结果或待复制索引 | 先只读检查，再受控复制；原对象不删 |
| 仅 Provider URL/结果 ID | 受限恢复定位与可用性状态 | 过期/权限不足/缺失明确列出，不再次生成 |
| 无主任务或非视频日志 | 可查询历史档案 | 保留原件及来源，不强塞成视频任务 |
旧 private_data 含 Key、ProviderRequest、代理/地址等潜在秘密；不能将 JSON 原文放在记录列表、源码或证据包。必要恢复秘密用限定用途加密引用；原始敏感归档只在受控迁移存储，UI 投影脱敏。旧密码/API token 不作为新管理员登录或新服务身份。
费用区分旧客户 quota、销售费用、上游采购和退款来源。保留历史事实，不把旧钱包退款直接当 Provider 退款，不用新的价格重算旧记录，更不补发任何扣费/结算事件。
迁移步骤与在途任务
- 在源实例只读盘点所有记录类别/存储，获取一致快照和独立库水位；生成计数/时间/主键摘要及对象索引，不在终端打印业务正文或秘密。
- 受控导出，保留原始快照、字段/Schema 版本、哈希、来源身份；不变更源数据库/旧桶/旧清理策略。需要防止源媒体过期时先做只读复制计划，涉及旧策略调整另立明确范围。
- 在隔离原生目标库演练，导入全部来源类别并建立映射；正常视频详情与只读档案分别可查，目标已有历史不覆盖。先核对记录，再检查/复制仍存在媒体，结果失败可以补迁，不回滚或删已入记录。
- 检查旧在途/Unknown：初次历史导入一律只读、不进入执行队列，不让新系统重新提交或同步消费旧费用事件。旧执行 Owner 保持；需要接管时单独核对任务、凭据、已有受理事实并受控交接。
- 按更新水位补增量，不因已有 task ID 漏掉晚到状态/费用/结果。到最终窗口固定快照/Owner；是否停旧服务属于后续切换，不是本轮授权。
- 只读核验和管理端浏览器核验完成后记录迁移范围；保留源数据及备份。永久保留的是已迁入记录，不以源删除证明迁移成功。
导入重跑不触发 Provider POST、退款、客户结算、生产启用、自动文件清理或旧库写操作。磁盘/对象容量不足时阻止新批次并告警，不能删历史腾空间。备份恢复、权限、分页/索引与来源映射一起验收。
完整性与可追溯验收
对每个来源快照满足“源记录数 = 可用业务投影对应的源记录数 + 只读档案对应的源记录数 + 明确失败且仍安全保留的来源记录数”；一条源记录只能计一次，多个投影不是多份源记录。迁移“完成”要求记录失败数为 0，所有记录均有查询去向。
按类型/状态/时间/渠道及原 ID 核对计数、摘要与费用原单位；同时检查源日期保持、孤立日志、已归档渠道、跨实例同 ID、目标既有记录、重复批次、缺快照和损坏行。不能只比总数或随机抽几条。
对象清单按已可读/复制成功/待恢复/源缺失/无权限分类核对，记录数通过不表示全部视频可播放。对象按大小/校验值及引用核验；过期文件缺口清楚呈现，不靠 Mock 或重新生成掩盖。对应 A17–A18 的证据必须分别说明记录与媒体状态。