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 |