feat(admin): 新增后台申诉列表与仲裁提交

2026-10-30 13:19:26 +08:00
parent f2cc2bb857
commit ab5dac51f7
9 changed files with 969 additions and 4 deletions
@@ -194,9 +194,9 @@ dist/assets/AdminLayout-*.js               36.87 kB │ gzip  13.02 kB
 ## 5. 已知限制

 1. 移动端订单列表/详情与消息中心已接入真实接口；下单、支付、交接、归还、结账等操作仍待迁移。
-2. 后台已完成仪表盘、订单列表/详情、退款审核、提现审核、商品列表/详情与审核、用户列表/详情与人工操作，其余页面仍为统一占位。
+2. 后台已完成仪表盘、订单列表/详情、退款审核、提现审核、商品列表/详情与审核、用户列表/详情与人工操作、申诉仲裁，其余页面仍为统一占位。
 3. 分销后台已完成主题、Logo、登录页与 Shell 轻改，页面结构未重写。
-4. 后台菜单权限码按后端逐个核对：订单 `order:list` / `order:view` / `order:close`，商品 `listing:view` / `listing:approve` / `listing:reject` / `listing:offline`，用户 `user:view` / `user:freeze` / `user:unfreeze` / `user:deposit_free` / `user:growth_points` / `user:manual_realname` / `user:revoke_realname` / `user:wallet_adjust`，提现 `withdrawal:list` / `withdrawal:detail` / `withdrawal:review` / `withdrawal:pay`；其余页面仍需核对。
+4. 后台菜单权限码按后端逐个核对：订单 `order:list` / `order:view` / `order:close`，商品 `listing:view` / `listing:approve` / `listing:reject` / `listing:offline`，用户 `user:view` / `user:freeze` / `user:unfreeze` / `user:deposit_free` / `user:growth_points` / `user:manual_realname` / `user:revoke_realname` / `user:wallet_adjust`，提现 `withdrawal:list` / `withdrawal:detail` / `withdrawal:review` / `withdrawal:pay`，申诉 `dispute:view` / `dispute:arbitrate`；其余页面仍需核对。
 5. SVG 中文尚未转曲。
 6. 入口包已降至 495 kB（gzip 161 kB）；AntD 共享基础设施仍在入口，后续可拆独立入口。
 7. 移动端、订单、分销轻改与首屏优化均已提交；商品管理与审核在本批次提交。
@@ -0,0 +1,82 @@
+# Phase 2 验收报告（后台申诉仲裁）
+
+> 日期：2026-10-30  
+> 项目：解忧商行（hfb_jysh）  
+> 范围：`/console-jy8k3m/disputes`  
+> 结论：**本切片通过，申诉列表、证据查看与仲裁提交已接真实接口**
+
+---
+
+## 1. 接口与权限
+
+| 能力 | 接口 | 权限码 |
+| --- | --- | --- |
+| 申诉列表 | `GET /api/admin/disputes` | `dispute:view` |
+| 提交仲裁 | `POST /api/admin/disputes/:id/arbitrate` | `dispute:arbitrate` |
+
+后端没有后台申诉详情接口，列表 DTO 已包含订单、双方、结账快照与证据，详情抽屉直接使用行数据；仲裁成功后用接口返回值刷新。
+
+## 2. 申诉列表
+
+`frontend/src/features/admin/AdminDisputesPage.tsx`
+
+- 筛选：关键词（订单号 / 商品编号 / 手机号）、申诉状态、申诉类型
+- 列：申诉（编号/类型/状态）、订单（单号/标题/商品编号/订单状态）、双方、发起方、诉求描述、提交时间、处理
+- 分页 10 / 20 / 50
+- 点击编号、行或「处理」打开详情抽屉
+- 无 `dispute:view` 时隐藏处理入口
+
+## 3. 详情与证据
+
+`frontend/src/features/admin/AdminDisputeDetailDrawer.tsx`
+
+- 分段：申诉概览、关联订单、交易双方、诉求描述、结账快照、裁决结果、证据材料
+- 结账快照展示哈夫币消耗、消耗品金额、押金扣除、结账单状态
+- 证据图片支持 AntD 预览；文件接口接受管理员 Cookie
+
+## 4. 仲裁提交
+
+- 仅 `open` / `processing` 且具备 `dispute:arbitrate` 时显示「提交仲裁」
+- 裁决结果支持 8 种：
+  - `actual_settlement` 按实际消耗结算
+  - `full_refund` 全额退款
+  - `partial_refund` 部分退款
+  - `deduct_deposit` 扣押金
+  - `release_deposit` 释放押金
+  - `compensate_owner` 赔付号主
+  - `order_close` 关闭订单
+  - `mark_abnormal` 标记异常
+- 按实际消耗类结果（实际结算/释放押金/扣押金/赔付号主）展示：
+  - 哈夫币实际消耗（M）
+  - 消耗品实际金额（元 → 分）
+- 金额字段：
+  - 部分退款：必填，大于 0
+  - 按实际结算：可选押金扣除，留空使用结账单快照
+  - 扣押金/赔付号主：可选押金扣除，留空按全额押金
+- 处理说明必填，最多 500 字
+- 提交成功刷新列表并更新当前抽屉状态
+
+## 5. 验证结果
+
+```text
+npx tsc --noEmit                                通过
+npm run build                                   通过（入口 496.32 kB，gzip 161.17 kB）
+GET /api/admin/disputes?page=1&page_size=5      ok，{"items":[],"total":0}
+GET /console-jy8k3m/disputes                    200
+```
+
+开发库当前没有申诉数据，仲裁未做真实写入验证，避免污染订单与资金数据；8 种结果的请求体与后端金额分支已逐项核对。
+
+## 6. 已知限制
+
+1. 后端无申诉详情接口，抽屉无法独立刷新单条申诉。
+2. 仲裁提交前无法预览双方最终到账金额，以后端计算为准。
+3. 未做证据上传、批量处理或申诉催办。
+4. 结账争议的结账单只展示快照字段，未嵌入完整协商时间线。
+
+## 7. 下一步建议
+
+1. 后台财务看板与资金流水。
+2. 后台公告管理与系统配置。
+3. 移动端下单、支付与交接/归还/结账。
+4. 聊天 SSE 与附件上传。
@@ -395,7 +395,7 @@ hfb_jysh/

 ### Phase 4：管理后台核心（4–5 周）

-> 状态：**进行中（2026-10-30）**。已完成仪表盘、订单列表/详情、退款审核、提现审核、商品列表/详情与审核、用户列表/详情与人工操作；申诉与系统配置待迁移。
+> 状态：**进行中（2026-10-30）**。已完成仪表盘、订单列表/详情、退款审核、提现审核、商品列表/详情与审核、用户列表/详情与人工操作、申诉仲裁；财务看板、系统配置与审计日志待迁移。

 - 后台登录、工作台、订单列表、订单详情。
 - 商品列表、商品详情、审核。