灵越智报 2.0 - 后端开发结构文档（定稿）

版本: v1.0-final
定稿时间: 2026-02-12
技术栈: Spring Boot 3.x + MyBatis-Plus + PostgreSQL 15+
设计原则: 简化单层项目结构，前端只关心"项目"概念

一、技术选型

1.1 核心框架

组件	技术	版本	说明
基础框架	Spring Boot	3.2.x	主框架
ORM	MyBatis-Plus	3.5.x	数据访问
数据库	PostgreSQL	15+	主数据库
缓存	Redis	7.x	会话、字典、配置缓存
安全	Spring Security + JWT	-	认证授权
接口文档	Knife4j (Swagger)	4.x	API文档
JSON	Jackson	-	JSON序列化
日志	SLF4J + Logback	-	日志框架

1.2 文件处理

组件	技术	说明
Word解析	Apache POI	docx读写
PDF解析	PDFBox	pdf读取
Excel解析	Apache POI / EasyExcel	xlsx读写
通用解析	Apache Tika	文件类型检测

1.3 AI与外部服务

组件	技术	说明
NER服务	Python独立服务	实体识别（HTTP调用）
LLM	OpenAI API	大模型调用
规则引擎	独立服务（待对接）	DSL规则执行
服务调用	RestTemplate / WebClient	HTTP客户端

1.4 实时通信

组件	技术	说明
WebSocket	Spring WebSocket + STOMP	实时推送

1.5 文件存储

组件	技术	说明
开发环境	本地文件系统	/uploads/
生产环境	MinIO / 阿里云OSS	对象存储

二、项目结构

2.1 Maven模块结构

