1|# 子系统 07 — 评价结果追踪 (`review`) v1.0
     2|
     3|## 子系统概述
     4|
     5|| 维度 | 说明 |
     6|| --- | --- |
     7|| 代号 | `review` |
     8|| 核心职责 | 用户真实提交评价记录、Amazon 展示核验、ASIN 健康/计划完成度更新回流 |
     9|| 数据所有权 | `review_submission_records`, `review_display_checks`, `review_results` |
    10|| 启动依赖 | identity / planning（软依赖） |
    11|| 外部系统依赖 | Amazon（评价展示状态、ASIN 评分数据） |
    12|
    13|---
    14|
    15|## 1. 模块划分
    16|
    17|```
    18|┌─────────────────────────────────────────────────────────────┐
    19|│                    review 子系统                             │
    20|│                                                             │
    21|│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
    22|│  │ M1: 评价提交 │  │ M2: 展示核验 │  │ M3: 结果回流 │       │
    23|│  │    记录      │→│              │→│    引擎      │       │
    24|│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘       │
    25|│         │                 │                 │                │
    26|│         ▼                 ▼                 ▼                │
    27|│  ┌──────────────┐  ┌──────────────┐                         │
    28|│  │ M4: 异常观察 │  │ M5: 对外 API │                         │
    29|│  │    队列      │  │    Gateway   │                         │
    30|│  └──────────────┘  └──────────────┘                         │
    31|│                                                             │
    32|└─────────────────────────────────────────────────────────────┘
    33|```
    34|
    35|| # | 模块 | 职责 |
    36|| --- | --- | --- |
    37|| M1 | 评价提交记录 | 记录用户真实提交评价的事实（提交时点、提交证据、关联计划、关联 ASIN） |
    38|| M2 | 展示核验 | 核查 Amazon 是否展示该评价 / 是否可核验 |
    39|| M3 | 结果回流引擎 | 将评价结果反馈给 planning（计划完成度）、identity（用户标签）、audit |
    40|| M4 | 异常观察队列 | 用户已提交但 Amazon 未展示 / 暂不可核验的评价，进入定期复查队列 |
    41|| M5 | 对外 API Gateway | 供 outreach、planning 查询评价进度、提交评价 |
    42|
    43|---
    44|
    45|## 2. 各模块内外说明
    46|
    47|### 2.1 M1: 评价提交记录
    48|
    49|| 维度 | 说明 |
    50|| --- | --- |
    51|| **对内** | 记录两个核心事实：①用户真实提交评价（时间、ASIN、评论内容/截图/链接、关联计划）；②提交后立即更新真实人累计评价额度（调用 quota 子系统 `commit`） |
    52|| **对外接口** | `POST /api/reviews/submission` — 记录评价提交 |
    53|| **数据写入** | `review_submission_records` |
    54|| **依赖** | `POST /api/quota/commit` — 确认额度占用（提交后立即计数12） |
    55|| **关键规则** | 「用户真实提交评价」和「Amazon 展示确认」是两个独立事实；额度计数按前者，计划完成按后者 |
    56|
    57|### 2.2 M2: 展示核验
    58|
    59|| 维度 | 说明 |
    60|| --- | --- |
    61|| **对内** | 核查 Amazon 是否展示该评价 / 是否可核验；核验方式（待确认：爬取 / 手动 / API / 截图？）；核验结果：①展示或可核验→计入计划完成 ②未展示/暂不可核验→保留已提交事实→进入异常观察 |
    62|| **对外接口** | `POST /api/reviews/verify` — 触发核验（或定时核验） |
    63|| **数据写入** | `review_display_checks` |
    64|| **依赖** | Amazon（评价展示数据） |
    65|| **待确认** | 核验是自动还是人工？核验频率？ |
    66|
    67|### 2.3 M3: 结果回流引擎
    68|
    69|| 维度 | 说明 |
    70|| --- | --- |
    71|| **对内** | 评价确认展示后：①通知 planning 更新计划完成度 ②通知 identity 更新用户标签（例如标记为「已回评用户」）③写入审计日志；免评结果回流：①更新 ASIN 健康与权重变化 ②更新计划完成度 ③通知 planning |
    72|| **对外接口** | 内部事件发布 |
    73|| **数据写入** | `review_results` |
    74|| **依赖** | `PUT /api/plans/{id}/status`（更新计划状态） |
    75|
    76|### 2.4 M4: 异常观察队列
    77|
    78|| 维度 | 说明 |
    79|| --- | --- |
    80|| **对内** | 用户已提交但 Amazon 未展示/暂不可核验的评价，进入异常观察队列；定期复查（例如每天查一次 Amazon 是否已展示）；超过观察期仍未展示→标记异常→通知运营 |
    81|| **数据写入** | `review_display_checks`（更新状态） |
    82|| **待确认** | 观察周期多长？复查频率？观察期满后如何处理？ |
    83|
    84|---
    85|
    86|## 3. 对外 API 契约（草案）
    87|
    88|| 接口 | 方法 | 输入 | 输出 | 消费者 |
    89|| --- | --- | --- | --- | --- |
    90|| 记录评价提交 | `POST /api/reviews/submission` | `{person_id, asin, plan_id, evidence, submitted_at}` | `{submission_id, quota_updated}` | outreach（IM 核验后/客服确认后） |
    91|| 查询计划评价进度 | `GET /api/reviews/status/{plan_id}` | plan_id | `{total_submissions, verified, pending, completion_rate}` | planning |
    92|| 查询用户评价历史 | `GET /api/reviews/history/{person_id}` | person_id | `[{submission_id, asin, status, submitted_at}]` | identity（上下文卡） |
    93|| ASIN 评价统计 | `GET /api/reviews/asin-stats/{asin}` | asin | `{submission_count, verified_count, pending_count}` | planning |
    94|
    95|---
    96|
    97|## 4. 数据对象
    98|
    99|| 对象 | 核心字段 | 说明 |
   100|| --- | --- | --- |
   101|| `review_submission_records` | submission_id, person_id, asin, plan_id, evidence_type, evidence, submitted_at, quota_updated | 评价提交记录（核心事实一） |
   102|| `review_display_checks` | check_id, submission_id, asin, check_method, check_result(DISPLAYED/NOT_DISPLAYED/UNVERIFIABLE), checked_at, retry_count, status(OBSERVING/CONFIRMED/ABNORMAL) | 展示核验记录（核心事实二） |
   103|| `review_results` | result_id, plan_id, asin, submission_count, verified_count, completion_rate, asin_health_change, updated_at | 评价结果汇总 |
   104|
   105|---
   106|
   107|## 5. 业务澄清问题清单 — review
   108|
   109|### 5.1 评价提交记录（3 项）
   110|
   111|| # | 问题 | 优先级 |
   112|| --- | --- | --- |
   113|| V-01 | 「用户真实提交评价」的证据形式是什么？（用户上传的截图？Amazon 评论链接？系统自动检测？）不同形式如何验证真伪？ | **P0** |
   114|| V-02 | 一个用户为同一个 ASIN 提交多条评价（如果 Amazon 允许）——每一条都独立计入累计12额度吗？ | **P0** |
   115|| V-03 | 评价提交记录是 outreach（IM/客服）写入还是用户直接提交？（系统内提交 vs 系统外提交的区别）系统外提交如何登记？ | P1 |
   116|
   117|### 5.2 展示核验（4 项）
   118|
   119|| # | 问题 | 优先级 |
   120|| --- | --- | --- |
   121|| V-04 | Amazon 评价展示的核验方式是？（定时爬取 Amazon 产品页？SP-API 拉取评价列表？用户上传截图人工审核？混合方式？） | **P0** |
   122|| V-05 | 如果通过爬取核验——爬取频率？（小时级？天级？）如何识别「哪条评价是本次计划用户提交的」？（靠评论者名字匹配？靠时间窗口？） | **P0** |
   123|| V-06 | 「暂不可核验」的常见原因有哪些？（Amazon 审核中/延迟展示/被 Amazon 删除？）每种原因的处理策略是否不同？ | P1 |
   124|| V-07 | 核验失败的兜底机制——如果 Amazon API 不可用或爬取失败，是否允许人工确认？ | P1 |
   125|
   126|### 5.3 异常观察队列（2 项）
   127|
   128|| # | 问题 | 优先级 |
   129|| --- | --- | --- |
   130|| V-08 | 异常观察队列的观察期多长？（1 天？7 天？30 天？）复查频率？（每天？每周？）观察期满后未展示→如何处理？ | P1 |
   131|| V-09 | 多少条评价进入异常观察算异常阈值？（单计划 10% 未展示→通知？单用户多次未展示→标记？） | P2 |
   132|
   133|### 5.4 结果回流（3 项）
   134|
   135|| # | 问题 | 优先级 |
   136|| --- | --- | --- |
   137|| V-10 | ASIN 健康「回流」的具体动作是什么？（更新 ASIN 评分/评价数到 planning？触发新一轮需求评估？更新 outreach 的触达策略？） | P1 |
   138|| V-11 | 计划完成度的计算方式——「评价确认展示」即算完成？还是需要确认展示 + 关联到本计划用户？（如何确保那条展示的评价确实是本计划用户的？） | P1 |
   139|| V-12 | 免评结果的「权重变化」如何量化？（Amazon 不直接提供权重数据——如何通过间接指标判断？） | P2 |
   140|
