# VOC 阶段报告数据规范 v2

> 本文档定义 OpenClaw VOC 工作坊每个阶段输出数据的**字段级规范**。
> Agent 在填充 stage-N-output.json 时必须严格遵循此规范，确保报告达到"好用"级别。
> 设计参考：msq-voc-web 前端 VOC 深度洞察系统。

---

## Stage 3：评论 VOC 深度分析（核心阶段）

### 3.1 voiceClassification — 用户声音分类

**目标**：将全量评论按情感极性分为正向/中性/负向三类，量化情感健康度。

#### summary 字段

| 字段 | 类型 | 说明 | 计算方式 |
|------|------|------|---------|
| totalReviews | number | 有效分析评论总数 | 去重后的评论条数 |
| positiveRate | number | 正向评论占比(%) | 4-5星评论百分比 |
| neutralRate | number | 中性评论占比(%) | 3星评论百分比 |
| negativeRate | number | 负向评论占比(%) | 1-2星评论百分比 |
| overallSentimentScore | number | 情感健康分(0-100) | positiveRate×1.0 + neutralRate×0.5 |

#### positive/neutral/negative 每个极性包含

| 字段 | 类型 | 说明 |
|------|------|------|
| items[] | array | 声音条目列表，按 reviewCount 降序 |
| items[].text | string | 声音摘要（如"面料柔软透气"） |
| items[].reviewCount | number | 提及该声音的评论数 |
| items[].keywords | string[] | 关联关键词（3-5个） |
| items[].representativeQuote | string | 代表性原文引用（≤120字） |
| totalCount | number | 该极性评论总数 |
| topKeywords | string[] | 高频关键词Top 10 |

**positive** 额外字段：`avgRating`（正向评论均分）
**neutral** 额外字段：`suggestions[]`（用户改进建议提取）
**negative** 额外字段：`returnRateImpact`（差评导致的退货影响率%）

#### categoryBreakdown — 问题维度细分

每条记录对应一个问题维度：

| 字段 | 类型 | 说明 | 枚举值 |
|------|------|------|--------|
| category | string | 维度类型 | function/quality/description/service/logistics |
| label | string | 中文标签 | 功能相关/质量相关/描述相关/服务相关/物流相关 |
| count | number | 该维度评论数 | |
| percentage | number | 占比(%) | |
| sentimentDist | object | 情感分布 | { positive: %, neutral: %, negative: % } |
| topKeywords | string[] | 维度高频词 | |
| sampleReviews[] | array | 代表评论 | [{ star, content, date }] |

---

### 3.2 painPointInsight — 痛点深度洞察

**目标**：区分显性投诉与隐性不满，通过权重矩阵锁定优先改进方向。

#### summary 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| totalPainPoints | number | 已识别痛点总数 |
| criticalCount | number | 严重/危机级痛点数 |
| highCount | number | 高优先级痛点数 |
| topUnsolvedByCompetitors | number | 竞品也未解决的痛点数（差异化机会） |
| avgWeightScore | number | 综合权重均值(0-100) |

#### explicit[] — 显性痛点（用户直接表达的不满）

| 字段 | 类型 | 说明 |
|------|------|------|
| name | string | 痛点名称（如"起球严重"） |
| description | string | 痛点描述（1-2句话） |
| severity | enum | low/medium/high/critical |
| frequency | number | 提及频次 |
| affectedUserRate | number | 影响用户比例(%) |
| weight | number | 综合权重(0-100) = 频次×严重度×退货影响×评分影响 |
| category | string | 所属类别（质量/功能/设计/物流） |
| keywords | string[] | 关联关键词 |
| suggestedFix | string | 建议修复方案 |
| competitorStatus | string | 竞品对此痛点的解决情况 |

#### implicit[] — 隐性痛点（通过语言模式推断的不满）

同 explicit[] 字段 + 额外 `representativeReview`（信号原文）

#### weightAnalysis[] — 痛点权重排行表

| 字段 | 类型 | 说明 |
|------|------|------|
| name | string | 痛点名 |
| type | enum | explicit/implicit |
| severity | enum | low/medium/high/critical |
| weight | number | 综合权重 |
| frequency | number | 频次得分 |
| returnImpact | number | 退货影响得分 |
| ratingImpact | number | 评分影响得分 |
| intensity | number | 痛点强度得分 |

#### correlations[] — 痛点关联分析

```json
{ "painA": "起球", "painB": "面料薄", "coCount": 47, "correlation": 0.82 }
```

#### scenarioMaps[] — 痛点×场景映射

```json
{ "painName": "不透气", "scenarios": [{ "name": "运动健身", "count": 89 }, { "name": "夏季穿着", "count": 52 }] }
```

---

### 3.3 featureSatisfaction — 功能满足度看板

**目标**：量化每个核心功能的用户满意度，识别功能缺口和功能对立。

