# 诊断模块

## 概述

诊断模块是GEO平台的核心功能，提供**传统SEO诊断**和**GEO诊断**两种能力，帮助用户全面了解网站和品牌在AI时代的搜索可见性。

## SEO诊断 vs GEO诊断

### 核心区别

| 维度 | SEO诊断 | GEO诊断 |
|------|---------|---------|
| **优化目标** | 网页排名 | 品牌被AI引用 |
| **诊断对象** | 网站 | 品牌实体+内容 |
| **成功指标** | 排名、流量、点击率 | 引用频率、AI声量占比 |
| **用户路径** | 点击链接访问网站 | AI直接推荐品牌 |
| **见效周期** | 3-6个月 | 2周-1个月 |

---

## SEO诊断

传统SEO诊断评估网站对搜索引擎的优化程度，包含以下维度：

### 1. 技术SEO诊断

| 诊断项 | 说明 | 工具/方法 |
|--------|------|----------|
| 索引状态 | 网站是否被搜索引擎正确索引 | site:domain.com、Search Console |
| 爬取错误 | 404、5xx、重定向链 | 爬虫工具 |
| Core Web Vitals | LCP<2.5s、FID<100ms、CLS<0.1 | PageSpeed Insights |
| URL结构 | 规范化、重复URL | 爬虫分析 |
| robots.txt | 是否阻止重要页面 | 文件检查 |
| sitemap | 站点地图完整性 | XML验证 |

### 2. 页面SEO诊断

| 诊断项 | 说明 |
|--------|------|
| Title/Meta标签 | 是否完整、是否关键词堆砌 |
| H标签结构 | 层级是否清晰 |
| 关键词密度 | 是否合理分布 |
| 内链结构 | 是否有死链、锚文本是否相关 |
| 图片Alt | 是否添加描述性Alt文本 |

### 3. 内容质量诊断

| 诊断项 | 说明 |
|--------|------|
| 可读性 | 内容是否易于理解 |
| 信息深度 | 是否全面覆盖主题 |
| E-E-A-T | 经验、专业性、权威性、可信度 |
| 内容新鲜度 | 是否定期更新 |
| 重复内容 | 是否有大量重复页面 |

### 4. 外链分析

| 诊断项 | 说明 |
|--------|------|
| 反向链接质量 | 链接来源权威性 |
| 毒性信号 | 是否有垃圾链接 |
| 锚文本分布 | 是否自然多样 |

### 5. 用户体验诊断

| 诊断项 | 说明 |
|--------|------|
| 移动适配 | 移动端显示是否正常 |
| 页面速度 | 加载时间是否达标 |
| 转化路径 | 用户操作是否顺畅 |

---

## GEO诊断

GEO诊断评估品牌在AI生成式引擎中的被引用能力，包含以下维度：

### 1. 内容可提取性诊断

AI需要能够轻松提取和理解内容：

| 诊断项 | 说明 | 优先级 |
|--------|------|--------|
| 直接回答块 | 页面首段是否有简洁明确的答案 | P0 |
| 问答式标题 | H2/H3是否采用问题形式 | P0 |
| 列表和表格 | 是否使用结构化数据展示 | P0 |
| 内链到子意图页 | 是否链接到相关深度内容 | P1 |
| 内容新鲜度 | 是否有更新日期和作者信息 | P1 |

### 2. 实体清晰度诊断

AI需要能够理解品牌是什么：

| 诊断项 | 说明 | 验证标准 |
|--------|------|----------|
| 品牌定义 | 是否清晰说明品牌做什么 | AI理解准确率≥95% |
| 目标受众 | 是否明确服务谁 | 实体识别准确率≥90% |
| 差异化价值 | 为什么选择这个品牌 | 独特性评分≥80 |
| 行业分类 | 品牌属于什么行业 | 分类准确率≥95% |

### 3. E-E-A-T信号诊断

AI需要验证品牌的可信度：

| 诊断项 | 说明 | 验证标准 |
|--------|------|----------|
| 作者资质 | 内容作者是否有专业背景 | 作者简介完整度≥90% |
| 专业认证 | 是否有行业认证/奖项 | 认证展示率≥80% |
| 数据来源 | 是否引用可靠数据 | 引用权威源≥70% |
| 专家背书 | 是否有行业专家认可 | 背书数量≥3 |

### 4. Schema标记诊断

结构化数据帮助AI理解内容：