### 5.5 评价质量管理（4 项）

| # | 问题 | 优先级 |
| --- | --- | --- |
| V-13 | 是否需要评价内容分析？（好评/中评/差评？评价字数？是否含图片/视频？——这些影响评价质量评分？） | P2 |
| V-14 | 差评检测和响应——用户提交了差评（1-2 星）是否需要自动触发售后工单？（「差评补救」流程？） | P1 |
| V-15 | 虚假评价检测——用户提交的评价是否可能被 Amazon 判定为虚假评价并删除？（系统是否需要内部质量评分来预测被删风险？） | P2 |
| V-16 | 评价的 ASIN 匹配校验——用户声称对 ASIN A 提交了评价但实际是对 ASIN B 提交的——如何检测和处理？ | P1 |

### 5.6 异常观察队列补充（3 项）

| # | 问题 | 优先级 |
| --- | --- | --- |
| V-17 | 评价提交后 Amazon 展示的预期时间窗口？（通常 24-48h？最长多久？）超出预期窗口后的自动通知？ | P1 |
| V-18 | Amazon 删除评价（违反社区准则）vs 用户删除评价 vs 评价被折叠——是否能区分？分别如何处理？ | P2 |
| V-19 | 大量评价同时进入异常观察（例如 Amazon 评价系统故障导致全站延迟）——系统如何处理？（自动暂停观察队列？人工干预？） | P2 |

### 5.7 ASIN 健康回流补充（3 项）

| # | 问题 | 优先级 |
| --- | --- | --- |
| V-20 | ASIN 健康更新的频率？（每次评价确认展示就更新？每天汇总更新一次？） | P2 |
| V-21 | 如果多人同时对同一 ASIN 提交了评价，是否对 ASIN 健康有复合影响？（例如 5 条 5 星好评 vs 1 条 1 星差评——权重不同） | P2 |
| V-22 | ASIN 健康数据的来源——是 Amazon 直接提供的数据还是系统内部计算？（Amazon 评分 vs 系统追踪到的评价评分可能有差异） | P1 |

### 5.8 实施层面（2 项）

| # | 问题 | 优先级 |
| --- | --- | --- |
| V-23 | 评价展示核验如果是爬取 Amazon 页面——爬取频率和多 ASIN 并行爬取能力？（需要爬取几百个 ASIN 时的时间和资源开销） | P1 |
| V-24 | 评价数据是否需要在系统间同步？（outreach 需要知道「用户已提交」→暂停触达；planning 需要知道「评价已确认」→更新计划完成度）数据一致性的保证？ | P1 |