v4.0.14概览和日报
CI / verify (pull_request) Waiting to run

This commit is contained in:
2026-09-02 21:11:58 +08:00
parent e5fe8b903a
commit 68a4b7f984
41 changed files with 3815 additions and 1098 deletions
+1
View File
@@ -34,6 +34,7 @@
| 3.5.11 | 08-26 | 城市三种履约起购;企微通知补提交人/规格物流/核销用户(明文手机+备注);结算任务失败通知 + 提现通过/四账单(城市合伙人、笔数、累计金额) | [`v3.5.11`](./杜康好客-v3.5.11-开发文档.md) |
| 3.5.12 | 08-26 | 发布会订单大屏循环 BGM;HQ 日志/订单状态流转/用户行为时间线展示中文;修复删除门店分类被默认树回种;HQ 侧栏顺序(业务前 11 项,系统设置置底) | [`v3.5.12`](./杜康好客-v3.5.12-开发文档.md) |
| 3.5.14 | 08-26 | 修复 C 端提交订单/支付成功日志误标 H5;线上 `order_submit`/`pay_success` 回填为小程序 | [`v3.5.14`](./杜康好客-v3.5.14-开发文档.md) |
| 3.5.15 | 09-02 | 企微机器人「报告」:日报/周报/月报;Webhook 与消息推送分开 | [`v3.5.15`](./杜康好客-v3.5.15-开发文档.md) |
**4.0 起**不再写入本表,见 [`v4-PRD`](./杜康好客-v4-PRD.md)。
+1 -1
View File
@@ -32,7 +32,7 @@
| **mini-user** | 购酒/权益/核销/门店/物流/版本门控 | 规则弹窗、发票、四类型工单、问卷 |
| **h5-shop** | 扫码核销、记录、营业、iOS 扫码 OAuth | 手机号核销、提现、子账号、弱网兜底 |
| **h5-partner** | 子账号、拓店、订单/账单、套餐 | 试核销100、负责人复核、代下单 |
| **admin-web** | 商品/开城/门店/订单(含 Excel/PDF 导出)/权益/核销/结算/推广码 metrics/开发计划/技术支持 | 完整 SOP 审核 UI、发票、热力图 |
| **admin-web** | 商品/开城/门店/订单(含 Excel/PDF 导出)/权益/核销/结算/推广码 metrics/开发计划/技术支持/企微报告 | 完整 SOP 审核 UI、发票、热力图 |
| **后端** | 主模块、支付、权益、核销、payout、Courier 适配 | 30min 取消 job、部分 Wave3 |
## 3. 场景 SC-01~09
+74
View File
@@ -0,0 +1,74 @@
# 杜康好客 · v3.5.15 开发文档
> **2026-09-02** · ops / admin-web / domain / shared-types
> **主题**:企微机器人增加经营报告(日报 / 周报 / 月报)
---
## 1. 版本目标
| # | 任务 | 类型 | 交付 |
|---|------|------|------|
| 1 | 报告模块 | 需求 | HQ「企微机器人 → 报告」,与「消息推送」分开 |
| 2 | 三种报 | 需求 | 日报、周报、月报:存量 + 本期新增 |
| 3 | 推送 | 需求 | 企微群机器人 Webhook markdown;可预览 / 立即发送 / 定时 |
**不做**:并入消息推送条件、新权限键、城市范围裁剪、同比。
---
## 2. 规则
配置在报告页,每种报一份 Webhook / 启用 / 发送时刻(周报另选星期,月报另选每月几号)。不占用「消息推送」的事件条件。
口径(北京日历,与概览折线一致):
| 指标 | 存量 | 新增 |
|------|------|------|
| 用户数量 | `status=1` 且未合并,`createdAt` < 期末 | 区间内创建 |
| 合伙人数量 | 主账号 `is_primary=1` | 区间内创建 |
| 门店数量 | 全部门店 | 区间内创建 |
| 订单数量 | 按下单 `createdAt` | 区间内下单 |
| 订单金额 | 已付 `payAmount``paidAt` | 区间内支付 |
| 核销单数量 / 金额 | `RedeemRecord` | 区间内核销 |
- **日报**:当天;默认 20:00 发送;新增文案「当日新增」。
- **周报**:上一自然周(周一~周日);默认周一 09:00。
- **月报**:上一自然月;默认每月 1 日 09:00。
错过发送时刻会在之后补发一次(按 `last_sent_period` 去重)。
---
## 3. API
`GET /admin/wecom-reports`
`GET/PUT /admin/wecom-reports/:kind``daily` \| `weekly` \| `monthly`
`POST /admin/wecom-reports/:kind/preview`
`POST /admin/wecom-reports/:kind/send`
权限:`wecom_bots`
`wecom_report_push``kind` 唯一)。
---
## 4. 变更面
| 层 | 路径 |
|----|------|
| domain | `wecom-report.ts` |
| shared-types | `wecom-report.ts` |
| Prisma | `WecomReportPush``prisma/migrate-wecom-report.ts` |
| API | `admin-wecom-reports.*` |
| HQ | `WecomReportsPage.tsx`;侧栏「报告」 |
---
## 5. 验收
- [ ] 侧栏企微机器人下有「报告」,与消息推送分开
- [ ] 日报/周报/月报可分别填 Webhook、启停、时刻并保存
- [ ] 预览文案含用户/合伙人/门店/订单数量与金额/核销数量与金额的存量+新增
- [ ] 立即发送走该报自己的 Webhook,不触发消息推送事件
- [ ] 启用后到达时刻只发一次该周期
+5 -1
View File
@@ -1,7 +1,7 @@
# 杜康好客 · V3 编码手册(交付业务版)
> **事实源**[`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md) · **审计**[`杜康好客-v3-现状对照.md`](./杜康好客-v3-现状对照.md)
> **佣金归属 / 关联码 / 合伙人账单明细(v4.0.1)· 活动图(v4.0.2)· 周结算与预付款(v4.0.9**[`杜康好客-v4-PRD.md`](./杜康好客-v4-PRD.md),冲突时 **V4 > V3**。
> **佣金归属 / 关联码 / 合伙人账单明细(v4.0.1)· 活动图(v4.0.2)· 周结算与预付款(v4.0.9)· HQ 概览(v4.0.14 / v4.0.15**[`杜康好客-v4-PRD.md`](./杜康好客-v4-PRD.md),冲突时 **V4 > V3**。
> V2/preV1 **非需求依据**。总部交付 = **`apps/admin-web`**(非 H5)。
## 1. 交付目标(六条)
@@ -44,6 +44,10 @@ C 端购酒核销 · 门店扫码核销+打款 · 合伙人拓店履约 · WebAd
**HQ 权限(v3.5.8**:生效 =(角色 ∪ 追加)− 撤销。城市范围绑在账号上(空=全国;「城市门店服务」必须勾城)。门店 API 按 `cityIds` 强制过滤。城市门店服务可新增分类、不可删除;概览按权限与城市范围裁剪。
**HQ 概览(v4.0.14 / v4.0.15**`GET /admin/dashboard/analytics` 支持日/周/月/季/年分桶;默认窗口为上一档起点~今天。全局筛城市+时间;日期快捷上周/上月/上季度;总量/增量单选分开展示。改粒度不改日期。查询右侧可下载当前折线图 PDF(不含 KPI/待办)。v4.0.15 起为多张全宽折线图:总量=桶末日存量,增量=桶内新增;用户线=推广码/关联合伙人/活动,门店线=关联合伙人,订单线=用户/关联合伙人/商品,核销线=门店/关联合伙人,合伙人单线。订单与核销同时出笔数和金额。关联合伙人=`assoc_partner_account_id`;活动=关联合伙人当前活动图。「查看」只带全局城市与日期。无权限模块后端不算不返回。时间按北京日历。
**HQ 企微报告(v3.5.15**:企微机器人下「报告」与「消息推送」分开。日报/周报/月报各配 Webhook 与发送时刻;走群机器人 markdown。日报=当天存量+当日新增;周报/月报=上一自然周/月期末存量+本期新增。用户=有效未合并;合伙人=主账号;订单金额=已付 `payAmount``paidAt`);核销=`RedeemRecord`
**HQ 列表(v3.5.9**:主表不省略号、可横滑;最左序号;列设置(显隐/顺序)与列宽(拖表头)存 `hq_account.list_column_prefs`。主展示列下划线,点击进编辑或详情。门店列表「累计核销好客权益」= 该店 `RedeemRecord.amount` 合计。用户列表昵称只读(点击进详情);双击「备注」离开即保存(`hq_remark`);列表手机号不脱敏。
**C 端(v3.5.10**:门店详情无顶栏分享按钮。同城送提示取开城仓库绑定承运商的 `delivery_hint_html``GET /catalog/local-deliveries`,按收货市是否开城);空则回退「同城配送,预计24小时内送到」。在线客服优先 `wx.openCustomerServiceChat``CUSTOMER_SERVICE_WECOM_URL` + `WECOM_CORP_ID`);未配 CorpID 回退小程序原生客服。
+5 -3
View File
@@ -1,8 +1,8 @@
# 杜康好客 · V4 PRD
> **v4.0**2026-08-29)· 关联码与分佣事实源;**v4.0.6** 酒厂对账;**v4.0.7** HQ 活动图快链与勾选导出;**v4.0.9** 合伙人 H5 周结算与用户管理
> 未改规则仍见 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md)。**冲突时 V4 > V3**(本主题:订单佣金归属、关联码、合伙人账单明细、活动图、酒厂对账、合伙人周结算)。
> 实现:[`v4.0.1 开发文档`](./杜康好客-v4.0.1-开发文档.md) · [`v4.0.2 开发文档`](./杜康好客-v4.0.2-开发文档.md) · [`v4.0.6 开发文档`](./杜康好客-v4.0.6-开发文档.md) · [`v4.0.7 开发文档`](./杜康好客-v4.0.7-开发文档.md) · [`v4.0.9 开发文档`](./杜康好客-v4.0.9-开发文档.md) · 审计:[`v4-现状对照`](./杜康好客-v4-现状对照.md)
> **v4.0**2026-08-29)· 关联码与分佣事实源;**v4.0.6** 酒厂对账;**v4.0.7** HQ 活动图快链与勾选导出;**v4.0.9** 合伙人 H5 周结算与用户管理**v4.0.14** HQ 概览粒度;**v4.0.15** HQ 概览折线图
> 未改规则仍见 [`杜康好客-v3-PRD.md`](./杜康好客-v3-PRD.md)。**冲突时 V4 > V3**(本主题:订单佣金归属、关联码、合伙人账单明细、活动图、酒厂对账、合伙人周结算、HQ 概览)。
> 实现:[`v4.0.1 开发文档`](./杜康好客-v4.0.1-开发文档.md) · [`v4.0.2 开发文档`](./杜康好客-v4.0.2-开发文档.md) · [`v4.0.6 开发文档`](./杜康好客-v4.0.6-开发文档.md) · [`v4.0.7 开发文档`](./杜康好客-v4.0.7-开发文档.md) · [`v4.0.9 开发文档`](./杜康好客-v4.0.9-开发文档.md) · [`v4.0.14 开发文档`](./杜康好客-v4.0.14-开发文档.md) · [`v4.0.15 开发文档`](./杜康好客-v4.0.15-开发文档.md) · 审计:[`v4-现状对照`](./杜康好客-v4-现状对照.md)
## 0. 版本
@@ -13,6 +13,8 @@
| 4.0.6 | 08-31 | 酒厂 T+3=每 3 天出一期;全部已完成已付订单(含现场提货);应付为 0 仍出账;核对补生成 | [`v4.0.6`](./杜康好客-v4.0.6-开发文档.md) |
| 4.0.7 | 09-01 | HQ 城市合伙人活动图快链;指定一张活动图为单个或勾选主合伙人合成下载(PNG / zip) | [`v4.0.7`](./杜康好客-v4.0.7-开发文档.md) |
| 4.0.9 | 09-02 | 子账号默认启用;关联码已扫码计数;零元账单不同步;主账号自填银行账号;周账周一 08:00 出账;预付款预估;子账号用户管理(无活动图) | [`v4.0.9`](./杜康好客-v4.0.9-开发文档.md) |
| 4.0.14 | 09-02 | HQ 概览:日/周/月/季/年、环比、全局城市/时间 + 五板块筛;订单/核销笔数与金额 | [`v4.0.14`](./杜康好客-v4.0.14-开发文档.md) |
| 4.0.15 | 09-02 | HQ 概览改为全宽折线图:粒度分桶、总量/增量、维度线条;查看快链只带全局筛选 | [`v4.0.15`](./杜康好客-v4.0.15-开发文档.md) |
## 1. 锚点(沿用 V3,佣金归属改写)
+5 -1
View File
@@ -7,7 +7,7 @@
| 维度 | 结论 |
|------|------|
| 版本线 | **v4.0.13** 收货地址禁「全市」+ 小飞侠拒单履约可感知 |
| 版本线 | **v4.0.15** HQ 概览折线图(粒度分桶、总量/增量、维度线条) |
| 订单佣金 | 区县归属已删除;只认关联 / 代下单选择 |
| 账单 | 酒订单 / 核销订单分列;合伙人改为周账(周一 08:00);零元不同步合伙人;酒厂含现场提货,零应付仍出账(无需打款) |
| 活动图 | HQ 上传底图/码栏/文案;合伙人选择写入库;HQ 可指定一张图为勾选主合伙人合成下载;子账号不可看活动图 |
@@ -22,6 +22,8 @@
| 4.0.7 | [`活动图快链与勾选导出`](./杜康好客-v4.0.7-开发文档.md) | ✅ 已实现 |
| 4.0.9 | [`合伙人 H5 周结算与用户管理`](./杜康好客-v4.0.9-开发文档.md) | ✅ 已实现 |
| 4.0.13 | [`收货地址把关与拒单可感知`](./杜康好客-v4.0.13-开发文档.md) | ✅ 已实现 |
| 4.0.14 | [`HQ 概览粒度与环比`](./杜康好客-v4.0.14-开发文档.md) | ✅ 已实现 |
| 4.0.15 | [`HQ 概览折线图`](./杜康好客-v4.0.15-开发文档.md) | ✅ 已实现 |
| 日期 | 说明 |
|------|------|
@@ -33,3 +35,5 @@
| 2026-09-01 | v4.0.7HQ 城市合伙人活动图快链;单张/勾选导出合成图(PNG / zip) |
| 2026-09-02 | v4.0.9:子账号默认启用;关联码已扫码;零元账单不同步;银行账号自填;周账周一 08:00;预付款预估;子账号用户管理无活动图 |
| 2026-09-02 | v4.0.13:收货禁「全市」;脏地址下单拦截;小飞侠超区/推单失败挂 `fulfillmentHold`(不做仓/收件坐标) |
| 2026-09-02 | v4.0.14HQ 概览日/周/月/季/年、环比;全局城市/时间 + 五板块筛;订单/核销笔数与金额 |
| 2026-09-02 | v4.0.15HQ 概览改为全宽折线图;去掉板块筛;查看快链只带全局城市与日期 |
+95
View File
@@ -0,0 +1,95 @@
# 杜康好客 · 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 周期/环比单测通过
+79
View File
@@ -0,0 +1,79 @@
# 杜康好客 · 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 折线单测通过