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 |