lingyue-zhibao/
├── pom.xml                              # 父POM
├── lingyue-common/                      # 公共模块
│   ├── pom.xml
│   └── src/main/java/com/lingyue/common/
│       ├── core/
│       │   ├── Result.java              # 统一返回结果
│       │   ├── PageResult.java          # 分页返回结果
│       │   ├── BaseEntity.java          # 实体基类
│       │   └── Constants.java           # 常量定义
│       ├── exception/
│       │   ├── BusinessException.java   # 业务异常
│       │   ├── AuthException.java       # 认证异常
│       │   └── GlobalExceptionHandler.java  # 全局异常处理
│       ├── config/
│       │   ├── MyBatisPlusConfig.java   # MyBatis-Plus配置
│       │   ├── RedisConfig.java         # Redis配置
│       │   ├── CorsConfig.java          # 跨域配置
│       │   └── JacksonConfig.java       # JSON配置
│       ├── security/
│       │   ├── JwtUtil.java             # JWT工具类
│       │   ├── JwtAuthFilter.java       # JWT认证过滤器
│       │   ├── SecurityConfig.java      # Security配置
│       │   ├── UserContext.java         # 当前用户上下文
│       │   └── PasswordUtil.java        # 密码工具（BCrypt）
│       ├── util/
│       │   ├── DateUtil.java
│       │   ├── StringUtil.java
│       │   ├── JsonUtil.java
│       │   ├── FileUtil.java
│       │   └── IdGenerator.java         # ID/编号生成器
│       └── annotation/
│           ├── OperationLog.java        # 操作日志注解
│           └── RequirePermission.java   # 权限注解
│
├── lingyue-graph/                       # 图数据核心模块
│   ├── pom.xml
│   └── src/main/java/com/lingyue/graph/
│       ├── entity/
│       │   ├── Node.java
│       │   ├── Edge.java
│       │   ├── NodeProperty.java
│       │   ├── EdgeProperty.java
│       │   ├── NodeType.java
│       │   └── EdgeType.java
│       ├── mapper/
│       │   ├── NodeMapper.java
│       │   ├── EdgeMapper.java
│       │   ├── NodePropertyMapper.java
│       │   ├── EdgePropertyMapper.java
│       │   └── xml/
│       │       ├── NodeMapper.xml
│       │       ├── EdgeMapper.xml
│       │       ├── NodePropertyMapper.xml
│       │       └── EdgePropertyMapper.xml
│       └── service/
│           ├── NodeService.java         # 节点CRUD
│           ├── EdgeService.java         # 关系CRUD
│           └── PropertyService.java     # 属性CRUD
│
└── lingyue-app/                         # 应用主模块
    ├── pom.xml
    └── src/main/java/com/lingyue/app/
        ├── LingyueApplication.java      # 启动类
        │
        ├── system/                      # ===== 系统管理模块 =====
        │   ├── controller/
        │   │   ├── AuthController.java
        │   │   ├── UserController.java
        │   │   ├── RoleController.java
        │   │   ├── PermissionController.java
        │   │   ├── DictController.java
        │   │   ├── ConfigController.java
        │   │   └── LogController.java
        │   ├── service/
        │   │   ├── AuthService.java
        │   │   ├── UserService.java
        │   │   ├── RoleService.java
        │   │   ├── PermissionService.java
        │   │   ├── DictService.java
        │   │   ├── ConfigService.java
        │   │   └── LogService.java
        │   ├── mapper/
        │   │   ├── SysUserMapper.java
        │   │   ├── SysRoleMapper.java
        │   │   ├── SysPermissionMapper.java
        │   │   ├── SysDictMapper.java
        │   │   ├── SysConfigMapper.java
        │   │   └── SysLogMapper.java
        │   ├── entity/
        │   │   ├── SysUser.java
        │   │   ├── SysRole.java
        │   │   ├── SysPermission.java
        │   │   ├── SysSession.java
        │   │   ├── SysConfig.java
        │   │   ├── SysDictType.java
        │   │   ├── SysDictItem.java
        │   │   ├── SysOperationLog.java
        │   │   └── SysLoginLog.java
        │   └── dto/
        │       ├── LoginRequest.java
        │       ├── LoginResponse.java
        │       ├── UserCreateDTO.java
        │       ├── UserUpdateDTO.java
        │       ├── UserVO.java
        │       ├── RoleVO.java
        │       └── PermissionTreeVO.java
        │
        ├── project/                     # ===== 项目管理模块 ⭐ =====
        │   ├── controller/
        │   │   ├── ProjectController.java
        │   │   ├── ElementController.java
        │   │   ├── ValueController.java
        │   │   └── ProjectExportController.java
        │   ├── service/
        │   │   ├── ProjectService.java
        │   │   ├── ProjectQueryService.java
        │   │   ├── ElementService.java
        │   │   ├── ValueService.java
        │   │   ├── ProjectCopyService.java
        │   │   └── ProjectExportService.java
        │   ├── dto/
        │   │   ├── ProjectCreateDTO.java
        │   │   ├── ProjectUpdateDTO.java
        │   │   ├── ProjectQueryDTO.java
        │   │   ├── ProjectVO.java
        │   │   ├── ProjectDetailVO.java
        │   │   ├── ElementDefineDTO.java
        │   │   ├── ElementVO.java
        │   │   ├── ValueUpdateDTO.java
        │   │   ├── ValueBatchUpdateDTO.java
        │   │   └── ValueVO.java
        │   ├── enums/
        │   │   ├── ProjectStatus.java   # draft/in_progress/completed/archived
        │   │   └── ElementType.java     # text/paragraph/table
        │   └── viewmapper/
        │       └── ProjectViewMapper.java   # 基于视图的查询
        │
        ├── attachment/                  # ===== 附件管理模块 =====
        │   ├── controller/
        │   │   └── AttachmentController.java
        │   ├── service/
        │   │   ├── AttachmentService.java
        │   │   ├── AttachmentUploadService.java
        │   │   └── AttachmentParseService.java
        │   ├── dto/
        │   │   ├── AttachmentVO.java
        │   │   └── AttachmentUploadVO.java
        │   └── viewmapper/
        │       └── AttachmentViewMapper.java
        │
        ├── entity/                      # ===== 实体管理模块 =====
        │   ├── controller/
        │   │   └── EntityController.java
        │   ├── service/
        │   │   ├── EntityService.java
        │   │   └── EntityMergeService.java
        │   ├── dto/
        │   │   ├── EntityVO.java
        │   │   ├── EntityUpdateDTO.java
        │   │   └── EntityMergeDTO.java
        │   └── viewmapper/
        │       └── EntityViewMapper.java
        │
        ├── rule/                        # ===== 规则管理模块 =====
        │   ├── controller/
        │   │   └── RuleController.java
        │   ├── service/
        │   │   ├── RuleService.java
        │   │   └── RuleExecuteService.java
        │   ├── executor/
        │   │   ├── RuleExecutor.java            # 执行器接口
        │   │   ├── DirectEntityExecutor.java    # 直接引用实体
        │   │   ├── RegexExtractExecutor.java    # 正则提取
        │   │   └── ExternalDSLExecutor.java     # 外部规则引擎（预留）
        │   ├── dto/
        │   │   ├── RuleCreateDTO.java
        │   │   ├── RuleUpdateDTO.java
        │   │   ├── RuleVO.java
        │   │   ├── RuleExecuteRequest.java
        │   │   └── RuleExecuteResult.java
        │   └── viewmapper/
        │       └── RuleViewMapper.java
        │
        ├── file/                        # ===== 文件服务模块 =====
        │   ├── controller/
        │   │   ├── FileUploadController.java
        │   │   └── FileDownloadController.java
        │   ├── service/
        │   │   ├── FileStorageService.java
        │   │   └── FilePreviewService.java
        │   ├── parser/
        │   │   ├── FileParser.java              # 解析器接口
        │   │   ├── DocxParser.java
        │   │   ├── PdfParser.java
        │   │   └── XlsxParser.java
        │   └── dto/
        │       ├── FileUploadVO.java
        │       └── FileParseResult.java
        │
        ├── ai/                          # ===== AI服务模块 =====
        │   ├── controller/
        │   │   ├── NerController.java
        │   │   ├── LLMController.java
        │   │   └── AIAssistantController.java
        │   ├── service/
        │   │   ├── NerService.java
        │   │   ├── LLMService.java
        │   │   ├── AIAssistantService.java
        │   │   └── PromptService.java
        │   ├── client/
        │   │   ├── NerServiceClient.java        # NER服务HTTP客户端
        │   │   ├── LLMClient.java               # LLM API客户端
        │   │   └── RuleEngineClient.java        # 规则引擎客户端（预留）
        │   └── dto/
        │       ├── NerRequest.java
        │       ├── NerResult.java
        │       ├── LLMRequest.java
        │       ├── LLMResponse.java
        │       ├── ChatMessage.java
        │       └── AISuggestion.java
        │
        ├── websocket/                   # ===== WebSocket模块 =====
        │   ├── config/
        │   │   └── WebSocketConfig.java
        │   ├── handler/
        │   │   ├── ParseProgressHandler.java    # 解析进度推送
        │   │   ├── RuleExecuteHandler.java      # 规则执行进度推送
        │   │   └── NotificationHandler.java     # 通知推送
        │   └── dto/
        │       └── WsMessage.java
        │
        └── task/                        # ===== 异步任务模块 =====
            ├── config/
            │   └── AsyncConfig.java
            ├── service/
            │   ├── TaskService.java
            │   ├── ParseTaskExecutor.java       # 文件解析任务
            │   ├── NerTaskExecutor.java          # NER识别任务
            │   └── ExportTaskExecutor.java       # 导出任务
            └── dto/
                └── TaskVO.java

