# 杜康好客 · 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，不触发消息推送事件
- [ ] 启用后到达时刻只发一次该周期