platforms/docs/操作日志_用户端APP_结算流程_20260907.md

用户端结算流程扩展

操作时间：2026-09-07。操作类型：扩展。影响模块：商城结算、库存事务与幂等恢复。

操作前后

原商城只能单件购买，以弹窗确认地址和金额。本次接入 /checkout/:identity 独立提交订单页面，选择地址、调整数量、填写配送备注、查看商品金额及合计，提交成功进入商城订单列表。游客登录回跳保留商品公开标识。图 12、14 原稿均已检查；本轮实现图 14 的基础结算链路，图 12 仍未实现，不能将商品摘要称作商品详情页。

关键代码

• apps/user_app/lib/ui/features/shop/checkout_page.dart：按标识加载商品和默认地址，数量范围 1 至 min(库存,999)，提交前不写订单；结果未知时冻结原数量、地址、备注，重试沿用原请求号。价格或库存明确变化时允许刷新后再确认。
• shop_page.dart、app/router.dart：购买进入独立结算页，路由继续受登录保护。
• data/repositories/client_repository.dart：新增 submitShopOrder，保留旧 createShopOrder 方法兼容调用。
• backend/api/internal/logic/client/user/shop.go：可选 expected_payable_amount；依据数据库价格计算，报价不符回滚库存。校验单项数量 ≤999、最多100项及备注长度。乘加之前检查整数溢出。优先查找本人同请求号订单，地址随后归档或库存归零不影响成功请求的恢复。
• backend/api/internal/logic/client/user/checkout_test.go：金额按数量结算、报价变化回滚、溢出不扣库存、已创建订单不再依赖地址。
• apps/user_app/test/ui/shop_address_selection_test.dart：确认前不下单、选择地址联系人、数量两件与金额一致、失败冻结输入、同请求号重试。

接口兼容与环境

原 POST /heqi/client/v1/user/shop/orders 接受新增可选 expected_payable_amount（整数分）；旧客户端可省略。客户端传入金额只用于确认，不代替服务端计算。错误 2401 表示价格变化，2402 表示库存不足或商品下架。错误对象在包初始化注册，避免并发请求修改 SDK 全局错误表。

本轮不修改数据库表，不运行迁移或 seed。本机 API 继续使用远程 PostgreSQL、Redis；没有启动本机数据库/缓存容器。

验证

• Go 结算专项通过，SQL Mock 验证失败时回滚，不连接真实数据库。
• 远程指定开发账户对 MOCK-EC-PRODUCT-010 验证错误报价拒绝、两件金额、备注持久化、重复提交恢复同一订单及库存只扣一次。临时订单已取消，库存恢复，未支付或配送。
• Widget 结算流程通过；图 14 已生成四种手机宽度与两种文字缩放的 8 张截图，检查滚动后无溢出。
• 用户端全量 53 项测试、Flutter 静态检查、Go 全量测试及 vet 通过；Web 最新构建成功。图 14 对照继续用于记录缺项，不是通过证明。
• 浏览器验证登录回到指定商品结算、数量由1变2时金额由105元变210元、打开地址选择后返回仍保留数量；390×844实际页面已核对。真实创建/取消验证由 API 完成，浏览器未再次创建订单。结算页285行、后端结算专项68行；无新增依赖。

未完成项与风险

图 14 中的预约配送、押金、优惠券、发票、结算前支付方式选择和多商品合并仍未接入。本页没有把设计示例金额当作真实收费规则。商品原图缺失仍需后台素材补齐；当前截图不通过严格 1:1。订单创建与付款分开，成功后进入既有订单页付款，不代表付款或配送已经成功。

单项数量/条目上限是本次输入保护，可能拒绝旧客户端超过上限的超大请求；正常用户端购买不受影响。后续购物车接入必须继续服务端计算总额，保留事务回滚与请求幂等测试。