一、大数据量下的传输方案
localStorage 单域容量通常在 5MB 左右，数据量级上限可控，但直接全量一次性传输仍存在请求体超限、弱网超时、中断后全量重传等问题，推荐按「轻量化优化 + 分批上传」的思路处理。
- 传输前的 payload 瘦身优化
先降低单次传输的数据体积，从源头减少传输压力：
• 字段精简映射：将长字段名替换为短别名（如 shopId→id、name→n、addedAt→t），后端接收后再映射回原字段，可减少 20%~40% 的 JSON 冗余体积。
• 数据压缩：使用 pako 等前端压缩库对 JSON 字符串做 gzip 压缩，以 ArrayBuffer 二进制或 base64 格式传输，通常能压缩 60%~80% 的体积，适合单批数据量较大的场景。
• 字段裁剪与校验：仅传输后端存储必需的字段，剔除前端本地冗余字段；上传前先做 JSON 合法性校验，避免解析异常导致上传畸形数据。
- 核心方案：分批分片上传
针对数组型数据，最稳妥的方式是按条数切片、分批次上传，兼顾可靠性与实现成本。
• 切片规则：将本地数组按固定条数拆分（建议单批 100~500 条，根据单条数据大小调整，控制单请求体在 100KB 以内），生成批次列表。
• 请求约定：每个批次请求携带统一的迁移任务ID、当前批次号、总批次数、当前批次数据，便于后端按任务聚合、按批次校验。
• 并发控制：采用串行或 2~3 个低并发上传，避免触发网关限流、占用过多浏览器连接数；弱网环境下优先串行。
• 优势：单请求体积小、超时概率低；失败仅需重传对应批次，无需全量重传；可实现可视化进度，用户体验更好。
- 后续同步优化：增量同步
首次全量迁移完成后，日常同步无需再传全量数据：
• 本地维护 lastSyncTime 同步时间戳，每次同步成功后更新。
• 后续仅上传 addedAt / updateAt 大于该时间戳的新增/变更数据，大幅减少传输量。
二、网络异常、上传不全的可靠性保障
核心思路是：幂等兜底 + 断点续传 + 重试容错 + 最终对账，确保数据最终一致，不丢不重。
- 接口幂等性设计（基础底线）
从后端层面避免重复上传导致脏数据，是所有重试、续传的前提：
• 数据级幂等：以 shopId 作为唯一主键，后端存储采用 upsert（存在则更新、不存在则插入）逻辑，同一条数据重复上传不会产生重复条目。
• 批次级幂等：为每个批次生成唯一 batchId，后端记录已处理完成的批次ID。重复请求同一批次时，直接返回成功，不重复写入。
- 断点续传 + 本地进度持久化
解决「传了一半断网/刷新页面，要从头开始」的问题：
• 迁移启动时，在 localStorage 中写入迁移进度记录（包含任务ID、已完成批次号、已上传条数）。
• 每成功完成一个批次，立即更新本地进度。
• 异常中断后重新启动迁移时，先读取本地进度，直接从下一个未完成的批次继续上传，跳过已成功的部分。
• 全量上传且对账通过后，再清除进度记录与旧的本地数据。
- 分级重试策略
针对不同失败原因做差异化处理，兼顾成功率与性能：
• 瞬时故障重试：对网络超时、5xx 服务端错误、DNS 抖动等瞬时异常，采用指数退避重试（间隔 1s → 2s → 4s），单批次最多重试 3~5 次。
• 错误分类处理：4xx 参数错误、权限错误等业务异常不重试，直接标记为失败并记录原因；仅网络类、服务端瞬时故障触发重试。
• 失败隔离：单个批次重试耗尽仍失败时，先标记为异常，继续推进后续批次，最后统一处理失败批次，不阻塞整体迁移进度。
- 最终一致性对账校验
全批次上传完成后，必须做一次完整性校验，避免「传完了但缺数据」的情况：
• 前端计算本地全量数据的总条数、按 shopId 排序后的哈希值。
• 后端返回对应任务在 DB 中的总条数、对应哈希值，两端做对比。
• 若对账不一致：后端返回缺失/异常的 shopId 列表，前端针对性补传对应条目；若差异过大，降级为重新全量分批上传。
- 兜底回滚机制
确保迁移失败不影响原有业务：
• 延迟删除本地数据：迁移过程中、对账通过前，绝对不删除 localStorage 中的原始数据。只有确认后端数据完整一致后，再清理本地数据。
• 业务降级：迁移未完成/失败时，前端业务继续读取本地 localStorage 数据，不强制切换到后端，用户无感知。
• 后端可回溯：迁移数据携带 migrate_task_id 标识，若出现脏数据，可按任务维度快速清理，不污染正式业务表。
补充工程建议
• 阈值降级：数据量小于 50 条时，直接走单请求全量上传，无需分批，降低实现复杂度。
• 进度可视化：给用户展示迁移进度条、当前状态（上传中/成功/失败），失败后提供手动重试按钮。
• 埋点监控：上报迁移成功率、失败原因、平均耗时、数据量级，便于后续迭代优化。
需要我帮你整理一份可直接落地的前端迁移核心代码示例吗？