| Schema类型 | 适用场景 | 优先级 | 实施难度 |
|-----------|---------|--------|---------|
| Organization | 企业主页 | P0必须 | ⭐ 简单 |
| Product | 产品页 | P0必须 | ⭐⭐ 中等 |
| Article/BlogPosting | 博客文章 | P0必须 | ⭐ 简单 |
| FAQPage | 常见问题 | P1推荐 | ⭐ 简单 |
| HowTo | 操作指南 | P1推荐 | ⭐⭐ 中等 |
| BreadcrumbList | 导航结构 | P1推荐 | ⭐ 简单 |
| Review/Rating | 评价评分 | P2可选 | ⭐⭐ 中等 |

### 5. 主题权威诊断

AI需要验证品牌在特定领域的权威性：

| 诊断项 | 说明 | 验证标准 |
|--------|------|----------|
| 内容深度 | 是否全面覆盖主题 | 内容质量QScore≥4.6/5 |
| 话题覆盖度 | 是否覆盖相关子话题 | 话题覆盖率≥80% |
| 实体信号一致性 | 各页面实体信号是否一致 | 一致性评分≥85% |
| 内链网络 | 是否形成主题内容集群 | 集群完整度≥70% |

### 6. 引用就绪度诊断

评估品牌在AI回答中被引用的可能性：

| 诊断项 | 说明 | 验证标准 |
|--------|------|----------|
| 引用频率 | 品牌在AI回答中被提及的频率 | AOR（Answer Ownership Rate）≥50% |
| 引用质量 | 引用内容是否准确完整 | 引用准确率≥90% |
| AI声量占比 | 品牌在AI回答中的占比 | AI SOV≥30% |
| 竞品对比 | 与竞品在AI回答中的表现 | 差距≤10pp |

---

## 诊断流程

### SEO诊断流程

```
1. 网站爬取 → 2. 技术分析 → 3. 内容分析 → 4. 外链分析 → 5. 生成报告
```

### GEO诊断流程

```
1. 品牌信息输入 → 2. 内容可提取性检测 → 3. 实体清晰度检测 → 4. E-E-A-T信号检测
   → 5. Schema标记检测 → 6. 主题权威检测 → 7. AI平台引用检测 → 8. 生成诊断报告
```

---

## 诊断报告输出

### SEO诊断报告

包含以下内容：
- 技术SEO评分
- 页面SEO评分
- 内容质量评分
- 外链质量评分
- 用户体验评分
- 综合评分
- 优先修复建议

### GEO诊断报告

包含以下内容：
- 内容可提取性评分
- 实体清晰度评分
- E-E-A-T信号评分
- Schema标记完整性
- 主题权威评分
- AI平台引用率
- 综合评分
- 优先优化建议

---

## 技术实现

### API端点

| 端点 | 方法 | 描述 | 状态 |
|------|------|------|------|
| `GET /api/v1/diagnosis/seo/{brand_id}` | GET | 获取品牌的SEO诊断结果 | ✅ 已完成 |
| `GET /api/v1/diagnosis/geo/{brand_id}` | GET | 获取品牌的GEO诊断结果 | ✅ 已完成 |
| `GET /api/v1/diagnosis/combined/{brand_id}` | GET | 获取品牌的SEO+GEO综合诊断结果 | ✅ 已完成 |

### API响应示例

#### SEO诊断响应

```json
{
  "success": true,
  "data": {
    "brand_id": "brand_123",
    "diagnosis_type": "seo",
    "overall_score": 78,
    "dimensions": {
      "technical_seo": {
        "score": 85,
        "status": "good",
        "issues": []
      },
      "page_seo": {
        "score": 72,
        "status": "needs_improvement",
        "issues": [
          {
            "type": "missing_meta_description",
            "severity": "medium",
            "description": "部分页面缺少Meta描述",
            "affected_pages": 12
          }
        ]
      },
      "content_quality": {
        "score": 80,
        "status": "good",
        "issues": []
      },
      "backlinks": {
        "score": 65,
        "status": "needs_improvement",
        "issues": []
      },
      "user_experience": {
        "score": 88,
        "status": "excellent",
        "issues": []
      }
    },
    "recommendations": [
      {
        "priority": "high",
        "action": "补充缺失的Meta描述",
        "impact": "提升页面相关性评分"
      }
    ],
    "diagnosed_at": "2024-01-15T10:30:00Z"
  }
}
```

#### GEO诊断响应