三、接口设计

3.1 认证接口（7个）

#	方法	路径	说明	认证
1	POST	`/api/v1/auth/login`	用户登录	否
2	POST	`/api/v1/auth/logout`	用户登出	是
3	POST	`/api/v1/auth/refresh`	刷新Token	否（需refresh_token）
4	GET	`/api/v1/auth/captcha`	获取验证码	否
5	GET	`/api/v1/auth/me`	获取当前用户信息	是
6	PUT	`/api/v1/auth/password`	修改密码	是
7	GET	`/api/v1/auth/permissions`	获取当前用户权限	是

登录接口详情

POST /api/v1/auth/login

Request:
{
  "username": "admin",
  "password": "123456",
  "captchaId": "uuid",
  "captchaCode": "abcd"
}

Response:
{
  "code": 200,
  "data": {
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "eyJhbGciOi...",
    "expiresIn": 7200,
    "user": {
      "id": 1,
      "username": "admin",
      "realName": "管理员",
      "avatar": null,
      "roles": ["admin"]
    }
  }
}

3.2 用户管理接口（11个）

#	方法	路径	说明
1	GET	`/api/v1/users`	用户列表（分页）
2	GET	`/api/v1/users/{id}`	用户详情
3	POST	`/api/v1/users`	创建用户
4	PUT	`/api/v1/users/{id}`	更新用户
5	DELETE	`/api/v1/users/{id}`	删除用户
6	PUT	`/api/v1/users/{id}/status`	启用/禁用用户
7	PUT	`/api/v1/users/{id}/password/reset`	重置密码
8	GET	`/api/v1/users/{id}/roles`	获取用户角色
9	PUT	`/api/v1/users/{id}/roles`	分配用户角色
10	GET	`/api/v1/users/export`	导出用户列表
11	POST	`/api/v1/users/import`	导入用户

用户列表接口详情

GET /api/v1/users?page=1&size=20&keyword=张&status=active&department=技术部

Response:
{
  "code": 200,
  "data": {
    "total": 50,
    "pages": 3,
    "current": 1,
    "records": [
      {
        "id": 1,
        "username": "admin",
        "realName": "管理员",
        "email": "admin@lingyue.com",
        "phone": "13800138000",
        "department": "技术部",
        "position": "系统管理员",
        "status": "active",
        "roles": [{"id": 1, "roleName": "超级管理员"}],
        "lastLoginAt": "2026-02-12T10:00:00",
        "createdAt": "2026-01-01T00:00:00"
      }
    ]
  }
}

3.3 角色管理接口（8个）

#	方法	路径	说明
1	GET	`/api/v1/roles`	角色列表
2	GET	`/api/v1/roles/{id}`	角色详情
3	POST	`/api/v1/roles`	创建角色
4	PUT	`/api/v1/roles/{id}`	更新角色
5	DELETE	`/api/v1/roles/{id}`	删除角色
6	GET	`/api/v1/roles/{id}/permissions`	获取角色权限
7	PUT	`/api/v1/roles/{id}/permissions`	分配角色权限
8	GET	`/api/v1/roles/{id}/users`	获取角色下用户

3.4 权限管理接口（4个）

#	方法	路径	说明
1	GET	`/api/v1/permissions/tree`	权限树
2	POST	`/api/v1/permissions`	创建权限
3	PUT	`/api/v1/permissions/{id}`	更新权限
4	DELETE	`/api/v1/permissions/{id}`	删除权限

3.5 数据字典接口（8个）

