199 lines
14 KiB
Markdown
199 lines
14 KiB
Markdown
1|# 子系统 03 — 额度与频控 (`quota`) v1.0
|
||
2|
|
||
3|## 子系统概述
|
||
4|
|
||
5|| 维度 | 说明 |
|
||
6|| --- | --- |
|
||
7|| 代号 | `quota` |
|
||
8|| 核心职责 | 额度台账（测评4/免评4/累计12）、额度预占与释放、频控规则引擎、发送前终校 |
|
||
9|| 数据所有权 | `person_quota_ledgers`, `quota_reservations`, `frequency_control_records` |
|
||
10|| 启动依赖 | identity（软依赖，额度按真实人计算，未归并时按单一账号） |
|
||
11|| 外部系统依赖 | 无直接外部依赖 |
|
||
12|
|
||
13|---
|
||
14|
|
||
15|## 1. 模块划分
|
||
16|
|
||
17|```
|
||
18|┌─────────────────────────────────────────────────────────────┐
|
||
19|│ quota 子系统 │
|
||
20|│ │
|
||
21|│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
22|│ │ M1: 额度台账 │ │ M2: 预占管理 │ │ M3: 频控引擎 │ │
|
||
23|│ │ (Ledger) │→│ (Reservation)│ │ (FreqCtrl) │ │
|
||
24|│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
|
||
25|│ │ │ │ │
|
||
26|│ ▼ ▼ ▼ │
|
||
27|│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
28|│ │ M4: 终校服务 │ │ M5: 额度管理 │ │ M6: 对外 API │ │
|
||
29|│ │ (FinalCheck)│ │ Admin │ │ Gateway │ │
|
||
30|│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||
31|│ │
|
||
32|└─────────────────────────────────────────────────────────────┘
|
||
33|```
|
||
34|
|
||
35|| # | 模块 | 代号 | 职责 |
|
||
36|| --- | --- | --- | --- |
|
||
37|| M1 | 额度台账 | `quota-ledger` | 维护真实人三层额度（测评4/免评4/累计12）、已用/进行中/已预占计数 |
|
||
38|| M2 | 预占管理 | `reservation-mgr` | 额度预占创建、确认占用、超时释放；跨计划重复入选检测 |
|
||
39|| M3 | 频控引擎 | `freq-control` | 渠道频控（IM/EDM/APP/TEL 最近触达间隔）、单 ASIN 短期触达次数、退订/投诉屏蔽 |
|
||
40|| M4 | 终校服务 | `final-check` | 发送前合并校验（最新额度 + 最新风险 + 最新未关闭工单），准入/撤出决策 |
|
||
41|| M5 | 额度管理 Admin | `quota-admin` | 额度手动调整、额度重置、额度审计 |
|
||
42|| M6 | 对外 API Gateway | `quota-api` | 供 planning（人群生成）、outreach（发送前校验）、review（提交后确认）调用 |
|
||
43|
|
||
44|---
|
||
45|
|
||
46|## 2. 各模块内外说明
|
||
47|
|
||
48|### 2.1 M1: 额度台账
|
||
49|
|
||
50|| 维度 | 说明 |
|
||
51|| --- | --- |
|
||
52|| **对内** | 按真实人维护三种额度：月度测评（已完成+进行中+已预占）、月度免评（同上）、累计真实提交评价（永久累计）；额度计数时点明确（提交评价立即计数12、不会因 Amazon 未展示回退）；接近上限时预警 |
|
||
53|| **对外接口** | `GET /api/quota/ledger/{person_id}` — 读取当前台账 |
|
||
54|| **数据写入** | `person_quota_ledgers` |
|
||
55|| **依赖** | `GET /api/identity/person` — 获取真实人 ID |
|
||
56|
|
||
57|### 2.2 M2: 预占管理
|
||
58|
|
||
59|| 维度 | 说明 |
|
||
60|| --- | --- |
|
||
61|| **对内** | 人群生成时预占额度（测评/免评）；计算：已用+进行中+已预占+本次拟发送 > 上限 → 拦截；剩余不足但>0 → 预警池 → 发送前人工复核；预占有效期管理，超时自动释放；并发占用控制（同一真实人跨计划重复入选检测） |
|
||
62|| **对外接口** | `POST /api/quota/reserve` — 创建预占；`POST /api/quota/commit` — 确认占用；`POST /api/quota/release` — 释放预占 |
|
||
63|| **数据写入** | `quota_reservations` |
|
||
64|
|
||
65|### 2.3 M3: 频控引擎
|
||
66|
|
||
67|| 维度 | 说明 |
|
||
68|| --- | --- |
|
||
69|| **对内** | 四种频控维度：①渠道频控（IM/EDM/APP/TEL 最近触达间隔）②单 ASIN 短期内触达同一用户次数 ③用户反感度（投诉/退订状态）④用户在客服工单中暂不触达；频控规则可配置 |
|
||
70|| **对外接口** | `GET /api/quota/freq-check/{person_id}?channel=IM&asin=xxx` — 频控检查 |
|
||
71|| **数据写入** | `frequency_control_records` |
|
||
72|| **依赖** | 触达历史来自 outreach（`GET /api/outreach/history/{person_id}`） |
|
||
73|
|
||
74|### 2.4 M4: 终校服务
|
||
75|
|
||
76|| 维度 | 说明 |
|
||
77|| --- | --- |
|
||
78|| **对内** | 发送前做最终校验：①重新读取最新额度（防止发送和预占之间额度变化）②重新读取最新风险状态 ③重新读取最新未关闭工单；三者全部通过→准入发送；任一新增超限/风险/工单→撤出本批次 |
|
||
79|| **对外接口** | `POST /api/quota/final-check` — 批量终校（输入 person_ids + plan_id，返回每个的准入/撤出决策） |
|
||
80|| **数据写入** | 终校结果写入审计日志 |
|
||
81|| **依赖** | `GET /api/risk/check/{person_id}`；`GET /api/tickets?person_id=&status=open` |
|
||
82|
|
||
83|### 2.5 M5: 额度管理 Admin
|
||
84|
|
||
85|| 维度 | 说明 |
|
||
86|| --- | --- |
|
||
87|| **对内** | 额度手动调整（运营确认某次测评不计入额度等）；额度重置（新月份额度初始化）；额度审计（谁改了什么额度） |
|
||
88|| **对外接口** | 管理 API |
|
||
89|
|
||
90|### 2.6 M6: 对外 API Gateway
|
||
91|
|
||
92|| 维度 | 说明 |
|
||
93|| --- | --- |
|
||
94|| **对外接口** | `GET /api/quota/check/{person_id}?type=测评` — 额度查询+可用判断；`POST /api/quota/reserve` — 预占；`POST /api/quota/commit` — 确认；`POST /api/quota/release` — 释放；`POST /api/quota/final-check` — 终校 |
|
||
95|
|
||
96|---
|
||
97|
|
||
98|## 3. 对外 API 契约（草案）
|
||
99|
|
||
100|| 接口 | 方法 | 输入 | 输出 | 消费者 |
|
||
101|| --- | --- | --- | --- | --- |
|
||
102|| 额度查询 | `GET /api/quota/check/{person_id}?type=REVIEW` | person_id + 额度类型 | `{used, in_progress, reserved, remaining, status(sufficient/warning/exceeded)}` | planning, outreach |
|
||
103|| 批量预占 | `POST /api/quota/reserve` | `[{person_id, type, plan_id, count}]` | `[{person_id, success, reservation_id}]` | planning（人群生成时） |
|
||
104|| 确认占用 | `POST /api/quota/commit` | `[{reservation_id}]` | `[{reservation_id, committed}]` | review（用户提交评价后） |
|
||
105|| 释放预占 | `POST /api/quota/release` | `[{reservation_id}]` | `[{success}]` | planning（计划取消时） |
|
||
106|| 频控检查 | `GET /api/quota/freq-check/{person_id}?channel=&asin=` | person_id + 渠道 + ASIN | `{allowed, reason, cooldown_until}` | outreach（发送前） |
|
||
107|| 发送前终校 | `POST /api/quota/final-check` | `[{person_id, plan_id}]` | `[{person_id, decision: APPROVED/WITHDRAWN, reasons}]` | outreach（发送前最后一步） |
|
||
108|
|
||
109|---
|
||
110|
|
||
111|## 4. 数据对象
|
||
112|
|
||
113|| 对象 | 核心字段 | 说明 |
|
||
114|| --- | --- | --- |
|
||
115|| `person_quota_ledgers` | ledger_id, person_id, quota_type (MONTHLY_REVIEW/MONTHLY_EXEMPTION/LIFETIME_SUBMISSION), period, used, in_progress, reserved, limit_value, status | 三层额度台账 |
|
||
116|| `quota_reservations` | reservation_id, person_id, ledger_id, plan_id, count, status (RESERVED/COMMITTED/RELEASED/EXPIRED), reserved_at, expires_at | 额度预占记录 |
|
||
117|| `frequency_control_records` | freq_id, person_id, channel, asin, last_contact_at, contact_count_period, status | 频控记录 |
|
||
118|
|
||
119|---
|
||
120|
|
||
121|## 5. 业务澄清问题清单 — quota
|
||
122|
|
||
123|### 5.1 额度规则细化（5 项）
|
||
124|
|
||
125|| # | 问题 | 优先级 |
|
||
126|| --- | --- | --- |
|
||
127|| Q-01 | 月度额度按自然月还是 30 天滚动？如果是自然月：①预占在 1 月 31 日，2 月 1 日释放还是保留？②1 月 31 日晚 23:59 的预占跨月怎么处理？ | **P0** |
|
||
128|| Q-02 | 「测评 4 次」中的「次」定义：是指参与 4 个不同的测评计划，还是提交 4 条评价？（如果 1 个计划要求用户提交 3 条评价，占 3 次还是 1 次？） | **P0** |
|
||
129|| Q-03 | 「累计 12 个真实提交评价」是永久上限还是可以动态调整？（例如用户长期优质且评价质量高，是否可以人工放宽？放宽流程？） | P1 |
|
||
130|| Q-04 | 测评和免评额度是否独立？（测评 4 次 + 免评 4 次 = 同一真实人一月最多参与 8 个计划？）还是测评和免评共享总额度？ | P1 |
|
||
131|| Q-05 | 额度计算中「进行中」的定义——什么状态才算进行中？（已生成人群？已发送触达？用户已回应？已提交评价待核验？） | P1 |
|
||
132|
|
||
133|### 5.2 预占机制（4 项）
|
||
134|
|
||
135|| # | 问题 | 优先级 |
|
||
136|| --- | --- | --- |
|
||
137|| Q-06 | 预占有效期多长？（预占后用户始终未响应，多久释放？1 天？7 天？计划周期结束？） | **P0** |
|
||
138|| Q-07 | 预占释放后是否可以自动重新分配给同一计划的其他用户？是否触发重新生成人群？ | P1 |
|
||
139|| Q-08 | 跨计划并发占用检测——同一真实人在计划 A 和计划 B 同时被入选，谁先预占谁得？还是按计划优先级？ | P1 |
|
||
140|| Q-09 | 预占是否可手动取消/释放？（运营发现某用户不应计入某计划时） | P2 |
|
||
141|
|
||
142|### 5.3 频控规则（4 项）
|
||
143|
|
||
144|| # | 问题 | 优先级 |
|
||
145|| --- | --- | --- |
|
||
146|| Q-10 | 各渠道频控的具体阈值是什么？（IM 每日最多 X 次？EDM 每周最多 Y 封？APP Push 每日最多 Z 条？TEL 每日最多 N 通？） | **P0** |
|
||
147|| Q-11 | 频控规则是否区分计划类型？（紧急催评是否可以突破频控？） | P1 |
|
||
148|| Q-12 | 频控是全局统一配置还是按用户层级可调整？（A 类和 C 类用户频控规则是否不同？） | P1 |
|
||
149|| Q-13 | 「单 ASIN 短期触达次数」——多少天内触达多少次算超标？ | P2 |
|
||
150|
|
||
151|### 5.4 预警与异常（3 项）
|
||
152|
|
||
153|| # | 问题 | 优先级 |
|
||
154|| --- | --- | --- |
|
||
155|| Q-14 | 预警阈值如何设定？（剩余 1 次时预警？剩余 N% 时预警？不同类型额度预警阈值是否不同？） | P1 |
|
||
156|| Q-15 | 终校中「新增风险」的判断——距离上次风险检查超过多少时间需重查？还是每次终校都实时查 risk？ | P1 |
|
||
157|| Q-16 | 额度数据异常时的处理策略？（台账数据与预占记录不一致、预占未释放导致额度泄漏——系统如何自动发现和修复？） | P2 |
|
||
158|
|
||
### 5.5 额度异常与纠错（4 项）
|
||
|
||
| # | 问题 | 优先级 |
|
||
| --- | --- | --- |
|
||
| Q-17 | 用户反馈「我明明只参与了 3 次测评，系统说我已用 4 次」——申诉流程？谁有权限查台账和修正？ | P1 |
|
||
| Q-18 | 额度台账的审计追踪——每次额度变更（预占/确认/释放/手动调整）是否记录完整操作人和原因？保留多久？ | P1 |
|
||
| Q-19 | 数据异常自动检测——台账数据与预占记录之和是否需要对账？系统是否定期自动化对账并报告差异？ | P1 |
|
||
| Q-20 | 如果发现「额度泄漏」（预占未释放导致额度永久被占），系统如何自动发现和修复？（定时扫描过期预占？手动触发对账？） | P2 |
|
||
|
||
### 5.6 紧急/例外处理（4 项）
|
||
|
||
| # | 问题 | 优先级 |
|
||
| --- | --- | --- |
|
||
| Q-21 | 大促期间（Prime Day/Black Friday）是否需要临时额度提升？（测评 4→8？）由谁审批？临时额度有效期？ | P1 |
|
||
| Q-22 | 高价值用户是否可以突破额度限制？（例如 KOC 级别的用户需要超额参与——人工审批流程？） | P1 |
|
||
| Q-23 | 「紧急计划」是否可以跳过频控？（例如 Listing 评分暴跌至 3.8 需要紧急大量催评——是否豁免部分频控规则？） | P1 |
|
||
| Q-24 | 额度手动调整是否需要审批？审批权限？（谁可以手动给某人加/减可用额度？） | P2 |
|
||
|
||
### 5.7 跨站点/跨平台额度（3 项）
|
||
|
||
| # | 问题 | 优先级 |
|
||
| --- | --- | --- |
|
||
| Q-25 | 额度是否跨 Amazon 站点？（.com 参与了 2 次测评 + .co.uk 参与了 3 次 → 全局算 5 次还是各自独立？） | P1 |
|
||
| Q-26 | 累计 12 个评价是否跨站点统计？（在 .com 提交了 8 个 + .co.uk 提交了 5 个 → 是否算 13 个超限？） | P1 |
|
||
| Q-27 | 未来扩展到非 Amazon 平台，额度体系是否独立？（eBay 的测评额度与 Amazon 的额度是否共享？） | P2 |
|
||
|
||
### 5.8 额度可见性（2 项）
|
||
|
||
| # | 问题 | 优先级 |
|
||
| --- | --- | --- |
|
||
| Q-28 | 用户是否能看到自己的额度状态？（APP 端显示「本月还可参与 2 次测评」——是否对用户可见？） | P2 |
|
||
| Q-29 | 运营视角的额度看板——能否看到「全局额度使用率」「各真实人的额度分布」「额度预警用户列表」？ | P1 |
|
||
|
||
### 5.9 实施层面（3 项）
|
||
|
||
| # | 问题 | 优先级 |
|
||
| --- | --- | --- |
|
||
| Q-30 | 终校服务的性能要求——批量终校（一次可能几百人）需要在多少 ms 内完成？（涉及跨子系统调用 risk + support） | P2 |
|
||
| Q-31 | 频控规则是否需要热更新（不重启服务即可调整阈值）？配置管理方案？ | P1 |
|
||
| Q-32 | 额度台账历史数据的初始化——旧系统的数据如何映射到三层额度模型？（无「真实人」概念的老数据如何归入？） | P1 |
|