dukang/docs/杜康好客-v3.5.5-开发文档.md

杜康好客 · 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

{
  "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 落地说明。