#	方法	路径	说明
1	GET	`/api/v1/dicts`	字典类型列表
2	POST	`/api/v1/dicts`	创建字典类型
3	PUT	`/api/v1/dicts/{id}`	更新字典类型
4	DELETE	`/api/v1/dicts/{id}`	删除字典类型
5	GET	`/api/v1/dicts/{code}/items`	获取字典项列表
6	POST	`/api/v1/dicts/{code}/items`	创建字典项
7	PUT	`/api/v1/dicts/items/{id}`	更新字典项
8	DELETE	`/api/v1/dicts/items/{id}`	删除字典项

3.6 系统配置接口（4个）

#	方法	路径	说明
1	GET	`/api/v1/configs`	配置列表
2	GET	`/api/v1/configs/{key}`	获取配置
3	PUT	`/api/v1/configs/{key}`	更新配置
4	GET	`/api/v1/configs/public`	获取公开配置（无需认证）

3.7 日志接口（4个）

#	方法	路径	说明
1	GET	`/api/v1/logs/operations`	操作日志列表
2	GET	`/api/v1/logs/operations/{id}`	操作日志详情
3	GET	`/api/v1/logs/logins`	登录日志列表
4	DELETE	`/api/v1/logs/operations/clean`	清理历史日志

3.8 项目管理接口（8个）⭐

#	方法	路径	说明
1	GET	`/api/v1/projects`	项目列表（分页）
2	GET	`/api/v1/projects/{id}`	项目详情（含要素、值、附件、规则）
3	POST	`/api/v1/projects`	创建项目
4	PUT	`/api/v1/projects/{id}`	更新项目
5	DELETE	`/api/v1/projects/{id}`	删除项目
6	POST	`/api/v1/projects/{id}/copy`	复制项目
7	PUT	`/api/v1/projects/{id}/archive`	归档项目
8	POST	`/api/v1/projects/{id}/export`	导出项目

创建项目接口详情

POST /api/v1/projects

Request:
{
  "title": "成都院2024年复审报告",
  "description": "成都院电力安全生产标准化复审报告",
  "templateType": "电力安全生产标准化复审报告",
  "fromProjectId": null    // 从已有项目复制（可选）
}

Response:
{
  "code": 200,
  "data": {
    "id": 10,
    "title": "成都院2024年复审报告",
    "projectCode": "PRJ-2024-001",
    "status": "draft",
    "templateType": "电力安全生产标准化复审报告",
    "elementCount": 8,
    "filledCount": 1,
    "createdAt": "2026-02-12T10:00:00"
  }
}

项目详情接口详情

GET /api/v1/projects/{id}

Response:
{
  "code": 200,
  "data": {
    "project": {
      "id": 10,
      "title": "成都院2024年复审报告",
      "projectCode": "PRJ-2024-001",
      "status": "draft",
      "description": "成都院电力安全生产标准化复审报告",
      "templateType": "电力安全生产标准化复审报告",
      "contentHtml": "<h1>...</h1>",
      "contentMarkdown": "# ...",
      "elementCount": 8,
      "attachmentCount": 2,
      "ruleCount": 5,
      "filledCount": 6,
      "createdByName": "admin",
      "createdAt": "2026-02-12T10:00:00",
      "updatedAt": "2026-02-12T15:00:00"
    },
    "elements": [
      {
        "id": 201,
        "elementKey": "basicInfo.projectCode",
        "elementName": "项目编号",
        "elementType": "text",
        "namespace": "basicInfo",
        "fieldName": "projectCode",
        "required": true,
        "description": "项目编号，格式如 BZ-0092-2024",
        "sortOrder": 1
      }
    ],
    "values": [
      {
        "valueId": 301,
        "elementKey": "basicInfo.projectCode",
        "valueText": "BZ-0092-2024",
        "isFilled": true,
        "fillSource": "rule"
      }
    ],
    "attachments": [
      {
        "id": 400,
        "displayName": "01-复审通知",
        "fileName": "复审通知.docx",
        "fileType": "docx",
        "fileSize": 512000,
        "parseStatus": "completed",
        "entityCount": 6,
        "sortOrder": 1
      }
    ],
    "rules": [
      {
        "id": 600,
        "ruleName": "项目编号-直接引用实体",
        "elementKey": "basicInfo.projectCode",
        "ruleType": "direct_entity",
        "actionType": "use_entity_value",
        "lastRunStatus": "success",
        "lastOutputText": "BZ-0092-2024"
      }
    ]
  }
}

项目列表接口详情

GET /api/v1/projects?page=1&size=20&status=draft&templateType=电力安全&keyword=成都

Response:
{
  "code": 200,
  "data": {
    "total": 15,
    "pages": 1,
    "current": 1,
    "records": [
      {
        "id": 10,
        "title": "成都院2024年复审报告",
        "projectCode": "PRJ-2024-001",
        "status": "draft",
        "templateType": "电力安全生产标准化复审报告",
        "elementCount": 8,
        "attachmentCount": 2,
        "filledCount": 6,
        "createdByName": "admin",
        "updatedAt": "2026-02-12T15:00:00"
      }
    ]
  }
}

3.9 要素管理接口（5个）

