51 lines
5.3 KiB
Markdown
51 lines
5.3 KiB
Markdown
# 用户端供气订单详情开发与验证
|
||
|
||
操作时间：2026-09-08。操作类型：扩展。影响模块：用户端订单、本人合同读取、供气签收。
|
||
|
||
## 行为变化
|
||
|
||
此前气瓶订单只有列表与通用操作。本次增加独立详情：历史气瓶明细、供气单位、配送员姓名、配送费、实际支付记录、状态发生时间及本人合同正文。订单列表点击详情进入 `/gas/orders/:identity`。只对待签收订单发布确认收货动作，用户确认后服务端事务记录本人签收、完成订单并释放气瓶占用；重复确认不重复写证据。
|
||
|
||
## 文件与职责
|
||
|
||
| 文件（相对仓库） | 函数及变更 |
|
||
| --- | --- |
|
||
| backend/api/internal/logic/client/user/gas_detail.go | GetGasOrder、GetGasContract；所有权过滤、显式公开字段与统一状态动作 |
|
||
| backend/api/internal/logic/client/user/gas_confirm.go | ConfirmGasReceipt；行锁、状态校验、签收证据、占用释放和历史记录 |
|
||
| backend/api/internal/logic/client/user/gasorder.go | ListGasOrders复用状态及动作定义 |
|
||
| backend/api/internal/models/gasorder_confirm.go | 中文注释补充user_app签收方式；无表结构变更 |
|
||
| backend/api/internal/routers/client.go | 增加受保护详情、合同和签收路由，原接口兼容保留 |
|
||
| apps/user_app/lib/domain/models/gas_order_detail.dart | 强类型详情、整数分支付、合同正文模型 |
|
||
| apps/user_app/lib/data/repositories/client_repository.dart | gasOrderDetail、gasContractDetail、confirmGasReceipt；会话与响应归属校验 |
|
||
| apps/user_app/lib/ui/features/orders/gas_order_sections.dart | 真实状态时间轴、服务资料、合同读取及失败重试 |
|
||
| apps/user_app/lib/ui/features/orders/shop_order_detail_page.dart | 兼容商城页面并增加供气分支 |
|
||
| apps/user_app/lib/ui/features/orders/order_action_handler.dart、orders_page.dart | 签收确认、稳定请求号重试、详情返回刷新 |
|
||
| apps/user_app/lib/app/router.dart | 本人供气订单深链与登录回跳 |
|
||
| scripts/compare-user-app-a1.ps1 | 图21气瓶与商城分支分别配对原图，十五组对照对应十四张设计 |
|
||
|
||
新增后端测试gas_detail_test.go、gas_confirm_test.go、gas_receipt_remote_test.go，前端test/data及test/ui/gas_order_detail_test.dart；视觉Fixture明确与真实数据分离。
|
||
|
||
## 接口与边界
|
||
|
||
- `GET /heqi/client/v1/user/gas/orders/:identity`、`GET gas/contracts/:identity`：JWT本人范围，缺失或非本人1112，匿名HTTP401。详情不返回内部主键、员工手机号、操作人身份或内部处理备注。
|
||
- `POST gas/orders/:identity/confirm-receipt`：只接受request_no，长度1—128；仅状态34可签收，已完成23幂等返回，其他状态1704。收货人取当前账户，不能由请求冒用；写入user_app证据，不伪造手写签名或图片。
|
||
- 合同仅阅读既有正文，附件地址不外泄；完整合同列表筛选、签署和附件下载仍未完成，不能把正文弹层计为图32完整页面。
|
||
- 支付记录只读本订单、本付款人的成功支付；不能从履约状态推断实付。订单无押金、ETA及受控联系方式契约时不填设计演示数值。
|
||
|
||
## 验证证据
|
||
|
||
- 本轮Go全量测试、vet和API构建通过；Flutter全量98项及analyze通过。时间轴调整后analyze与5项详情定向测试再次通过。
|
||
- 气瓶/商城订单列表与详情32组布局检查通过；时间轴调整后图21-gas的320/360/390/430宽度、1.0/1.3字号8组再次通过。已实际查看390常规、320大字体及最新原图，常规宽度改为横向时间轴，窄屏/大字体保留竖向完整历史。
|
||
- 一次不带`--update-goldens`的全视觉检查出现22项旧截图差异失败，不能当成全视觉回归通过；此次仅更新并核对气瓶详情8组。生成截图不等于1:1断言。
|
||
- 远程数据库显式回滚事务测试通过：临时订单、气瓶、合同绑定、占用明细均在同一事务，验证签收、重复确认、证据与占用释放，再回滚并确认临时记录数为0。无迁移、种子或本机数据库/缓存操作。
|
||
- 真实HTTP读取MOCK-GASORDER-001：1条气瓶、1条历史、1条支付，配送费500分；合同MOCK-CONTRACT-001正文读取成功。缺失订单1112、匿名401。没有对既有真实订单执行签收。
|
||
- 浏览器验证登录回跳、气瓶列表进入详情、读取合同正文及关闭。示例数据的完成时间早于建单时间，保留原值并记录为数据异常，不篡改历史。Web Release及Android Debug构建通过；平台契约同步与检查通过48个资源。
|
||
|
||
## 视觉结论与维护
|
||
|
||
**图21仍未通过严格1:1。** 时间轴已按真实数据横向排列；气站与商品分组、原始商品图片、押金、预计送达、地图配送、受控联系、完整售后和部分密度仍有差异。图32仍无完整对应页面。58图仍为14张部分实现、44张无完整页面、0张严格全功能验收通过。
|
||
|
||
证据：[气瓶详情对照](视觉验收/A1/21-gas_并排对照.png)、[390截图](视觉验收/A1/21-gas_390_1.0.png)、[320大字体](视觉验收/A1/21-gas_320_1.3.png)。
|
||
|
||
签收规则变更须同时回归原配送签收、订单占用释放与幂等。远程回滚测试默认跳过，仅明确设置HEQI_REMOTE_RECEIPT_TEST=1时执行；不得去掉外层回滚或运行全库初始化。新字段必须继续使用白名单和本人过滤。
|