feat(pickup): 新增线下提号列表与详情页

2026-10-30 16:45:25 +08:00
parent c0c9f161ae
commit 030cedb6fd
9 changed files with 1643 additions and 14 deletions
@@ -0,0 +1,88 @@
+# Phase 2 验收报告（线下提号）
+
+> 日期：2026-10-30  
+> 项目：解忧商行（hfb_jysh）  
+> 范围：后台线下提号列表、创建、详情与结算动作  
+> 结论：**页面与路由已落地，tsc/build 通过，只读接口回归 200；写操作未在验收中执行**
+
+---
+
+## 1. 命名口径
+
+`pickup` 模块统一称「线下提号」，与旧站 `AdminLayout.vue` 菜单「线下提号」及 `AdminPickupView` 文案（创建提号 / 完成提号 / 取消提号 / 提号编号 / 提号状态 `picking_up`）一致。
+
+本轮同时修正了 `frontend/src/features/admin/labels.ts` 中遗留的错误译法：
+
+- `pickup: '捡漏订单'` → `线下提号`
+- `pickup_shop: '捡漏店铺'` → `提号店铺`
+- 审计动作 `pickup_create / pickup_cancel / pickup_complete / pickup_profit_update / pickup_offline_settlement / pickup_financial_adjustment_* / pickup_shop_*` 全部由「捡漏」改为「提号」口径。
+
+## 2. 页面与路由
+
+| 页面 | 路由 | 文件 |
+|---|---|---|
+| 线下提号列表 | `/console-jy8k3m/pickup` | `frontend/src/features/admin/AdminPickupsPage.tsx` |
+| 线下提号详情 | `/console-jy8k3m/pickup/:id` | `frontend/src/features/admin/AdminPickupDetailPage.tsx` |
+
+权限：`order:pickup`（列表、创建、完成、取消、结算、利润调整、第三方单号、店铺管理均复用该权限，与后端路由一致）。
+
+## 3. 列表页能力
+
+- 筛选：关键字（提号/上架编号/账号标题/手机号）、提号状态（提号中/已完成/已取消）、账号来源（站内/外部）、线下结算状态（未结算/待结算/已结算）、操作人、创建时间区间。
+- 列表：提号编号、账号标题与上架编号、来源与店铺、下单/押金/利润金额、状态双标签、操作人与第三方单号、创建时间。
+- 创建提号弹窗：
+  - 账号来源切换（全部 / 外部上传·平台代管 / 站内上传）驱动 `GET /admin/pickups/available-listings?source_type=`；
+  - 远程搜索已发布且未在交易的账号；
+  - 操作人、交易渠道、第三方单号、店铺（AutoComplete 支持手填）、下单金额、押金、线下利润、备注；
+  - 金额按元录入并 `Math.round(yuan * 100)` 转分提交；
+  - 创建成功后跳转详情页。
+- 店铺管理弹窗：`GET/POST/DELETE /admin/pickups/shops`，标签式展示与删除，新增后刷新 `shop-options` 下拉。
+
+## 4. 详情页能力
+
+- 基本信息：提号编号、上架编号、账号标题、区服/登录方式、号主手机、操作人、交易渠道、店铺、第三方单号（可改）、结算模式、创建/完成时间、备注。
+- 金额区：下单金额、押金、站点售价、号主价、线下利润（含原值与调整）、应结算（含原值与调整）。
+- 操作：
+  - 完成提号 → `POST /admin/pickups/:id/complete`（结算金额、可选利润、备注）
+  - 取消提号 → `POST /admin/pickups/:id/cancel`（必填原因）
+  - 标记线下已结算 → `POST /admin/pickups/:id/offline-settlement`（仅 `completed` + `pending` 显示）
+  - 修改线下利润 → `PUT /admin/pickups/:id/profit`
+  - 修改第三方单号 → `PUT /admin/pickups/:id/third-party-order-no`
+  - 新建财务调整 → `POST /admin/pickups/:id/financial-adjustments`（目标利润/目标结算，至少填一项）
+  - 结算财务调整 → `POST /admin/pickup-financial-adjustments/:id/settle`
+- 流程事件：`GET /admin/pickups/:id/process-events` 以 Timeline 展示阶段、动作、内容、操作人与时间。
+
+## 5. 菜单接入
+
+- `frontend/src/layouts/AdminLayout.tsx`
+  - 交易组新增「线下提号」→ `/pickup`（`order:pickup`）。
+  - `sectionMeta` 补 `/pickup` 标题与描述。
+
+## 6. 回归结果
+
+```text
+前端 http://localhost:5289
+后端 http://127.0.0.1:18089
+Cookie /tmp/jysh-admin-cookie2.txt
+```
+
+| 检查项 | 状态 |
+|---|---|
+| `GET /console-jy8k3m/pickup` | 200 |
+| `GET /console-jy8k3m/pickup/1` | 200 |
+| `GET /api/admin/pickups?page=1&page_size=2` | 200（空列表） |
+| `GET /api/admin/pickups/shops` | 200 |
+| `GET /api/admin/pickups/shop-options` | 200 |
+| `GET /api/admin/pickups/available-listings?page=1&page_size=2` | 200 |
+
+`npx tsc --noEmit` 通过；`npm run build` 通过，主入口 `498.58 kB` / gzip `156.99 kB`，无超大包告警。
+
+## 7. 未覆盖
+
+- 创建、完成、取消、线下结算、利润调整、财务调整与店铺增删均未执行写操作（开发库无可用账号与历史提号数据）。
+- 财务调整的金额差值口径（目标金额 vs 差额）仅在类型层面对齐，未用真实数据验证。
+- 提号完成后对号主钱包的实际入账未验证。
+
+## 8. 下一步（B2 剩余）
+
+客服会话工作台 `/chats`、主站二维码池 `/qrcode-pool`、通知 `/notifications`、推送 `/push`、邀请 `/invitations`。
@@ -413,8 +413,8 @@ hfb_jysh/
 - 用户端资金闭环。
  - 已落地：`/wallet`（余额 + 流水）、`/wallet/payment-accounts`、`/wallet/withdrawal`、移动端 `/m/wallet/withdrawal`、卖家 `/seller/earnings`、`/seller/handoffs`、`/seller/pickups`。
 - 申诉仲裁、手工订单、提号、客服群、快捷回复。
-  - 已落地：客服群组（`/chat-support-groups`，权限 `chat:manage`），角色权限矩阵（`/roles`，权限 `role:manage`），手工录单（`/manual-entries`，权限 `cs_manual_entry:*`），快捷回复（`/chat-quick-replies`，权限 `chat:view` / `chat:send`）。
-  - 待落地：无（手工录单与快捷回复已迁移完毕）。
+  - 已落地：客服群组（`/chat-support-groups`，权限 `chat:manage`），角色权限矩阵（`/roles`，权限 `role:manage`），手工录单（`/manual-entries`，权限 `cs_manual_entry:*`），快捷回复（`/chat-quick-replies`，权限 `chat:view` / `chat:send`），线下提号（`/pickup`、`/pickup/:id`，权限 `order:pickup`，口径统一为「线下提号」）。
+  - 待落地：客服会话工作台 `/chats`、主站二维码池 `/qrcode-pool`。
 - 分销站点、规则、订单、结算、二维码池、分销用户、公告。
 - 公告、邀请返利、推送、追踪链接。
  - 已落地：公告管理、邀请返利、推广追踪（`/tracking-links`，权限 `ad_tracking:manage`）。