#	方法	路径	说明
1	GET	`/api/v1/projects/{id}/elements`	获取项目要素列表
2	POST	`/api/v1/projects/{id}/elements`	添加要素定义
3	PUT	`/api/v1/projects/{id}/elements/{elementId}`	更新要素定义
4	DELETE	`/api/v1/projects/{id}/elements/{elementId}`	删除要素定义
5	POST	`/api/v1/projects/{id}/elements/parse`	从样本文件解析要素

添加要素定义接口详情

POST /api/v1/projects/{id}/elements

Request:
{
  "elementKey": "basicInfo.projectCode",
  "elementName": "项目编号",
  "elementType": "text",
  "namespace": "basicInfo",
  "fieldName": "projectCode",
  "required": true,
  "defaultValue": null,
  "description": "项目编号，格式如 BZ-0092-2024"
}

Response:
{
  "code": 200,
  "data": {
    "elementId": 201,
    "valueId": 301,
    "elementKey": "basicInfo.projectCode"
  }
}

3.10 要素值接口（4个）

#	方法	路径	说明
1	GET	`/api/v1/projects/{id}/values`	获取所有要素值
2	GET	`/api/v1/projects/{id}/values/{elementKey}`	获取单个要素值
3	PUT	`/api/v1/projects/{id}/values/{elementKey}`	更新要素值
4	POST	`/api/v1/projects/{id}/values/batch`	批量更新要素值

更新要素值接口详情

PUT /api/v1/projects/{id}/values/{elementKey}

Request:
{
  "valueText": "BZ-0092-2024",
  "fillSource": "manual"
}

Response:
{
  "code": 200,
  "data": {
    "valueId": 301,
    "elementKey": "basicInfo.projectCode",
    "valueText": "BZ-0092-2024",
    "isFilled": true,
    "fillSource": "manual"
  }
}

3.11 附件管理接口（6个）

#	方法	路径	说明
1	POST	`/api/v1/projects/{id}/attachments/upload`	上传附件
2	GET	`/api/v1/projects/{id}/attachments`	获取附件列表
3	GET	`/api/v1/attachments/{id}`	获取附件详情
4	DELETE	`/api/v1/attachments/{id}`	删除附件
5	POST	`/api/v1/attachments/{id}/parse`	触发附件解析
6	PUT	`/api/v1/attachments/{id}/sort`	调整附件排序

上传附件接口详情

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

FormData:
  file: (binary)
  displayName: "01-复审通知"    // 可选

Response:
{
  "code": 200,
  "data": {
    "id": 400,
    "displayName": "01-复审通知",
    "fileName": "复审通知.docx",
    "fileType": "docx",
    "fileSize": 512000,
    "parseStatus": "pending",
    "taskId": "task_20240212_001"
  }
}

3.12 实体管理接口（5个）

#	方法	路径	说明
1	GET	`/api/v1/attachments/{attachmentId}/entities`	获取附件实体列表
2	GET	`/api/v1/projects/{projectId}/entities`	获取项目所有实体
3	GET	`/api/v1/entities/{id}`	获取实体详情
4	PUT	`/api/v1/entities/{id}`	更新实体
5	POST	`/api/v1/entities/merge`	合并实体

获取项目所有实体接口详情

GET /api/v1/projects/{projectId}/entities?entityType=ORG&keyword=成都

Response:
{
  "code": 200,
  "data": [
    {
      "id": 500,
      "entityText": "中国电建集团成都勘测设计研究院有限公司",
      "entityType": "ORG",
      "businessLabel": "评审对象",
      "confidence": 0.95,
      "occurrenceCount": 5,
      "attachmentId": 400,
      "attachmentName": "01-复审通知"
    }
  ]
}

3.13 规则管理接口（7个）

#	方法	路径	说明
1	GET	`/api/v1/projects/{projectId}/rules`	获取项目规则列表
2	GET	`/api/v1/rules/{id}`	获取规则详情（含输入）
3	POST	`/api/v1/projects/{projectId}/rules`	创建规则
4	PUT	`/api/v1/rules/{id}`	更新规则
5	DELETE	`/api/v1/rules/{id}`	删除规则
6	POST	`/api/v1/rules/{id}/execute`	执行单个规则
7	POST	`/api/v1/projects/{projectId}/rules/execute-all`	批量执行规则

创建规则接口详情

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

Request:
{
  "elementKey": "basicInfo.projectCode",
  "ruleName": "项目编号-直接引用实体",
  "ruleType": "direct_entity",
  "actionType": "use_entity_value",
  "description": "直接使用附件实体值填充项目编号",
  "inputs": [
    {
      "inputKey": "entity",
      "inputType": "entity_ref",
      "inputName": "项目编号实体",
      "sourceNodeId": 502
    }
  ]
}

Response:
{
  "code": 200,
  "data": {
    "id": 600,
    "ruleName": "项目编号-直接引用实体",
    "ruleType": "direct_entity",
    "status": "active"
  }
}

执行规则接口详情

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

