Taro + Zustand 跨端购物清单：本地持久化与报价边界

本文来自对一个个人多端零售客户端默认分支的只读源码审阅，检查日期为 2026-10-14。源码声明 Taro 4.1.11、React 18、Zustand 5，并配置了微信、支付宝、抖音和 H5 构建入口；这只能证明工程声明了目标，不能证明每个目标都已经构建、发布或真机验收。文中不保留项目品牌、接口地址、联系人或配置值。

状态模型从用户任务出发

客户端把配件和服务统一放进采购清单。当前条目模型含类型、ID、名称、品牌、价格、单位、图片、分类、数量和加入时间；Zustand store 负责添加、移除、改量、清空与抽屉状态，Taro 同步存储 API 在每次变更后写入。页面提供清单为空、数量调整、删除、确认清空、复制文本和保存报价等操作。

这类状态不是“商品目录”的副本，而是一个可恢复的用户草稿。建议把持久化 DTO 与 UI store 分开，只保存继续完成任务所需的白名单字段；临时弹层状态、回调、加载状态和冗余展示数据不要一起序列化。

读取持久化数据要校验

当前实现对本地内容直接 JSON.parse 并断言为 CartItem[]。TypeScript 类型不会在运行时验证 JSON；旧版字段、截断数据、手工修改和存储版本变化都可能让页面收到不符合预期的对象。当前读取异常会返回空数组，写入异常也会被吞掉，而状态仍继续更新。这让 UI 看起来成功，但应用重启后清单可能消失。

把持久化边界写成明确的版本化协议，并逐项验证：

type StoredCartV1 = {
  version: 1;
  items: Array<{
    type: 'part' | 'service';
    id: string;
    quantity: number;
  }>;
};

function isQuantity(value: unknown): value is number {
  return Number.isSafeInteger(value) && Number(value) > 0 && Number(value) <= 99;
}

解析成功后仍要核对版本、字段类型、字符串长度、数量上下限和条目总数。无法迁移的旧数据应说明并允许用户清理，不要把“解析失败”悄悄伪装成主动清空。若存储写入失败，应让界面明确区分“本次会话可见”和“已成功保存”，并提供重试或复制备份的路径。

多端身份和数量约束

源码按 id 查找并合并条目。如果配件和服务分别生成 ID，两个领域恰好使用同一个 ID 时会误合并；身份键宜使用经过规范化的 type:id，并在 isInCart、更新、删除和持久化迁移中统一。数量操作不应只靠加减按钮限制，store 入口也要拒绝非有限数、非整数、负数和超过上限的值。

Taro 的同步存储调用短而直观，也有对应的异步 API。同步读写会占用当前 JS 执行时段；当数据量变大或写入频繁时，先做真实设备测量，再决定是否改为异步存储、批量写入或延迟持久化。各端可用 API、配额、卸载清理和页面生命周期并不天然相同，要把适配差异收敛到 storage adapter，并对每个目标端单独测量。

预估金额不能成为报价

页面用 price * quantity 计算预估小计，并将整个条目对象发送到报价接口。浏览器里的价格、名称、数量和总额都可被修改，不能作为服务端账本。更稳妥的提交只传 type、商品 ID 与数量；服务端重新查询当前有效目录、核验权限和库存，再使用整数最小货币单位或 Decimal 规则计算金额，并保存不可变的报价明细快照。列表展示的价格应明确标为预估值。

报价提交还要区分“按钮防连点”和服务端幂等。网络超时后客户端可能不知道请求是否成功；带稳定 request ID 的重试应返回原报价，而不是重复创建。手机号、车牌、车型与备注属于额外个人信息，应按业务必需性收集、说明用途、限制日志和设置保留期限。

页面生命周期与错误状态

当前清单页在 React useEffect 和 Taro useDidShow 中都会读取店铺配置，首次展示可能重复请求；页面还保留硬编码联系占位值，并静默忽略配置失败。更稳妥的方式是选定唯一数据加载入口，或使用可去重缓存；为请求设置过期响应保护，并在配置缺失时隐藏拨号动作、显示可重试状态，而不是展示看似真实的占位联系人。

验收时覆盖冷启动恢复、畸形/旧版本数据、存储配额失败、重复点击、ID 冲突、超限数量、失效登录、目录改价、报价超时重试、返回页面刷新和切换平台。测试存储失败不能误报“已保存”；每个平台分别检查同步/异步 API、导航、剪贴板和弱网行为。源码审阅不是构建或真机结果，发布结论必须等到对应工具和设备验证后再写。

这篇前端状态管理复盘与多端零售全栈报价链路互补：前者聚焦客户端状态、持久化与交互，后者讨论跨端领域流和服务端报价不变量。

参考：Taro 同步读取本地存储、Taro 同步写入本地存储、Zustand 持久化数据、React Effect 与请求清理。