修复退款审核详情关联与空值展示

docs/操作日志_退款审核关联名称展示修复_20260817.md

@@ -0,0 +1,65 @@
+# 退款审核关联名称展示修复操作日志
+
+操作时间：2026-08-17
+
+操作类型：修改
+
+影响模块：平台总后台、财务管理、退款审核
+
+## 操作前状态
+
+- 退款业务对象依赖前端动态加载原订单关系，加载不到时显示“名称加载失败”。
+- 申请用户直接显示截断 UUID，财务列表无法直接识别用户。
+
+## 具体操作
+
+1. 退款列表按当前页批量读取气体配送订单、商城订单和用户名称，不执行逐行查询。
+2. 退款详情复用同一展示构建逻辑，接口增加 `business_display_name` 和 `user_display_name` 只读展示字段。
+3. 业务对象显示原订单号，用户显示姓名；两个字段均保留 UUID 复制和详情跳转。
+4. 订单或用户已失效时显示明确业务文案，不将失效关系误报为普通网络加载失败。
+5. 增加业务类型、订单号和失效关系的回归测试及前端展示契约断言。
+6. 新增“退款商品”：商城订单使用成交快照，气体配送订单通过退款明细关联原订单项和产品档案，多件退款显示“× 数量”。
+7. 空说明和空审核说明分别显示“无说明”“无审核说明”，不再使用无语义短横线。
+8. 审核人由后端解析平台账号展示名称；历史账号归档后仍可读取，失效时显示明确文案，并保留标识复制。
+9. 支付记录显示支付单号，钱包显示归属类型摘要，完整唯一标识继续作为辅助复制信息。
+10. 修正 `MOCK-REFUND-001` 的审核人归属：由气站账号改为平台根管理员，并在重复执行 Mock 初始化时修复已有错误数据。
+11. 增加独立命令 `repair-mock-refund-reviewer`，用于绕开无关 Mock 数据冲突并安全修复当前数据库。
+
+## 行为变化
+
+- 修改前：业务对象显示“名称加载失败”，用户显示 UUID。
+- 修改后：业务对象显示原订单号，用户显示姓名。
+- 当前 Mock 退款的“退款商品”显示“示例液化气钢瓶”。
+- 当前 Mock 退款的“审核人”显示平台根管理员，不再显示“审核人记录已失效”。
+- 退款金额、审核状态、入账事务、权限和接口路径均未改变。
+
+## 代码变更
+
+- `backend/api/internal/logic/platform/payment/refund.go`：增加退款列表和详情可读关系字段。
+- `backend/api/internal/logic/platform/payment/refund_test.go`：增加订单类型、订单号和失效关系测试。
+- `backend/api/internal/seed/mock.go`：修正 Mock 退款审核人并增加历史错误数据幂等修复。
+- `backend/api/internal/seed/mock_test.go`：增加修复范围的输入保护测试。
+- `backend/api/cmd/cli/main.go`：增加 Mock 退款审核人定向修复命令。
+- `frontend/platform_admin/src/api/resources.ts`：退款关系字段改用接口展示名称。
+- `frontend/platform_admin/src/api/resource-detail-contract.ts`：固定退款详情字段顺序并隐藏审核人辅助名称字段。
+- `frontend/platform_admin/scripts/check-resource-display-contracts.mjs`：增加退款展示契约断言。
+- `docs/项目文档_平台资源中文展示统一_v1.0.md`：记录 v1.10 至 v1.13 变更。
+
+## 验证结果
+
+- `go test ./internal/logic/platform/payment ./internal/routers`：通过。
+- `go test ./...`：通过。
+- `go vet ./...`：通过。
+- `go build ./cmd/main/main.go`：通过。
+- `pnpm resource-display-contracts:check`：通过。
+- `pnpm contract:check`：通过，48 个资源契约一致。
+- 修改文件定向 Biome lint：通过。
+- `pnpm build`：通过，TypeScript 类型检查及 Vite 生产构建完成，共转换 2621 个模块。
+- 新增退款商品汇总后再次执行退款模块、全量后端测试、`go vet`、主程序构建及前端全套检查：全部通过。
+- `go run ./cmd/cli repair-mock-refund-reviewer`：执行成功，当前数据库修复 1 条 Mock 退款审核人记录。
+- 增加定向修复命令后再次执行后端全量测试、`go vet`、主程序与 CLI 构建：全部通过。
+
+## 风险评估
+
+- 可读名称仅用于已授权财务审核页面，不改变退款事实字段或跨服务标识。
+- 订单号来自不可变业务编号；用户姓名用于退款审核识别，UUID 仍作为审计定位依据保留。

docs/项目文档_平台资源中文展示统一_v1.0.md

@@ -72,3 +72,7 @@ frontend/platform_admin/
 - v1.7.1：提现列表的审核人改为直接使用审核姓名快照，并保留审核人标识复制与详情跳转，避免历史账户关系加载失败影响列表展示。
 - v1.8：财务支付记录的商城订单关系统一显示订单号，支付状态使用财务领域的 `35=已支付`，渠道按业务文档统一显示“余额支付”“支付宝”“微信支付”。
 - v1.9：财务支付详情新增“支付商品”，由后端按商城订单明细的成交快照汇总商品名称和数量，确保商品改名后仍可按交易事实核对。
+- v1.10：退款审核列表和详情由接口直接返回原订单号与申请用户姓名，前端保留关系标识复制和详情跳转，不再依赖临时关系加载。
+- v1.11：退款审核新增“退款商品”，商城退款读取成交快照，气体配送退款通过原订单项读取产品名称，并汇总退款数量。
+- v1.12：退款审核补齐空值业务文案、审核人名称、支付单号和钱包归属摘要，UUID 统一降级为复制信息。
+- v1.13：修正固定 Mock 退款误把气站账号写为平台审核人的数据错误，并在重复初始化时幂等修复历史记录；退款审核人由接口稳定返回平台账号名称。