Response:
{
  "code": 200,
  "data": {
    "ruleId": 600,
    "status": "success",
    "outputText": "BZ-0092-2024",
    "elementKey": "basicInfo.projectCode",
    "valueUpdated": true,
    "duration": 15
  }
}

3.14 AI服务接口（5个）

#	方法	路径	说明
1	POST	`/api/v1/ai/ner/extract`	同步提取实体
2	POST	`/api/v1/ai/ner/extract/async`	异步提取实体
3	POST	`/api/v1/ai/chat`	AI对话
4	POST	`/api/v1/ai/suggest`	AI建议
5	POST	`/api/v1/ai/optimize`	AI优化文本

AI对话接口详情

POST /api/v1/ai/chat

Request:
{
  "projectId": 10,
  "messages": [
    {"role": "user", "content": "帮我总结一下评审结论"}
  ],
  "context": {
    "elementKey": "result.conclusion"
  }
}

Response:
{
  "code": 200,
  "data": {
    "reply": "根据评审材料，成都院在安全生产标准化方面...",
    "suggestions": [
      {"type": "fill_element", "elementKey": "result.conclusion", "value": "..."}
    ]
  }
}

3.15 文件服务接口（4个）

#	方法	路径	说明
1	POST	`/api/v1/files/upload`	通用文件上传
2	GET	`/api/v1/files/{fileKey}`	文件下载
3	GET	`/api/v1/files/{fileKey}/preview`	文件预览
4	DELETE	`/api/v1/files/{fileKey}`	删除文件

3.16 任务接口（3个）

#	方法	路径	说明
1	GET	`/api/v1/tasks/{id}`	查询任务状态
2	GET	`/api/v1/tasks?type=parse&status=running`	任务列表
3	POST	`/api/v1/tasks/{id}/cancel`	取消任务

3.17 接口统计

模块	接口数
认证	7
用户管理	11
角色管理	8
权限管理	4
数据字典	8
系统配置	4
日志	4
项目管理	8
要素管理	5
要素值	4
附件管理	6
实体管理	5
规则管理	7
AI服务	5
文件服务	4
任务	3
合计	93

四、核心业务流程

4.1 创建项目流程

用户点击"新建项目"
    │
    ├─ 选择"空白项目"
    │   └─ 创建 PROJECT 节点（status=draft）
    │       └─ 返回项目ID，跳转编辑器
    │
    ├─ 选择"从预设模板创建"
    │   └─ 创建 PROJECT 节点
    │       └─ 根据 templateType 自动创建 ELEMENT 节点
    │           └─ 为每个 ELEMENT 创建空的 VALUE 节点
    │               └─ 建立所有关系（HAS_ELEMENT, HAS_VALUE, FOR_ELEMENT）
    │                   └─ 返回项目ID，跳转编辑器
    │
    └─ 选择"从已有项目复制"
        └─ 复制源项目的 ELEMENT 节点和 RULE 节点
            └─ 创建新的空 VALUE 节点
                └─ 建立 COPIED_FROM 关系
                    └─ 返回项目ID，跳转编辑器

后端实现要点:

@Service
public class ProjectService {
    
    @Transactional
    public ProjectVO createProject(ProjectCreateDTO dto) {
        // 1. 创建 PROJECT 节点
        Long projectId = nodeService.createNode("PROJECT", generateProjectCode(), dto.getTitle(), currentUserId());
        
        // 2. 设置属性
        propertyService.set(projectId, "title", dto.getTitle());
        propertyService.set(projectId, "description", dto.getDescription());
        propertyService.set(projectId, "status", "draft");
        propertyService.set(projectId, "template_type", dto.getTemplateType());
        
        // 3. 如果有模板类型，初始化要素
        if (dto.getTemplateType() != null) {
            initializeElements(projectId, dto.getTemplateType());
        }
        
        // 4. 如果是复制项目
        if (dto.getFromProjectId() != null) {
            copyProjectElements(projectId, dto.getFromProjectId());
        }
        
        return getProjectVO(projectId);
    }
}

4.2 附件上传与解析流程

用户上传文件
    │
    ▼
FileUploadController.upload()
    │
    ├─ 1. 保存文件到存储（本地/OSS）
    │   └─ 记录到 sys_files 表
    │
    ├─ 2. 创建 ATTACHMENT 节点
    │   ├─ 设置属性：file_name, file_path, file_type, file_size
    │   ├─ 设置 parse_status = 'pending'
    │   └─ 建立 PROJECT --HAS_ATTACHMENT--> ATTACHMENT 关系
    │
    ├─ 3. 创建异步解析任务
    │   └─ 记录到 sys_tasks 表
    │
    └─ 4. 返回附件信息 + taskId
    
异步任务执行:
    │
    ├─ 5. 文件解析（提取文本）
    │   ├─ DocxParser / PdfParser / XlsxParser
    │   ├─ 更新 parsed_text 属性
    │   └─ WebSocket 推送进度 30%
    │
    ├─ 6. NER实体识别
    │   ├─ 调用 NER 服务
    │   ├─ 创建 ENTITY 节点
    │   ├─ 建立 ATTACHMENT --HAS_ENTITY--> ENTITY 关系
    │   └─ WebSocket 推送进度 80%
    │
    └─ 7. 完成
        ├─ 更新 parse_status = 'completed'
        └─ WebSocket 推送进度 100%