#### summary 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| totalFeatures | number | 分析功能维度数 |
| avgSatisfactionRate | number | 平均满足率(%) |
| highSatisfactionCount | number | 高满足(≥80%)功能数 |
| criticalGapCount | number | 关键缺口数 |
| conflictCount | number | 功能对立数 |

#### corePerformance[] — 核心功能表现

| 字段 | 类型 | 说明 |
|------|------|------|
| feature | string | 功能名称（如"透气性"） |
| category | string | 功能类别 |
| satisfactionRate | number | 满足率(0-100%) |
| importanceScore | number | 重要度(0-100) |
| mentionCount | number | 提及次数 |
| positiveRate | number | 正面提及率 |
| negativeRate | number | 负面提及率 |
| trend | enum | improving/stable/declining |
| gap | number | 缺口值(重要度-满足率) |

#### quadrantGroups — 四象限分类

- **coreAdvantage**：高重要度 + 高满足度 → 核心优势，继续保持
- **criticalGap**：高重要度 + 低满足度 → 关键缺口，优先改进
- **niceToHave**：低重要度 + 高满足度 → 锦上添花
- **lowPriority**：低重要度 + 低满足度 → 低优先级

#### gaps[] — 功能缺口

| 字段 | 类型 | 说明 |
|------|------|------|
| name | string | 缺口名称 |
| description | string | 描述 |
| demandFrequency | number | 需求提及频次 |
| currentSatisfaction | number | 当前满足率(%) |
| opportunityScore | number | 机会值(0-100) |
| targetFeature | string | 建议目标特性 |
| relatedPainPoints | string[] | 关联痛点 |
| implementationDifficulty | enum | low/medium/high |

#### conflicts[] — 功能对立

```json
{
  "featureA": "紧身修身",
  "featureB": "宽松舒适",
  "conflictType": "用户群体需求互斥",
  "userGroupA": "年轻时尚用户",
  "userGroupB": "注重舒适的中年用户",
  "impactLevel": "high",
  "resolutionSuggestion": "通过SKU差异化满足两类需求"
}
```

---

### 3.4 scenarioDashboard — 使用场景看板

**目标**：识别高频场景、失败场景、新兴场景，输出可落地行动建议。

#### summary 字段

| 字段 | 类型 | 说明 |
|------|------|------|
| totalScenarios | number | 识别场景总数 |
| topScenarioUserRate | number | 头部场景用户占比(%) |
| criticalFailureCount | number | 严重失败场景数 |
| emergingOpportunities | number | 新兴机会场景数 |
| coverageRate | number | 场景覆盖率(%) |

#### highFrequency[] — 高频使用场景

| 字段 | 类型 | 说明 |
|------|------|------|
| name | string | 场景名称（如"日常通勤穿着"） |
| description | string | 场景描述 |
| userRate | number | 用户占比(%) |
| frequency | enum | daily/weekly/monthly/occasional |
| topFeatures | string[] | 场景关联功能 |
| painPoints | string[] | 场景关联痛点 |
| satisfactionRate | number | 场景满足度(%) |
| representativeQuote | string | 代表性用户评论 |

#### failure[] — 失败场景

| 字段 | 类型 | 说明 |
|------|------|------|
| name | string | 失败场景名称 |
| description | string | 失败描述 |
| triggerCondition | string | 触发条件 |
| frequency | number | 发生频次 |
| affectedUserRate | number | 影响用户比例(%) |
| primaryFeature | string | 主要关联功能 |
| userReaction | string | 用户反应描述 |
| returnCorrelation | number | 退货相关性(0-1) |
| fixSuggestion | string | 修复建议 |

#### emerging[] — 新兴场景

| 字段 | 类型 | 说明 |
|------|------|------|
| name | string | 场景名称 |
| description | string | 场景描述 |
| growthRate | number | 增长率(%) |
| currentUserRate | number | 当前用户占比(%) |
| projectedGrowth | number | 预测未来占比(%) |
| requiredFeatures | string[] | 需要的功能 |
| opportunity | string | 机会描述 |
| entryDifficulty | enum | low/medium/high |

---

### 3.5 brandVsCompetitor — 品牌vs竞品对比

| 字段 | 说明 |
|------|------|
| brandSentimentScore | 品牌情感健康分 |
| competitorAvgSentimentScore | 竞品平均情感健康分 |
| brandNegativeRate | 品牌差评率 |
| competitorAvgNegativeRate | 竞品平均差评率 |
| brandTopPainPoints | 品牌Top痛点 |
| competitorTopPainPoints | 竞品共性痛点 |
| differentiators | 品牌差异化优势 |

---

## Stage 1：品类全景分析

### healthScore — 品类健康度评分

| 维度 | 说明 | 评分逻辑 |
|------|------|---------|
| overall | 综合得分(0-100) | 各维度加权平均 |
| marketAttractiveness | 市场吸引力 | 规模×增速 |
| competitiveIntensity | 竞争烈度 | CR5/HHI反向 |
| growthPotential | 增长潜力 | 搜索趋势+新品率 |
| entryDifficulty | 进入难度 | 评论门槛+品牌集中度 |

