Shopify 产品数据导入的完成标准，不是后台出现“上传成功”，而是每一行商品数据都能回答四个问题：它要新建还是更新，字段由谁负责，导入后应该看到什么，出现错误时怎样停在一个仍可验证的状态。本页把 9916 限定为一次性或由操作者明确触发的产品目录装载，覆盖 CSV 文件、受控的 Admin GraphQL 批量操作、字段验收、失败隔离和恢复材料。它不把产品目录装载包装成永久同步服务。
先把边界写在批次单上：本次文件的版本、导出时间、店铺时区、负责人、样本范围、允许改变的字段、禁止改变的字段，以及最终核对人。商品、变体、图片、价格、库存、市场和搜索字段经常同时出现，但它们的身份键和责任并不相同。只要一个字段没有可追溯的来源，就先把它标记为待确认，而不是用“看起来合理”的默认值补齐。
1. 先分类：一次性导入还是持续同步
9916 的人工触发边界
一次性导入有一个明确的起点和终点：操作者准备一份固定版本的文件或一组受控 API 输入，完成预览、批准、运行、结果抽样和对账，然后关闭批次。文件名、校验值、样本行、操作时间和异常清单构成批次证据。即使同一份文件稍后再次运行，只要没有新的调度器、外部源和冲突决策，它仍然属于人工触发的修复或补丁批次。
本页可以讨论从现有店铺导出目录，再将整理后的字段装回 Shopify；也可以讨论一次性的迁移、季节性目录刷新或少量新 SKU 上架。每种情况都必须声明哪些列有权覆盖旧值。图片 URL 可作为行字段检查，库存可作为结果核对字段，但它们不会自动带来图片创意、履约流程或库存账务的完整定义。
何时必须转到 9917
当需求出现“每天自动拉取”“外部 PIM 变更后自动推送”“收到 webhook 就重放”“两个系统同时修改后自动解决冲突”等词时，问题已经从一次性导入变成持续同步。它需要调度、增量游标、重试、幂等、来源真相和冲突所有权，不能在一次 CSV runbook 中顺手承诺。请把这类问题留给 9917 产品数据同步指南，9916 只保留停止条件和所需输入清单。
一个 Admin GraphQL mutation 也不等于持续同步。productSet 可以在一次受控请求中创建或更新产品，但它没有替你保存外部系统的长期游标，也没有证明存在双向连接。判断标准不是 API 名称，而是有没有持续事件、调度、重放和冲突规则；没有就按一次性批次验收。
2. 先导出，再建立可恢复的工作点
导出目录、原始文件和校验值
开始前先导出当前目录或保存一份店铺认可的基线。原始导出文件保持只读，另存清洗版、字段映射表、样本结果和错误记录。为每个文件记录 SHA-256、字节数、生成时间、店铺时区、操作者和工具版本；文件名可以包含批次号，但不要用“最终版”这种会被反复覆盖的名称。Shopify 官方导入说明建议在导入前备份，并建议先测试少量商品或开发店。
备份不是一句“已经下载”就结束。抽取几条稳定身份记录，记录 handle、SKU、变体、价格、库存地点和发布状态；如果某个字段无法导出，要在基线中写明缺口。这样导入后发现一个集合少了商品时，团队可以区分源文件缺失、映射错误和后台结果错误，而不是把所有问题归到 CSV。
可验证的回退点不等于自动撤销
Shopify 文档说明 CSV 导入开始后不能取消，且不要把导入界面当成有完整历史恢复能力的事务日志。因此“可回退”在本页是操作设计：保存变更前的字段、保留输入文件、隔离失败行、用明确的反向修复文件或后台操作恢复已批准的字段，再逐项验收。它不是平台保证的一键撤销，也不是对所有关联对象的原子还原。
回退材料应至少包括原始导出、清洗前文件、字段矩阵、允许覆盖列、导入预览、成功与失败 ID、操作者记录和前后差异。若本次批次只允许改标题和描述，就不要用一个“全字段回写”的文件回退；回退文件应只带经过批准的列。任何无法确认旧值的列都先停止，避免用空值覆盖可用数据。
| 风险情形 | 导入前证据 | 停止门 | 可执行的恢复准备 |
|---|---|---|---|
| handle 指向错误商品 | handle/SKU 对照样本 | 一条身份键不唯一 | 暂停文件，保留旧导出与映射 |
| 变体数量不符 | 产品—变体清单 | 样本的选项或 SKU 缺失 | 只切出该产品的修复行 |
| 图片 URL 失败 | URL、来源行、预期顺序 | 关键媒体无法核验 | 隔离媒体行，不扩大批次 |
| 价格或库存异常 | 金额、单位、地点基线 | 数值或单位无法解释 | 停止覆盖，回到基线核对 |
| 导入结果不完整 | 预览与结果样本 | 成功数无法对账 | 固定已验证行，另开补丁 |
3. 字段字典、所有权和稳定身份
handle、title、SKU 与变体 ID 的职责
handle 是公开 URL 相关的产品标识，title 是面向读者的名称，SKU 通常用于库存或运营系统的商品/变体识别；它们不能互相替代。产品级 handle 的拼写改变可能影响外部链接和后续匹配，标题相同也不证明是同一商品。变体还需要自己的选项组合、SKU、价格和库存语义。若 Shopify 返回了资源 ID，应把它作为结果证据，不要把一个外部行号冒充平台 ID。
先决定身份优先级：更新时使用已确认的 handle 或资源 ID，还是由内部 SKU 找到一个唯一产品；新建时如何防止旧 handle、重复 SKU 或空标题造成误建。把“查不到”“查到一个”“查到多个”分别处理。任何自动填充都要留下原值和新值，避免先把身份键改掉，再失去查找旧记录的能力。
新建与更新的冲突检测
新建行的检查重点是必需身份和不会撞上现有目录；更新行的检查重点是匹配对象、允许覆盖列和空值行为。把产品级字段、变体级字段、媒体字段和地点字段分成不同列组。若一行同时携带多个职责，先拆成矩阵再决定能否装载。对同一个 handle 出现多个互相矛盾的 title、vendor 或 SKU 时，文件必须失败，而不是按行顺序猜一个。
| 字段组 | 原始责任 | 导入前检查 | 导入后证据 | 失败动作 |
|---|---|---|---|---|
| 产品身份 | 商家目录主数据 | handle、title、内部键唯一 | 产品 ID 与 handle 查询 | 隔离身份冲突 |
| 变体身份 | 选项与 SKU | 选项组合不重复 | 变体列表和 SKU 抽样 | 不覆盖整组变体 |
| 文本 | 编辑/本地化团队 | 编码、语言、空值 | 标题/描述逐字段 diff | 退回该文本行 |
| 商业数值 | 运营或财务批准人 | 币种、单位、精度 | 价格/重量样本 | 停止数值覆盖 |
| 媒体 | 内容团队与 URL 所有人 | URL、行关系、顺序 | 媒体结果与失败清单 | 单独修复媒体 |
| 库存 | 库存负责人 | 地点、单位、时间点 | 地点级结果 | 转库存流程核对 |
4. CSV 模板与产品、变体、图片行
首行、变体行和图片行的关系
按 Shopify 官方 CSV 指南建立行模型，不要凭视觉猜表格含义。产品首行承载标题、handle 和产品级字段；后续变体行表达不同选项、SKU、价格等变体属性；图片行用于补充媒体关联。一个产品跨越多行时，行顺序和空白字段的意义必须先用官方样例和小批量测试确认。不要把下一件商品的标题留空来表示“继续上一件”，除非模板规则明确支持这种结构。
图片 URL、变体图片和产品级图片需要单独列入字段字典。URL 能打开不表示它被正确关联，图片出现也不表示顺序、替代文本或销售渠道展示符合预期。每一条媒体行都保存来源行号、所属 handle、变体关系和验收状态；这能在产品主体成功、媒体失败时切出小修复，不必重跑完整目录。
空行、重复行和顺序检查
导入前先去掉意外空行，检查 header 是否唯一、列名是否与模板一致、产品首行是否完整、变体选项是否重复、图片行是否落在正确产品范围。用脚本做确定性检查，再人工阅读十几行代表性样本。把原始文件与规范化文件分开保存，不要让表格软件自动改日期、去掉前导零、重排列或改变 URL 编码。
表格处理的目标不是“看起来整齐”，而是保持每个值可被同一规则再现。SKU、条码和 handle 可能需要按文本读取；价格和重量要写清单位；多语言文本不能因为错误编码变成问号。发现一个结构错误时，先修模板和生成规则，再重新生成整批文件，不在导入界面逐行补救。
| 行类型 | 主要作用 | 必核关系 | 典型异常 | 隔离范围 |
|---|---|---|---|---|
| 产品首行 | 建立产品与产品级字段 | handle/title/产品键 | 空标题、重复 handle | 单个产品 |
| 变体行 | 表达选项与变体数值 | 所属产品、选项组合、SKU | 重复组合、价格缺失 | 该产品变体组 |
| 图片行 | 关联媒体或图片 URL | 所属 handle/变体、顺序 | URL 失效、错绑产品 | 媒体行 |
| 分隔空行 | 文件可读性 | 不得改变解析边界 | 隐藏字符、额外列 | 文件级 |
| 新批次首行 | 开启下一个范围 | 旧产品字段不可继承 | handle 串行、错位 | 当前批次 |
5. 小批量 rehearsal：先证明路径再放大
选择开发店或代表性样本
先选能覆盖风险的少量商品，而不是只挑最简单的一行。样本应包括一个新产品、一个更新产品、一个多变体产品、一个有多张图片的产品、一个含特殊字符的标题，以及一个有多地点库存字段的产品。若有开发店或内部测试空间，先在那里验证；若只能在目标店操作，也要将范围限制在明确的少量 SKU，并提前记录观察窗口。
样本不是为了证明整批必然成功，而是为了暴露模板、权限、字段和结果解释的问题。每个样本记录预期值、实际值、截图或导出、错误信息和下一步。只要身份键、货币、图片关联或发布状态出现无法解释的差异，就不要把剩余行加入同一次运行。
预览、批准和结果样本
按照 Shopify 的上传、检查、导入流程先阅读预览。批准人逐列确认：这是要覆盖的字段吗？空值会带来什么含义？这个 handle 是否真属于目标商品？变体数量和图片行是否对应？批准不能只看总行数。把预览文件、批准人、批准时间、原始文件 SHA 和实际运行文件 SHA 关联在一个批次记录中。
导入结束后立即抽样，不要等到下一次目录刷新才检查。抽样至少覆盖成功行、失败行、边界字符、无图片和多变体行。结果报告中的“成功”只是处理结果，应继续验证读回数据和页面表现。批次单明确写出扩大范围的条件；如果条件不满足，留下已验证的小批量并停止。
6. 文本字段、分类字段与多语言
标题、描述、供应商、标签和类型
文本字段先做语言、编码、空值、长度和 HTML 安全检查。标题应与身份矩阵中的产品一致；描述中的换行、列表和链接要经过渲染抽样；供应商、标签和产品类型应有允许值或人工批准。不要用标签替代分类，不要把一段营销文案自动复制到所有产品。缺失描述可以是有意的，也可以是源文件缺口，必须在结果清单中区分。
如果同一产品有中文和英文内容，分别保存源列和目标列，记录翻译版本和编辑人。没有事实依据的规格、认证、库存承诺或市场资格不应通过导入模板“补齐”。导入只负责传输获得批准的值；内容质量、合规和本地化判断仍由相应负责人完成。
分类和集合字段的边界
产品类别、产品类型、集合和导航可能都出现在导入文件，但字段被接受不表示分类体系设计正确。9916 只验证列名、值的格式、产品与集合的关联结果以及失败行；分类层级、命名规范、筛选器、导航和分类 SEO 属于 9922 分类与集合治理指南。如果导入前没有可批准的分类字典，把未知值隔离，不要由脚本临时创建一套新 taxonomy。
集合规则可能在数据导入后重新计算，所以验收要记录导入时间、集合条件和抽样结果。一个产品显示在集合中，不证明所有相关产品都正确；一个产品暂时未显示，也不必然说明 CSV 失败。分别读取产品字段、集合结果和导航呈现，使用不同责任人确认不同层级。
7. 价格、SKU、库存与地点语义
金额、重量、单位和精度
价格不能只看字符串是否能解析成数字。字段矩阵要写明币种、含税或未税假设、舍入规则、折扣是否另列，以及小数位如何验收；若这些问题未被官方或店铺规则确认，就只做格式检查，不推导财务结论。重量同样需要单位和精度，不能把磅、千克和克混在一张无单位的列里。
SKU 和条码要保留前导零，避免表格工具把它们转成数字。导入前统计空值、重复值和异常字符，导入后按产品与变体两个层级抽样读回。价格变了不代表订单价格或历史财务记录变了；本页只说明目录字段的传输和验证，不将它扩展为支付、税务或会计判断。
产品导入与库存转移的边界
库存字段要写清地点、数量、可售与否、读取时间点和授权人。一个产品 CSV 行被接受，不等于库存已经在地点之间移动，也不等于履约系统、库存账或订单可用量完成对账。涉及地点间调拨时，应按 Shopify 库存转移文档 另行核对流程；9916 只保存导入前后字段样本。
如果库存结果与预期不一致，先冻结后续批次，区分产品属性成功、库存字段失败和地点操作未完成三类情况。不要使用反向 CSV 试图替代调拨流程。库存负责人确认数量和地点，产品负责人确认 SKU 与变体，审计记录保留两者的时间点，避免把不同快照相减后得出没有来源的损益。
| 验收对象 | 需要记录 | 通过条件 | 不应推断 |
|---|---|---|---|
| SKU/条码 | 原值、前导零、变体归属 | 唯一且可读回 | 库存一定正确 |
| 价格 | 数值、币种、精度、更新时间 | 与批准矩阵一致 | 税费或订单金额 |
| 重量 | 数值、单位、变体归属 | 单位明确且可读回 | 运费或包装成本 |
| 地点库存 | 地点、数量、时间、负责人 | 样本与授权基线一致 | 已完成调拨/履约 |
| 变体选项 | 选项名、组合、SKU | 组合不重复 | 订单历史被改写 |
8. 图片 URL、媒体关系和失败隔离
URL、行关系、顺序和替代文本
图片 URL 预检至少包括协议、主机、响应可达性、文件类型、所属产品和变体关系。预检通过不代表 Shopify 成功抓取或页面按预期呈现，所以仍需在结果中记录平台返回、媒体顺序和渲染样本。不要把图片尺寸、压缩质量或 SEO 价值写成导入成功的同义词；这些属于媒体运营和页面性能的另一组验收。
媒体行的顺序很重要。为每个产品建立“预期第一图、其他图片、变体关联、替代文本”清单，导入后逐项核对。URL 中的临时签名、访问控制和重定向可能在预检后失效；记录检查时间和失败原因，把不稳定的 URL 留在隔离清单。
媒体失败时隔离产品批次
产品主字段成功而图片失败时，不要立刻重跑全目录。先保存已成功的产品字段读回值，标记失败媒体行，确认该行没有改变产品身份，再生成只包含媒体的补丁。若多个产品共享同一失效主机，按根因停下；若只有一条 URL 失效，可在修复来源后重新进行小批量验收。
图片缺失也可能影响页面审阅，但不应由编辑臆测为产品没有库存、没有发布资格或 SEO 一定下降。产品主体、媒体、渠道展示和搜索表现分别记录。需要讨论拍摄、压缩、替代文本体系和性能时，转阅 9921 产品图片优化指南，不要在本页扩张成媒体创意方案。
9. 状态、市场、集合与发布结果
草稿或发布意图要单独确认
新建产品的状态、发布渠道和市场可见性不能仅由“CSV 已处理”推断。Admin GraphQL 产品文档也区分产品字段、状态和发布信息；因此矩阵中要把“目标状态”“目标市场/渠道”“实际读回状态”分开。小批量先验证一个应该保持草稿的商品和一个经过批准可见的商品，避免把测试内容误放到公开页面。
状态改变时记录批准人、时间、渠道和测试账号。若一个渠道没有显示，先检查渠道资格、发布设置和数据是否已读回，不要直接改写更多字段。市场、语言、币种和 URL 本地化有各自的配置；产品导入只能证明传输的字段，不能替代整店上线检查。
集合结果只记录，不替代 taxonomy 设计
如果 CSV 包含集合或类型列，导入后以固定产品样本检查：值是否保留、规则集合是否重新计算、页面是否出现正确标题和链接。集合暂未更新时，保存观察时间和刷新条件，再决定是否重新读取。不要为了让一个样本出现而改变全局集合规则，这会把数据导入变成分类治理操作。
市场和集合的异常应按对象拆分：产品属性、变体、媒体、发布、集合、导航各有一条结果线。每条线有自己的负责人和停止门，最终在批次报告中合并。这样即使集合审核尚未结束，也能明确产品字段已经通过或仍需补验。
10. 文件格式、大小与导入前门禁
UTF-8、LF、header 和 15 MB
CSV 文件要按官方说明检查 UTF-8 编码、LF 换行、header 唯一性、列数一致性和文件大小。官方产品导入说明给出了 15 MB 的文件大小限制；这项限制属于当前文档的操作门禁，文件接近上限时不要依赖压缩或界面“似乎能上传”来推断可用。导入前计算字节数，不把字符数当作文件大小。
检查文件首尾、引号、逗号、换行、不可见字符、空列和超长文本。保留一份原始字节文件，再生成规范化版本；规范化后重新计算 SHA。若文件经过表格软件打开和保存，重新检查前导零、日期、换行、编码和图片 URL，不能只比较文件名。
防止表格软件破坏原始结构
建立一个只读原始区和一个可重建的生成区。生成脚本从字段字典读取列顺序和转义规则，输出后再用独立解析器检查行数、列数和关键字段。人工可以阅读抽样，但不能把手工改单元格作为唯一变更记录。所有修复用规则或补丁文件表达，便于再次生成和回到上一个版本。
文件门禁失败时不进入后台导入。常见错误页面只能作为诊断入口，不能证明所有语义问题都已解决；header 修好后仍要检查身份、数值、媒体和发布结果。把“格式失败”“数据失败”“平台处理失败”分开记录，下一步动作也不同。
| Preflight 项目 | 检查方法 | 证据 | 停止条件 |
|---|---|---|---|
| 原始文件 | 保存只读副本并算 SHA | 文件名、字节数、哈希 | 哈希无法重现 |
| 编码换行 | 独立解析 UTF-8/LF | 编码与行尾报告 | 出现替代字符或混合行尾 |
| Header/列数 | 与批准模板逐字比较 | 列清单、错误行 | 缺列、重复列、额外列 |
| 大小 | 读取文件字节数 | 字节数与文档门禁 | 超过 15 MB 或接近上限未拆分 |
| 身份样本 | handle/SKU/变体抽样 | 预期与实际表 | 空、重复或撞现有对象 |
| 回退材料 | 检查导出、映射、修复计划 | 目录清单 | 无法恢复批准字段 |
11. CSV runbook：上传、预览、批准、验收
把一个批次拆成可观察步骤
第一步冻结范围：写入产品 ID 或 SKU 集合、允许字段、文件 SHA、操作者和窗口。第二步导出基线并生成样本。第三步运行本地格式和身份检查。第四步在开发店或小样本中上传，完整阅读预览。第五步由批准人确认覆盖列和状态。第六步执行导入并保存活动证据。第七步读回结果，完成字段 diff、媒体抽样、集合/渠道抽样和错误分类。
每一步都有明确的“继续/停止”信号。上传成功只能让流程进入预览；预览通过才能进入批准；批准不能跳过小样本；导入处理完成不能跳过读回。执行时不要同时修改原始文件和后台设置，否则异常发生后无法定位因果。一个批次结束后再开始下一个批次。
记录活动证据、错误、责任人和停止点
活动记录至少含开始/结束时间、文件名和 SHA、范围、操作者、批准人、平台提示、成功/失败数量、失败行、读回样本和下一步。Shopify 的活动日志或后台提示可作为证据之一，但不替代字段级对账。若界面没有提供完整历史，就把外部批次记录作为团队自己的可追溯层。
错误信息要原样保存，再加上团队分类：格式、身份、字段值、媒体、权限、状态、集合或未知。不要把错误文本直接当成解决方案。失败行先隔离，修复后生成新文件和新 SHA；不要在同一文件上覆盖修复，避免无法知道哪一版产生了结果。
12. Admin GraphQL 的受控批量替代路径
productCreate 与 productUpdate 的职责差异
官方 Admin GraphQL 文档把 productCreate 和 productUpdate 分开。创建产品通常需要 write_products 权限，且初始变体和后续变体操作有各自的处理边界；更新产品字段也不等于自动更新全部变体。文章可以把它们作为一个受控的批量装载路径，但每一个 mutation 都要记录 API 版本、权限、输入、返回错误和资源状态。
API 路径适合结构已稳定、需要明确字段选择和结果 ID 的小批量。它不自动成为 CSV 的全字段替代，也不保证多对象事务。请求成功后继续查询产品、变体、媒体和发布状态；返回无错误只说明那次请求被接受。需要变体时使用文档规定的变体操作，不把产品 mutation 的结果扩大解释。
productSet 与变体批量更新的风险
productSet 可以创建或更新产品，并可采用同步或异步模式；文档还提示，输入中省略的列表字段可能被删除，而其他省略字段有不同保留行为。productVariantsBulkUpdate 有部分更新选项和变体数量边界。使用前把每个列表字段写进矩阵，明确“保留”“替换”“清空”三种意图，不能从一次成功响应推断没有破坏性变化。
部分更新也不等于原子回滚。为产品、变体和媒体分别保存前值，限制批次大小，读取返回的 user errors 和结果对象，遇到一个无法解释的错误就停止同类请求。API 版本和限制会变化，发布前重新打开官方文档；不要硬编码一个适用于所有计划、应用和版本的速率或上限。
13. 限流、异步批量与重试边界
bulk query 的异步完成证据
Admin GraphQL bulk query 是异步操作。发起请求、等待完成、取得结果和把结果纳入导入文件是四个不同阶段。保存操作 ID、提交时间、状态变化、错误、下载地址的保留规则和结果 SHA。状态变成完成，不等于每一列都符合字段字典，也不等于后台页面马上反映；先做记录数、空值和固定样本检查。
如果批量读回结果用于生成下一份 CSV，保留“读取版本”和“写入版本”的关系。读取失败时不要用旧文件冒充新结果；下载不完整时也不要开始覆盖。异步任务超过团队设定的等待窗口，应进入人工诊断，不要无限重试或重复创建同一任务。
query cost、输入数组和退避记录
Shopify API 限制文档以计算成本和 leaky-bucket 行为解释请求限制，并给出单次查询与输入数组的约束示例。真实限制取决于当前 API 版本、计划、查询结构和响应成本，所以每次运行记录查询成本、响应扩展、限流提示和退避时间。重试要有次数、间隔、是否可安全重复的判断，不要把指数退避写成“必然成功”。
批量输入拆分应按稳定身份键分组，避免同一产品同时落入两个请求。遇到超时或限流，先确认服务端是否已经处理，再决定是否重试；重复请求可能重复产生可见变化。对于不可判定状态，停止该批次，查询结果并人工确认，再生成只含未验证范围的补丁。
14. 结果校验、差异诊断与失败隔离
前后字段 diff 与样本对账
验收分三层。第一层是结构：文件是否解析、行数是否符合、身份键是否唯一、请求是否返回错误。第二层是对象：产品、变体、媒体、价格、库存、状态和集合是否与批准矩阵一致。第三层是页面和运营抽样：标题、选项、图片、可见性和链接是否符合预期。每层都保存前值、后值、比较规则和负责人。
字段 diff 要区分“缺失”“变空”“格式归一化”“预期改变”和“未授权改变”。例如价格小数显示不同可能是格式差异，但价格数值改变可能是高风险；空描述可能是批准的清空，也可能是列错位。不要用一个总成功率掩盖一条高风险异常。统计只是导航，逐条证据才是通过依据。
对账样本要固定窗口和顺序：先按产品身份匹配，再按变体选项匹配，最后比较字段。媒体用 URL 与关系匹配，库存用地点和时间点匹配，状态用批准记录匹配。若查询读回的是缓存或不同时间点，记录这一事实并重新取样；不要为了让数字相等而修改源文件。
按错误类型切出修复批次
失败隔离的最小单元通常是一个产品、一个变体组、一个媒体行或一个字段列，取决于错误的传播范围。身份冲突隔离产品；图片主机失效隔离媒体；全文件编码错误则停止整个批次；API 限流按尚未确认的请求范围隔离。每个隔离单元有原错误、修复动作、修复后 SHA 和复验结果。
修复批次不能含未验证的成功行。对已通过的行保持只读，导出差异后生成最小补丁。再次运行前确认旧状态仍是预期状态；如果已经被人工改变，重新取得基线。这样做可能比“再全量跑一次”慢，却能减少覆盖范围和未知副作用。
| 信号 | 证据 | 处置 | 可继续条件 |
|---|---|---|---|
| header 错误 | 解析器错误与文件行 | 修模板，重新算 SHA | 结构检查全绿 |
| handle 未匹配 | 查询结果与身份表 | 隔离该行 | 唯一对象已确认 |
| 变体部分失败 | user error、变体读回 | 按变体组拆补丁 | 每个组合可解释 |
| 图片不可用 | URL/媒体结果 | 单独修复媒体 | 产品主体已通过 |
| 限流/超时 | 成本、状态和时间 | 暂停并确认服务端状态 | 未确认请求已清点 |
| 未授权字段改变 | 前后 diff | 停止并恢复批准范围 | 责任人重新批准 |
15. 验收、恢复与边界内导航
9916 的完成定义与恢复材料
一个 9916 批次只有在以下证据齐全时才算完成：原始导出和输入 SHA 可重现，预览与批准记录存在，产品与变体身份无重复，字段矩阵中的允许列通过，媒体和状态样本通过，集合/渠道结果已分别记录，错误行已隔离或关闭，前后 diff 已签字，恢复材料可读取。任何“未检查”都不能写成通过。
恢复不是把所有旧数据无差别覆盖。先确认要恢复的字段、旧值和当前值，再生成最小反向补丁；执行后重新查询并签字。若平台或源记录无法证明旧值，停止恢复并等待负责人决定。不要把 CSV、GraphQL、webhook 或活动日志中的任一单项当作完整事务历史。
9917、9921、9922、5946 和 9746 的阅读边界
需要长期外部同步、增量游标、webhook 重试和多系统冲突规则时，阅读 9917 产品数据同步指南。需要拍摄、压缩、替代文本、媒体 SEO 或性能时，阅读 9921 产品图片优化指南。需要分类层级、集合规则、导航和分类 SEO 时，阅读 9922 分类治理指南。需要整店的产品、支付、运输和上线顺序时，阅读 5946 基础店铺搭建指南。需要礼品卡发行、退款、币种、安全或财务时，阅读 9746 礼品卡指南。这些链接只是同语种导航，不是本页的事实来源，也不改变 9916 的一次性导入边界。
常见问题
CSV 导入开始后能不能取消？
不能把它当成可取消任务。Shopify 官方导入说明提示，导入开始后不能取消，所以应在上传前完成导出、样本 rehearsal、字段批准和回退材料准备。开始后发现问题时，先记录已经处理的范围，停止后续批次，读取结果并按最小字段补丁修复。不要承诺平台有一键撤销或完整导入历史恢复。
更新已有产品时为什么必须核对 handle？
因为 handle 参与产品身份和 URL 相关匹配，标题相同不保证对象相同。更新前用已确认的 handle、SKU 或资源 ID 做唯一查询，并把查不到、查到多个和查到一个分别处理。任何 handle 改动都要单独批准；不要先改身份键，再尝试用新键寻找旧值。
多变体产品的行和图片应怎样排列？
按当前 Shopify CSV 模板的产品首行、变体行和图片行规则组织，并在小批量中验证关联。每个变体的选项组合和 SKU 应唯一，图片行要记录所属产品或变体及预期顺序。不要仅凭空白单元格推断继承关系；以官方模板、预览和读回结果共同验收。
productSet 是否等于 Shopify 原生双向同步？
不是。productSet 是 Admin GraphQL 的一次产品创建/更新能力，存在列表字段、省略字段、同步/异步和变体数量等边界。它没有自动提供外部源的调度、游标、冲突所有权、重放或双向真相。需要持续同步时，按 9917 的意图另行设计和验收。
导入失败时怎样回到上一个可验证状态？
先停止扩大范围，保留原始导出、输入 SHA、预览、结果和错误行。按产品、变体、媒体或字段确定失败传播范围，再生成只覆盖已批准旧值的最小反向补丁；执行后重新读回并比较。若旧值、当前值或平台处理状态不完整，暂停恢复并人工确认。这个方法依赖证据，不等同于 Shopify 平台自动事务回滚。