172 lines
12 KiB
Markdown
172 lines
12 KiB
Markdown
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 |
|