```json
{
  "success": true,
  "data": {
    "brand_id": "brand_123",
    "diagnosis_type": "geo",
    "overall_score": 72,
    "dimensions": {
      "content_extractability": {
        "score": 75,
        "status": "good",
        "metrics": {
          "direct_answer_blocks": 85,
          "qa_headings": 70,
          "structured_data": 80
        }
      },
      "entity_clarity": {
        "score": 80,
        "status": "good",
        "metrics": {
          "brand_definition_accuracy": 95,
          "target_audience_clarity": 85,
          "differentiation_score": 75
        }
      },
      "eeat_signals": {
        "score": 68,
        "status": "needs_improvement",
        "metrics": {
          "author_credentials": 60,
          "certifications": 70,
          "data_sources": 75,
          "expert_endorsements": 50
        }
      },
      "schema_markup": {
        "score": 70,
        "status": "good",
        "coverage": {
          "organization": true,
          "product": true,
          "article": true,
          "faq": false,
          "howto": false
        }
      },
      "topic_authority": {
        "score": 74,
        "status": "good",
        "metrics": {
          "content_depth": 80,
          "topic_coverage": 72,
          "entity_consistency": 85,
          "internal_linking": 65
        }
      },
      "citation_readiness": {
        "score": 65,
        "status": "needs_improvement",
        "metrics": {
          "citation_frequency": 60,
          "citation_accuracy": 75,
          "ai_sov": 55,
          "competitor_gap": -8
        }
      }
    },
    "recommendations": [
      {
        "priority": "high",
        "action": "增强E-E-A-T信号",
        "impact": "提升AI对品牌可信度的评估"
      }
    ],
    "diagnosed_at": "2024-01-15T10:30:00Z"
  }
}
```

#### 综合诊断响应

```json
{
  "success": true,
  "data": {
    "brand_id": "brand_123",
    "diagnosis_type": "combined",
    "seo_score": 78,
    "geo_score": 72,
    "combined_score": 75,
    "seo_summary": {
      "strengths": ["技术SEO基础良好", "用户体验优秀"],
      "weaknesses": ["外链质量需提升", "部分页面Meta描述缺失"]
    },
    "geo_summary": {
      "strengths": ["实体清晰度高", "内容结构化良好"],
      "weaknesses": ["E-E-A-T信号不足", "AI引用率偏低"]
    },
    "priority_actions": [
      {
        "type": "seo",
        "action": "建设高质量外链",
        "expected_impact": "提升域名权威性"
      },
      {
        "type": "geo",
        "action": "添加专家背书和认证",
        "expected_impact": "提升AI引用率"
      }
    ],
    "diagnosed_at": "2024-01-15T10:30:00Z"
  }
}
```

### 后端实现

| 组件 | 文件 | 职责 |
|------|------|------|
| SEO诊断服务 | `backend/app/services/seo_diagnosis.py` | 执行SEO诊断分析 |
| GEO诊断服务 | `backend/app/services/geo_diagnosis.py` | 执行GEO诊断分析 |
| 引用检测Agent | `backend/app/agent_framework/agents/citation_detector.py` | 检测AI平台引用情况 |
| 诊断报告生成 | `backend/app/services/diagnosis_report.py` | 生成诊断报告 |
| 诊断路由 | `backend/app/api/routes/diagnosis.py` | API端点定义 |

### 前端实现

| 页面 | 路径 | 说明 | 状态 |
|------|------|------|------|
| SEO诊断 | `/dashboard/seo-diagnosis` | SEO诊断入口和报告展示 | ✅ 已完成 |
| GEO诊断 | `/dashboard/geo-diagnosis` | GEO诊断入口和报告展示 | ✅ 已完成 |
| 综合诊断 | `/dashboard/diagnosis` | SEO+GEO综合诊断报告 | ✅ 已完成 |

前端实现包括：
- 诊断任务触发和进度展示
- 多维度评分可视化（雷达图、进度条）
- 问题列表和修复建议
- 历史诊断记录对比
- 诊断报告导出功能

---

## 改进建议

### 当前问题

| 问题 | 说明 | 优先级 | 状态 |
|------|------|--------|------|
| 诊断定义不完整 | 仅实现引用检测，缺少完整GEO诊断 | P0 | ✅ 已解决 |
| SEO诊断缺失 | 未实现传统SEO诊断能力 | P1 | ✅ 已解决 |
| 前后端断裂 | 诊断页面是占位页面 | P0 | ✅ 已解决 |

### 改进计划

| 阶段 | 目标 | 时间 | 状态 |
|------|------|------|------|
| Phase 1 | 完善GEO诊断（补充6大维度） | 2周 | ✅ 已完成 |
| Phase 2 | 新增SEO诊断能力 | 2周 | ✅ 已完成 |
| Phase 3 | 整合SEO+GEO诊断报告 | 1周 | ✅ 已完成 |
| Phase 4 | 前端诊断页面实现 | 1周 | ✅ 已完成 |

### 后续优化

| 阶段 | 目标 | 预计时间 |
|------|------|----------|
| Phase 5 | 诊断报告导出（PDF/Excel） | 1周 |
| Phase 6 | 历史诊断趋势分析 | 2周 |
| Phase 7 | 竞品诊断对比功能 | 2周 |