# 产品功能文档

- 文档名称：`FeatureSummary.md`
- 文档状态：Draft
- 版本：v0.4
- 更新时间：2026-04-02
- 依据文档：
  - `docs/PRD.md`
  - `docs/CrawlerFeasibility.md`
  - `docs/review-PRD-codex.md`

## 1. 文档目的

本文件用于从功能视角总结跨平台商品聚合与 AI 分析产品的 MVP 方案，供产品、设计、研发和测试快速对齐。

相较完整 PRD，本文件重点回答四类问题：

1. 产品到底要做哪些功能。
2. 这些功能按什么流程组织。
3. 关键状态、规则和输出口径如何定义。
4. 哪些能力属于 MVP，哪些能力明确不做。

## 2. 产品概述

### 2.1 一句话定位

这是一个面向品牌运营、电商运营和竞品分析岗位的跨平台商品分析工作台：用户输入商品名称或描述，系统完成多平台搜索、人工确认、商品与评论抓取、标准化处理和 AI 分析，最终输出可追溯、可用于决策的结构化报告。

### 2.2 目标用户

| 用户角色 | 核心诉求 |
| --- | --- |
| 品牌方运营 | 快速了解同款或竞品在不同平台的卖点、价格、评价和风险 |
| 电商运营 | 对比自家商品与竞品在商品页、评论和店铺层面的表现差异 |
| 商品研究/竞品分析 | 产出一份可复用、可引用、可追溯的结构化分析报告 |

### 2.3 核心价值

1. 把分散在多个平台的手工检索整合成一次任务发起。
2. 用“系统召回 + 人工确认”降低同款识别错误率。
3. 把商品信息和评论样本统一成标准结构，减少人工整理成本。
4. 基于证据生成平台差异、卖点、风险点和运营建议，提升决策效率。

### 2.4 产品交付形态

MVP 以“内部受控部署的网页工作台”形态交付。用户通过浏览器访问统一 Web 工作台，在页面内完成任务创建、候选确认、抓取执行、报告查看和历史回看；采集执行、会话复用和阻塞恢复统一在服务端受控环境完成。

关键边界：

1. 首版以内部受控服务器部署、单工作区使用为基线。
2. 当前不以用户本机执行采集、多租户协作或云端 SaaS 作为 MVP 交付形态。
3. 团队协作与更广泛部署能力放入后续版本评估。

### 2.5 非目标

1. 不做持续监控、自动巡检或定时更新。
2. 不做消费者导购推荐。
3. 不做内容平台或社媒平台舆情分析。
4. 不保证评论全量抓取。
5. 不在无人工确认的前提下自动认定同款商品。
6. 不承诺绕过验证码、风控和登录限制。

## 3. MVP 范围

### 3.1 平台范围

MVP 仅支持以下平台：

1. 天猫
2. 京东

MVP 暂不覆盖：

1. 淘宝，作为下一优先扩展平台
2. 抖音电商，当前阶段延后实现
3. 拼多多、Amazon 等其他电商平台
4. 小红书、微博、B 站、短视频内容平台

### 3.2 输入与输出

输入：

1. 商品关键词或自然语言描述
2. 单链接评论抓取上限 `N`

输出：

1. 任务内结构化网页报告页
2. 原始抓取数据
3. 标准化商品与评论数据
4. 历史任务与报告版本回看

### 3.3 任务模式

1. MVP 采用一次性分析任务模式。
2. 每个任务从搜索开始，到报告产出结束。
3. 任务结束后支持回看和失败平台重试，不支持自动增量更新。

### 3.4 默认配置

1. 每个平台默认返回 Top 5 候选商品。
2. 单链接评论样本上限默认值为 `100`。
3. 单任务评论总上限为 `500`。

### 3.5 运行方式

1. MVP 先以内部受控服务端部署方式运行，用户通过浏览器访问统一工作台。
2. 当前不以用户本机执行采集或开放多租户形态交付。
3. 团队协作和更广泛部署能力放入后续版本评估。

## 4. 核心功能闭环

完整任务按以下顺序执行：

