feat(coupon-data): 点位成功率改为按券成功率的算术平均(前端从按券明细上卷) (#46)
点位成功率改为按券成功率的算术平均(前端从按券明细上卷) --------- Co-authored-by: guke <guke@autohome.com.cn> Reviewed-on: #46
This commit was merged in pull request #46.
This commit is contained in:
@@ -0,0 +1,101 @@
|
||||
# 点位成功率改为「按券成功率的算术平均」设计
|
||||
|
||||
- **日期**：2026-07-11
|
||||
- **范围**：纯前端 `shaguabijia-admin-web`，**后端零改动、零 schema 改动、零迁移**
|
||||
- **涉及文件**：`src/app/(main)/coupon-data/page.tsx`（单文件）
|
||||
|
||||
## 目标
|
||||
|
||||
「领券数据」看板汇总卡里的 **分平台点位成功率**（美团/淘宝/京东）与 **点位成功率(合计)**，改为
|
||||
**该平台（/全部）几张券成功率的算术平均**，让平台数字与下方「按券明细」自洽，便于快速揪出坏券。
|
||||
|
||||
## 背景
|
||||
|
||||
现状：分平台 / 合计点位成功率来自后端 `_success_rates`（**会话口径**，数据源 `coupon_session.platform_success`），
|
||||
与页面下方「按券成功率」（数据源 `coupon_claim_record`）口径不同，导致同一平台的平台数（如淘宝 71.4%）
|
||||
与其券明细（100%/80%/80%）对不上，甚至出现「合计低于每个平台」的反直觉现象。
|
||||
|
||||
关键点：**本页已经把全量按券数据拉到前端**——`couponSlots`（来自 `/admin/api/coupon-data/coupons`，
|
||||
后端 `coupon_slot_report` 不分页、返回全量），每行含 `platform` 与 `success_rate`。因此直接在前端
|
||||
对其求算术平均即可，**无需后端改动**。
|
||||
|
||||
## 口径（改动后）
|
||||
|
||||
- **分平台点位成功率** = 该平台所有券 `success_rate` 的算术平均（每张券等权；`success_rate` 为空的券跳过；无券 → 显示 `-`）。
|
||||
- **点位成功率(合计)** = `couponSlots` 全部券 `success_rate` 的算术平均。
|
||||
- **每张券成功率**（按券明细，不变）：成功(success + already_claimed) ÷ 尝试(+ failed)，skipped 排除（后端 `coupon_slot_report`）。
|
||||
|
||||
例：淘宝三张券 100% / 80% / 80% → 淘宝点位 = (100+80+80)/3 = **86.7%**。
|
||||
|
||||
## 不改（其他保持不变）
|
||||
|
||||
- **后端**：`coupon_slot_report` / `_success_rates` / `CouponDataSummary` schema 全不动。
|
||||
`summary.per_platform`、`summary.point_success_rate` 仍会返回（会话口径），只是前端这两处不再引用它们（留着不删，接口稳定）。
|
||||
- **整单成功率**：会话口径不变。
|
||||
- **按券明细表**：排序、列等不动。
|
||||
- **筛选联动**：整单 / 发起 / 完成 / 耗时仍随「用户 / 状态 / 日期 / 环境」全部筛选；
|
||||
点位随 `couponSlots` 走（= 日期 + 环境，不随「用户 / 状态」搜索变——与按券表现状一致）。
|
||||
|
||||
## 实现（单文件 `page.tsx`）
|
||||
|
||||
### 1. 加一个求均值 helper（放 `fmtPct` 附近）
|
||||
|
||||
```ts
|
||||
// 一组按券行的 success_rate 算术平均;无有效券 → null(显示 -)
|
||||
const slotRateMean = (rows: CouponSlotRow[]): number | null => {
|
||||
const rates = rows
|
||||
.map((r) => r.success_rate)
|
||||
.filter((v): v is number => v != null);
|
||||
return rates.length ? rates.reduce((a, b) => a + b, 0) / rates.length : null;
|
||||
};
|
||||
```
|
||||
|
||||
### 2. 合计：改 value
|
||||
|
||||
把
|
||||
```tsx
|
||||
value={fmtPct(summary.point_success_rate)}
|
||||
```
|
||||
改成
|
||||
```tsx
|
||||
value={fmtPct(slotRateMean(couponSlots))}
|
||||
```
|
||||
|
||||
### 3. 分平台卡：改 rate 来源
|
||||
|
||||
把每个平台卡里的
|
||||
```tsx
|
||||
const rate = summary.per_platform?.[pid];
|
||||
```
|
||||
改成
|
||||
```tsx
|
||||
const rate = slotRateMean(couponSlots.filter((r) => r.platform === pid));
|
||||
```
|
||||
|
||||
### 4. 更新口径 tooltip 文案
|
||||
|
||||
`POINT_RATE_HINT` 改成（去掉旧的会话口径描述）：
|
||||
```ts
|
||||
const POINT_RATE_HINT =
|
||||
'点位成功率(合计):当前区间内全部券成功率的算术平均(每张券等权);' +
|
||||
'单券成功率=成功(含已领)÷尝试(不含跳过),源自领券每券记录。';
|
||||
```
|
||||
分平台卡标题（`${SLOT_PLATFORM[pid]}点位成功率`）如需补口径，注明「该平台各券成功率的算术平均」。
|
||||
|
||||
## 边角 / 注意
|
||||
|
||||
- **精度**：`success_rate` 后端已 round 到 4 位，前端再平均，展示只到 1 位小数（`fmtPct`），误差可忽略。
|
||||
- **依赖按券请求**：点位现在依赖 `couponSlots`（独立请求，失败时 `setCouponSlots([])`）。若该请求失败，点位卡显示 `-`（优雅降级）。此前它来自主 `summary` 请求。
|
||||
- **platform=null 的券**：coupon_id 前缀无法识别的券（实践中 pricebot 都是 `mt_`/`tb_`/`ele_`/`elm_`/`jd_`，基本不出现）会计入 **合计**、但不在任何分平台卡里。可接受。
|
||||
|
||||
## 验证
|
||||
|
||||
- **手动**：选一天，展开某平台「查看明细」，核对该平台卡数字 = 明细表各券成功率的算术平均；合计 = 全部券的算术平均。
|
||||
- `npx tsc --noEmit` 通过；`npm run lint` 无新增 error。
|
||||
|
||||
## 不做（YAGNI）
|
||||
|
||||
- 最小尝试数阈值 / 低量券滤噪 / 坏券标红。
|
||||
- 按券表默认升序（坏券置顶）。
|
||||
- 「数据大盘」overview 的领券点位成功率（另一页、另一口径）。
|
||||
- 删除后端已不再被前端使用的 `per_platform` / `point_success_rate` 字段。
|
||||
@@ -128,11 +128,21 @@ const fmtPct = (v: number | null | undefined): string =>
|
||||
const fmtYuan = (v: number | null | undefined): string =>
|
||||
v == null || v <= 0 ? '-' : `¥${v.toFixed(4)}`;
|
||||
|
||||
// 一组按券行的 success_rate 算术平均(每张券等权;空值券跳过);无有效券 → null(显示 -)。
|
||||
// 汇总卡「分平台/合计点位成功率」据此由按券明细上卷,口径与下方按券表一致。
|
||||
const slotRateMean = (rows: CouponSlotRow[]): number | null => {
|
||||
const rates = rows
|
||||
.map((r) => r.success_rate)
|
||||
.filter((v): v is number => v != null);
|
||||
return rates.length ? rates.reduce((a, b) => a + b, 0) / rates.length : null;
|
||||
};
|
||||
|
||||
// 汇总卡成功率口径 tooltip 文案
|
||||
const FULL_RATE_HINT =
|
||||
'整单成功率:一次领券勾选的平台全部至少领到一张的场次 ÷ 领券发起数;基数含未完成/失败/中途退出。';
|
||||
const POINT_RATE_HINT =
|
||||
'点位成功率(合计):平台粒度——各平台(美团/淘宝闪购/京东)成功点位数之和 ÷ 勾选平台点位数之和;空勾选按全领三档计。注意与「数据大盘」券粒度的点位成功率口径不同。';
|
||||
'点位成功率(合计):当前区间内全部券成功率的算术平均(每张券等权);' +
|
||||
'单券成功率=成功(含已领)÷尝试(不含跳过),源自领券每券记录。';
|
||||
|
||||
// 按券表:coupon_id 平台 → 中文
|
||||
const SLOT_PLATFORM: Record<string, string> = {
|
||||
@@ -717,7 +727,7 @@ export default function CouponDataPage() {
|
||||
</Tooltip>
|
||||
</span>
|
||||
}
|
||||
value={fmtPct(summary.point_success_rate)}
|
||||
value={fmtPct(slotRateMean(couponSlots))}
|
||||
/>
|
||||
</Col>
|
||||
</Row>
|
||||
@@ -725,7 +735,8 @@ export default function CouponDataPage() {
|
||||
<Row gutter={[16, 12]}>
|
||||
{(['meituan-waimai', 'taobao-shanguang', 'jd-waimai'] as const).map((pid) => {
|
||||
const active = selectedSlotPlatform === pid;
|
||||
const rate = summary.per_platform?.[pid];
|
||||
// 点位成功率 = 该平台各券成功率的算术平均(源自按券明细 couponSlots,与下方展开的按券表一致)
|
||||
const rate = slotRateMean(couponSlots.filter((r) => r.platform === pid));
|
||||
// 平台名(前置品牌色圆点) | 大数字成功率 | 「查看明细」按钮;仅按钮可展开表格。
|
||||
return (
|
||||
<Col flex="1 1 0" key={pid}>
|
||||
|
||||
Reference in New Issue
Block a user