4.2 KiB
4.2 KiB
杜康好客 · v4.0.14 开发文档
2026-09-02 · ops / admin-web / domain / shared-types
主题：HQ 概览日/周/月/季/年分桶、环比、板块筛、订单/核销金额
1. 版本目标
| # | 任务 | 类型 | 交付 |
|---|---|---|---|
| 1 | 时间粒度 | 体验 | day/week/month/quarter/year + 自选日期 |
| 2 | 环比 | 需求 | 整段按粒度回退一档；上期 0 且本期 0 为 —，本期 > 0 为 +100% |
| 3 | 筛选分层 | 体验 | 全局只筛城市 + 时间；五板块各自筛选 |
| 4 | 金额 | 需求 | 订单/核销同时出笔数与金额 |
| 5 | 权限 | 安全 | 无权限模块后端不算不返回；城市范围只看负责城 |
不做：同比、测试单开关、新权限键、Prisma 迁移。
2. 规则
2.1 筛选分层
全局：粒度 + 日期 + 城市。环比窗口仍按全局日期、按粒度回退一档。
板块筛（只影响本板块 KPI / 趋势该系列 / 城市该系列）：
| 板块 | 筛选 | 口径 |
|---|---|---|
| 用户 | 推广码、关联合伙人、活动 | 推广码=user_promo_attribution；关联合伙人=assoc_partner_account_id；活动=关联合伙人当前所选活动图（partner_account.activity_poster_id） |
| 合伙人 | 无 | 仅全局 |
| 门店 | 合伙人 | 门店归属主合伙人 store.partner_account_id |
| 订单 | 推广码、关联合伙人、活动、商品 | 推广码=order.promo_code_id；关联合伙人/活动同用户（下单用户）；商品=order.product_id。笔数=createdAt；金额=已付 payAmount（paidAt） |
| 核销单 | 门店、关联合伙人 | 门店=redeem.store_id；关联合伙人=核销用户 assoc_partner_account_id。笔数与 RedeemRecord.amount |
下拉：合伙人「企业-个人」；活动=活动图标题（需 activity_posters）。缺对应权限则忽略该筛。
2.2 模块口径
| 模块 | 权限键 | 数量 | 新增 | 金额 |
|---|---|---|---|---|
| 用户 | users |
区间末日存量 | createdAt 落入区间 |
有 orders 时交叉付费用户 / 客单价（跟用户筛，不跟订单筛） |
| 合伙人 | partners |
主账号期末存量 | 区间新签 | 交叉：支付时归属 GMV / 名下门店核销额（仅全局） |
| 门店 | stores |
期末存量 | 区间新签 | 交叉：本板块门店筛下的核销额（需 benefit） |
| 订单 | orders |
区间下单笔数 | 同左 | 已付 payAmount |
| 核销单 | benefit |
区间核销笔数 | 同左 | RedeemRecord.amount |
时间一律北京日历。周=周一～周日；季=自然季；年=自然年。
默认窗口：日=昨天今天；周=上周一今天；月=上月 1 日今天；季=上季首日今天；年=去年 1 月 1 日~今天。
2.3 权限与城市
- 进页仍需
dashboard。 - 无权限模块：后端不算、响应省略。
- 城市范围：只统计负责城市；筛选项无「未选城」。
3. API
GET /admin/dashboard/analytics
全局：granularity、dateFrom、dateTo、cityId（none=用户未选城）。
板块：usersPromoCodeId（none=无归因）、usersPartnerAccountId、usersActivityPosterId；storesPartnerAccountId；ordersPromoCodeId（none=无推广码）、ordersPartnerAccountId、ordersActivityPosterId、ordersProductId；redeemsStoreId、redeemsPartnerAccountId。
响应：granularity、range、prevRange、modules、byPeriod、byCity、byProduct、byPartner。
GET /admin/dashboard/stats、/version 不变。
4. 变更面
| 层 | 路径 |
|---|---|
| domain | dashboard-period.ts（分桶 / 上期 / 环比） |
| shared-types | ops.ts 概览 DTO |
| API | admin-dashboard.service.ts、admin-dashboard-analytics.ts、admin-query.dto.ts |
| HQ | DashboardPage.tsx |
5. 验收
- 全局只有城市与时间；五板块筛互不影响
- 日默认昨天
今天，环比为前天昨天；周月季年按粒度回退一档 - 订单/核销同时展示笔数与金额
- 用户筛关联合伙人后只计
assoc_partner_account_id - 客服（仅 users/orders）：无合伙人/门店/核销卡
- 待办卡与超管发版区行为不变
- domain 周期/环比单测通过