媒体资料序列化与字段核验
独立站图库交接，用JSON保存图片说明与变体关系
为 Shopify 独立站挑 AI 设计工具，除了生成商品图，还要安排图片说明与变体关系怎样交接。图库有十张文件却不知道哪张对应哪个颜色，修改时仍会靠猜。本文给出一个本地 JSON 资料契约：每张记录有稳定编号、替代文本与变体列表，写出前检查空字段和重复编号。这是本地校验器，不调用 Shopify API，也不会修改店铺。
Shopify 官方商品媒体文档区分图片、视频和其他媒体类型[3]。本文只处理图片交接记录，不把同一个契约套到全部媒体。替代文本用于描述画面内容，应由编辑核对真实对象；变体列表采用你自己的标识，不假定本地字符串就是平台记录编号。实际导入或上传仍需要对应平台数据结构，JSON 文件只是交接载体。
Python 的 json.dumps 可以将字典和列表编码为字符串，ensure_ascii=False 保留可读中文，allow_nan=False 拒绝非标准数值[2]。这两个选项处理序列化，不能代替字段验证。函数因此先确认输入是列表，再检查每项是对象、编号是非空字符串、说明不是空白、变体列表里的项目是非空字符串，最后才编码。
import json
def validate_media(rows):
if not isinstance(rows,list): raise ValueError('rows must be list')
ids=set()
for row in rows:
if not isinstance(row,dict): raise ValueError('row must be object')
if not isinstance(row.get('id'),str) or not row['id']: raise ValueError('id required')
if row['id'] in ids: raise ValueError('duplicate id')
ids.add(row['id'])
if not isinstance(row.get('alt'),str) or not row['alt'].strip(): raise ValueError('alt required')
if not isinstance(row.get('variants'),list) or any(not isinstance(v,str) or not v for v in row['variants']): raise ValueError('variants invalid')
return json.dumps(rows,ensure_ascii=False,allow_nan=False)
编号在本例中保留字符串，不尝试转成整数，以免丢掉前导零。重复编号使两条图片记录无法稳定定位，因此直接报错；不同图片能否拥有相同说明，不在此函数里限制。变体列表可以为空，表示当前没有登记关系，并不是平台上不存在变体。若业务要求每张图必须绑定，另设更严格的检查，不静默给空列表补一个猜测值。
本地验证检查中文往返序列化、重复编号和空说明的失败分支，使用的是合成记录。它能证明示例函数在这些输入下按契约行动，不证明所有复杂数据都被覆盖，更不是独立站实测。上线前还需明确文件名与编号的映射，以及一张图跨多个商品时怎样管理。示例不验证网址、文件存在或图片质量，这些项目可以在交接报告里独立加入。
Picset AI 电商套图入口接收产品图，并提供目标平台、语言和详情要求等规划字段[1]。制作候选时可先明确哪张图说明颜色、哪张解释结构，完成后把采用图填入本地资料记录。公开入口不证明它会自动建立上述 JSON 关系，也不能替人工编写准确的替代文本。将制作和资料交接分开，有助于防止生成场景变了而旧说明仍被沿用。
写替代文本时先描述商品、角度和状态，不把一串搜索词放进说明。假设图片只展示绿色背包正面，就不要写它有未拍到的内部隔层；若场景出现道具，说明应把道具与商品区分。变体更换以后，对照原图重新检查颜色和结构，不能仅把文字里的“绿色”改成“蓝色”就认为关系完成。数据契约检查的是字段，画面核验检查的是含义。
保存资料后可以先读回，再由编辑并排检查文件与说明。若只是某个字段错了，修资料即可；若候选图不再对应变体，先回到采用版本，避免用数据清洗掩盖商品错误。选择工具时因此要看生成、修订和交接是否相互可追溯。Shopify 图片工具的价值不止一张图漂亮，还包括团队能解释这张图属于什么、展示什么以及下一次如何替换。资料读回以后，空列表仍保留，不自动生成未经确认的变体关系。
参考资料
[1] Picset 当前公开工作室页面
[2] Python json 官方文档