# 灵越智保 API 文档

## 概述

- **Base URL**: `http://47.108.80.98:8001/api/v1`
- **认证方式**: Bearer Token (JWT)
- **Content-Type**: `application/json`

## 认证

### 登录
```
POST /auth/login
```

**请求体**:
```json
{
  "username": "admin",
  "password": "admin123"
}
```

**响应**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "accessToken": "eyJhbGciOiJIUzM4NCJ9...",
    "refreshToken": "...",
    "expiresIn": 86400
  }
}
```

---

## 项目管理

### 获取项目列表
```
GET /projects?page=1&size=20
```

**响应**:
```json
{
  "code": 200,
  "data": {
    "records": [
      {
        "id": 10,
        "projectKey": "PRJ-2024-001",
        "projectName": "成都院安全生产标准化复审",
        "status": "active",
        "createdAt": "2024-01-01T00:00:00"
      }
    ],
    "total": 1
  }
}
```

### 获取项目详情
```
GET /projects/{projectId}
```

---

## 要素管理

### 获取项目要素列表
```
GET /projects/{projectId}/elements
```

**响应**:
```json
{
  "code": 200,
  "data": [
    {
      "id": 701,
      "elementKey": "project.reviewObject",
      "elementName": "评审对象",
      "elementType": "text",
      "namespace": "project"
    }
  ]
}
```

### 获取项目要素值列表
```
GET /projects/{projectId}/values
```

**响应**:
```json
{
  "code": 200,
  "data": [
    {
      "valueId": 801,
      "elementKey": "PRJ-2024-001:project.reviewObject",
      "valueText": "中国电建集团成都勘测设计研究院有限公司",
      "isFilled": true
    }
  ]
}
```

### 更新要素值
```
PUT /projects/{projectId}/values/{elementKey}
```

**请求体**:
```json
{
  "valueText": "新的要素值"
}
```

---

## 附件管理

### 获取项目附件列表
```
GET /projects/{projectId}/attachments
```

**响应**:
```json
{
  "code": 200,
  "data": [
    {
      "id": 2367,
      "displayName": "附件8 工作方案.zip",
      "fileName": "att08-工作方案.zip",
      "fileKey": "uuid-xxx",
      "fileType": "zip",
      "fileSize": 312859,
      "parseStatus": "completed"
    }
  ]
}
```

### 上传附件
```
POST /projects/{projectId}/attachments
Content-Type: multipart/form-data
```

**表单字段**:
- `file`: 文件
- `displayName`: 显示名称（可选）

**响应**:
```json
{
  "code": 200,
  "data": {
    "attachmentId": 2367,
    "attachmentKey": "ATT-1234567890-123",
    "fileKey": "uuid-xxx"
  }
}
```

### 删除附件
```
DELETE /attachments/{attachmentId}
```

### 获取附件文件
```
GET /files/{fileKey}
```

**响应**: 文件二进制流

### 保存附件解析结果
```
POST /attachments/{attachmentId}/parsed-content
```

**请求体**:
```json
{
  "content": "解析后的 HTML 或 Markdown 内容"
}
```

---

## 规则管理

### 获取项目规则列表
```
GET /projects/{projectId}/rules
```

**响应**:
```json
{
  "code": 200,
  "data": [
    {
      "id": 2301,
      "ruleName": "评审对象全称",
      "elementKey": "project.reviewObject",
      "ruleType": "auto",
      "actionType": "summary",
      "actionConfig": "{\"description\": \"...\"}",
      "description": "来源：工作方案",
      "status": "active",
      "inputs": [
        {
          "inputId": 3779,
          "ruleId": 2301,
          "sourceNodeId": 2367,
          "inputKey": "attachment",
          "inputName": "附件8 工作方案.zip",
          "inputType": "ATTACHMENT",
          "entryPath": "成都院本部...复审工作方案.pdf",
          "sourceText": "来源段落文本...",
          "sourceType": "ATTACHMENT",
          "sourceName": "附件8 工作方案.zip",
          "sortOrder": 0
        }
      ]
    }
  ]
}
```

### 获取单个规则
```
GET /rules/{ruleId}
```

### 创建规则
```
POST /projects/{projectId}/rules
```

**请求体**:
```json
{
  "elementKey": "project.reviewObject",
  "ruleName": "评审对象全称",
  "ruleType": "auto",
  "actionType": "summary",
  "actionConfig": "{\"description\": \"...\"}",
  "dslContent": "规则描述",
  "description": "来源：工作方案",
  "inputs": [
    {
      "sourceNodeId": 2367,
      "inputKey": "attachment",
      "inputType": "ATTACHMENT",
      "inputName": "附件8 工作方案.zip",
      "entryPath": "folder/file.pdf",
      "sourceText": "来源段落文本"
    }
  ]
}
```

### 更新规则
```
PUT /rules/{ruleId}
```

**请求体**: 同创建规则

### 删除规则
```
DELETE /rules/{ruleId}
```

### 执行规则
```
POST /rules/{ruleId}/execute
```

**响应**:
```json
{
  "code": 200,
  "data": {
    "ruleId": 2301,
    "status": "success",
    "outputText": "执行结果",
    "elementKey": "project.reviewObject",
    "valueUpdated": true,
    "duration": 1234
  }
}
```

### 执行项目所有规则
```
POST /projects/{projectId}/rules/execute-all
```

---

## 文件服务

### 上传文件
```
POST /files/upload
Content-Type: multipart/form-data
```

**表单字段**:
- `file`: 文件

**响应**:
```json
{
  "code": 200,
  "data": {
    "fileKey": "uuid-xxx",
    "fileName": "file.pdf",
    "fileSize": 12345,
    "fileUrl": "/files/uuid-xxx"
  }
}
```

### 下载文件
```
GET /files/{fileKey}
```

---

## 数据模型

### Rule Input 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `sourceNodeId` | Long | 来源节点 ID（附件 ID） |
| `inputKey` | String | 输入键（如 "attachment"） |
| `inputType` | String | 输入类型（ATTACHMENT, VALUE, FIXED） |
| `inputName` | String | 输入名称（附件显示名） |
| `entryPath` | String | ZIP 内文件路径（如 "folder/file.pdf"） |
| `sourceText` | String | 来源段落/摘要文本 |
| `fixedValue` | String | 固定值（当 inputType=FIXED 时） |

### Element Type 说明

| 类型 | 说明 |
|------|------|
| `text` | 短文本（单行） |
| `paragraph` | 段落（多行长文本） |
| `table` | 表格 |

### Action Type 说明

| 类型 | 说明 |
|------|------|
| `quote` | 直接引用 |
| `summary` | AI 总结 |
| `table_extract` | 表格提取 |

---

## 错误码

| 状态码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权（Token 无效或过期） |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

---

## 示例：完整的附件上传和规则关联流程

```bash
# 1. 登录获取 Token
TOKEN=$(curl -s -X POST "$BASE/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}' | jq -r '.data.accessToken')

# 2. 上传附件
curl -X POST "$BASE/projects/10/attachments" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@工作方案.zip" \
  -F "displayName=附件8 工作方案.zip"

# 3. 创建规则并关联附件
curl -X POST "$BASE/projects/10/rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "elementKey": "project.reviewObject",
    "ruleName": "评审对象全称",
    "actionType": "summary",
    "inputs": [{
      "sourceNodeId": 2367,
      "inputKey": "attachment",
      "inputType": "ATTACHMENT",
      "inputName": "附件8 工作方案.zip",
      "entryPath": "成都院本部...复审工作方案.pdf"
    }]
  }'
```