1. 用户创建任务，输入商品关键词和评论抓取配置。
2. 系统先按平台执行搜索前预检查，判断能否进入搜索。
3. 系统对可搜索平台执行站内搜索，返回候选结果、无结果或阻塞原因。
4. 用户按平台确认一个、多个或零个商品链接。
5. 若最终没有任何链接被确认，任务进入 `NoSelection` 终态，不进入抓取与报告生成。
6. 系统仅对已确认的平台执行抓取前会话与访问校验。
7. 校验通过的平台进入商品和评论抓取；校验失败的平台进入平台级阻塞。
8. 系统完成数据标准化、多链接聚合和 AI 分析。
9. 系统生成结构化报告快照，并写入历史任务记录。
10. 若存在失败或阻塞平台，用户可定向重试，不覆盖既有报告。

关键收敛规则：

1. 搜索前预检查发生在搜索之前；抓取前校验只发生在用户确认之后。
2. 单个平台异常不会默认终止整任务，只要仍有至少一个已确认平台可执行，任务继续。
3. 报告必须为结构化输出，不接受只有自由文本而无证据索引的结果。
4. 重试只针对失败、阻塞类平台执行；结果变化才生成新报告版本。
5. 新建任务页允许在创建任务前进入全局会话准备入口；该入口只更新平台会话状态，不创建任务。

## 5. 功能模块说明

### 5.1 任务创建

系统需支持：

1. 输入商品关键词或商品描述。
2. 配置单链接评论样本上限 `N`。
3. 在任务发起前展示平台可用性提示。

关键规则：

1. 平台提示来源于平台能力配置与最近一次会话校验结果，仅作预告。
2. `N` 的作用域为每个已确认链接，不是整任务统一平均值。
3. 若多个链接合计样本超过任务总上限，系统按比例收缩并明确提示。
4. 若平台需要会话准备，用户可直接进入全局会话准备入口，处理完成后返回当前页继续创建任务。

### 5.2 搜索召回与候选展示

系统需支持：

1. 分平台执行站内搜索。
2. 搜索前做轻量预检查，判断平台是否可搜索。
3. 返回候选商品列表、无结果或阻塞原因。
4. 对候选卡片展示足够用于判断的信息。

候选卡片至少包含：

1. 平台名称
2. 商品标题
3. 商品链接
4. 价格
5. 店铺名称
6. 主图或缩略图
7. 销量、热度、评分等辅助识别信息

候选规则：

1. 同平台下重复候选需去重，但原始候选结果仍可回看。
2. 同店铺疑似同款但规格不同的候选，不自动合并，需展示规格差异标签。
3. 不同店铺即使疑似同款，也保持独立候选，避免掩盖店铺差异。
4. 平台内默认排序按关键词匹配度、销量或热度、评价完整性、价格完整性综合排序。

### 5.3 商品链接确认

系统需支持：

1. 用户逐个平台浏览候选商品。
2. 在单个平台中单选、多选或跳过。
3. 记录确认结果并支持回看。

关键规则：

1. 平台内多选属于 MVP 核心能力。
2. 只有至少确认一个链接后，任务才允许进入抓取流程。
3. 一旦进入抓取阶段，只处理用户已确认的链接，不再自动扩展范围。
4. 若用户最终提交零确认链接，任务进入 `NoSelection` 终态；系统保留候选结果与原因摘要，但不生成报告快照。

### 5.4 平台登录与访问策略

MVP 采用“用户自有账号登录 + 服务端受控会话复用”模式。

每个平台需配置 `search_requirement`：

| 配置值 | 含义 | 搜索时行为 |
| --- | --- | --- |
| `none` | 搜索不依赖登录态 | 可直接搜索 |
| `recommended` | 不登录也可搜索，但结果可能不完整 | 允许搜索并提示风险 |
| `required` | 搜索依赖有效会话 | 无有效会话时不进入搜索 |

系统需支持：

1. 在真实搜索前执行平台预检查。
2. 仅对已确认平台执行抓取前校验。
3. 识别登录失效、跳转登录页、验证码和风控拦截。
4. 指引用户在服务端受控浏览器中处理登录或验证后继续任务。
5. 在任务外提供全局会话准备入口，用于在创建任务前预热 `required` 平台的会话状态。

