# AI 审计 API 文档

## 概述

`system-audit` Edge Function 提供系统架构、代码结构、安全配置的完整文档输出，并支持调用外部 AI (GPT/Gemini) 进行自动化评估和审计。

## 端点

```
POST /functions/v1/system-audit
```

## 请求参数

| 参数 | 类型 | 必须 | 描述 |
|------|------|------|------|
| action | string | 是 | 操作类型: `export` \| `audit` |
| scope | string[] | 否 | 审计范围: `architecture`, `security`, `code`, `database`, `api` |
| model | string | 否 | AI模型: `gemini-3-flash-preview`(默认), `gemini-2.5-pro`, `gpt-5` |
| detailed | boolean | 否 | 是否返回详细报告 (默认: false) |

## 操作类型

### 1. 导出文档 (`action: "export"`)

返回完整的系统文档，不调用AI。

**请求示例**:
```json
{
  "action": "export"
}
```

**响应结构**:
```json
{
  "version": "2.0.0",
  "exportedAt": "2026-01-28T10:00:00Z",
  "documentation": {
    "overview": { ... },
    "architecture": { ... },
    "agents": { ... },
    "genui": { ... },
    "database": { ... },
    "api": { ... },
    "security": { ... }
  }
}
```

### 2. AI 审计 (`action: "audit"`)

调用 AI 对系统进行评估审计。

**请求示例**:
```json
{
  "action": "audit",
  "scope": ["architecture", "security"],
  "model": "gemini-3-flash-preview",
  "detailed": true
}
```

**响应结构**:
```json
{
  "auditId": "uuid",
  "model": "gemini-3-flash-preview",
  "completedAt": "2026-01-28T10:00:00Z",
  "summary": {
    "overallScore": 85,
    "categories": {
      "architecture": { "score": 90, "findings": 3 },
      "security": { "score": 80, "findings": 5 }
    }
  },
  "findings": [
    {
      "id": "F001",
      "category": "security",
      "severity": "medium",
      "title": "部分表缺少 RLS 策略",
      "description": "...",
      "recommendation": "...",
      "affectedResources": ["table_name"]
    }
  ],
  "recommendations": [ ... ],
  "rawAnalysis": "..." // AI 原始输出 (detailed=true时)
}
```

## 审计范围说明

| 范围 | 审计内容 |
|------|----------|
| architecture | 整体架构设计、模块划分、依赖关系 |
| security | RLS策略、认证授权、数据保护 |
| code | 代码结构、最佳实践、重复代码 |
| database | 表设计、索引、关系完整性 |
| api | Edge Functions设计、错误处理、性能 |

## 评分标准

| 分数范围 | 等级 | 说明 |
|----------|------|------|
| 90-100 | A | 优秀，符合最佳实践 |
| 80-89 | B | 良好，有小改进空间 |
| 70-79 | C | 合格，建议优化 |
| 60-69 | D | 需改进，存在明显问题 |
| <60 | F | 不合格，需重大改进 |

## 严重程度定义

| 级别 | 描述 |
|------|------|
| critical | 关键问题，必须立即修复 |
| high | 高优先级，应尽快处理 |
| medium | 中等优先级，计划修复 |
| low | 低优先级，可选优化 |
| info | 信息性建议 |

## 使用示例

### cURL 调用

```bash
# 导出文档
curl -X POST \
  'https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/system-audit' \
  -H 'Content-Type: application/json' \
  -d '{"action": "export"}'

# AI 审计
curl -X POST \
  'https://tlsofopqzrzuduinsicm.supabase.co/functions/v1/system-audit' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "action": "audit",
    "scope": ["architecture", "security", "database"],
    "model": "gemini-3-flash-preview"
  }'
```

### JavaScript 调用

```typescript
import { supabase } from '@/integrations/supabase/client';

// 导出文档
const { data: docs } = await supabase.functions.invoke('system-audit', {
  body: { action: 'export' }
});

// AI 审计
const { data: audit } = await supabase.functions.invoke('system-audit', {
  body: {
    action: 'audit',
    scope: ['architecture', 'security'],
    detailed: true
  }
});

console.log('审计得分:', audit.summary.overallScore);
console.log('发现问题:', audit.findings.length);
```

## 限制

- 单次审计最大超时: 60秒
- 每日审计次数限制: 100次/项目
- 详细报告会增加 token 消耗

## 错误码

| 状态码 | 描述 |
|--------|------|
| 400 | 请求参数无效 |
| 401 | 未认证 (audit 操作需要认证) |
| 429 | 超出速率限制 |
| 500 | 服务器内部错误 |
| 503 | AI 服务暂时不可用 |
