Add under-anything knowledge dashboard

wishfulfilled-wiki/05_需求文档/03-子系统-额度与频控.md

@@ -0,0 +1,198 @@
+     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 |