关键规则：

1. 系统不保存用户账号密码。
2. 会话缓存仅在当前部署实例/工作区的服务端会话中心复用，并支持用户主动清除。
3. 搜索前校验失败只阻塞对应平台，不阻塞其余平台。
4. 抓取前校验失败不回退用户已完成的候选确认结果。

### 5.4.1 当前阶段可行性摘要

本节与 `docs/CrawlerFeasibility.md` 保持一致，用于把爬虫难点直接收敛进功能定义。

| 平台 | 暂定 `search_requirement` | 功能侧结论 |
| --- | --- | --- |
| 天猫 | `recommended` | 当前 MVP 平台；搜索和评论都应按“服务端会话驱动请求回放 + Hydration”预期设计 |
| 京东 | `required` | 当前 MVP 平台；搜索前必须做登录预检查，详情和评论优先走接口层 |
| 淘宝 | `recommended` | 下一优先平台；后续预期复用天猫适配栈 |
| 抖音电商 | `required` | 当前阶段延后实现；不进入当前验收与排期 |

关键规则：

1. 当前阶段不把官方开放平台当作本项目的直接数据源承诺。
2. 功能验收时要分别看搜索、详情、评论三项能力，不能只看“该平台是否有结果”。
3. 当前阶段的浏览器能力只用于登录、模板刷新和阻塞恢复，不承接常规抓取吞吐。

### 5.5 商品信息抓取

系统需对已确认链接抓取商品页可见信息，并保留原始字段。

MVP 优先抓取字段：

1. 商品标题、品牌、型号或系列
2. 当前价格、促销信息
3. 规格参数、SKU 选项
4. 商品详情文案与主卖点
5. 店铺名称、店铺类型、店铺评分
6. 商品评分、评论总量、销量或热度
7. 商品链接、平台名称、抓取时间

### 5.6 评论抓取与抽样

评论抓取目标是支撑分析，而不是全量抓取。

抽样规则：

1. 每个已确认链接独立抽样。
2. 优先从最新评论、最热评论、低分或差评评论三个桶取样。
3. 默认比例为 `40% / 30% / 30%`。
4. 若平台不支持某一抽样桶，则按剩余桶重新分配比例。
5. 若评论总量不足 `N`，抓取实际可得评论并标记样本不足。

评论至少保留：

1. 评论内容
2. 评论时间
3. 评论评分或情感标识
4. 点赞数或互动数
5. 规格或 SKU 信息
6. 评论来源标识
7. 对应商品链接
8. 抓取平台

去重规则：

1. 优先使用平台评论 ID 去重。
2. 无评论 ID 时，使用来源链接、评论时间和归一化评论文本组合去重。

### 5.7 数据标准化

系统需输出商品标准表和评论标准表，并保留原始字段。

核心标准字段包括：

1. `platform`
2. `source_url`
3. `price`
4. `product_rating`
5. `sales_volume`
6. `review_time`
7. `crawl_time`
8. `sampling_bucket`

关键规则：

1. 价格统一为人民币数值，原始价格文案单独保留。
2. 评分统一映射到 5 分制，无法映射时允许为空。
3. 时间统一使用 `Asia/Shanghai` 时区。
4. 所有无法标准化的原始字段不得丢弃。

### 5.8 多链接聚合

MVP 采用三级聚合逻辑：

1. 链接级：每个确认链接是最小分析单元，独立抓取、独立保留。
2. 平台级：同一平台下多个链接汇总，产出平台内价格区间、卖点共性、差评共性和店铺差异。
3. 跨平台级：以平台级结果作为主比较对象，同时保留链接级证据下钻能力。

关键规则：

1. 不把同一平台多个已确认链接强行合并成单一商品。
2. 报告中允许同时存在平台汇总结论和具体链接差异。
3. 跨平台对比默认展示平台聚合结果，避免报告被链接明细淹没。

### 5.9 AI 分析与结构化报告

AI 分析输出必须是结构化报告，而不是自由文本。

报告需包含以下核心部分：

1. 执行摘要
2. 商品快照
3. 平台洞察
4. 跨平台对比洞察
5. 运营或竞品建议
6. 证据索引
7. 质量标记

