# AI 巡检报告分析 - 设计文档

## 1. 背景

clinic_data_service 已有完整的巡检系统，可生成包含慢查询分析、指标健康检查、全表扫描检测等多维度的结构化 JSON 巡检报告。为了降低 DBA 人工分析报告的成本，新增 AI 分析功能，将巡检报告发送给大模型进行智能分析，输出专业的健康分析报告。

## 2. 架构设计

### 2.1 分层架构

```
┌──────────────────────────────────────────────────┐
│                   HTTP Layer                      │
│  AIHealthCheckHandler (healtheck_handler.go)      │
│  POST /clinic-internal/healthcheck/ai/analyze     │
└──────────────────┬───────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────┐
│                 Service Layer                     │
│  AIService (ai_service.go)                        │
│  - fetchReport(): 获取巡检报告                     │
│  - Analyze(): 编排 AI 分析流程                     │
│  - DefaultHealthCheckPrompt: 内置分析提示词         │
└──────┬──────────────────────────────┬────────────┘
       │                              │
┌──────▼──────────┐    ┌──────────────▼────────────┐
│  Report Fetcher  │    │      AI Client Layer       │
│  - 本地文件读取   │    │  pkg/thirdapi/ai/          │
│  - Clinic API    │    │  ┌─────────────────────┐   │
│    GET /result   │    │  │   AIClient 接口      │   │
└─────────────────┘    │  └──────┬──────────────┘   │
                       │         │                   │
                       │  ┌──────▼──────┐  ┌────────▼────────┐
                       │  │OpenAIClient │  │BedrockClaudeClient│
                       │  │ (HTTP API)  │  │ (AWS SDK v2)     │
                       │  └─────────────┘  └──────────────────┘
                       └────────────────────────────────────────┘
```

### 2.2 核心接口

```go
// pkg/thirdapi/ai/client.go
type AIClient interface {
    Chat(ctx context.Context, req *ChatRequest) (*ChatResponse, error)
    Name() string
}
```

通过统一接口，屏蔽不同 AI 提供商的调用差异。新增模型只需实现 `AIClient` 接口。

## 3. 文件清单

| 文件路径 | 类型 | 说明 |
|---------|------|------|
| `pkg/thirdapi/ai/client.go` | 新建 | AIClient 统一接口、ChatRequest/ChatResponse 定义 |
| `pkg/thirdapi/ai/openai_client.go` | 新建 | OpenAI 实现，纯 HTTP 调用，无第三方 SDK |
| `pkg/thirdapi/ai/bedrock_client.go` | 新建 | AWS Bedrock Claude 实现，使用 aws-sdk-go-v2 |
| `pkg/config/ai_config.go` | 新建 | AIConfig、OpenAIConfig、BedrockConfig 结构体 |
| `pkg/service/ai_service.go` | 新建 | AIService 服务层、请求/响应 DTO、默认 Prompt |
| `pkg/config/dataproxy_config.go` | 修改 | DataProxyConfig 新增 `AI AIConfig` 字段 |
| `pkg/handlers/healtheck_handler.go` | 修改 | 新增 AIHealthCheckHandler |
| `pkg/server/router.go` | 修改 | 注册 AI 分析路由 |
| `configs/config-dataproxy.yaml` | 修改 | 添加 `ai` 配置节 |

## 4. 数据流

```
1. 客户端 POST /clinic-internal/healthcheck/ai/analyze
   ├── orgId, clusterId, reportId, model, prompt
   │
2. AIHealthCheckHandler 参数校验
   │
3. AIService.Analyze()
   │
   ├── 3a. fetchReport()
   │   ├── 本地模式: 读取 output/healthcheck-report/healthcheck_resout.json
   │   └── 生产模式: GET {clinicAPIBase}/compute-engine/{orgId}/{clusterId}/healthcheck/result/{reportId}
   │                 Header: Authorization: Bearer {clinic_api_key}
   │
   ├── 3b. 选择 AI 客户端 (openai / claude)
   │
   ├── 3c. 组装请求
   │   ├── SystemPrompt: 用户自定义 prompt 或 DefaultHealthCheckPrompt
   │   ├── UserMessage: 巡检报告 JSON 全文
   │   ├── MaxTokens: 8192
   │   └── Temperature: 0.3
   │
   └── 3d. 调用 AI 模型
       ├── OpenAI: POST https://api.openai.com/v1/chat/completions
       └── Bedrock: InvokeModel API (aws-sdk-go-v2)
   │
4. 返回 AIAnalyzeResponse (analysis: Markdown, token 统计)
```

