Add under-anything knowledge dashboard

2026-05-27 15:40:32 +08:00
commit e31a75d2bb
565 changed files with 143063 additions and 0 deletions
--- a/wishfulfilled-wiki/05_需求文档/07-子系统-评价结果追踪.md
+++ b/wishfulfilled-wiki/05_需求文档/07-子系统-评价结果追踪.md
@@ -0,0 +1,171 @@
+     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 |