# 灵越智报 2.0 后端接口设计文档

> **基于前端原型 + 数据库设计 + Mock数据**
> 
> **最后更新**: 2026-02-12
> 
> **负责人**: 何文松

---

## 目录

1. [接口规范](#1-接口规范)
2. [认证授权接口](#2-认证授权接口)
3. [项目管理接口](#3-项目管理接口)
4. [原始文件接口](#4-原始文件接口)
5. [模板管理接口](#5-模板管理接口)
6. [报告管理接口](#6-报告管理接口)
7. [要素管理接口](#7-要素管理接口)
8. [附件管理接口](#8-附件管理接口)
9. [实体管理接口](#9-实体管理接口)
10. [规则管理接口](#10-规则管理接口)
11. [AI助手接口](#11-ai助手接口)
12. [系统管理接口](#12-系统管理接口)
13. [数据字典接口](#13-数据字典接口)

---

## 1. 接口规范

### 1.1 基础URL

```
开发环境: http://localhost:8080/api/v1
生产环境: https://api.lingyue.com/api/v1
```

### 1.2 请求规范

| 项目 | 规范 |
|------|------|
| 协议 | HTTPS |
| 编码 | UTF-8 |
| 格式 | JSON |
| 认证 | Bearer Token |

**请求头**:
```http
Content-Type: application/json
Authorization: Bearer <access_token>
X-Request-Id: <uuid>
```

### 1.3 响应规范

**成功响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": { ... },
  "timestamp": 1707724800000
}
```

**分页响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "list": [ ... ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 100,
      "totalPages": 5
    }
  }
}
```

**错误响应**:
```json
{
  "code": 40001,
  "message": "参数错误",
  "errors": [
    { "field": "name", "message": "名称不能为空" }
  ],
  "timestamp": 1707724800000
}
```

### 1.4 错误码定义

| 错误码 | 说明 |
|--------|------|
| 0 | 成功 |
| 40001 | 参数错误 |
| 40101 | 未认证 |
| 40301 | 无权限 |
| 40401 | 资源不存在 |
| 40901 | 资源冲突 |
| 50001 | 服务器内部错误 |
| 50301 | 服务不可用 |

---

## 2. 认证授权接口

### 2.1 用户登录

**POST** `/auth/login`

**请求体**:
```json
{
  "username": "admin",
  "password": "admin123",
  "captcha": "abc123",
  "captchaKey": "uuid-xxx"
}
```

**响应**:
```json
{
  "code": 0,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 7200,
    "tokenType": "Bearer",
    "user": {
      "id": 1,
      "username": "admin",
      "realName": "管理员",
      "avatar": "/avatars/admin.png",
      "department": "技术部",
      "roles": ["super_admin"],
      "permissions": ["dashboard", "project", "template", "report", "system"]
    }
  }
}
```

### 2.2 刷新令牌

**POST** `/auth/refresh`

**请求体**:
```json
{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}
```

### 2.3 退出登录

**POST** `/auth/logout`

### 2.4 获取当前用户信息

**GET** `/auth/me`

**响应**:
```json
{
  "code": 0,
  "data": {
    "id": 1,
    "username": "admin",
    "realName": "管理员",
    "email": "admin@example.com",
    "phone": "13800138000",
    "avatar": "/avatars/admin.png",
    "department": "技术部",
    "position": "系统管理员",
    "roles": [
      { "id": 1, "code": "super_admin", "name": "超级管理员" }
    ],
    "permissions": ["dashboard", "project", "project:list", "project:create", ...]
  }
}
```

### 2.5 修改密码

**PUT** `/auth/password`

**请求体**:
```json
{
  "oldPassword": "admin123",
  "newPassword": "newPassword123",
  "confirmPassword": "newPassword123"
}
```

---

## 3. 项目管理接口

### 3.1 获取项目列表

**GET** `/projects`

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认1 |
| pageSize | int | 否 | 每页数量，默认20 |
| keyword | string | 否 | 搜索关键词 |
| status | string | 否 | 状态筛选: active/archived |
| sortBy | string | 否 | 排序字段: created_at/updated_at/name |
| sortOrder | string | 否 | 排序方向: asc/desc |

**响应**:
```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 2,
        "nodeKey": "PRJ-001",
        "name": "成都院-安全生产标准化复审报告",
        "description": "2024年度安全生产标准化复审项目",
        "status": "active",
        "reportCount": 2,
        "attachmentCount": 6,
        "createdBy": {
          "id": 1,
          "name": "管理员"
        },
        "createdAt": "2026-02-01T10:00:00Z",
        "updatedAt": "2026-02-12T08:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 5,
      "totalPages": 1
    }
  }
}
```

### 3.2 获取项目详情

**GET** `/projects/{id}`

**响应**:
```json
{
  "code": 0,
  "data": {
    "id": 2,
    "nodeKey": "PRJ-001",
    "name": "成都院-安全生产标准化复审报告",
    "description": "2024年度安全生产标准化复审项目",
    "status": "active",
    "properties": {
      "startDate": "2024-07-01",
      "endDate": "2024-12-31"
    },
    "reports": [
      {
        "id": 200,
        "name": "成都院2024年安全生产标准化复审报告",
        "status": "draft"
      }
    ],
    "createdBy": {
      "id": 1,
      "name": "管理员"
    },
    "createdAt": "2026-02-01T10:00:00Z",
    "updatedAt": "2026-02-12T08:30:00Z"
  }
}
```

### 3.3 创建项目

**POST** `/projects`

**请求体**:
```json
{
  "name": "华东院-安全生产标准化复审报告",
  "description": "2024年度华东院安全生产标准化复审项目",
  "properties": {
    "startDate": "2024-07-01",
    "endDate": "2024-12-31"
  }
}
```

### 3.4 更新项目

**PUT** `/projects/{id}`

**请求体**:
```json
{
  "name": "成都院-安全生产标准化复审报告（修订）",
  "description": "更新后的描述",
  "status": "active"
}
```

### 3.5 删除项目

**DELETE** `/projects/{id}`

### 3.6 归档项目

**POST** `/projects/{id}/archive`

### 3.7 复制项目

**POST** `/projects/{id}/copy`

**请求体**:
```json
{
  "name": "华东院-安全生产标准化复审报告",
  "copyReports": true,
  "copyAttachments": false
}
```

---

## 4. 原始文件接口

### 4.1 上传原始文件

**POST** `/source-files/upload`

**请求**: `multipart/form-data`

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | file | 是 | 文件（支持docx/doc/pdf） |
| projectId | int | 否 | 关联项目ID |

**响应**:
```json
{
  "code": 0,
  "data": {
    "id": 100,
    "nodeKey": "SF-001",
    "name": "成都院复审报告样本.docx",
    "originalName": "成都院复审报告样本.docx",
    "filePath": "/uploads/2026/02/12/xxx.docx",
    "fileType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "fileSize": 1024000,
    "parseStatus": "pending",
    "createdAt": "2026-02-12T10:00:00Z"
  }
}
```

### 4.2 获取原始文件列表

**GET** `/source-files`

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码 |
| pageSize | int | 否 | 每页数量 |
| parseStatus | string | 否 | 解析状态: pending/parsing/completed/failed |

### 4.3 获取原始文件详情

**GET** `/source-files/{id}`

**响应**:
```json
{
  "code": 0,
  "data": {
    "id": 100,
    "nodeKey": "SF-001",
    "name": "成都院复审报告样本.docx",
    "originalName": "成都院复审报告样本.docx",
    "filePath": "/uploads/2026/02/12/xxx.docx",
    "fileType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "fileSize": 1024000,
    "contentHtml": "<html>...</html>",
    "contentJson": { "sections": [...] },
    "parseStatus": "completed",
    "parsedAt": "2026-02-12T10:05:00Z",
    "template": {
      "id": 101,
      "name": "电力安全生产标准化复审报告模板"
    },
    "createdBy": {
      "id": 1,
      "name": "管理员"
    },
    "createdAt": "2026-02-12T10:00:00Z"
  }
}
```

### 4.4 触发文件解析

**POST** `/source-files/{id}/parse`

**响应**:
```json
{
  "code": 0,
  "data": {
    "taskId": "task-uuid-xxx",
    "status": "parsing",
    "message": "文件解析任务已提交"
  }
}
```

### 4.5 获取解析进度

**GET** `/source-files/{id}/parse-status`

**响应**:
```json
{
  "code": 0,
  "data": {
    "status": "parsing",
    "progress": 60,
    "currentStep": "extracting_elements",
    "steps": [
      { "name": "uploading", "status": "completed", "message": "文件上传完成" },
      { "name": "converting", "status": "completed", "message": "格式转换完成" },
      { "name": "extracting_elements", "status": "running", "message": "正在提取动态要素..." },
      { "name": "extracting_entities", "status": "pending", "message": "等待提取实体" },
      { "name": "generating_template", "status": "pending", "message": "等待生成模板" }
    ]
  }
}
```

### 4.6 删除原始文件

**DELETE** `/source-files/{id}`

---

## 5. 模板管理接口

### 5.1 获取模板列表

**GET** `/templates`

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码 |
| pageSize | int | 否 | 每页数量 |
| keyword | string | 否 | 搜索关键词 |
| category | string | 否 | 分类筛选 |
| status | string | 否 | 状态: active/disabled |

**响应**:
```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 101,
        "nodeKey": "TPL-001",
        "name": "电力安全生产标准化复审报告模板",
        "category": "安全生产",
        "description": "适用于电力勘测设计企业安全生产标准化复审",
        "elementCount": 47,
        "useCount": 128,
        "status": "active",
        "createdBy": {
          "id": 1,
          "name": "管理员"
        },
        "createdAt": "2026-02-01T10:00:00Z"
      }
    ],
    "pagination": { ... }
  }
}
```

### 5.2 获取模板详情

**GET** `/templates/{id}`

**响应**:
```json
{
  "code": 0,
  "data": {
    "id": 101,
    "nodeKey": "TPL-001",
    "name": "电力安全生产标准化复审报告模板",
    "category": "安全生产",
    "description": "适用于电力勘测设计企业安全生产标准化复审",
    "contentHtml": "<html>...<span class=\"placeholder\">{{basicInfo.projectCode}}</span>...</html>",
    "contentJson": {
      "sections": [
        {
          "title": "封面",
          "elements": ["basicInfo.projectCode", "project.reviewObject", ...]
        }
      ]
    },
    "elements": [
      {
        "id": 1001,
        "elementKey": "basicInfo.projectCode",
        "name": "项目编号",
        "elementType": "text",
        "namespace": "basicInfo",
        "fieldName": "projectCode",
        "required": true,
        "description": "项目唯一编号"
      },
      {
        "id": 1044,
        "elementKey": "SPSRRReviewProject",
        "name": "现场复审项目选择（表格）",
        "elementType": "table",
        "tableColumns": [
          { "key": "序号", "name": "序号", "type": "number" },
          { "key": "项目名称", "name": "项目名称", "type": "text" },
          { "key": "项目类型", "name": "项目类型", "type": "text" }
        ]
      }
    ],
    "sourceFile": {
      "id": 100,
      "name": "成都院复审报告样本.docx"
    },
    "createdBy": {
      "id": 1,
      "name": "管理员"
    },
    "createdAt": "2026-02-01T10:00:00Z"
  }
}
```

### 5.3 创建模板

**POST** `/templates`

**请求体**:
```json
{
  "name": "新模板名称",
  "category": "安全生产",
  "description": "模板描述",
  "sourceFileId": 100,
  "elements": [
    {
      "elementKey": "basicInfo.projectCode",
      "name": "项目编号",
      "elementType": "text",
      "required": true
    }
  ]
}
```

### 5.4 更新模板

**PUT** `/templates/{id}`

### 5.5 删除模板

**DELETE** `/templates/{id}`

### 5.6 基于模板创建报告

**POST** `/templates/{id}/create-report`

**请求体**:
```json
{
  "projectId": 2,
  "reportName": "成都院2024年安全生产标准化复审报告",
  "copyFromReportId": null
}
```

**响应**:
```json
{
  "code": 0,
  "data": {
    "reportId": 200,
    "reportName": "成都院2024年安全生产标准化复审报告",
    "templateId": 101,
    "status": "draft"
  }
}
```

---

## 6. 报告管理接口

### 6.1 获取报告列表

**GET** `/reports`

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码 |
| pageSize | int | 否 | 每页数量 |
| projectId | int | 否 | 项目ID筛选 |
| templateId | int | 否 | 模板ID筛选 |
| status | string | 否 | 状态: draft/reviewing/published |
| keyword | string | 否 | 搜索关键词 |

**响应**:
```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 200,
        "nodeKey": "RPT-001",
        "name": "成都院2024年安全生产标准化复审报告",
        "status": "draft",
        "template": {
          "id": 101,
          "name": "电力安全生产标准化复审报告模板"
        },
        "project": {
          "id": 2,
          "name": "成都院-安全生产标准化复审报告"
        },
        "progress": {
          "filledCount": 35,
          "totalCount": 47,
          "percentage": 74.5
        },
        "attachmentCount": 6,
        "createdBy": {
          "id": 1,
          "name": "管理员"
        },
        "createdAt": "2026-02-01T10:00:00Z",
        "updatedAt": "2026-02-12T08:30:00Z"
      }
    ],
    "pagination": { ... }
  }
}
```

### 6.2 获取报告详情

**GET** `/reports/{id}`

**响应**:
```json
{
  "code": 0,
  "data": {
    "id": 200,
    "nodeKey": "RPT-001",
    "name": "成都院2024年安全生产标准化复审报告",
    "status": "draft",
    "contentHtml": "<html>...填充后的内容...</html>",
    "template": {
      "id": 101,
      "name": "电力安全生产标准化复审报告模板"
    },
    "project": {
      "id": 2,
      "name": "成都院-安全生产标准化复审报告"
    },
    "sourceReport": null,
    "progress": {
      "filledCount": 35,
      "totalCount": 47,
      "percentage": 74.5
    },
    "createdBy": {
      "id": 1,
      "name": "管理员"
    },
    "createdAt": "2026-02-01T10:00:00Z",
    "updatedAt": "2026-02-12T08:30:00Z"
  }
}
```

### 6.3 获取报告要素值列表

**GET** `/reports/{id}/values`

**响应**:
```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 2001,
        "elementKey": "basicInfo.projectCode",
        "elementName": "项目编号",
        "elementType": "text",
        "valueText": "BZ-0092-2024",
        "valueJson": null,
        "isFilled": true,
        "fillSource": "rule",
        "ruleId": 600
      },
      {
        "id": 2002,
        "elementKey": "project.reviewObject",
        "elementName": "评审对象",
        "elementType": "text",
        "valueText": "中国电建集团成都勘测设计研究院有限公司",
        "valueJson": null,
        "isFilled": true,
        "fillSource": "rule",
        "ruleId": 601
      },
      {
        "id": 2047,
        "elementKey": "target_responsibility",
        "elementName": "目标职责复审情况（表格）",
        "elementType": "table",
        "valueText": null,
        "valueJson": [
          {
            "序号": 1,
            "项目": "5.1.1.1\n目标制定",
            "存在的问题": "大邑地勘项目部制定的2024年度安全生产目标，缺少设备设施方面的事故控制目标。",
            "扣分标准": "依据评分标准②目标内容有缺失，扣1分/项，共扣1分。"
          }
        ],
        "isFilled": true,
        "fillSource": "manual"
      }
    ],
    "summary": {
      "total": 47,
      "filled": 35,
      "unfilled": 12,
      "bySource": {
        "manual": 10,
        "rule": 20,
        "default": 5
      }
    }
  }
}
```

### 6.4 更新报告要素值

**PUT** `/reports/{reportId}/values/{elementKey}`

**请求体**:
```json
{
  "valueText": "BZ-0092-2024",
  "fillSource": "manual"
}
```

或表格类型：
```json
{
  "valueJson": [
    { "序号": 1, "项目": "目标制定", "存在的问题": "...", "扣分标准": "..." }
  ],
  "fillSource": "manual"
}
```

### 6.5 批量更新报告要素值

**PUT** `/reports/{id}/values/batch`

**请求体**:
```json
{
  "values": [
    { "elementKey": "basicInfo.projectCode", "valueText": "BZ-0092-2024" },
    { "elementKey": "project.reviewObject", "valueText": "中国电建集团成都勘测设计研究院有限公司" }
  ]
}
```

### 6.6 创建报告

**POST** `/reports`

**请求体**:
```json
{
  "name": "华东院2024年安全生产标准化复审报告",
  "templateId": 101,
  "projectId": 2,
  "copyFromReportId": 200
}
```

### 6.7 更新报告

**PUT** `/reports/{id}`

**请求体**:
```json
{
  "name": "成都院2024年安全生产标准化复审报告（修订版）",
  "status": "reviewing"
}
```

### 6.8 删除报告

**DELETE** `/reports/{id}`

### 6.9 复制报告

**POST** `/reports/{id}/copy`

**请求体**:
```json
{
  "name": "华东院2024年安全生产标准化复审报告",
  "projectId": 3,
  "copyValues": true,
  "copyAttachments": false,
  "copyRules": true
}
```

### 6.10 导出报告

**POST** `/reports/{id}/export`

**请求体**:
```json
{
  "format": "docx",
  "includeAttachments": false
}
```

**响应**:
```json
{
  "code": 0,
  "data": {
    "taskId": "export-task-uuid",
    "status": "processing"
  }
}
```

### 6.11 获取导出状态

**GET** `/reports/{id}/export/{taskId}`

**响应**:
```json
{
  "code": 0,
  "data": {
    "status": "completed",
    "downloadUrl": "/downloads/reports/xxx.docx",
    "expiresAt": "2026-02-12T12:00:00Z"
  }
}
```

### 6.12 生成报告预览

**GET** `/reports/{id}/preview`

**响应**: HTML内容，填充了所有要素值

---

## 7. 要素管理接口

### 7.1 获取模板要素列表

**GET** `/templates/{templateId}/elements`

**响应**:
```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 1001,
        "elementKey": "basicInfo.projectCode",
        "name": "项目编号",
        "elementType": "text",
        "namespace": "basicInfo",
        "fieldName": "projectCode",
        "required": true,
        "defaultValue": null,
        "description": "项目唯一编号",
        "sortOrder": 1
      },
      {
        "id": 1044,
        "elementKey": "SPSRRReviewProject",
        "name": "现场复审项目选择（表格）",
        "elementType": "table",
        "tableColumns": [
          { "key": "序号", "name": "序号", "type": "number" },
          { "key": "项目名称", "name": "项目名称", "type": "text" },
          { "key": "项目类型", "name": "项目类型", "type": "text" }
        ],
        "sortOrder": 44
      }
    ],
    "summary": {
      "total": 47,
      "byType": {
        "text": 30,
        "paragraph": 13,
        "table": 4
      }
    }
  }
}
```

### 7.2 获取要素详情

**GET** `/elements/{id}`

### 7.3 创建要素

**POST** `/templates/{templateId}/elements`

**请求体**:
```json
{
  "elementKey": "newElement.field",
  "name": "新要素",
  "elementType": "text",
  "required": false,
  "defaultValue": "默认值",
  "description": "要素描述"
}
```

### 7.4 更新要素

**PUT** `/elements/{id}`

### 7.5 删除要素

**DELETE** `/elements/{id}`

### 7.6 调整要素顺序

**PUT** `/templates/{templateId}/elements/reorder`

**请求体**:
```json
{
  "elementIds": [1001, 1002, 1003, ...]
}
```

---

## 8. 附件管理接口

### 8.1 上传附件

**POST** `/reports/{reportId}/attachments/upload`

**请求**: `multipart/form-data`

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | file | 是 | 附件文件 |
| displayName | string | 否 | 显示名称 |

**响应**:
```json
{
  "code": 0,
  "data": {
    "id": 400,
    "nodeKey": "ATT-001",
    "name": "现场检测点位布置图",
    "fileName": "现场检测点位布置图.png",
    "filePath": "/uploads/attachments/2026/02/12/xxx.png",
    "fileType": "image/png",
    "fileSize": 512000,
    "parseStatus": "pending",
    "sortOrder": 1,
    "createdAt": "2026-02-12T10:00:00Z"
  }
}
```

### 8.2 获取报告附件列表

**GET** `/reports/{reportId}/attachments`

**响应**:
```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 400,
        "nodeKey": "ATT-001",
        "name": "现场检测点位布置图",
        "fileName": "现场检测点位布置图.png",
        "fileType": "image/png",
        "fileSize": 512000,
        "parseStatus": "completed",
        "parsedText": "...",
        "entityCount": 5,
        "sortOrder": 1
      },
      {
        "id": 401,
        "nodeKey": "ATT-002",
        "name": "现场检测照片",
        "fileName": "现场检测照片.zip",
        "fileType": "application/zip",
        "fileSize": 10240000,
        "parseStatus": "completed",
        "entityCount": 0,
        "sortOrder": 2
      }
    ],
    "total": 6
  }
}
```

### 8.3 获取附件详情

**GET** `/attachments/{id}`

**响应**:
```json
{
  "code": 0,
  "data": {
    "id": 400,
    "nodeKey": "ATT-001",
    "name": "现场检测点位布置图",
    "fileName": "现场检测点位布置图.png",
    "filePath": "/uploads/attachments/2026/02/12/xxx.png",
    "fileType": "image/png",
    "fileSize": 512000,
    "parseStatus": "completed",
    "parsedText": "检测点位布置说明...",
    "parsedAt": "2026-02-12T10:05:00Z",
    "entities": [
      { "id": 500, "name": "中国电建集团成都勘测设计研究院有限公司", "entityType": "ORG" }
    ],
    "report": {
      "id": 200,
      "name": "成都院2024年安全生产标准化复审报告"
    }
  }
}
```

### 8.4 触发附件解析

**POST** `/attachments/{id}/parse`

### 8.5 更新附件

**PUT** `/attachments/{id}`

**请求体**:
```json
{
  "name": "更新后的附件名称"
}
```

### 8.6 删除附件

**DELETE** `/attachments/{id}`

### 8.7 调整附件顺序

**PUT** `/reports/{reportId}/attachments/reorder`

**请求体**:
```json
{
  "attachmentIds": [400, 401, 402, ...]
}
```

### 8.8 下载附件

**GET** `/attachments/{id}/download`

---

## 9. 实体管理接口

### 9.1 获取附件实体列表

**GET** `/attachments/{attachmentId}/entities`

**响应**:
```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 500,
        "nodeKey": "ENT-001",
        "name": "中国电建集团成都勘测设计研究院有限公司",
        "entityType": "ORG",
        "businessLabel": "评审对象",
        "confidence": 0.95,
        "occurrenceCount": 15
      },
      {
        "id": 506,
        "nodeKey": "ENT-007",
        "name": "何彦锋",
        "entityType": "PERSON",
        "businessLabel": "评审组成员",
        "confidence": 0.92,
        "occurrenceCount": 3
      }
    ],
    "summary": {
      "total": 27,
      "byType": {
        "ORG": 5,
        "PERSON": 12,
        "DATE": 8,
        "LOC": 2
      }
    }
  }
}
```

### 9.2 获取报告所有实体

**GET** `/reports/{reportId}/entities`

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| entityType | string | 否 | 实体类型筛选: ORG/PERSON/DATE/PHONE/LOC |
| source | string | 否 | 来源: source_file/attachment |

### 9.3 获取实体详情

**GET** `/entities/{id}`

**响应**:
```json
{
  "code": 0,
  "data": {
    "id": 500,
    "nodeKey": "ENT-001",
    "name": "中国电建集团成都勘测设计研究院有限公司",
    "entityType": "ORG",
    "businessLabel": "评审对象",
    "confidence": 0.95,
    "occurrenceCount": 15,
    "source": {
      "type": "ATTACHMENT",
      "id": 400,
      "name": "现场检测点位布置图"
    },
    "usedInRules": [
      { "id": 601, "name": "评审对象-直接引用实体" }
    ]
  }
}
```

### 9.4 更新实体

**PUT** `/entities/{id}`

**请求体**:
```json
{
  "name": "成都院",
  "businessLabel": "评审对象简称"
}
```

### 9.5 合并实体

**POST** `/entities/merge`

**请求体**:
```json
{
  "sourceEntityIds": [503, 500],
  "targetName": "中国电建集团成都勘测设计研究院有限公司",
  "targetBusinessLabel": "评审对象"
}
```

---

## 10. 规则管理接口

### 10.1 获取报告规则列表

**GET** `/reports/{reportId}/rules`

**响应**:
```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 600,
        "nodeKey": "RPT-001:basicInfo.projectCode",
        "name": "项目编号提取规则",
        "elementKey": "basicInfo.projectCode",
        "elementName": "项目编号",
        "ruleType": "extract",
        "actionType": "llm",
        "status": "active",
        "lastRunStatus": "success",
        "lastRunTime": "2026-02-12T09:00:00Z",
        "lastOutputText": "BZ-0092-2024"
      },
      {
        "id": 601,
        "nodeKey": "RPT-001:project.reviewObject",
        "name": "评审对象-直接引用实体",
        "elementKey": "project.reviewObject",
        "elementName": "评审对象",
        "ruleType": "extract",
        "actionType": "lookup",
        "status": "active",
        "lastRunStatus": "success",
        "lastOutputText": "中国电建集团成都勘测设计研究院有限公司"
      }
    ],
    "summary": {
      "total": 5,
      "byStatus": {
        "success": 4,
        "failed": 1,
        "pending": 0
      }
    }
  }
}
```

### 10.2 获取规则详情

**GET** `/rules/{id}`

**响应**:
```json
{
  "code": 0,
  "data": {
    "id": 600,
    "nodeKey": "RPT-001:basicInfo.projectCode",
    "name": "项目编号提取规则",
    "description": "从附件中提取项目编号",
    "elementKey": "basicInfo.projectCode",
    "elementName": "项目编号",
    "ruleType": "extract",
    "actionType": "llm",
    "actionConfig": {
      "prompt": "从以下文本中提取项目编号：\n{input1}\n\n只返回项目编号，格式如：BZ-XXXX-XXXX",
      "model": "gpt-4"
    },
    "dslContent": "EXTRACT project_code FROM $input1 PATTERN 'BZ-\\d{4}-\\d{4}'",
    "inputs": [
      {
        "inputKey": "input1",
        "inputName": "附件文本",
        "inputType": "entity_ref",
        "sourceNodeId": 400,
        "sourceNodeName": "现场检测点位布置图"
      }
    ],
    "lastOutputText": "BZ-0092-2024",
    "lastOutputJson": null,
    "lastRunStatus": "success",
    "lastRunTime": "2026-02-12T09:00:00Z",
    "lastRunError": null,
    "status": "active"
  }
}
```

### 10.3 创建规则

**POST** `/reports/{reportId}/rules`

**请求体**:
```json
{
  "name": "评审得分提取规则",
  "elementKey": "project.resultScore",
  "ruleType": "extract",
  "actionType": "llm",
  "actionConfig": {
    "prompt": "从以下文本中提取评审得分：\n{input1}\n\n只返回数字分数",
    "model": "gpt-4"
  },
  "inputs": [
    {
      "inputKey": "input1",
      "inputType": "entity_ref",
      "sourceNodeId": 400
    }
  ]
}
```

### 10.4 更新规则

**PUT** `/rules/{id}`

### 10.5 删除规则

**DELETE** `/rules/{id}`

### 10.6 执行规则

**POST** `/rules/{id}/execute`

**响应**:
```json
{
  "code": 0,
  "data": {
    "status": "success",
    "outputText": "93.33",
    "outputJson": null,
    "executionTime": 1500,
    "appliedToValue": true
  }
}
```

### 10.7 批量执行规则

**POST** `/reports/{reportId}/rules/execute-all`

**请求体**:
```json
{
  "ruleIds": [600, 601, 602],
  "applyToValues": true
}
```

**响应**:
```json
{
  "code": 0,
  "data": {
    "taskId": "batch-rule-task-uuid",
    "status": "processing",
    "total": 3,
    "completed": 0
  }
}
```

### 10.8 获取规则执行状态

**GET** `/reports/{reportId}/rules/execute-status/{taskId}`

---

## 11. AI助手接口

### 11.1 发送对话消息

**POST** `/ai/chat`

**请求体**:
```json
{
  "message": "帮我分析一下评审得分的扣分情况",
  "context": {
    "reportId": 200,
    "elementKey": "target_responsibility"
  },
  "mode": "deep_thinking",
  "stream": false
}
```

**响应**:
```json
{
  "code": 0,
  "data": {
    "messageId": "msg-uuid-xxx",
    "content": "根据目标职责复审情况表格分析，主要扣分项如下：\n\n1. **目标制定**（扣1分）：大邑地勘项目部2024年度安全生产目标缺少设备设施方面的事故控制目标。\n\n2. **目标落实**（扣1分）：双江口设计项目部项目经理与各专业部门负责人签订的责任书中，目标分解不明确。\n\n...",
    "suggestions": [
      "查看完整扣分明细",
      "生成整改建议",
      "对比历史评审数据"
    ],
    "references": [
      { "type": "element", "id": 1047, "name": "目标职责复审情况（表格）" }
    ]
  }
}
```

### 11.2 流式对话

**POST** `/ai/chat/stream`

**请求体**: 同上

**响应**: Server-Sent Events (SSE)

```
event: message
data: {"content": "根据目标职责复审情况表格分析，"}

event: message
data: {"content": "主要扣分项如下：\n\n"}

event: done
data: {"messageId": "msg-uuid-xxx"}
```

### 11.3 AI生成要素值

**POST** `/ai/generate-value`

**请求体**:
```json
{
  "reportId": 200,
  "elementKey": "project.reviewObjectDescription",
  "prompt": "根据附件信息生成企业简介",
  "attachmentIds": [400, 401]
}
```

**响应**:
```json
{
  "code": 0,
  "data": {
    "generatedText": "中国电建集团成都勘测设计研究院有限公司（以下简称\"成都院\"或\"公司\"）是中国电力建设集团（股份）有限公司的全资子企业...",
    "confidence": 0.92,
    "sources": [
      { "attachmentId": 400, "relevance": 0.85 }
    ]
  }
}
```

### 11.4 AI优化文本

**POST** `/ai/optimize-text`

**请求体**:
```json
{
  "text": "原始文本内容...",
  "instruction": "使文本更加专业和规范",
  "context": {
    "reportId": 200,
    "elementKey": "project.target"
  }
}
```

### 11.5 获取AI建议

**GET** `/ai/suggestions`

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| reportId | int | 是 | 报告ID |
| elementKey | string | 否 | 要素key |

**响应**:
```json
{
  "code": 0,
  "data": {
    "suggestions": [
      {
        "type": "fill_value",
        "elementKey": "project.resultScore",
        "message": "检测到附件中包含评审得分信息，建议自动填充",
        "suggestedValue": "93.33",
        "confidence": 0.95
      },
      {
        "type": "optimize",
        "elementKey": "project.target",
        "message": "目标描述可以更加具体，建议补充量化指标"
      }
    ]
  }
}
```

---

## 12. 系统管理接口

### 12.1 用户管理

#### 获取用户列表
**GET** `/system/users`

#### 创建用户
**POST** `/system/users`

**请求体**:
```json
{
  "username": "zhangsan",
  "password": "password123",
  "realName": "张三",
  "email": "zhangsan@example.com",
  "phone": "13800138000",
  "department": "技术部",
  "roleIds": [2, 3]
}
```

#### 更新用户
**PUT** `/system/users/{id}`

#### 删除用户
**DELETE** `/system/users/{id}`

#### 重置密码
**POST** `/system/users/{id}/reset-password`

### 12.2 角色管理

#### 获取角色列表
**GET** `/system/roles`

**响应**:
```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 1,
        "roleCode": "super_admin",
        "roleName": "超级管理员",
        "description": "系统最高权限",
        "userCount": 1,
        "status": "active"
      },
      {
        "id": 2,
        "roleCode": "admin",
        "roleName": "管理员",
        "description": "可管理用户、项目、模板等",
        "userCount": 3,
        "status": "active"
      }
    ]
  }
}
```

#### 创建角色
**POST** `/system/roles`

#### 更新角色
**PUT** `/system/roles/{id}`

#### 删除角色
**DELETE** `/system/roles/{id}`

#### 获取角色权限
**GET** `/system/roles/{id}/permissions`

#### 更新角色权限
**PUT** `/system/roles/{id}/permissions`

**请求体**:
```json
{
  "permissionIds": [1, 2, 3, 4, 5]
}
```

### 12.3 权限管理

#### 获取权限树
**GET** `/system/permissions/tree`

**响应**:
```json
{
  "code": 0,
  "data": [
    {
      "id": 1,
      "permCode": "dashboard",
      "permName": "工作台",
      "permType": "menu",
      "path": "/dashboard",
      "icon": "Dashboard",
      "children": []
    },
    {
      "id": 2,
      "permCode": "project",
      "permName": "项目管理",
      "permType": "menu",
      "path": "/project",
      "icon": "Folder",
      "children": [
        {
          "id": 6,
          "permCode": "project:list",
          "permName": "项目列表",
          "permType": "menu",
          "path": "/project/list"
        },
        {
          "id": 7,
          "permCode": "project:create",
          "permName": "创建项目",
          "permType": "button"
        }
      ]
    }
  ]
}
```

### 12.4 系统配置

#### 获取配置列表
**GET** `/system/configs`

#### 获取配置值
**GET** `/system/configs/{key}`

#### 更新配置
**PUT** `/system/configs/{key}`

**请求体**:
```json
{
  "configValue": "新值",
  "description": "配置描述"
}
```

### 12.5 操作日志

#### 获取操作日志
**GET** `/system/logs`

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码 |
| pageSize | int | 否 | 每页数量 |
| userId | int | 否 | 用户ID |
| module | string | 否 | 模块 |
| action | string | 否 | 操作 |
| startTime | string | 否 | 开始时间 |
| endTime | string | 否 | 结束时间 |

---

## 13. 数据字典接口

### 13.1 获取字典类型列表

**GET** `/dicts`

**响应**:
```json
{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 1,
        "dictCode": "parse_status",
        "dictName": "解析状态",
        "description": "文件解析状态",
        "itemCount": 4
      },
      {
        "id": 2,
        "dictCode": "element_type",
        "dictName": "要素类型",
        "description": "动态要素类型",
        "itemCount": 3
      }
    ]
  }
}
```

### 13.2 获取字典项列表

**GET** `/dicts/{dictCode}/items`

**响应**:
```json
{
  "code": 0,
  "data": {
    "list": [
      { "itemCode": "pending", "itemName": "待解析", "sortOrder": 1 },
      { "itemCode": "parsing", "itemName": "解析中", "sortOrder": 2 },
      { "itemCode": "completed", "itemName": "已完成", "sortOrder": 3 },
      { "itemCode": "failed", "itemName": "解析失败", "sortOrder": 4 }
    ]
  }
}
```

### 13.3 创建字典类型

**POST** `/dicts`

### 13.4 更新字典类型

**PUT** `/dicts/{id}`

### 13.5 删除字典类型

**DELETE** `/dicts/{id}`

### 13.6 创建字典项

**POST** `/dicts/{dictCode}/items`

### 13.7 更新字典项

**PUT** `/dicts/{dictCode}/items/{itemCode}`

### 13.8 删除字典项

**DELETE** `/dicts/{dictCode}/items/{itemCode}`

---

## 附录A: 前端页面与接口映射

| 页面/功能 | 主要接口 |
|----------|---------|
| **登录页** | `POST /auth/login` |
| **首页仪表盘** | `GET /auth/me`, `GET /reports` (统计), `GET /templates` |
| **项目列表** | `GET /projects`, `POST /projects`, `DELETE /projects/{id}` |
| **报告列表** | `GET /reports`, `POST /reports`, `DELETE /reports/{id}` |
| **报告编辑器** | `GET /reports/{id}`, `GET /reports/{id}/values`, `PUT /reports/{id}/values/{key}` |
| **报告要素面板** | `GET /templates/{id}/elements`, `GET /reports/{id}/values` |
| **附件管理** | `GET /reports/{id}/attachments`, `POST /reports/{id}/attachments/upload` |
| **实体列表** | `GET /reports/{id}/entities`, `GET /attachments/{id}/entities` |
| **规则配置** | `GET /reports/{id}/rules`, `POST /rules/{id}/execute` |
| **AI助手** | `POST /ai/chat`, `POST /ai/generate-value` |
| **模板管理** | `GET /templates`, `POST /templates`, `PUT /templates/{id}` |
| **用户管理** | `GET /system/users`, `POST /system/users` |
| **角色管理** | `GET /system/roles`, `PUT /system/roles/{id}/permissions` |

---

## 附录B: Mock数据示例

### B.1 报告要素值示例

基于 `mock数据-图数据库.json` 中的数据：

```json
{
  "basicInfo.projectCode": "BZ-0092-2024",
  "project.reviewObject": "中国电建集团成都勘测设计研究院有限公司",
  "basicInfo.requestLevel": "一级",
  "project.resultScore": "93.33",
  "project.resultLevel": "一级",
  "project.workStartAt": "2024年7月13日",
  "project.workEndAt": "2024年10月17日",
  "project.createdAt": "2024年11月",
  "project.reviewObjectAlias": "成都院",
  "basicInfo.reviewObjectCertificateCode": "ZGDIDBOY-083",
  "basicInfo.applyAt": "2024年7月8日",
  "project.reviewPeriod": "2023年7月8日至2024年7月7日"
}
```

### B.2 表格类型要素值示例

```json
{
  "target_responsibility": [
    {
      "序号": 1,
      "项目": "5.1.1.1\n目标制定",
      "存在的问题": "大邑地勘项目部制定的2024年度安全生产目标，缺少设备设施方面的事故控制目标。",
      "扣分标准": "依据评分标准②目标内容有缺失，扣1分/项，共扣1分。"
    },
    {
      "序号": 2,
      "项目": "5.1.1.2\n目标落实",
      "存在的问题": "双江口设计项目部项目经理与各专业部门负责人签订的《2024年度安全责任书》中，目标分解不明确，不满足要求。",
      "扣分标准": "依据评分标准②签订责任书、目标分解不满足要求，扣1分/单位，共扣1分。"
    }
  ]
}
```

### B.3 附件列表示例

```json
{
  "attachments": [
    { "id": 400, "name": "现场检测点位布置图", "fileType": "image/png" },
    { "id": 401, "name": "现场检测照片", "fileType": "application/zip" },
    { "id": 402, "name": "检测计划与检测方案", "fileType": "application/pdf" },
    { "id": 403, "name": "工况记录表", "fileType": "application/vnd.ms-excel" },
    { "id": 404, "name": "噪声检测原始记录表", "fileType": "application/vnd.ms-excel" },
    { "id": 405, "name": "工频电场、工频磁场检测原始记录表", "fileType": "application/vnd.ms-excel" }
  ]
}
```

### B.4 实体列表示例

```json
{
  "entities": [
    { "id": 500, "name": "中国电建集团成都勘测设计研究院有限公司", "type": "ORG" },
    { "id": 503, "name": "成都院", "type": "ORG" },
    { "id": 506, "name": "何彦锋", "type": "PERSON" },
    { "id": 511, "name": "93.33", "type": "NUMBER" },
    { "id": 513, "name": "2024年7月13日", "type": "DATE" }
  ]
}
```

---

## 附录C: WebSocket接口

### C.1 实时通知

**连接**: `wss://api.lingyue.com/ws/notifications`

**认证**: 通过URL参数传递token
```
wss://api.lingyue.com/ws/notifications?token=<access_token>
```

**消息格式**:
```json
{
  "type": "parse_complete",
  "data": {
    "fileId": 100,
    "fileName": "成都院复审报告样本.docx",
    "status": "completed"
  },
  "timestamp": 1707724800000
}
```

**消息类型**:
| 类型 | 说明 |
|------|------|
| `parse_complete` | 文件解析完成 |
| `rule_executed` | 规则执行完成 |
| `export_ready` | 导出文件就绪 |
| `ai_response` | AI响应（流式） |

---

*文档结束*