### competitiveLandscape — 竞争格局增强字段

| 字段 | 说明 |
|------|------|
| entryBarrier | 进入壁垒(low/medium/high) |
| marketMaturity | 市场成熟度(emerging/growing/mature/declining) |
| fbaAdoptionRate | FBA使用率(%) |
| videoAdoptionRate | 视频listing占比(%) |
| aPlusAdoptionRate | A+页面占比(%) |

---

## Stage 2：品牌+竞品分析

### brandProfile.dimensions — 六维画像

每个维度包含 `{ score: 0-100, rank: "Top X%", detail: "说明" }`

| 维度 | 说明 |
|------|------|
| pricing | 定价竞争力 |
| rating | 评分口碑 |
| traffic | 流量排名 |
| sales | 销售表现 |
| growth | 增长势头 |
| reputation | 品牌声誉 |

### competitorComparison.vulnerabilities — 竞品漏洞

```json
{
  "competitorName": "竞品A",
  "vulnerability": "差评集中在包装问题",
  "exploitStrategy": "强化包装体验作为卖点",
  "expectedImpact": "可抢占约15%的不满用户"
}
```

---

## Stage 4：用户画像

### userPersona.personas[] — 画像结构

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | 画像唯一ID |
| label | string | 画像标签（如"品质生活追求者"） |
| demographics | object | { ageRange, gender, income, location } |
| psychographics | object | { values, lifestyle, personality } |
| shoppingBehavior | object | { priceRange, decisionFactors, purchaseFrequency, channels } |
| needs | string[] | 核心需求列表 |
| painPoints | string[] | 核心痛点 |
| scenarios | string[] | 主要使用场景 |
| triggerKeywords | string[] | 搜索/决策触发词 |
| estimatedMarketShare | number | 预估市场占比(%) |
| acquisitionStrategy | string | 获客建议 |

---

## Stage 5：最终报告

### actionableInsights.topActions[] — 优先行动项

| 字段 | 类型 | 说明 |
|------|------|------|
| scenario | string | 关联场景 |
| feature | string | 关联功能 |
| gap | string | 缺口描述 |
| suggestion | string | 行动建议 |
| priority | enum | P0(立即)/P1(本月)/P2(本季) |
| expectedImpact | string | 预期影响（量化） |
| investmentLevel | enum | zero/low/medium/high |
| timeToResult | string | 见效周期 |

### overallHealthScore.dimensions — 五维综合评分

| 维度 | 说明 | 数据来源 |
|------|------|---------|
| marketPosition | 市场定位得分 | stage-1 |
| productQuality | 产品质量得分 | stage-3 featureSatisfaction |
| customerSatisfaction | 客户满意度 | stage-3 voiceClassification |
| competitiveAdvantage | 竞争优势 | stage-2 + stage-3 brandVsCompetitor |
| growthPotential | 增长潜力 | stage-1 + stage-4 |

---

## 报告输出质量标准

### 必须达到的"好用"级别要求

1. **数据精确性**：所有数字必须有明确来源（评论计数/API数据），不可凭空捏造
2. **量化指标**：每个分析维度必须包含量化指标（百分比、评分、频次），不接受纯文字描述
3. **行动导向**：每个痛点/缺口必须附带 `suggestedFix` 或 `suggestion`
4. **竞品参照**：关键指标必须有竞品对比基准（"我的品牌 vs 竞品平均"）
5. **优先级排序**：所有列表按权重/影响力降序排列，最重要的在最前面
6. **用户原声**：关键发现必须附带 `representativeQuote`（原文引用），增强可信度
7. **可视化友好**：数据结构支持直接映射为图表（柱状图/饼图/四象限/趋势线）
8. **校准闭环**：每个阶段输出后必须包含 calibrationTable，记录用户专业判断

### 报告章节对应关系

| 最终报告章节 | 数据来源 | 可视化形式 |
|-------------|---------|-----------|
| 品类全景 | stage-1 | 市场规模柱状图 + 品牌份额饼图 + 价格带分布 |
| 品牌六维画像 | stage-2.brandProfile | 雷达图 |
| 竞品对比矩阵 | stage-2.competitorComparison | 多维对比表 + 漏洞卡片 |
| 用户声音分类 | stage-3.voiceClassification | 情感分布条 + 三栏明细 |
| 痛点深度洞察 | stage-3.painPointInsight | 权重排行表 + 痛点卡片 |
| 功能满足度 | stage-3.featureSatisfaction | 四象限矩阵 + 缺口卡片 |
| 使用场景看板 | stage-3.scenarioDashboard | 场景卡片 + 满意度排行 |
| 用户画像 | stage-4.userPersona | 画像卡片（3-5个） |
| 行动计划 | stage-5.actionableInsights | P0/P1/P2优先级表 + 30天时间线 |
| ROI估算 | stage-5.proposal.roiEstimates | 投入产出对比表 |