developer_liu
115 lines
4.9 KiB
Markdown
115 lines
4.9 KiB
Markdown
# 杜康好客 · 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 行为不变
|