# 灵越智报 - 前端接口接入文档

> **Base URL**: `http://47.108.80.98:8001`  
> **版本**: v1  
> **更新日期**: 2026-02-13

---

## 通用说明

### 响应格式

所有接口统一返回格式：

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

| code | 说明 |
|------|------|
| 200  | 成功 |
| 400  | 参数错误 |
| 401  | 未认证 / Token 过期 |
| 403  | 无权限 |
| 404  | 资源不存在 |
| 500  | 服务器内部错误 |

### 认证方式

除登录接口外，所有接口需在请求头中携带 Token：

```
Authorization: Bearer <accessToken>
```

### 分页参数（适用于列表接口）

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| page | int  | 1      | 页码 |
| size | int  | 20     | 每页条数 |

### 分页响应结构

```json
{
  "code": 200,
  "data": {
    "records": [ ... ],
    "total": 100,
    "page": 1,
    "size": 20,
    "pages": 5
  }
}
```

---

## 1. 认证模块

### 1.1 用户登录

```
POST /api/v1/auth/login
```

**请求体**：

```json
{
  "username": "admin",
  "password": "admin123"
}
```

**响应**：

```json
{
  "code": 200,
  "data": {
    "accessToken": "eyJhbGciOiJIUzM4NCJ9...",
    "refreshToken": "xxx",
    "expiresIn": 86400,
    "user": {
      "id": 1,
      "username": "admin",
      "realName": "管理员",
      "avatar": null,
      "roles": ["admin"]
    }
  }
}
```

### 1.2 用户登出

```
POST /api/v1/auth/logout
```

**请求头**：`Authorization: Bearer <accessToken>`

### 1.3 刷新 Token

```
POST /api/v1/auth/refresh
```

**请求体**：

```json
{
  "refreshToken": "xxx"
}
```

**响应**：同登录响应。

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

```
GET /api/v1/auth/me
```

**响应**：

```json
{
  "code": 200,
  "data": {
    "id": 1,
    "username": "admin",
    "realName": "管理员",
    "avatar": null,
    "roles": ["admin"]
  }
}
```

### 1.5 修改密码

```
PUT /api/v1/auth/password
```

**请求体**：

```json
{
  "oldPassword": "admin123",
  "newPassword": "newpass456"
}
```

### 1.6 获取当前用户权限树

```
GET /api/v1/auth/permissions
```

**响应**：

```json
{
  "code": 200,
  "data": [
    {
      "id": 1,
      "permKey": "project:view",
      "permName": "查看项目",
      "children": [ ... ]
    }
  ]
}
```

---

## 2. 项目模块

### 2.1 项目列表（分页）

```
GET /api/v1/projects
```

**查询参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | int | 否 | 页码，默认 1 |
| size | int | 否 | 每页条数，默认 20 |
| status | string | 否 | 状态筛选 |
| templateType | string | 否 | 模板类型筛选 |
| keyword | string | 否 | 关键词搜索 |

**响应 `data`**：

```json
{
  "records": [
    {
      "id": 10,
      "title": "成都院安全生产标准化复审",
      "projectCode": "PRJ-2024-001",
      "status": "active",
      "description": "",
      "templateType": "safety_review",
      "elementCount": 47,
      "attachmentCount": 9,
      "ruleCount": 0,
      "filledCount": 47,
      "createdByName": "管理员",
      "createdAt": "2026-02-13T00:38:50",
      "updatedAt": "2026-02-13T00:38:50"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 20,
  "pages": 1
}
```

### 2.2 项目详情

```
GET /api/v1/projects/{id}
```

**响应 `data`**：

```json
{
  "project": {
    "id": 10,
    "title": "成都院安全生产标准化复审",
    "projectCode": "PRJ-2024-001",
    "status": "active",
    "description": "",
    "templateType": "safety_review",
    "elementCount": 47,
    "attachmentCount": 9,
    "ruleCount": 0,
    "filledCount": 47,
    "contentHtml": null,
    "contentMarkdown": null,
    "createdByName": "管理员",
    "createdAt": "2026-02-13T00:38:50",
    "updatedAt": "2026-02-13T00:38:50"
  },
  "elements": [ ... ],
  "values": [ ... ]
}
```

### 2.3 创建项目

```
POST /api/v1/projects
```

**请求体**：