关键规则：

1. 每条强结论都必须可回溯到证据索引。
2. 若证据不足，不输出强结论，而是标记样本不足。
3. 报告中必须保留被纳入任务但未成功完成的平台状态。
4. 报告优先服务决策，不追求长篇自由描述。

### 5.10 历史任务、重试与版本

系统需支持：

1. 查看历史任务列表。
2. 回看任务输入、确认链接、执行状态和最终报告。
3. 在同一任务下切换不同报告版本。
4. 对失败或阻塞平台发起定向重试。

版本规则：

1. 同一 `task_id` 下首次成功产出报告记为 `report_version = 1`。
2. 重试仅针对 `SearchBlocked`、`Blocked`、`Failed` 平台。
3. 已完成平台默认复用上一次成功结果，不重复抓取。
4. 若重试导致平台状态或报告内容变化，生成新的报告版本。
5. 若重试未改变结果，仅追加执行日志，不生成新快照。
6. `default_report_version` 在 P0 恒等于 `latest_successful_report_version`，不支持人工改设默认版本。

## 6. 状态模型

### 6.1 状态口径

系统必须同时维护三层状态：

1. `task_status`：任务总体状态
2. `task_stage`：任务执行阶段
3. `platform_status`：单平台状态

### 6.2 `task_status`

| 状态 | 含义 |
| --- | --- |
| `Draft` | 任务已创建，尚未开始执行 |
| `Searching` | 正在做预检查或候选搜索 |
| `AwaitingConfirmation` | 等待用户确认候选商品 |
| `NoSelection` | 用户未确认任何链接，任务在确认阶段结束 |
| `Running` | 已进入抓取、标准化或分析阶段 |
| `Completed` | 所有已确认且可执行的平台均成功完成 |
| `PartialCompleted` | 已生成报告，但部分已确认平台失败或阻塞 |
| `Blocked` | 无成功平台，且剩余平台均因人工处理问题阻塞 |
| `Failed` | 无成功平台，且不存在可恢复执行对象 |

### 6.3 `task_stage`

| 阶段 | 说明 |
| --- | --- |
| `precheck` | 搜索前预检查 |
| `search` | 平台搜索候选 |
| `confirmation` | 用户确认链接 |
| `session_check` | 抓取前会话校验 |
| `crawl` | 商品与评论抓取 |
| `normalize` | 数据标准化 |
| `analyze` | AI 分析 |
| `publish` | 报告发布与版本写入 |

### 6.4 `platform_status`

| 状态 | 含义 |
| --- | --- |
| `Pending` | 未开始处理 |
| `SearchBlocked` | 搜索前已知受登录限制阻塞 |
| `Searching` | 搜索候选中 |
| `NoResult` | 搜索成功但无候选 |
| `AwaitingSelection` | 等待用户选择 |
| `Skipped` | 用户跳过平台 |
| `Selected` | 用户已确认链接，等待抓取前校验 |
| `Blocked` | 抓取前或抓取中遇到登录、验证码、风控问题 |
| `Running` | 抓取或平台级清洗中 |
| `Completed` | 平台结果已纳入报告 |
| `Failed` | 平台出现不可恢复执行失败 |

### 6.5 状态汇总规则

1. 单个平台进入 `SearchBlocked`、`Blocked` 或 `Failed`，不会自动把整任务置为失败。
2. `NoResult` 和 `Skipped` 不计入任务失败，但也不计入成功完成平台。
3. 若用户最终未确认任何链接，任务直接进入 `NoSelection`，不生成报告但保留历史记录。
4. 除 `NoSelection` 外，任务最终状态只基于已确认平台计算。
5. 只要至少一个已确认平台仍可继续，任务保持进行中或部分完成，而不是整体失败。

## 7. 报告输出结构

### 7.1 顶层结构

报告顶层至少包括以下字段：

