diff --git a/changelogs-v2/2026-09/29_frontend_应收台账加全散客订单团期页签与查看按钮-前端优化-管理后台.md b/changelogs-v2/2026-09/29_frontend_应收台账加全散客订单团期页签与查看按钮-前端优化-管理后台.md new file mode 100644 index 00000000..9acbfe1e --- /dev/null +++ b/changelogs-v2/2026-09/29_frontend_应收台账加全散客订单团期页签与查看按钮-前端优化-管理后台.md @@ -0,0 +1,99 @@ +--- +schema: "hl-changelog/v2" +ticket: "frontend" +title: "应收台账:加「全部 / 散客订单 / 团期」页签 + 行内「查看」按钮(按 rowType 分流跳转)" +consumer: "admin" +author: "yst" +change_type: "前端优化" +backend_status: "deployed" +gateway_status: "not_required" +frontend_status: "required" +frontend_owner: "mmg" +frontend_ref: "" +verified_at: "" +target_release: "v2.1" +status_note: "应收台账页加「全部/散客订单/团期」页签 + 行内查看按钮,后端 rowType 入参与跳转字段已就绪并部署测试服" +updated_at: "2026-09-29" +base: "dev-v3" +--- + +# 应收台账:加「全部 / 散客订单 / 团期」页签 + 查看按钮(管理后台) + +> 本条是**前端动作指引**:告诉你要改哪个页面、加什么、怎么跳。接口字段级契约 +> (请求参数 / 响应字段 / 枚举值 / 示例)见 #8504 接口 changelog +> `changelogs-v2/2026-09/29_8504_应收台账加rowType入参-修改接口-管理后台.md`,本条不重复抄字段表。 +> 后端已部署测试服,**可直接联调**。 + +## 一、背景 + +应收台账页 `src/views/finance/receipt/receivable/index.vue`(菜单「收款管理 / 应收台账」,#8369 已挂) +当前是**单列混合列表**(订单行与团行混在一起)且**没有查看入口**。财务提了两个诉求: + +1. 顶部按行类型分流:能只看散客订单、或只看团期; +2. 点行能直接跳进对应详情页,不用再手抄单号去别的页面查。 + +后端已就绪:`GET /admin/finance/receipt/receivable/page` 新增可选入参 `rowType`, +且每行都带了 `rowType` / `id` / `groupBatchId` 三个跳转所需字段。**本次是纯前端改动,等前端实施。** + +## 二、动作 1:顶部加页签「全部 / 散客订单 / 团期」 + +- 数据源:`GET /admin/finance/receipt/receivable/page` 新增**可选**入参 `rowType` +- 页签与传参映射: + +| 页签 | `rowType` 传值 | 含义 | +|---|---|---| +| 全部 | **不传**(默认页签) | 订单行 + 团行混合 | +| 散客订单 | `rowType=ORDER` | 只返回订单行 | +| 团期 | `rowType=GROUP_BATCH` | 只返回团行 | + +- ⚠️ **必须走后端过滤**:切页签时带 `rowType` 重新请求接口,**不要**拿到全量数据后在前端本地过滤—— + 本地过滤会让分页 `total` 算错,翻页直接乱。 +- 页签切换时**重置到第 1 页**再请求。 + +## 三、动作 2:行内加「查看」按钮,按 `rowType` 分流跳转 + +先看这一行的 `rowType`,再决定跳哪里、用哪个字段: + +| `rowType` | 跳前端路由 | 用行内哪个字段 | 该路由对应的后端接口 | +|---|---|---|---| +| `ORDER` | `/order-v2/detail/{id}` | 行的 `id`(= 订单 ID) | `GET /v3/admin/order/{id}` | +| `GROUP_BATCH` | `/order-v2/batch/detail/{code}` | 行的 **`groupBatchId`**(= 团期批次 ID) | `GET /v3/admin/order/group-batch/{groupBatchId}` | + +### 🔴 三条红线(踩了必 404) + +1. 🚫 **必须先读 `rowType` 再决定跳哪**——`GROUP_BATCH` 行**绝不能拿 `id` 去跳订单详情**: + 团行的 `id` 里装的是批次 ID 不是订单 ID,拿去查订单详情必 404。 +2. 团行跳转参数用**独立的 `groupBatchId` 字段**,别复用 `id`。 +3. 团期详情路由的参数名是 **`:code`** 不是 `:id`(页面叫「出团详情」)。 + +## 四、行内差异渲染 + +- `GROUP_BATCH` 行的 `customerName` / `customerPhone` 恒为 `null`(团行没有单一客户概念)→ 显示「—」,不要渲染成「null」或空白。 +- `orderStatusName` / `receivableStatusName` 后端已翻译成中文,**直接展示**,不用前端再映射。 + +## 五、测试服联调 + +- 接口已部署测试服,网关地址 `http://192.168.100.236:8080`。 +- `rowType` 三态过滤(不传 / ORDER / GROUP_BATCH)与行内跳转字段已实测通过: + ORDER 纯订单行、GROUP_BATCH 纯团行、分页 `total` 正确。 +- 可直接联调,无需等后端部署。 + +## 六、验证检查清单 + +- [ ] 页签「全部 / 散客订单 / 团期」三态切换,请求分别不带 rowType / `rowType=ORDER` / `rowType=GROUP_BATCH`(Network 确认) +- [ ] 切页签时重置到第 1 页,分页 `total` 与当前页签数据一致(不是前端本地过滤) +- [ ] 「散客订单」页签点「查看」→ 跳 `/order-v2/detail/{id}`,`id` 为行内订单 ID,详情正常打开 +- [ ] 「团期」页签点「查看」→ 跳 `/order-v2/batch/detail/{code}`,参数取行内 `groupBatchId`,出团详情正常打开 +- [ ] 团行的客户姓名 / 手机号显示「—」,不出现 null 字样 +- [ ] 状态列直接展示后端返回的中文名 + +## 七、关联 + +- 接口契约(入参 / 出参 / 枚举 / 示例,字段级):#8504 changelog + `changelogs-v2/2026-09/29_8504_应收台账加rowType入参-修改接口-管理后台.md` +- Issue:https://git.1814.love/wx/HL/issues/8504 +- PR:https://git.1814.love/wx/HL/pulls/8505 + +## 联系人 + +后端:yst | 前端:mmg