# AI 巡检报告分析 - 使用手册

## 接口说明

使用 AI 大模型对 TiDB 集群巡检报告进行智能分析，输出专业的健康分析报告（Markdown 格式）。

**路由**: `POST /clinic-internal/healthcheck/ai/analyze`

## 请求参数

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| orgId | string | 是 | 组织 ID |
| clusterId | string | 是 | 集群 ID |
| reportId | string | 是 | 巡检报告 ID（strategyUuid） |
| model | string | 是 | AI 模型：`"openai"` 或 `"claude"` |
| prompt | string | 否 | 自定义分析提示词，为空时使用内置默认 Prompt |

### 请求示例

```bash
curl -X POST http://localhost:8087/clinic-internal/healthcheck/ai/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "1372813089209213994",
    "clusterId": "1379661944646413035",
    "reportId": "816d3192-c09b-4f30-82a6-346fcf43e1d1",
    "model": "claude"
  }'
```

### 使用自定义 Prompt

```bash
  curl -X POST http://localhost:8087/clinic-internal/healthcheck/ai/analyze \
    -H "Content-Type: application/json" \
    -d '{
      "orgId": "1372813089209213994",
      "clusterId": "1379661944646413035",
      "reportId": "816d3192-c09b-4f30-82a6-346fcf43e1d1",
      "model": "claude",
      "prompt": "你是一位资深 TiDB DBA。请对以下巡检报告 JSON 生成一份简洁的健康摘要，严格控制在 500 字以内。\n\n要求：\n1. 用一句话给出整体结论和风险等级（🟢健康 / 🟡需关注 / 🔴高风险）\n2.
   列出 Top 3 关键风险点，每个风险用一行描述：问题 + 影响 + 建议动作\n3. 关键指标速览：仅列出异常或需关注的指标，正常指标不要列出\n4. 最多给出 3 条优先行动项，按 P0 > P1 > P2
  排列\n\n输出格式：纯文本，不要使用表格，不要展开细节分析。像写给领导的汇报邮件一样简洁。"
    }'
```

## 响应格式

### 成功响应 (200)

```json
{
  "orgId": "1372813089209213994",
  "clusterId": "1379661944646413035",
  "reportId": "816d3192-c09b-4f30-82a6-346fcf43e1d1",
  "model": "claude-opus-4-6",
  "analysis": "# TiDB 集群健康分析报告\n\n## 1. 总体概览\n...",
  "inputTokens": 10794,
  "outputTokens": 5144
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| orgId | string | 组织 ID |
| clusterId | string | 集群 ID |
| reportId | string | 报告 ID |
| model | string | 实际使用的模型标识 |
| analysis | string | AI 分析结果（Markdown 格式） |
| inputTokens | int | 输入 token 数 |
| outputTokens | int | 输出 token 数 |

### 错误响应 (400/500)

```json
{
  "error": "unsupported model: xxx, available: [openai claude]"
}
```

## 支持的模型

| model 参数 | 实际模型 | 提供商 |
|-----------|---------|--------|
| `openai` | GPT-5.4 (gpt-5.4) | OpenAI |
| `claude` | Claude Opus 4.6 (claude-opus-4-6) | AWS Bedrock |

模型可在 `configs/config-dataproxy.yaml` 的 `ai` 配置节中修改。

## 配置说明

在 `configs/config-dataproxy.yaml` 中配置：

```yaml
ai:
  # 调用 clinic API 获取巡检报告的 Bearer token
  clinic_api_key: "your-token-here"

  openai:
    api_key: "sk-proj-xxx"        # OpenAI API Key
    # base_url: "https://api.openai.com/v1"  # 可选，支持代理
    model: "gpt-5.4"              # 模型名称

  bedrock:
    region: "us-east-1"           # AWS Bedrock Region
    access_key_id: "AKIA..."      # AWS Access Key ID
    secret_access_key: "xxx"      # AWS Secret Access Key
    model: "arn:aws:bedrock:us-east-1::inference-profile/global.anthropic.claude-opus-4-6-v1"
```

**安全建议**: 生产环境中，API Key 和 Access Key 应通过环境变量注入：

```yaml
ai:
  openai:
    api_key: ${AI_OPENAI_API_KEY}
  bedrock:
    access_key_id: ${AI_BEDROCK_ACCESS_KEY_ID}
    secret_access_key: ${AI_BEDROCK_SECRET_ACCESS_KEY}
```

## 巡检报告数据来源

- **生产环境**: 通过 clinic API 获取巡检报告
  ```
  GET {clinic_api_base}/compute-engine/{orgId}/{clusterId}/healthcheck/result/{reportId}
  ```
- **本地开发** (`env: "local"`): 读取本地文件 `output/healthcheck-report/healthcheck_resout.json`

## 注意事项

1. AI 分析调用耗时较长（通常 30-120 秒），HTTP 客户端超时设置为 300 秒
2. 巡检报告 JSON 会完整发送给 AI 模型，请注意 token 消耗
3. 默认 Prompt 会指导 AI 按以下维度分析：慢查询、集群指标、全表扫描、综合建议
4. 返回的 `analysis` 字段为 Markdown 格式，前端可直接渲染