| 字段 | 说明 |
| --- | --- |
| `report_id` | 报告唯一 ID |
| `report_version` | 报告版本号 |
| `task_id` | 所属任务 ID |
| `generated_at` | 报告生成时间 |
| `task_status` | 仅允许 `Completed` 或 `PartialCompleted` |
| `summary` | 执行摘要与限制 |
| `product_snapshot` | 分析对象快照 |
| `platform_insights` | 各平台结构化洞察 |
| `cross_platform_insights` | 跨平台对比洞察 |
| `recommendations` | 运营或竞品建议 |
| `evidence_index` | 证据索引 |
| `quality_flags` | 样本不足、部分失败等质量标记 |

### 7.2 报告内容要求

1. `summary` 需包含一句话摘要、关键结论和限制说明。
2. `platform_insights` 必须覆盖所有纳入任务的平台，即使该平台未成功完成。
3. 洞察卡片需包含标题、结论说明、置信度、样本标记、来源范围和证据引用。
4. `evidence_index` 至少包含平台、来源类型、原始链接、评论引用标识和抓取时间。
5. `quality_flags` 至少标记样本不足、部分平台失败和阻塞平台列表。
6. 报告页使用发布后的 `execution_status`，其值由运行态 `platform_status` 在发布阶段映射得到，不直接复用执行中状态枚举。

## 8. 数据、安全与合规边界

### 8.1 账号与会话

1. 不保存用户账号密码。
2. 仅复用当前工作区服务端会话中心中的用户会话态。
3. 会话缓存需支持加密存储和手动清除。

### 8.2 数据留存

1. 原始抓取数据默认保存 30 天。
2. 标准化数据、报告快照和证据索引默认保存 90 天。
3. 即使原始 DOM/HAR 等大对象在 30 天后清理，报告依赖的证据摘录与来源元数据仍保留到 90 天。
4. 用户可主动删除历史任务及相关数据。

### 8.3 合规边界

1. 仅抓取用户有权访问且页面可见的数据。
2. 不承诺绕过平台安全机制。
3. 平台规则变化导致能力不可用时，系统需明确提示，而非静默失败。

## 9. 版本优先级

### 9.1 P0

1. 新建任务页
2. 天猫、京东站内搜索
3. 候选结果展示
4. 商品链接人工确认
5. 登录态校验与人工阻塞处理
6. 商品信息抓取
7. 评论分层抽样抓取
8. 数据标准化
9. 多链接三级聚合
10. 结构化 AI 报告
11. 历史任务回看

### 9.2 P1

1. 更丰富的证据展示
2. Markdown/PDF 导出
3. 多租户与团队协作
4. 更细粒度的运营建议
5. 更强的失败重试与任务编排
6. 更多平台接入

## 10. 关键验收与质量指标

MVP 以“稳定产出可用报告”为验收目标，核心指标如下：

1. 任务完成率：进入 `Completed` 或 `PartialCompleted` 的任务占比不低于 `75%`。
2. 候选可用率：至少 2 个平台返回可确认候选或明确返回无结果的占比不低于 `85%`。
3. 候选确认准确率：人工抽检中，被确认链接确属目标分析对象的占比不低于 `90%`。
4. 任务时长：默认配置下，从任务发起到报告完成的 P50 时长不高于 `20` 分钟。
5. 报告可追溯率：关键结论带证据引用或明确标记样本不足的比例为 `100%`。
6. 证据引用有效率：可根据平台、链接、评论 ID 或索引与抓取时间定位到原证据的比例不低于 `95%`。
7. 用户可用性评分：试运行用户对报告“可用于决策”的评分不低于 `4/5`。
8. 报告采纳率：试运行用户认为无需重新整理即可进入后续分析或讨论的比例不低于 `70%`。

补充规则：

1. `PartialCompleted` 仅在已产出可阅读报告时计入完成率。
2. 若系统未产出报告，即使部分步骤成功，也不计入任务完成率。
3. `NoSelection` 不计入任务完成率，也不计入失败率。
4. 质量类指标以人工抽检和试运行记录为准，不依赖系统自报。

## 11. 一句话总结

本产品的本质不是跨平台抓取工具，而是一个围绕“商品分析任务”构建的产品化工作流：把搜索、确认、抓取、标准化、聚合和 AI 分析收敛为可追溯、可复用、可用于决策的结构化报告能力。