OpenClaw—AI研究ShopSystem Day 14 完成路线图第一阶段「基础设施补全」末项 物流跟踪(模拟快递100 API):新建 shipments 与 shipment_tracks 两表存储运单主记录与逐段轨迹明细,把「admin/merchant 发货」事务化(锁订单 + 校验已支付 + 一次性写入完整 6 段轨迹 + 返回运单号),新增 GET /api/shipments/[trackingNo] 买家查询接口(401/403/404 鉴权齐全,允许匿名订单归属),订单详情页加 ShipmentTracker 时间线组件(承运商 + 运单号 + 状态徽章 + 6 段倒序轨迹 + 当前节点高亮 + 过去/未来灰显分层)。附带把 /api/admin/orders/[id]/status 的 catch 内业务错误从 HTTP 500 改 400(RESTful 化,引入 HttpError 类),解决调试/前端区分错误类型的痛点。Qclaw 浏览器用户视角测试 12 项全过,顺带挖出一个 P3 边角 bug(地址脏数据拼接导致 location 显示重复)也已修。整套改动 6 个文件 ~630 行新增 / ~50 行修改,2 个新表,0 个未修 bug。
买家订单详情页物流跟踪卡片视图(已发货/已揽收状态):进入 /orders/[orderNo],服务端在订单 status 为 shipped 或 delivered 时拉 shipments + shipment_tracks(shipment 为 null 时不渲染卡片),传给客户端组件渲染。卡片头部有「📦 物流跟踪」标题 + 当前状态徽章(已揽收/已签收等),下方是承运商(顺丰速运 SF)+ 快递单号(等宽字体显示便于复制)。垂直时间线按时间倒序展示(最新在上),6 段轨迹从 T+0min「快递员已揽件」到 T+36h「已签收」,每一段有圆点 + 时间 + 地点 + 描述,当前节点用 brand 主色高亮(ring-2 ring-brand-200),已走过的节点灰显,未到的浅色——一眼看出物流推进到了哪一步。本图展示的是脏数据订单的真实渲染(地址里省=市的旧测试数据),中间修复后会正常合并,但旧运单按修复范围不追溯。
发货链路设计要点:admin/merchant 在 /ladmintood/orders 看到 paid 状态订单点「发货」按钮 → 调 POST /api/admin/orders/[id]/status body {status:'shipped'} → 后端 transaction() 内先 SELECT ... FOR UPDATE 锁订单(防并发双发)→ 校验 status === 'paid'(否则 400 明确错误)→ 随机选承运商(SF/ZTO/YTO/ST 四家)→ 生成运单号(承运商前缀 + YYYYMMDD + 6 位字母数字,避开易混的 0/O/1/I)→ 写 shipments 主表(收件人姓名/手机/地址冗余存,不 JOIN addresses 防地址改污染历史物流)→ 生成 6 段轨迹并批量写 shipment_tracks → 返回 {trackingNo, carrier} 给前端。demo 阶段一次性写完整 timeline 无需后台推进任务,真实集成场景可改成定时任务增量更新。delivered 状态走单独的事务分支同步更新 shipments.delivered_at 与 status,保持两边状态一致。
买家物流跟踪已签收视图:同一组件渲染,状态徽章切换到「已签收」绿色,时间线里最新一段「[城市] 已签收」显示在顶部并以 brand 主色高亮(圆点 bg-brand-500 + ring-2 ring-brand-200),其余 5 段全部以 bg-gray-300 灰显表示已走过。运单号 SF202608275RMGVP(本图为真实查询结果),承运商顺丰速运,完整 6 段轨迹从揽件到签收的地理流转(深圳 → 武汉中转 → 深圳分拣 → 派件 → 签收)清晰可见,中转城市从常用枢纽里随机抽(武汉/郑州/西安/广州)以增加真实感。鉴权层做了严格归属校验:登录用户必须是订单归属者(order.user_id 匹配),或订单本身是匿名订单(user_id IS NULL)允许通过;非归属 403、tracking_no 不存在 404、未登录 401,错误码与文案 RESTful 化便于前端按 status 分支处理。
admin 后台订单管理视图:全部订单列表,左侧状态筛选 tab(全部/待支付/已支付/已发货/已送达/已取消/已退款),每条订单根据当前状态显示对应操作按钮组——待支付订单有「标记已支付」与「取消」两按钮(后者二次确认弹窗),已发货订单显示「确认送达」按钮,已送达/已取消/已退款订单无可操作项(显示「—」)。admin 触发发货/标记送达的操作统一走 POST /api/admin/orders/[id]/status 接口,商户发货需先验证订单归属(订单项里至少有一件商品属于自己),否则 403「订单不属于您的店铺」。HttpError 类把所有业务校验错误(不允许的状态 / 订单当前状态为 X / 订单不存在 / 订单不属于您的店铺)从原版的 HTTP 500 catch-all 改成对应 4xx(400/403/404),只有真正的系统异常才返回 500,前端可以用 if (status === 400) 精准弹出字段错误提示而无需无差别 toast。
附带的 P3 数据/边角修复:deriveOriginCity / deriveDestCity 直接 ${province}${city} 拼接,遇到脏数据(测试时复制的 province=city 同名地址)会显示 [广州市广州市] 重复。提取 combineProvinceCity(province, city) helper 加 4 层去重逻辑——全等/省含市/市含省/正常拼接,顺带 .trim() 防御空格脏数据;两个函数共用 helper 消除复制粘贴。Qclaw 浏览器用户视角 12 项 + P3 复测 4 项全部通过,发货链路 / 买家物流卡片 / 鉴权边界 / 回归均无新 bug。第一阶段 4 天(SKU 多规格 Day11 / 优惠券 Day12 / 地址管理 Day13 / 物流跟踪 Day14)至此全部完成,基础设施闭环就绪,Day 15 起进入第二阶段「用户体验」首项 退款/售后流程。代码 commit 已推送到 GitHub main 分支(c1c9a6a feat(day14): 物流跟踪(模拟快递100 API) + P3 bug 修复),本帖已同步发布到 hk temp 网站。累计项目:ShopSystem Day 14 / 目标 30+ 天…