finrep-report/backend/docs/api-guide.md

API 使用指南

认证

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

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}

通用响应格式

成功响应

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

错误响应

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

任务管理 API

创建任务

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

请求体：

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

响应：

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

查询任务列表

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

查询任务详情

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

更新任务

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

请求体：

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

开始任务

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

取消任务

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

大纲管理 API

创建大纲

POST /api/v1/tasks/{taskId}/outline HTTP/1.1
Content-Type: application/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
      }
    ]
  }
}

确认大纲

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

请求体：

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

数据包管理 API

创建数据包

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

请求体：

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

确认数据包

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

报告管理 API

创建报告

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

请求体：

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

导出报告

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

响应：

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

SSE 实时进度

订阅任务进度

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);
};

事件格式：

{
  "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. 错误重试: 对于网络错误使用指数退避重试