## 5. AI 客户端实现细节

### 5.1 OpenAI (openai_client.go)

- **调用方式**: 纯 `net/http`，不引入 openai SDK，保持轻量
- **API**: `POST {baseURL}/chat/completions`
- **认证**: `Authorization: Bearer {apiKey}`
- **参数**: 使用 `max_completion_tokens`（兼容 GPT-5.x 系列）
- **超时**: 300 秒
- **默认模型**: `gpt-5.4`

### 5.2 Bedrock Claude (bedrock_client.go)

- **调用方式**: `aws-sdk-go-v2/service/bedrockruntime.InvokeModel`
- **认证**: 静态凭证 (AccessKeyID + SecretAccessKey)
- **请求体**: Anthropic Messages API 格式 (`anthropic_version: bedrock-2023-05-31`)
- **模型 ID**: 使用 inference profile ARN 格式
- **默认模型**: `arn:aws:bedrock:us-east-1::inference-profile/global.anthropic.claude-opus-4-6-v1`

### 5.3 扩展新模型

实现 `AIClient` 接口即可：

```go
type MyNewClient struct { ... }
func (c *MyNewClient) Chat(ctx context.Context, req *ChatRequest) (*ChatResponse, error) { ... }
func (c *MyNewClient) Name() string { return "my-model" }
```

然后在 `AIService.NewAIService()` 中注册到 `clients` map。

## 6. 配置结构

```go
type AIConfig struct {
    ClinicApiKey string        // clinic API Bearer token
    OpenAI            OpenAIConfig  // OpenAI 配置
    Bedrock           BedrockConfig // AWS Bedrock 配置
}

type OpenAIConfig struct {
    APIKey  string // API Key
    BaseURL string // 可选，支持代理端点
    Model   string // 模型名称
}

type BedrockConfig struct {
    Region         string // AWS Region
    AccessKeyID    string // AWS Access Key
    SecretAccessKey string // AWS Secret Key
    Model          string // Inference Profile ARN
}
```

配置文件支持环境变量替换（`${ENV_VAR}`），通过 `LoadDataProxyConfig` 中的 `os.ExpandEnv` 实现。

## 7. 默认 Prompt 设计

内置的 `DefaultHealthCheckPrompt` 指导 AI 按以下维度分析：

1. **总体概览** - 健康状态和风险等级
2. **慢查询分析** - Top SQL 识别、模式分析、优化建议
3. **集群指标分析** - 关注 "Need Attention" 指标、趋势判断
4. **全表扫描分析** - 影响范围、索引建议
5. **综合建议** - P0/P1/P2 优先级行动项

Prompt 中包含单位说明（KB、秒）和阈值含义（偏差百分比），确保 AI 正确理解数据。

## 8. 依赖

新增依赖：
- `github.com/aws/aws-sdk-go-v2/service/bedrockruntime` — Bedrock InvokeModel API

复用已有依赖：
- `github.com/aws/aws-sdk-go-v2/config` — AWS 配置加载
- `github.com/aws/aws-sdk-go-v2/credentials` — 静态凭证
- `github.com/gin-gonic/gin` — HTTP 框架
- `go.uber.org/zap` — 日志

## 9. 测试结果

| 模型 | 实际标识 | 输入 Tokens | 输出 Tokens | 耗时 | 状态 |
|------|---------|------------|------------|------|------|
| claude | claude-opus-4-6 | 10,794 | 5,144 | ~60s | 通过 |
| openai | gpt-5.4-2026-03-05 | 9,132 | 4,928 | ~45s | 通过 |

两个模型均能正确读取本地巡检报告、生成完整的 Markdown 分析报告，包含慢查询分析、指标分析、全表扫描分析和分优先级的行动建议。