4.3 规则创建与执行流程

用户从实体列表拖拽实体到要素
    │
    ▼
RuleController.createRule()
    │
    ├─ 1. 创建 RULE 节点
    │   ├─ rule_type = 'direct_entity'
    │   ├─ action_type = 'use_entity_value'
    │   └─ status = 'active'
    │
    ├─ 2. 建立关系
    │   ├─ PROJECT --HAS_RULE--> RULE
    │   ├─ RULE --FOR_ELEMENT--> ELEMENT
    │   └─ RULE --INPUT_FROM--> ENTITY（带 edge_properties）
    │
    └─ 3. 自动执行规则
        │
        ▼
    RuleExecuteService.execute(ruleId)
        │
        ├─ 4. 获取规则输入（INPUT_FROM 边）
        │   └─ 获取 ENTITY 节点的 name
        │
        ├─ 5. 执行规则逻辑
        │   └─ DirectEntityExecutor: 直接使用实体值
        │
        ├─ 6. 更新 VALUE 节点
        │   ├─ value_text = entity.name
        │   ├─ is_filled = 'true'
        │   └─ fill_source = 'rule'
        │
        └─ 7. 更新 RULE 节点
            ├─ last_output_text = entity.name
            ├─ last_run_status = 'success'
            └─ last_run_time = NOW()

4.4 项目导出流程

用户点击"导出"
    │
    ▼
ProjectExportController.export(projectId, format)
    │
    ├─ 1. 查询项目完整数据
    │   ├─ 项目基本信息（v_projects）
    │   ├─ 要素定义列表（v_project_elements）
    │   ├─ 要素值列表（v_project_values）
    │   └─ 报告内容（content_html / content_markdown）
    │
    ├─ 2. 渲染模板
    │   ├─ Word: Apache POI + 模板文件
    │   └─ PDF: iText / PDFBox
    │
    ├─ 3. 替换要素占位符
    │   └─ {{basicInfo.projectCode}} → "BZ-0092-2024"
    │
    └─ 4. 返回文件流
        └─ Content-Disposition: attachment; filename="报告.docx"

五、WebSocket 消息设计

5.1 连接地址

ws://host:port/ws?token={accessToken}

5.2 消息格式

{
  "type": "PARSE_PROGRESS",
  "data": {
    "taskId": "task_001",
    "attachmentId": 400,
    "progress": 80,
    "stage": "ner_extracting",
    "message": "正在识别实体..."
  }
}

5.3 消息类型

type	说明	触发场景
PARSE_PROGRESS	解析进度	附件解析过程中
PARSE_COMPLETE	解析完成	附件解析完成
PARSE_FAILED	解析失败	附件解析失败
RULE_EXECUTED	规则执行完成	规则执行后
VALUE_UPDATED	要素值更新	要素值被修改后
NOTIFICATION	通知	系统通知

六、统一返回格式

6.1 成功响应

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

6.2 分页响应

{
  "code": 200,
  "message": "success",
  "data": {
    "total": 100,
    "pages": 5,
    "current": 1,
    "size": 20,
    "records": [ ... ]
  }
}

6.3 错误响应

{
  "code": 400,
  "message": "参数错误：标题不能为空",
  "data": null
}

6.4 错误码定义

code	说明
200	成功
400	参数错误
401	未认证
403	无权限
404	资源不存在
409	资源冲突
500	服务器内部错误

七、规则引擎对接（预留）

7.1 当前状态

规则引擎由独立团队开发，将提供接口供本系统调用。接口参数格式待确认。

7.2 对接设计

/**
 * 规则引擎客户端（预留）
 * 待规则引擎接口定义后实现
 */
@Service
public class RuleEngineClient {
    
    /**
     * 调用规则引擎执行DSL
     * @param dslContent DSL代码
     * @param params 参数（节点ID映射）
     * @return 执行结果
     */
    public RuleExecuteResult executeDSL(String dslContent, Map<String, Object> params) {
        // TODO: 待规则引擎接口定义后实现
        throw new UnsupportedOperationException("规则引擎接口待对接");
    }
}

7.3 已知信息

根据规则引擎同事提供的DSL示例，对接时需要传递的核心参数为节点ID。当前数据库设计中所有业务实体都有唯一的 nodes.id，可直接作为参数。

7.4 待确认事项

接口请求/响应格式
调用方式（HTTP/gRPC/消息队列）
异步执行和回调机制
错误处理和重试策略

八、配置文件模板

8.1 application.yml

server:
  port: 8080
  servlet:
    context-path: /

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/lingyue_zhibao
    username: postgres
    password: ${DB_PASSWORD}
    driver-class-name: org.postgresql.Driver
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
  
  redis:
    host: localhost
    port: 6379
    password: ${REDIS_PASSWORD:}
    database: 0
  
  servlet:
    multipart:
      max-file-size: 100MB
      max-request-size: 100MB