```json
{
  "title": "新项目名称",
  "description": "项目描述",
  "templateType": "safety_review",
  "fromProjectId": null
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| title | string | ✅ | 项目标题 |
| description | string | 否 | 项目描述 |
| templateType | string | 否 | 模板类型 |
| fromProjectId | long | 否 | 从已有项目复制 |

**响应 `data`**：`ProjectVO` 对象。

### 2.4 更新项目

```
PUT /api/v1/projects/{id}
```

**请求体**：

```json
{
  "title": "更新后的标题",
  "description": "更新后的描述",
  "templateType": "safety_review"
}
```

### 2.5 删除项目

```
DELETE /api/v1/projects/{id}
```

### 2.6 复制项目

```
POST /api/v1/projects/{id}/copy
```

**响应 `data`**：新创建的 `ProjectVO` 对象。

### 2.7 归档项目

```
PUT /api/v1/projects/{id}/archive
```

### 2.8 导出项目

```
POST /api/v1/projects/{id}/export?format=docx
```

**响应**：二进制文件流（`Content-Type: application/octet-stream`）。

### 2.9 获取项目文档内容

```
GET /api/v1/projects/{id}/doc-content
```

返回模板文档的结构化 JSON，用于前端渲染文档视图和要素高亮。

**响应 `data`**：

```json
{
  "page": {
    "widthMm": 210.0,
    "heightMm": 297.0,
    "marginTopMm": 25.4,
    "marginBottomMm": 20.0,
    "marginLeftMm": 28.0,
    "marginRightMm": 28.0
  },
  "blocks": [
    {
      "id": "b0",
      "type": "paragraph",
      "runs": [
        {
          "text": "正文内容",
          "bold": true,
          "fontSize": 14.0,
          "fontFamily": "宋体"
        }
      ],
      "style": {
        "alignment": "center",
        "lineSpacing": 1.5
      },
      "images": [
        {
          "rId": "rId8",
          "src": "data:image/png;base64,iVBOR...",
          "widthInch": 6.3,
          "heightInch": 1.2
        }
      ]
    },
    {
      "id": "b5",
      "type": "table",
      "table": {
        "rows": 10,
        "cols": 4,
        "data": [
          [
            { "text": "序号", "colspan": 1 },
            { "text": "项目名称", "colspan": 1 }
          ]
        ]
      }
    }
  ],
  "totalBlocks": 311
}
```

**Block 类型说明**：

| type | 说明 |
|------|------|
| `paragraph` | 普通段落 |
| `heading1` ~ `heading3` | 标题 |
| `table` | 表格 |
| `toc1` ~ `toc3` | 目录项 |
| `list_item` | 列表项 |

**Run 格式字段**：

| 字段 | 类型 | 说明 |
|------|------|------|
| text | string | 文本内容 |
| bold | boolean | 粗体 |
| italic | boolean | 斜体 |
| underline | string | 下划线类型 |
| fontSize | number | 字号（pt） |
| fontFamily | string | 字体名称 |
| color | string | 文字颜色（RGB） |

---

## 3. 要素模块

### 3.1 获取项目要素列表

```
GET /api/v1/projects/{projectId}/elements
```

**响应 `data`**：

```json
[
  {
    "id": 701,
    "elementKey": "basicInfo.projectCode",
    "elementName": "项目编号",
    "elementType": "text",
    "namespace": "basicInfo",
    "fieldName": "projectCode",
    "tableColumns": null,
    "required": true,
    "defaultValue": null,
    "description": "安全生产标准化项目编号",
    "projectId": 10,
    "sortOrder": 0,
    "createdAt": "2026-02-13T00:38:50"
  }
]
```

**elementType 取值**：

| 值 | 说明 | 高亮方式 |
|------|------|------|
| `text` | 短文本 | 行内子串匹配，背景色高亮 |
| `paragraph` | 长文本/段落 | 整段匹配，左边框 + 背景色 |
| `table` | 表格 | 表格外框高亮 |

### 3.2 添加要素定义

```
POST /api/v1/projects/{projectId}/elements
```

**请求体**：

```json
{
  "elementKey": "basicInfo.newField",
  "elementName": "新字段",
  "elementType": "text",
  "namespace": "basicInfo",
  "fieldName": "newField",
  "required": false,
  "defaultValue": "",
  "description": "字段描述",
  "sortOrder": 50
}
```

### 3.3 更新要素定义

```
PUT /api/v1/projects/{projectId}/elements/{elementId}
```

**请求体**：同添加。

### 3.4 删除要素定义

```
DELETE /api/v1/projects/{projectId}/elements/{elementId}
```

---

## 4. 要素值模块

### 4.1 获取所有要素值

```
GET /api/v1/projects/{projectId}/values
```

**响应 `data`**：

```json
[
  {
    "valueId": 801,
    "elementKey": "PRJ-2024-001:basicInfo.projectCode",
    "valueText": "BZ-0092-2024",
    "valueJson": null,
    "isFilled": true,
    "fillSource": "manual",
    "projectId": 10,
    "createdAt": "2026-02-13T00:38:50",
    "updatedAt": "2026-02-13T00:38:50"
  }
]
```

> **注意**：`elementKey` 带有项目前缀（如 `PRJ-2024-001:`），前端匹配要素时需去除前缀。

### 4.2 获取单个要素值

```
GET /api/v1/projects/{projectId}/values/{elementKey}
```

> `elementKey` 需要 URL 编码（如 `basicInfo.projectCode`）。

### 4.3 更新要素值

```
PUT /api/v1/projects/{projectId}/values/{elementKey}
```

**请求体**：

```json
{
  "valueText": "新的值文本",
  "valueJson": null,
  "fillSource": "manual"
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| valueText | string | 文本值 |
| valueJson | string | JSON 格式值（表格类型使用） |
| fillSource | string | 填充来源：`manual` / `ai` / `rule` |

### 4.4 批量更新要素值

```
POST /api/v1/projects/{projectId}/values/batch
```

**请求体**：

```json
{
  "values": [
    {
      "elementKey": "basicInfo.projectCode",
      "valueText": "BZ-0092-2024",
      "fillSource": "manual"
    },
    {
      "elementKey": "basicInfo.companyName",
      "valueText": "成都院",
      "fillSource": "ai"
    }
  ]
}
```

---

## 5. 附件模块

### 5.1 获取附件列表

```
GET /api/v1/projects/{projectId}/attachments
```

**响应 `data`**：

```json
[
  {
    "id": 400,
    "displayName": "01-附件1  成都院核心要素评审情况记录表.docx",
    "fileKey": "ATT-001",
    "fileName": "01-附件1  成都院核心要素评审情况记录表.docx",
    "filePath": null,
    "fileType": "docx",
    "fileSize": 376919,
    "parseStatus": null,
    "parsedText": null,
    "parsedAt": null,
    "entityCount": 0,
    "projectId": 10,
    "sortOrder": 0,
    "createdAt": "2026-02-13T17:11:28",
    "updatedAt": "2026-02-13T17:11:28"
  }
]
```

**当前附件数据**（9 个）：

| sortOrder | displayName | fileType | fileSize |
|-----------|-------------|----------|----------|
| 0 | 01-附件1  成都院核心要素评审情况记录表.docx | docx | 376,919 |
| 1 | 02-附件2  成都院现场评审分工表.zip | zip | 2,171,136 |
| 2 | 03-附件3 关于深入开展电力安全生产标准化建设暨安全环保提升专项行动的通知.pdf | pdf | 360,940 |
| 3 | 04-附件4  成都院材料真实性说明.png | png | 514,264 |
| 4 | 05-附件5  成都院在建项目一览表.docx | docx | 16,056 |
| 5 | 06-附件6  成都院安全管理制度清单.docx | docx | 16,942 |
| 6 | 07-附件7  成都院现场评审末次会签到表.png | png | 564,269 |
| 7 | 08-中国电建集团成都勘测设计工作方案.zip | zip | 299,279 |
| 8 | 09-附件8 复审问题建议表.docx | docx | 29,034 |

### 5.2 上传附件

```
POST /api/v1/projects/{projectId}/attachments/upload
Content-Type: multipart/form-data
```

**表单参数**：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | File | ✅ | 文件 |
| displayName | string | 否 | 显示名称（默认取文件名） |

**响应 `data`**：

```json
{
  "id": 409,
  "displayName": "新附件.docx",
  "fileName": "新附件.docx",
  "fileType": "docx",
  "fileSize": 12345,
  "parseStatus": "pending",
  "taskId": null
}
```

### 5.3 获取附件详情

```
GET /api/v1/attachments/{id}
```

**响应 `data`**：`AttachmentVO` 对象。

### 5.4 删除附件

```
DELETE /api/v1/attachments/{id}
```

### 5.5 触发附件解析

```
POST /api/v1/attachments/{id}/parse
```

### 5.6 调整附件排序

```
PUT /api/v1/attachments/{id}/sort
```

**请求体**：

```json
{
  "sortOrder": 3
}
```

### 5.7 获取附件文档内容

```
GET /api/v1/attachments/{id}/doc-content
```

返回附件解析后的结构化 JSON（格式同 2.9 项目文档内容）。

---

## 6. 规则模块

### 6.1 获取项目规则列表

```
GET /api/v1/projects/{projectId}/rules
```

**响应 `data`**：

```json
[
  {
    "id": 1,
    "ruleName": "提取项目编号",
    "elementKey": "basicInfo.projectCode",
    "ruleType": "direct_entity",
    "actionType": "extract",
    "actionConfig": null,
    "dslContent": null,
    "description": "从附件中提取项目编号",
    "status": "active",
    "lastOutputText": null,
    "lastOutputJson": null,
    "lastRunStatus": null,
    "lastRunTime": null,
    "lastRunError": null,
    "projectId": 10,
    "inputs": [
      {
        "inputId": 1,
        "ruleId": 1,
        "sourceNodeId": 400,
        "inputKey": "attachment",
        "inputName": "附件来源",
        "inputType": "attachment",
        "fixedValue": null,
        "sourceType": "ATTACHMENT",
        "sourceName": "01-附件1",
        "sortOrder": 0
      }
    ],
    "createdAt": "2026-02-13T00:38:50",
    "updatedAt": "2026-02-13T00:38:50"
  }
]
```

### 6.2 获取规则详情

```
GET /api/v1/rules/{id}
```

### 6.3 创建规则

```
POST /api/v1/projects/{projectId}/rules
```

**请求体**：

```json
{
  "elementKey": "basicInfo.projectCode",
  "ruleName": "提取项目编号",
  "ruleType": "direct_entity",
  "actionType": "extract",
  "actionConfig": null,
  "dslContent": null,
  "description": "从附件中提取项目编号",
  "inputs": [
    {
      "inputKey": "attachment",
      "inputType": "attachment",
      "inputName": "附件来源",
      "sourceNodeId": 400,
      "fixedValue": null
    }
  ]
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| elementKey | string | ✅ | 目标要素键 |
| ruleName | string | ✅ | 规则名称 |
| ruleType | string | 否 | 规则类型 |
| actionType | string | 否 | 动作类型 |
| description | string | 否 | 描述 |
| inputs | array | 否 | 规则输入列表 |

### 6.4 更新规则

```
PUT /api/v1/rules/{id}
```

**请求体**：同创建。

### 6.5 删除规则

```
DELETE /api/v1/rules/{id}
```

### 6.6 执行单个规则

```
POST /api/v1/rules/{id}/execute
```

**响应 `data`**：

```json
{
  "ruleId": 1,
  "status": "success",
  "outputText": "BZ-0092-2024",
  "elementKey": "basicInfo.projectCode",
  "valueUpdated": true,
  "duration": 1200
}
```

### 6.7 批量执行规则

```
POST /api/v1/projects/{projectId}/rules/execute-all
```

**响应 `data`**：`RuleExecuteResultVO[]` 数组。

---

## 接口总览

| # | 方法 | 路径 | 说明 |
|---|------|------|------|
| **认证** | | | |
| 1 | POST | `/api/v1/auth/login` | 用户登录 |
| 2 | POST | `/api/v1/auth/logout` | 用户登出 |
| 3 | POST | `/api/v1/auth/refresh` | 刷新 Token |
| 4 | GET | `/api/v1/auth/me` | 获取当前用户信息 |
| 5 | PUT | `/api/v1/auth/password` | 修改密码 |
| 6 | GET | `/api/v1/auth/permissions` | 获取权限树 |
| **项目** | | | |
| 7 | GET | `/api/v1/projects` | 项目列表（分页） |
| 8 | GET | `/api/v1/projects/{id}` | 项目详情 |
| 9 | POST | `/api/v1/projects` | 创建项目 |
| 10 | PUT | `/api/v1/projects/{id}` | 更新项目 |
| 11 | DELETE | `/api/v1/projects/{id}` | 删除项目 |
| 12 | POST | `/api/v1/projects/{id}/copy` | 复制项目 |
| 13 | PUT | `/api/v1/projects/{id}/archive` | 归档项目 |
| 14 | POST | `/api/v1/projects/{id}/export` | 导出项目 |
| 15 | GET | `/api/v1/projects/{id}/doc-content` | 获取项目文档内容 |
| **要素** | | | |
| 16 | GET | `/api/v1/projects/{projectId}/elements` | 要素列表 |
| 17 | POST | `/api/v1/projects/{projectId}/elements` | 添加要素 |
| 18 | PUT | `/api/v1/projects/{projectId}/elements/{elementId}` | 更新要素 |
| 19 | DELETE | `/api/v1/projects/{projectId}/elements/{elementId}` | 删除要素 |
| **要素值** | | | |
| 20 | GET | `/api/v1/projects/{projectId}/values` | 获取所有要素值 |
| 21 | GET | `/api/v1/projects/{projectId}/values/{elementKey}` | 获取单个要素值 |
| 22 | PUT | `/api/v1/projects/{projectId}/values/{elementKey}` | 更新要素值 |
| 23 | POST | `/api/v1/projects/{projectId}/values/batch` | 批量更新要素值 |
| **附件** | | | |
| 24 | GET | `/api/v1/projects/{projectId}/attachments` | 附件列表 |
| 25 | POST | `/api/v1/projects/{projectId}/attachments/upload` | 上传附件 |
| 26 | GET | `/api/v1/attachments/{id}` | 附件详情 |
| 27 | DELETE | `/api/v1/attachments/{id}` | 删除附件 |
| 28 | POST | `/api/v1/attachments/{id}/parse` | 触发附件解析 |
| 29 | PUT | `/api/v1/attachments/{id}/sort` | 调整附件排序 |
| 30 | GET | `/api/v1/attachments/{id}/doc-content` | 获取附件文档内容 |
| **规则** | | | |
| 31 | GET | `/api/v1/projects/{projectId}/rules` | 规则列表 |
| 32 | GET | `/api/v1/rules/{id}` | 规则详情 |
| 33 | POST | `/api/v1/projects/{projectId}/rules` | 创建规则 |
| 34 | PUT | `/api/v1/rules/{id}` | 更新规则 |
| 35 | DELETE | `/api/v1/rules/{id}` | 删除规则 |
| 36 | POST | `/api/v1/rules/{id}/execute` | 执行单个规则 |
| 37 | POST | `/api/v1/projects/{projectId}/rules/execute-all` | 批量执行规则 |

---

## 快速接入示例

### Axios 配置

```javascript
import axios from 'axios'

const api = axios.create({
  baseURL: 'http://47.108.80.98:8001/api/v1',
  timeout: 30000,
  headers: { 'Content-Type': 'application/json' }
})

// 请求拦截器：自动携带 Token
api.interceptors.request.use(config => {
  const token = localStorage.getItem('accessToken')
  if (token) config.headers.Authorization = `Bearer ${token}`
  return config
})

// 响应拦截器：统一处理
api.interceptors.response.use(
  res => {
    if (res.data.code === 200) return res.data.data
    return Promise.reject(new Error(res.data.message))
  },
  err => {
    if (err.response?.status === 401) {
      // Token 过期，跳转登录
      localStorage.removeItem('accessToken')
      window.location.href = '/login'
    }
    return Promise.reject(err)
  }
)

export default api
```

### 典型调用流程

```javascript
// 1. 登录
const { accessToken } = await api.post('/auth/login', {
  username: 'admin',
  password: 'admin123'
})
localStorage.setItem('accessToken', accessToken)

// 2. 获取项目列表
const projects = await api.get('/projects')

// 3. 加载项目数据（并行请求）
const projectId = 10
const [elements, values, attachments, rules] = await Promise.all([
  api.get(`/projects/${projectId}/elements`),
  api.get(`/projects/${projectId}/values`),
  api.get(`/projects/${projectId}/attachments`),
  api.get(`/projects/${projectId}/rules`)
])

// 4. 加载文档内容
const docContent = await api.get(`/projects/${projectId}/doc-content`)

// 5. 更新要素值
await api.put(`/projects/${projectId}/values/${encodeURIComponent('basicInfo.projectCode')}`, {
  valueText: '新编号'
})
```

---

## 测试账号

| 用户名 | 密码 | 角色 |
|--------|------|------|
| admin  | admin123 | 管理员 |