171 lines
6.5 KiB
Markdown
171 lines
6.5 KiB
Markdown
# 杜康好客 · v3.5.5 开发文档
|
||
|
||
> **2026-08-23** · admin-web / API
|
||
> **主题**：HQ 订单监控导出（Excel / PDF）+ 订单列表页布局优化
|
||
|
||
---
|
||
|
||
## 1. 版本目标
|
||
|
||
1. 总部 **订单监控** 支持按筛选或勾选导出 **Excel（.xlsx）** / **PDF（.pdf）**。
|
||
2. 导出内容聚焦运营履约：**商品明细、收货信息、好客权益摘要**；次要字段从列表与导出列中精简。
|
||
3. **订单列表页** 筛选区改为网格布局，支持日期快捷选择；导出、查询、重置、批量删除同一操作行。
|
||
4. 修复现场取货订单地址展示为「现场现场取货现场取货」的问题。
|
||
|
||
**不做**：C 端 / 合伙人 / 门店端改动；无 Prisma 迁移。
|
||
|
||
---
|
||
|
||
## 2. 功能清单
|
||
|
||
### 2.1 HQ 订单导出（核心）
|
||
|
||
| # | 模块 | 交付说明 |
|
||
|---|------|----------|
|
||
| 1 | API | `POST /api/v1/admin/orders/export` — 生成文件，响应 `{ filename, mimeType, contentBase64, count }` |
|
||
| 2 | 预览 | `POST /api/v1/admin/orders/export/preview` — 返回 `{ count, max, exceeds }`（上限 5000） |
|
||
| 3 | 导出范围 | `scope=filter` 按当前筛选；`scope=selected` 仅导出勾选 `ids` |
|
||
| 4 | 格式 | `format=xlsx`（exceljs）/ `format=pdf`（pdfkit，横向 A4） |
|
||
| 5 | 权限 | `HqAuthGuard` + `orders`；操作审计 `ORDER_EXPORT` |
|
||
| 6 | 筛选复用 | `buildOrderWhere()` 与列表查询共用；新增 `deliveryType` 筛选 |
|
||
|
||
**导出列**（11 列）：
|
||
|
||
订单号、下单时间、状态、商品、规格、数量、实付、好客权益、收货人、手机、收货地址。
|
||
|
||
好客权益列：有权益券时 `总额¥X / 已用¥Y / 余¥Z`；否则回落订单 `benefitAmount`。
|
||
|
||
### 2.2 订单列表页（admin-web）
|
||
|
||
| # | 项 | 说明 |
|
||
|---|----|------|
|
||
| 7 | 筛选布局 | 网格表单：下单日期、状态、类型、配送、城市、收货手机；大单拦截 / 过滤测试 |
|
||
| 8 | 日期快捷 | 当日、当周（周一至周日）、当月、当季、当年 |
|
||
| 9 | 列表列 | 商品（含规格/数量/标签）、状态+实付、好客权益、收货信息、下单时间、操作 |
|
||
| 10 | 勾选导出 | 列表常驻勾选；左侧 Excel/PDF +「导出已勾选」「导出全部筛选」 |
|
||
| 11 | 操作行 | 右侧同一行：查询、重置、批量删除（有权限时） |
|
||
| 12 | 现场取货 | 收货地址识别 `ON_SITE_PICKUP` 或省市区占位后，统一显示「现场取货」 |
|
||
|
||
### 2.3 列表数据增强
|
||
|
||
| # | 项 | 说明 |
|
||
|---|----|------|
|
||
| 13 | 权益关联 | `GET /admin/orders` include `benefitCoupon`（券号、总额/已用/余额、状态） |
|
||
| 14 | 收货字段 | `AdminOrderRow` 增加省市区、地址、`benefitAmount`、`benefitCoupon` 类型 |
|
||
|
||
---
|
||
|
||
## 3. API 契约
|
||
|
||
### 3.1 导出请求体 `AdminOrdersExportDto`
|
||
|
||
```json
|
||
{
|
||
"scope": "filter",
|
||
"format": "xlsx",
|
||
"ids": ["123"],
|
||
"status": "PENDING_SHIP",
|
||
"orderType": "NORMAL",
|
||
"cityId": "1",
|
||
"receiverPhone": "138",
|
||
"deliveryType": "LOCAL",
|
||
"fulfillmentHold": true,
|
||
"excludeTest": true,
|
||
"createdFrom": "2026-08-01",
|
||
"createdTo": "2026-08-23"
|
||
}
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `scope` | `filter` \| `selected`（勾选时仅传 `ids`，忽略其它筛选） |
|
||
| `format` | `xlsx` \| `pdf` |
|
||
| `createdFrom` / `createdTo` | 按筛选导出且均未填时，服务端默认近 30 天 |
|
||
|
||
### 3.2 错误码
|
||
|
||
| 场景 | HTTP | message |
|
||
|------|------|---------|
|
||
| 超过 5000 条 | 400 | 超过 5000 条，请缩小日期或筛选条件 |
|
||
| 无数据 | 400 | 没有可导出的订单 |
|
||
| 勾选为空 | 400 | 请先勾选要导出的订单 |
|
||
| PDF 无字体 | 500 | 未找到可用于 PDF 的中文字体… |
|
||
|
||
### 3.3 列表查询增量
|
||
|
||
`GET /admin/orders` 查询参数新增（与导出筛选一致）：
|
||
|
||
- `deliveryType`：`LOCAL` \| `CROSS_CITY` \| `ON_SITE_PICKUP`
|
||
- `createdFrom` / `createdTo`：下单日期（已有 DTO，本版接 UI）
|
||
|
||
---
|
||
|
||
## 4. 依赖与部署
|
||
|
||
### 4.1 新增 npm 依赖（仅 API）
|
||
|
||
- `exceljs` — xlsx 生成
|
||
- `pdfkit` + `@types/pdfkit` — pdf 生成
|
||
|
||
### 4.2 PDF 中文字体
|
||
|
||
路径：`server/dukang-api/assets/fonts/`（见 `README.md`）。
|
||
|
||
解析顺序：
|
||
|
||
1. 环境变量 `EXPORT_PDF_FONT_PATH`
|
||
2. `assets/fonts/NotoSansSC-Regular.otf` / `simhei.ttf` / `msyh.ttc`
|
||
3. Linux 系统 Noto CJK
|
||
4. Windows 系统字体（开发机）
|
||
|
||
> 字体二进制已加入 `.gitignore`；生产部署需放置字体或安装 `fonts-noto-cjk`。
|
||
|
||
### 4.3 发版步骤
|
||
|
||
| 步骤 | 动作 |
|
||
|------|------|
|
||
| 1 | `pnpm install`（根目录，拉取 exceljs/pdfkit） |
|
||
| 2 | 确认 `server/dukang-api/assets/fonts/` 有中文字体（PDF 必需） |
|
||
| 3 | `pnpm build`（API + admin-web） |
|
||
| 4 | 发 `dukang-api` + `admin-web`；**无需** `prisma migrate` |
|
||
|
||
---
|
||
|
||
## 5. 关键路径（便于排查）
|
||
|
||
| 域 | 路径 |
|
||
|----|------|
|
||
| 导出工具 | `server/dukang-api/src/modules/ops/admin-order-export.util.ts` |
|
||
| 订单服务 | `server/dukang-api/src/modules/ops/admin-orders.service.ts` |
|
||
| 控制器 | `server/dukang-api/src/modules/ops/admin-orders.controller.ts` |
|
||
| DTO | `server/dukang-api/src/modules/ops/dto/admin-query.dto.ts` |
|
||
| 审计常量 | `server/dukang-api/src/common/hq-operation/hq-operation.constants.ts`（`ORDER_EXPORT`） |
|
||
| 前端页面 | `apps/admin-web/src/pages/OrdersPage.tsx` |
|
||
| 下载工具 | `apps/admin-web/src/lib/exportExcel.ts`（`downloadBase64File`） |
|
||
| 类型 | `apps/admin-web/src/lib/api.ts`（`AdminOrderRow`） |
|
||
| 需求 | `docs/杜康好客-v3-PRD.md` §3.2 HQ 订单导出 |
|
||
| 现状 | `docs/杜康好客-v3-现状对照.md` |
|
||
|
||
---
|
||
|
||
## 6. 验收清单
|
||
|
||
- [ ] 订单列表：网格筛选 + 日期快捷（当日/当周/当月/当季/当年）可用
|
||
- [ ] 列表展示：商品（规格×数量）、状态/实付、好客权益、收货人+手机+地址
|
||
- [ ] 现场取货订单地址仅显示「现场取货」，不出现重复拼接
|
||
- [ ] 勾选若干订单 →「导出已勾选」→ xlsx / pdf 条数与勾选一致
|
||
- [ ] 设筛选条件 →「导出全部筛选」→ 文件含筛选范围内全部订单（≤5000）
|
||
- [ ] 超 5000 条时导出全部筛选返回明确错误
|
||
- [ ] Excel / PDF 中文正常；PDF 表头与分页可读
|
||
- [ ] 无 `orders` 权限账号无法调用导出接口
|
||
- [ ] HQ 操作日志有 `ORDER_EXPORT` 记录
|
||
- [ ] 无删除权限账号仍可勾选并导出；有删除权限时批量删除与导出/查询同一行
|
||
|
||
---
|
||
|
||
## 7. 与 v3.5.4 关系
|
||
|
||
- **仅 HQ 内部工具**，不影响 C 端小程序版本号。
|
||
- 商品规格（SPU/SKU）、发票等 v3.5.4 能力保持不变。
|
||
- PRD §3.2 已补充 HQ 订单导出业务规则；本版为实现与 UI 落地说明。
|