mybatis-plus:
  mapper-locations: classpath*:mapper/**/*.xml
  configuration:
    map-underscore-to-camel-case: true
    log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl

# JWT配置
jwt:
  secret: ${JWT_SECRET}
  access-token-expire: 7200      # 2小时
  refresh-token-expire: 604800   # 7天

# 文件存储配置
file:
  storage:
    type: local                   # local / oss / minio
    local:
      base-path: /data/lingyue/uploads
    oss:
      endpoint: ${OSS_ENDPOINT:}
      access-key: ${OSS_ACCESS_KEY:}
      secret-key: ${OSS_SECRET_KEY:}
      bucket: ${OSS_BUCKET:}

# NER服务配置
ner:
  service:
    url: http://localhost:5000
    timeout: 30000

# LLM配置
llm:
  api-key: ${LLM_API_KEY:}
  base-url: ${LLM_BASE_URL:https://api.openai.com/v1}
  model: gpt-4
  max-tokens: 4096

# 规则引擎配置（预留）
rule-engine:
  url: ${RULE_ENGINE_URL:}
  timeout: 60000

九、开发优先级

Phase 1（Week 1-2）：基础设施 + 用户系统 + 项目管理

优先级	模块	接口数
P0	项目框架搭建	-
P0	数据库初始化	-
P0	图数据核心服务（NodeService, EdgeService）	-
P0	认证接口	7
P0	用户管理接口	11
P0	项目管理接口	8
P0	要素管理接口	5
P0	要素值接口	4

Phase 2（Week 3-4）：附件 + 实体 + 规则

优先级	模块	接口数
P0	文件服务接口	4
P0	附件管理接口	6
P0	实体管理接口	5
P0	规则管理接口	7
P0	WebSocket推送	-
P0	异步任务	3

Phase 3（Week 5-6）：AI + 导出 + 系统管理

优先级	模块	接口数
P1	AI服务接口	5
P0	项目导出	1
P1	角色管理接口	8
P1	权限管理接口	4
P2	数据字典接口	8
P2	系统配置接口	4
P2	日志接口	4

十、总结

10.1 核心数据

维度	数值
Maven模块	3个（common, graph, app）
业务模块	9个（system, project, attachment, entity, rule, file, ai, websocket, task）
接口总数	93个
数据库表	20张
数据库视图	7个
节点类型	6种
关系类型	11种

10.2 核心设计决策

单层项目结构: 前端只关心"项目"，不区分模板/报告
图数据库架构: 关系型数据库实现图结构，灵活扩展
视图抽象: 通过数据库视图简化业务查询
规则引擎预留: DSL对接接口预留，待规则引擎团队提供接口后实现
异步任务: 文件解析、NER识别等耗时操作异步执行，WebSocket推送进度

【定稿】后端开发结构文档.md 39 KB Pysyvä linkki Historia Raaka

灵越智报 2.0 - 后端开发结构文档（定稿）

一、技术选型

1.1 核心框架

1.2 文件处理

1.3 AI与外部服务

1.4 实时通信

1.5 文件存储

二、项目结构

2.1 Maven模块结构

三、接口设计

3.1 认证接口（7个）

登录接口详情

3.2 用户管理接口（11个）

用户列表接口详情

3.3 角色管理接口（8个）

3.4 权限管理接口（4个）

3.5 数据字典接口（8个）

3.6 系统配置接口（4个）

3.7 日志接口（4个）

3.8 项目管理接口（8个）⭐

创建项目接口详情

项目详情接口详情

项目列表接口详情

3.9 要素管理接口（5个）

添加要素定义接口详情

3.10 要素值接口（4个）

更新要素值接口详情

3.11 附件管理接口（6个）

上传附件接口详情

3.12 实体管理接口（5个）

获取项目所有实体接口详情

3.13 规则管理接口（7个）

创建规则接口详情

执行规则接口详情

3.14 AI服务接口（5个）

AI对话接口详情

3.15 文件服务接口（4个）

3.16 任务接口（3个）

3.17 接口统计

四、核心业务流程

4.1 创建项目流程

4.2 附件上传与解析流程

4.3 规则创建与执行流程

4.4 项目导出流程

五、WebSocket 消息设计

5.1 连接地址

5.2 消息格式

5.3 消息类型

六、统一返回格式

6.1 成功响应

6.2 分页响应

6.3 错误响应

6.4 错误码定义

七、规则引擎对接（预留）

7.1 当前状态

7.2 对接设计

7.3 已知信息

7.4 待确认事项

八、配置文件模板

8.1 application.yml

九、开发优先级

Phase 1（Week 1-2）：基础设施 + 用户系统 + 项目管理

Phase 2（Week 3-4）：附件 + 实体 + 规则

Phase 3（Week 5-6）：AI + 导出 + 系统管理

十、总结

10.1 核心数据

10.2 核心设计决策

【定稿】后端开发结构文档.md 39 KB

Pysyvä linkki Historia Raaka