cross-platform-products-ai-analyst/docs/review-FeatureSummary-codex.md

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”，这两项会直接影响状态机、接口定义和测试用例；随后再处理证据留存与模块级验收口径，否则这份摘要文档会更像“压缩版说明书”，而不是一份真正可执行的对齐基线。