77 lines
2.8 KiB
Markdown
77 lines
2.8 KiB
Markdown
# 杜康好客 · 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` | 区间内核销 |
|
||
|
||
- **日报**：发送日前一自然日（截账至发送日 0 点 / 前一天 24 点）；默认 20:00 发送；新增文案「当日新增」。
|
||
- **周报**：上一自然周（周一～周日）；默认周一 09:00；期末为该周日 24 点。
|
||
- **月报**：上一自然月；默认每月 1 日 09:00；期末为该月最后一日 24 点。
|
||
|
||
三种报都不含发送当天发生额。
|
||
|
||
错过发送时刻会在之后补发一次（按 `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，不触发消息推送事件
|
||
- [ ] 启用后到达时刻只发一次该周期
|