后端接口设计文档.md 38 KB
灵越智报 2.0 后端接口设计文档
基于前端原型 + 数据库设计 + Mock数据
最后更新: 2026-02-12
负责人: 何文松
目录
1. 接口规范
1.1 基础URL
开发环境: http://localhost:8080/api/v1
生产环境: https://api.lingyue.com/api/v1
1.2 请求规范
| 项目 | 规范 |
|---|---|
| 协议 | HTTPS |
| 编码 | UTF-8 |
| 格式 | JSON |
| 认证 | Bearer Token |
请求头:
Content-Type: application/json
Authorization: Bearer <access_token>
X-Request-Id: <uuid>
1.3 响应规范
成功响应:
{
"code": 0,
"message": "success",
"data": { ... },
"timestamp": 1707724800000
}
分页响应:
{
"code": 0,
"message": "success",
"data": {
"list": [ ... ],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 100,
"totalPages": 5
}
}
}
错误响应:
{
"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
请求体:
{
"username": "admin",
"password": "admin123",
"captcha": "abc123",
"captchaKey": "uuid-xxx"
}
响应:
{
"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
请求体:
{
"refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}
2.3 退出登录
POST /auth/logout
2.4 获取当前用户信息
GET /auth/me
响应:
{
"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
请求体:
{
"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 |
响应:
{
"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}
响应:
{
"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
请求体:
{
"name": "华东院-安全生产标准化复审报告",
"description": "2024年度华东院安全生产标准化复审项目",
"properties": {
"startDate": "2024-07-01",
"endDate": "2024-12-31"
}
}
3.4 更新项目
PUT /projects/{id}
请求体:
{
"name": "成都院-安全生产标准化复审报告（修订）",
"description": "更新后的描述",
"status": "active"
}
3.5 删除项目
DELETE /projects/{id}
3.6 归档项目
POST /projects/{id}/archive
3.7 复制项目
POST /projects/{id}/copy
请求体:
{
"name": "华东院-安全生产标准化复审报告",
"copyReports": true,
"copyAttachments": false
}
4. 原始文件接口
4.1 上传原始文件
POST /source-files/upload
请求: multipart/form-data
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| file | file | 是 | 文件（支持docx/doc/pdf） |
| projectId | int | 否 | 关联项目ID |
响应:
{
"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}
响应:
{
"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
响应:
{
"code": 0,
"data": {
"taskId": "task-uuid-xxx",
"status": "parsing",
"message": "文件解析任务已提交"
}
}
4.5 获取解析进度
GET /source-files/{id}/parse-status
响应:
{
"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 |
响应:
{
"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}
响应:
{
"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
请求体:
{
"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
请求体:
{
"projectId": 2,
"reportName": "成都院2024年安全生产标准化复审报告",
"copyFromReportId": null
}
响应:
{
"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 | 否 | 搜索关键词 |
响应:
{
"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}
响应:
{
"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
响应:
{
"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}
请求体:
{
"valueText": "BZ-0092-2024",
"fillSource": "manual"
}
或表格类型：
{
"valueJson": [
{ "序号": 1, "项目": "目标制定", "存在的问题": "...", "扣分标准": "..." }
],
"fillSource": "manual"
}
6.5 批量更新报告要素值
PUT /reports/{id}/values/batch
请求体:
{
"values": [
{ "elementKey": "basicInfo.projectCode", "valueText": "BZ-0092-2024" },
{ "elementKey": "project.reviewObject", "valueText": "中国电建集团成都勘测设计研究院有限公司" }
]
}
6.6 创建报告
POST /reports
请求体:
{
"name": "华东院2024年安全生产标准化复审报告",
"templateId": 101,
"projectId": 2,
"copyFromReportId": 200
}
6.7 更新报告
PUT /reports/{id}
请求体:
{
"name": "成都院2024年安全生产标准化复审报告（修订版）",
"status": "reviewing"
}
6.8 删除报告
DELETE /reports/{id}
6.9 复制报告
POST /reports/{id}/copy
请求体:
{
"name": "华东院2024年安全生产标准化复审报告",
"projectId": 3,
"copyValues": true,
"copyAttachments": false,
"copyRules": true
}
6.10 导出报告
POST /reports/{id}/export
请求体:
{
"format": "docx",
"includeAttachments": false
}
响应:
{
"code": 0,
"data": {
"taskId": "export-task-uuid",
"status": "processing"
}
}
6.11 获取导出状态
GET /reports/{id}/export/{taskId}
响应:
{
"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
响应:
{
"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
请求体:
{
"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
请求体:
{
"elementIds": [1001, 1002, 1003, ...]
}
8. 附件管理接口
8.1 上传附件
POST /reports/{reportId}/attachments/upload
请求: multipart/form-data
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| file | file | 是 | 附件文件 |
| displayName | string | 否 | 显示名称 |
响应:
{
"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
响应:
{
"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}
响应:
{
"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}
请求体:
{
"name": "更新后的附件名称"
}
8.6 删除附件
DELETE /attachments/{id}
8.7 调整附件顺序
PUT /reports/{reportId}/attachments/reorder
请求体:
{
"attachmentIds": [400, 401, 402, ...]
}
8.8 下载附件
GET /attachments/{id}/download
9. 实体管理接口
9.1 获取附件实体列表
GET /attachments/{attachmentId}/entities
响应:
{
"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}
响应:
{
"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}
请求体:
{
"name": "成都院",
"businessLabel": "评审对象简称"
}
9.5 合并实体
POST /entities/merge
请求体:
{
"sourceEntityIds": [503, 500],
"targetName": "中国电建集团成都勘测设计研究院有限公司",
"targetBusinessLabel": "评审对象"
}
10. 规则管理接口
10.1 获取报告规则列表
GET /reports/{reportId}/rules
响应:
{
"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}
响应:
{
"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
请求体:
{
"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
响应:
{
"code": 0,
"data": {
"status": "success",
"outputText": "93.33",
"outputJson": null,
"executionTime": 1500,
"appliedToValue": true
}
}
10.7 批量执行规则
POST /reports/{reportId}/rules/execute-all
请求体:
{
"ruleIds": [600, 601, 602],
"applyToValues": true
}
响应:
{
"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
请求体:
{
"message": "帮我分析一下评审得分的扣分情况",
"context": {
"reportId": 200,
"elementKey": "target_responsibility"
},
"mode": "deep_thinking",
"stream": false
}
响应:
{
"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
请求体:
{
"reportId": 200,
"elementKey": "project.reviewObjectDescription",
"prompt": "根据附件信息生成企业简介",
"attachmentIds": [400, 401]
}
响应:
{
"code": 0,
"data": {
"generatedText": "中国电建集团成都勘测设计研究院有限公司（以下简称\"成都院\"或\"公司\"）是中国电力建设集团（股份）有限公司的全资子企业...",
"confidence": 0.92,
"sources": [
{ "attachmentId": 400, "relevance": 0.85 }
]
}
}
11.4 AI优化文本
POST /ai/optimize-text
请求体:
{
"text": "原始文本内容...",
"instruction": "使文本更加专业和规范",
"context": {
"reportId": 200,
"elementKey": "project.target"
}
}
11.5 获取AI建议
GET /ai/suggestions
查询参数: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | reportId | int | 是 | 报告ID | | elementKey | string | 否 | 要素key |
响应:
{
"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
请求体:
{
"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
响应:
{
"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
请求体:
{
"permissionIds": [1, 2, 3, 4, 5]
}
12.3 权限管理
获取权限树
GET /system/permissions/tree
响应:
{
"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}
请求体:
{
"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
响应:
{
"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
响应:
{
"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 中的数据：
{
"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 表格类型要素值示例
{
"target_responsibility": [
{
"序号": 1,
"项目": "5.1.1.1\n目标制定",
"存在的问题": "大邑地勘项目部制定的2024年度安全生产目标，缺少设备设施方面的事故控制目标。",
"扣分标准": "依据评分标准②目标内容有缺失，扣1分/项，共扣1分。"
},
{
"序号": 2,
"项目": "5.1.1.2\n目标落实",
"存在的问题": "双江口设计项目部项目经理与各专业部门负责人签订的《2024年度安全责任书》中，目标分解不明确，不满足要求。",
"扣分标准": "依据评分标准②签订责任书、目标分解不满足要求，扣1分/单位，共扣1分。"
}
]
}
B.3 附件列表示例
{
"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 实体列表示例
{
"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>
消息格式:
{
"type": "parse_complete",
"data": {
"fileId": 100,
"fileName": "成都院复审报告样本.docx",
"status": "completed"
},
"timestamp": 1707724800000
}
消息类型:
| 类型 | 说明 |
|------|------|
| parse_complete | 文件解析完成 |
| rule_executed | 规则执行完成 |
| export_ready | 导出文件就绪 |
| ai_response | AI响应（流式） |
文档结束