# API 使用指南

## 认证

所有 API 请求都需要在 Header 中提供认证信息和租户信息：

```http
GET /api/v1/tasks HTTP/1.1
Host: api.example.com
Authorization: Bearer {jwt_token}
X-Tenant-Id: {tenant_id}
X-Trace-Id: {trace_id}
```

## 通用响应格式

### 成功响应

```json
{
  "code": 200,
  "message": "success",
  "data": {}
}
```

### 错误响应

```json
{
  "code": 400,
  "message": "参数校验失败",
  "data": null,
  "errors": [
    {
      "field": "taskName",
      "message": "任务名称不能为空"
    }
  ]
}
```

## 任务管理 API

### 创建任务

```http
POST /api/v1/tasks HTTP/1.1
Content-Type: application/json
```

**请求体：**

```json
{
  "taskName": "贷前调查报告",
  "description": "某企业贷前调查",
  "modelConfigId": "default_gpt4",
  "parameters": {
    "enterpriseId": "123456",
    "reportType": "PRE_LOAN_INVESTIGATION"
  }
}
```

**响应：**

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_123",
    "taskName": "贷前调查报告",
    "status": "PENDING_OUTLINE",
    "progress": 0,
    "createTime": "2024-01-01T00:00:00"
  }
}
```

### 查询任务列表

```http
GET /api/v1/tasks?page=1&size=10&status=PENDING_OUTLINE HTTP/1.1
```

### 查询任务详情

```http
GET /api/v1/tasks/{taskId} HTTP/1.1
```

### 更新任务

```http
PUT /api/v1/tasks/{taskId} HTTP/1.1
Content-Type: application/json
```

**请求体：**

```json
{
  "taskName": "更新后的任务名称",
  "description": "更新后的描述"
}
```

### 开始任务

```http
POST /api/v1/tasks/{taskId}/start HTTP/1.1
```

### 取消任务

```http
POST /api/v1/tasks/{taskId}/cancel HTTP/1.1
```

## 大纲管理 API

### 创建大纲

```http
POST /api/v1/tasks/{taskId}/outline HTTP/1.1
Content-Type: application/json
```

**请求体：**

```json
{
  "title": "贷前调查报告大纲",
  "type": "LEVEL1",
  "rootNode": {
    "nodeId": "root",
    "title": "贷前调查报告",
    "children": [
      {
        "nodeId": "node_1",
        "chapterNumber": "1",
        "title": "企业基本信息",
        "knowledgeUnitId": "ku_001",
        "sortOrder": 1
      },
      {
        "nodeId": "node_2",
        "chapterNumber": "2",
        "title": "财务状况分析",
        "knowledgeUnitId": "ku_002",
        "sortOrder": 2
      }
    ]
  }
}
```

### 确认大纲

```http
POST /api/v1/outline/{outlineId}/confirm HTTP/1.1
Content-Type: application/json
```

**请求体：**

```json
{
  "confirmerId": "user_123",
  "confirmerName": "张三"
}
```

## 数据包管理 API

### 创建数据包

```http
POST /api/v1/tasks/{taskId}/data-packages HTTP/1.1
Content-Type: application/json
```

**请求体：**

```json
{
  "knowledgeUnitId": "ku_001",
  "status": "READY",
  "autoData": {
    "企业名称": "ABC公司",
    "统一社会信用代码": "91110000000000000X",
    "成立时间": "2010-01-01"
  },
  "manualData": "",
  "dataSources": {
    "source": "工商信息API",
    "queryTime": "2024-01-01"
  }
}
```

### 确认数据包

```http
POST /api/v1/data-packages/{packageId}/confirm HTTP/1.1
Content-Type: application/json
```

## 报告管理 API

### 创建报告

```http
POST /api/v1/tasks/{taskId}/reports HTTP/1.1
Content-Type: application/json
```

**请求体：**

```json
{
  "title": "ABC公司贷前调查报告",
  "format": "PDF",
  "outlineId": "outline_123",
  "metadata": {
    "enterpriseId": "123456",
    "reportType": "PRE_LOAN_INVESTIGATION"
  }
}
```

### 导出报告

```http
POST /api/v1/reports/{reportId}/export?format=PDF HTTP/1.1
```

**响应：**

返回二进制文件流，Content-Type 为 `application/pdf`。

## SSE 实时进度

### 订阅任务进度

```javascript
const eventSource = new EventSource('/api/v1/tasks/{taskId}/progress?tenantId={tenantId}', {
  headers: {
    'Authorization': 'Bearer {token}',
    'X-Tenant-Id': '{tenantId}'
  }
});

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('任务进度:', data);
};

eventSource.onerror = (error) => {
  console.error('SSE 连接错误:', error);
};
```

**事件格式：**

```json
{
  "taskId": "task_123",
  "status": "GENERATING",
  "stage": "report_generate",
  "progress": 65,
  "message": "正在生成报告内容...",
  "timestamp": "2024-01-01T00:00:00"
}
```

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 参数错误 |
| 401 | 未认证 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 409 | 资源冲突 |
| 429 | 请求超限 |
| 500 | 服务器内部错误 |
| 503 | 服务不可用 |

## 限流规则

- 每租户每分钟最多创建 10 个任务
- 每个用户每秒最多发起 50 个请求
- SSE 连接每租户最多 5 个并发

## 最佳实践

1. **使用幂等键**: 重复提交时使用相同的幂等键
2. **使用 TraceId**: 调用链追踪使用 TraceId
3. **订阅进度**: 长耗时任务使用 SSE 获取实时进度
4. **确认机制**: 大纲和数据包确认后才能进入下一阶段
5. **错误重试**: 对于网络错误使用指数退避重试