# 杜康好客 · v4.0.15 开发文档

> **2026-09-02** · ops / admin-web / domain / shared-types  
> **主题**：HQ 概览改为分指标折线图；全局筛选不变

---

## 1. 版本目标

| # | 任务 | 类型 | 交付 |
|---|------|------|------|
| 1 | 横轴 | 体验 | 粒度 = 时间分桶（日/周/月/季/年） |
| 2 | 纵轴 | 需求 | 总量 / 增量；订单与核销再拆笔数与金额 |
| 3 | 线条 | 需求 | 用户：推广码 / 关联合伙人 / 活动；门店：关联合伙人；订单：用户 / 关联合伙人 / 商品；核销：门店 / 关联合伙人；合伙人无维度单线 |
| 4 | 布局 | 体验 | 一图一行、宽度拉满；改全局筛选全部重绘 |
| 5 | 快链 | 体验 | 「查看」只带全局城市 + 日期，不带线条维度 |

**不做**：同比、板块筛、环比卡、Prisma 迁移、新权限键。

---

## 2. 规则

**全局筛选**：粒度 + 日期 + 城市；日期旁快捷「上周 / 上月 / 上季度」；查询左侧总量 / 增量单选（互斥，只渲染对应折线图）；查询右侧「下载PDF」只导出当前指标下的折线图（不含 KPI / 待办 / 版本）。改粒度**不**改日期区间。

**总量** = 该桶结束时的累计存量（含区间前基线）。**增量** = 落入该桶的新增/发生额。订单笔数按 `createdAt`，订单金额按已付 `payAmount`（`paidAt`）；核销按 `RedeemRecord`。

**线条口径**（与 v4.0.14 归因一致）：

| 板块 | 维度 | 字段 |
|------|------|------|
| 用户 | 推广码 | `user_promo_attribution`；空=自然量 |
| 用户 | 关联合伙人 | `assoc_partner_account_id`；空=未关联 |
| 用户 | 活动 | 关联合伙人当前 `activity_poster_id`；空=无活动 |
| 门店 | 关联合伙人 | `store.partner_account_id` |
| 订单 | 用户 | `order.user_id` |
| 订单 | 关联合伙人 | 下单用户 `assoc_partner_account_id` |
| 订单 | 商品 | `order.product_id` |
| 核销 | 门店 | `redeem.store_id` |
| 核销 | 关联合伙人 | 核销用户 `assoc_partner_account_id` |

高基数维度：按期末存量 Top 10，长尾并入「其他」；`none` 有数据则始终保留。

无对应权限则不返回该图；无任何维度权限时用户/门店/核销退回单线。城市范围只统计负责城。时间北京日历。

---

## 3. API

`GET /admin/dashboard/analytics?granularity&dateFrom&dateTo&cityId`

响应：`granularity`、`range`、`periods[]`、`charts[]`（`key/title/unit/href/series`）。不再返回 `modules` / `byPeriod` / `byCity` / `byProduct` / `byPartner` / 板块筛参数。

`GET /admin/dashboard/stats`、`/version` 不变。

---

## 4. 变更面

| 层 | 路径 |
|----|------|
| domain | `dashboard-series.ts`（累计 / TopN） |
| shared-types | `ops.ts` 折线 DTO |
| API | `admin-dashboard-lines.ts`、`admin-dashboard.service.ts`、`admin-query.dto.ts` |
| HQ | `DashboardPage.tsx`；订单/合伙人列表消费快链城市与日期 |

---

## 5. 验收

- [ ] 全局：粒度、日期、城市；日期快捷上周/上月/上季度；查询左侧总量/增量单选只出对应图
- [ ] 查询右侧下载 PDF：仅当前总量或增量折线图；不含 KPI / 待办 / 版本
- [ ] 改粒度不改日期区间；改全局筛选（除指标单选）全部折线重绘
- [ ] 每个指标×维度一张全宽折线图；合伙人仅单线
- [ ] 日粒度横轴为日期区间按日划分
- [ ] 「查看」只带 `cityId` + `createdFrom/createdTo`，不带推广码/合伙人/商品等
- [ ] 客服无合伙人/门店/核销图
- [ ] 待办卡与超管发版区不变
- [ ] domain 折线单测通过

---

## 6. 活动图上传压缩（DPT-20260902-849）

### 6.1 目标

HQ 上传活动底图时，后端用 Sharp 自动等比缩放至 v4.0.7 底图限制（最长边 ≤ 2500px、宽×高 ≤ 400 万），并在响应与表单中提示尺寸。

### 6.2 规则

- 入口：`POST /common/resources/upload`，`bizType=ACTIVITY_POSTER`、`mediaType=IMAGE`
- 尺寸合规：原样存 OSS，响应 `image.compressed=false`
- 尺寸超限：Sharp 等比缩放后存 OSS，响应含 `width/height/originalWidth/originalHeight/compressed`
- 有 alpha 通道保留 PNG；否则按原 mime 或 JPEG quality 85 输出
- 压缩后仍超过 `OSS_MAX_UPLOAD_BYTES` → 4xx，文案含当前尺寸
- **手动粘贴 URL** 仍不经上传压缩；合成时沿用 v4.0.7 校验

### 6.3 变更面

| 层 | 路径 |
|----|------|
| shared-types | `activity-poster.ts`：`activityPosterResizeTarget`、`OssUploadImageMeta`、`ACTIVITY_POSTER_UPLOAD_HINT` |
| API | `common/image/activity-poster-upload.util.ts`、`resource.service.ts` |
| HQ | `OssUpload.tsx`、`ActivityPostersPage.tsx`、`lib/upload.ts` |

无 Prisma 迁移。

### 6.4 验收

- [ ] 上传 1080×1920：成功，提示尺寸，未标记压缩
- [ ] 上传 4000×3000：成功，提示压缩后尺寸与原尺寸
- [ ] 保存后「为该合伙人下载」/ zip 导出不再报底图过大
- [ ] 非图片 / 损坏文件：明确 4xx
- [ ] AVATAR 等其他 bizType 行为不变