76 lines
5.5 KiB
Markdown
76 lines
5.5 KiB
Markdown
# `FeatureSummary.md` 审阅报告
|
||
|
||
- 审阅对象：`docs/FeatureSummary.md`
|
||
- 文档版本：Draft v0.1
|
||
- 审阅时间：2026-04-02
|
||
- 审阅人：Codex
|
||
|
||
## 1. 总体结论
|
||
|
||
这份 `FeatureSummary.md` 已经把 PRD 中的大部分核心功能、流程、状态和边界压缩成了一份更适合横向对齐的摘要文档，整体方向是对的，且没有明显偏离 MVP 范围。
|
||
|
||
但如果它要作为“产品、设计、研发和测试快速对齐”的直接基线，当前版本还有 4 个需要尽快收紧的问题：零确认链接任务缺少明确终态、报告 Schema 被压缩得过粗、证据留存策略和可追溯承诺互相冲突、模块级验收口径缺失。这些问题不解决，后续最容易出现的不是“功能没做”，而是“状态口径、接口契约和验收标准各自理解不同”。
|
||
|
||
## 2. 主要发现
|
||
|
||
### 2.1 P0：缺少“零确认链接/全无结果”任务的明确终态
|
||
|
||
当前文档要求“至少确认一个链接后，任务才允许进入抓取流程”（`FeatureSummary.md:167-168`），同时又规定 `NoResult` 和 `Skipped` 不计入失败，且任务最终状态只基于“已确认平台”计算（`FeatureSummary.md:366-369`）。但 `task_status` 枚举中并没有为“用户全部跳过”“所有平台都无结果”“没有任何确认链接可执行”提供稳定终态（`FeatureSummary.md:324-333`）。
|
||
|
||
这会导致历史任务列表、重试入口和完成率统计出现歧义：任务既不能进入 `Running`，又不完全符合 `Blocked`/`Failed` 的定义，最终很容易在实现里被各端自行兜底。
|
||
|
||
建议至少补一种明确口径：
|
||
|
||
1. 增加 `NoSelection` / `NoExecutableTarget` 一类任务终态；或
|
||
2. 明确“零确认链接”统一归入 `Failed`，并把该条件写入 `task_status` 定义和汇总规则。
|
||
|
||
### 2.2 P0：报告结构只保留顶层字段，已经不足以支撑研发与测试对齐
|
||
|
||
摘要文档当前只保留了报告顶层字段和少量内容要求（`FeatureSummary.md:375-398`），但文档同时又要求：
|
||
|
||
1. 每条强结论都必须可回溯到证据索引（`FeatureSummary.md:290-292`）。
|
||
2. 洞察卡片需包含置信度、样本标记、来源范围和证据引用（`FeatureSummary.md:396-398`）。
|
||
3. 报告必须覆盖失败/阻塞平台及质量标记（`FeatureSummary.md:292-293`, `FeatureSummary.md:398`）。
|
||
|
||
问题在于，这些约束都没有被收敛为字段级契约。例如 `platform_insights` 是否必须包含执行状态、`quality_flags` 的固定字段有哪些、证据引用是 `id` 还是内嵌对象、失败平台如何在报告中表达，当前都没有定义。相比 `PRD.md` 已经给出的详细 Schema（`PRD.md:434-514`），这里的压缩已经丢失了前后端接口和测试用例所需的最小约束。
|
||
|
||
建议直接把 PRD 中已经冻结的最小 Schema 下沉到摘要文档，至少补齐：
|
||
|
||
1. `platform_insights[].execution_status`
|
||
2. `InsightCard.confidence` / `sample_flag` / `evidence_ids`
|
||
3. `evidence_index[].evidence_id` / `source_type` / `review_ref` / `captured_at`
|
||
4. `quality_flags.sample_insufficient` / `blocked_platforms` / `failed_platforms`
|
||
|
||
### 2.3 P1：证据留存策略与“可追溯报告”承诺存在时间窗口冲突
|
||
|
||
文档规定原始抓取数据默认保存 30 天，而标准化数据和报告保存 90 天（`FeatureSummary.md:410-412`）。但同一份文档又把“可追溯、可用于决策”作为产品核心承诺（`FeatureSummary.md:26`, `FeatureSummary.md:111`, `FeatureSummary.md:452-453`），并要求证据引用可以定位到原证据。
|
||
|
||
如果第 31 天开始原始抓取数据已经过期，而报告还要继续保留 60 天，那么很多历史报告实际上只剩结论、链接和索引，未必还能完成“定位到原证据”的核验。这会直接削弱文档最强调的证据可信度。
|
||
|
||
建议二选一：
|
||
|
||
1. 将原始证据最小留存期对齐到报告留存期；或
|
||
2. 在报告侧定义“长期留存的最小证据快照”，例如评论摘要、来源链接、评论引用标识、抓取时间和必要上下文，确保 90 天内仍可核验。
|
||
|
||
### 2.4 P1：文档目标强调“供设计、研发、测试快速对齐”，但摘要版已丢失模块级验收口径
|
||
|
||
文档开头明确说这份摘要是给产品、设计、研发和测试快速对齐使用的（`FeatureSummary.md:13`）。但在可验证性上，当前只保留了总体质量指标（`FeatureSummary.md:446-461`），没有保留 PRD 中按模块拆开的验收标准，例如任务创建、搜索召回、状态模型、评论抓取、重试版本等模块的通过条件（`PRD.md:597-614`）。
|
||
|
||
这会让 QA 和研发在执行层面只能对齐“总体结果”，难以对齐“每个模块做到什么程度算完成”。尤其是异常流和状态流相关能力，很容易在联调后才暴露口径差异。
|
||
|
||
建议在摘要文档末尾补一个极简“模块级验收清单”，不需要复刻完整 PRD，但至少保留：
|
||
|
||
1. 搜索召回
|
||
2. 候选确认
|
||
3. 状态模型
|
||
4. 登录与会话
|
||
5. 评论抽样
|
||
6. 报告可追溯性
|
||
7. 失败重试与版本
|
||
|
||
## 3. 最终判断
|
||
|
||
这份 `FeatureSummary.md` 作为“功能摘要”已经合格，但作为直接驱动设计、开发和测试协作的摘要基线，仍然少了几条关键硬约束。
|
||
|
||
优先级上，建议先补“零确认链接终态”和“报告最小 Schema”，这两项会直接影响状态机、接口定义和测试用例；随后再处理证据留存与模块级验收口径，否则这份摘要文档会更像“压缩版说明书”，而不是一份真正可执行的对齐基线。
|