杜康好客 · 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 行为不变

4.9 KiB Raw Blame History Unescape Escape