# 商城订单详情开发与验证记录

操作时间：2026-09-08。操作类型：新增详情、提取共用操作、修复底栏。影响模块：用户商城订单接口、订单列表、详情路由。数据库与缓存继续连接既有远程服务；本轮无迁移、无本机数据库容器、无订单或库存写入。

## 操作前后

已打开最新21-订单详情原图，检查状态、配送进度、联系人、商品、费用、订单信息及操作入口。原订单列表只能打开操作弹层，没有独立详情。新增`/shop/orders/:identity`，点击商城订单或“查看详情”进入；直接深链需登录，登录后返回原订单。气瓶订单仍沿用旧入口，本轮未把商城详情冒充气瓶完整详情。

详情独立读取本人订单。商品名称、数量、单价与收货信息来自成交快照；资料缺失明确显示空态，不读取当前商品/地址覆盖历史。仅展示真实记录的下单、支付、发货及收货时间，电话按原图脱敏，应付金额不标为已实付。

## 代码变更

| 文件（仓库相对路径） | 职责/函数及行数 |
| --- | --- |
| backend/api/internal/logic/client/user/shop_detail.go | 新增73行；GetShopOrder本人详情，shopOrderState共用动作与状态 |
| backend/api/internal/logic/client/user/shop.go | ListShopOrders复用shopOrderState，原响应及操作规则保持兼容 |
| backend/api/internal/logic/client/user/shop_detail_test.go | 新增73行；归属条件、成交快照、白名单、非法订单和状态动作 |
| backend/api/internal/routers/client.go、client_test.go | 新增受JWT保护的GET shop/orders/:identity及路由检查 |
| apps/user_app/lib/domain/models/shop_order_detail.dart | 新增89行；ShopOrderDetail、ShopOrderLine，整数分金额、成交数量、时间与OrderSummary适配 |
| apps/user_app/lib/data/repositories/client_repository.dart | shopOrderDetail独立读取，校验返回identity及会话一致性 |
| apps/user_app/lib/ui/features/orders/order_action_handler.dart | 新增217行；从原订单页提取确认、支付、退款及退款原因对话框，不重复实现交易规则 |
| apps/user_app/lib/ui/features/orders/orders_page.dart、order_list.dart | 列表点击进入详情；保留“查看操作”，详情返回刷新订单和退款列表 |
| apps/user_app/lib/ui/features/orders/shop_order_detail_page.dart | 新增302行；_load、_act、_copy、_footer，独立加载、操作前刷新、复制反馈、底栏布局 |
| apps/user_app/lib/app/router.dart | 新增受会话守卫保护的/shop/orders/:identity |
| apps/user_app/test/ui/shop_order_detail_test.dart、test/data/shop_order_detail_test.dart | 新增137/70行；失败重试、复制、确认取消、过期动作、金额、响应归属 |
| apps/user_app/test/support/a1_fixture.dart、tool/a1_visual_test.dart | 明确独立测试Fixture及图21多尺寸截图 |
| scripts/compare-user-app-a1.ps1 | 加入图21，现14组并排设计证据 |

## 接口及交互边界

- `GET /heqi/client/v1/user/shop/orders/:identity`在SQL中同时限定公开identity和JWT对应user_account_id，未命中返回1112，未登录HTTP401。
- 响应显式列出订单信息和商品快照字段，不返回内部主键、用户外键或完整任意JSON快照。商品已改价/删除不会改变成交明细。暂无历史图片的订单继续显示缺失状态。
- 商城状态16发布pay/cancel，18发布refund，18且物流20发布confirm_receipt，取消订单不发布动作；详情与列表共用定义。服务端动作接口仍负责最终状态及所有权校验。
- 详情操作前重新读取订单，原动作已失效时不提交。取消/收货必须确认，未知错误显示失败并重读，不伪造成功。支付与退款复用原请求号策略；本轮没有执行真实支付或退款。
- 操作栏放在Scaffold底栏，避免SnackBar遮挡按钮；按容器宽度约束两个按钮，修复原主题最小宽度导致申请退款独占整行的问题。

## 验证

- Go全量`go test ./...`、`go vet ./...`与API构建通过；路由与业务测试覆盖本人过滤、历史名称/金额、字段白名单、缺失订单及五组状态动作。
- Flutter analyze通过，全量95项测试通过。原订单取消、确认收货、退款刷新回归保留；新增详情测试覆盖深链、首读失败重试、复制内容、确认取消、失败重试、已失效动作不提交、整数分及跨账号迟到响应。
- 图20（两种标签）和21的320/360/390/430宽度与1.0/1.3字号共24项布局检查通过。查看图21的390普通和320大字体截图后修复按钮布局，图21再次8项通过，并实际查看修复截图。
- Web Release与Android Debug构建通过；Android仍提示既有插件Kotlin和SDK XML版本兼容警告，未影响当前产物。构建通过不代表真机相机/语音或支付验收完成。
- 本机API进程6884运行新后端，端口12426；18571提供Web。读取此前已取消测试订单`EC1788842040900189900`：商品9/10各2件，单价10400/10500分，总金额41800分，动作列表为空。不存在订单返回1112，匿名访问HTTP401。
- 浏览器390×844实际验证深链跳登录并回原订单，显示已取消、历史联系人与地址、两项商品、418元费用和订单备注；点击复制显示“已复制订单号”。订单及库存未改变。
- 浏览器返回商城订单列表后再点击“查看详情”，重新进入同一订单并独立读取；没有回退到旧操作弹层。浏览器错误/警告日志为空。

## 视觉结果与待办

整页验收仍failed。原图是气瓶配送中的示例，商城分支尚不能提供押金、配送员、预计送达、供气合同、服务联系与地图轨迹；历史商品图缺失，时间轴结构和页面密度仍有差异。未填入设计示例时间、照片、合同或实付数据。58图中现14张部分实现、44张无完整页面、0张严格全功能1:1通过。

证据：[图21并排](视觉验收/A1/21_并排对照.png)、[390截图](视觉验收/A1/21_390_1.0.png)、[320大字体](视觉验收/A1/21_320_1.3.png)。后续需继续补气瓶订单详情与配送业务，不能仅将路由存在视为完成。

## 维护方式

订单列表与详情的允许动作只能修改shopOrderState并补状态测试，写操作继续保留服务端锁和幂等边界。公共字段扩展使用白名单，不直接透传模型或JSON快照；详情显示历史资料的含义不得变成当前商品信息。运行`flutter test test/ui/orders_page_test.dart test/ui/shop_order_detail_test.dart test/data/shop_order_detail_test.dart`与Go用户逻辑/路由测试后，使用图21多视口截图核对布局。