# 杜康好客 · 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 周期/环比单测通过