灵越智报 2.0 - 后端开发结构设计（简化版）

设计时间: 2026-02-12
核心变化: 前端只关心"项目"概念，不区分项目/模板/报告
技术栈: Spring Boot 3.x + PostgreSQL + 图数据库架构

一、核心设计理念

1.1 简化的图数据库思想

单层结构: 只有"项目"概念，包含要素定义和内容
节点驱动: 项目、要素、值、附件、实体、规则均为节点
关系驱动: 通过边（Edge）描述节点间的关联关系
属性灵活: 节点和边的属性通过 KV 存储，支持动态扩展

1.2 前后端分离

前端: Vue 3 + TypeScript + Vite
后端: Spring Boot 3.x + MyBatis-Plus
通信: RESTful API + WebSocket (实时推送)

二、模块划分

2.1 核心模块结构

lingyue-zhibao-backend/
├── common/                          # 公共模块
│   ├── core/                        # 核心工具
│   │   ├── exception/              # 统一异常处理
│   │   ├── result/                 # 统一返回结果
│   │   ├── config/                 # 全局配置
│   │   └── util/                   # 工具类
│   ├── security/                    # 安全模块
│   │   ├── jwt/                    # JWT工具
│   │   ├── filter/                 # 安全过滤器
│   │   └── handler/                # 认证处理器
│   └── graph/                       # 图数据库基础
│       ├── entity/                 # 图实体基类
│       ├── mapper/                 # 图Mapper基类
│       └── service/                # 图服务基类
│
├── modules/                         # 业务模块
│   ├── system/                     # 系统管理模块
│   │   ├── controller/
│   │   │   ├── UserController.java
│   │   │   ├── RoleController.java
│   │   │   ├── PermissionController.java
│   │   │   ├── DictController.java
│   │   │   └── ConfigController.java
│   │   ├── service/
│   │   ├── mapper/
│   │   └── entity/
│   │
│   ├── graph/                      # 图数据核心模块 ⭐
│   │   ├── controller/
│   │   │   ├── NodeController.java          # 节点通用操作
│   │   │   ├── EdgeController.java          # 关系通用操作
│   │   │   └── PropertyController.java      # 属性操作
│   │   ├── service/
│   │   │   ├── NodeService.java
│   │   │   ├── EdgeService.java
│   │   │   └── PropertyService.java
│   │   ├── mapper/
│   │   │   ├── NodeMapper.java
│   │   │   ├── EdgeMapper.java
│   │   │   └── PropertyMapper.java
│   │   └── entity/
│   │       ├── Node.java
│   │       ├── Edge.java
│   │       ├── NodeProperty.java
│   │       └── EdgeProperty.java
│   │
│   ├── project/                    # 项目管理模块 ⭐⭐⭐
│   │   ├── controller/
│   │   │   ├── ProjectController.java       # 项目CRUD
│   │   │   ├── ElementController.java       # 要素定义管理
│   │   │   ├── ValueController.java         # 要素值管理
│   │   │   └── ProjectExportController.java # 项目导出
│   │   ├── service/
│   │   │   ├── ProjectService.java
│   │   │   ├── ElementService.java
│   │   │   ├── ValueService.java
│   │   │   ├── ProjectCopyService.java
│   │   │   └── ProjectExportService.java
│   │   ├── dto/
│   │   │   ├── ProjectCreateDTO.java
│   │   │   ├── ProjectUpdateDTO.java
│   │   │   ├── ProjectVO.java
│   │   │   ├── ElementDefineDTO.java
│   │   │   └── ValueUpdateDTO.java
│   │   └── enums/
│   │       ├── ProjectStatus.java
│   │       └── ElementType.java      # text/paragraph/table
│   │
│   ├── attachment/                 # 附件管理模块
│   │   ├── controller/
│   │   │   └── AttachmentController.java
│   │   ├── service/
│   │   │   ├── AttachmentService.java
│   │   │   ├── AttachmentParseService.java
│   │   │   └── AttachmentUploadService.java
│   │   ├── dto/
│   │   │   ├── AttachmentUploadDTO.java
│   │   │   └── AttachmentVO.java
│   │   └── enums/
│   │       ├── AttachmentType.java   # pdf/docx/xlsx
│   │       └── ParseStatus.java
│   │
│   ├── entity/                     # 实体管理模块（NER结果）
│   │   ├── controller/
│   │   │   └── EntityController.java
│   │   ├── service/
│   │   │   ├── EntityService.java
│   │   │   ├── EntityMergeService.java
│   │   │   └── EntityExtractionService.java
│   │   ├── dto/
│   │   │   ├── EntityCreateDTO.java
│   │   │   ├── EntityMergeDTO.java
│   │   │   └── EntityVO.java
│   │   └── enums/
│   │       ├── EntityType.java       # ORG/PERSON/DATE/NUMBER/LOCATION
│   │       └── BusinessLabel.java
│   │
│   ├── rule/                       # 规则引擎模块 ⭐
│   │   ├── controller/
│   │   │   └── RuleController.java
│   │   ├── service/
│   │   │   ├── RuleService.java
│   │   │   ├── RuleExecutor.java
│   │   │   └── RuleConfigService.java
│   │   ├── executor/               # 规则执行器
│   │   │   ├── DirectEntityExecutor.java    # 直接引用实体
│   │   │   ├── RegexExtractExecutor.java    # 正则提取
│   │   │   ├── LLMGenerateExecutor.java     # LLM生成
│   │   │   └── TableAggregateExecutor.java  # 表格聚合
│   │   ├── dto/
│   │   │   ├── RuleCreateDTO.java
│   │   │   ├── RuleExecuteDTO.java
│   │   │   └── RuleVO.java
│   │   └── enums/
│   │       ├── RuleType.java         # direct_entity/extraction/llm/aggregate
│   │       └── ActionType.java
│   │
│   ├── file/                       # 文件服务模块
│   │   ├── controller/
│   │   │   ├── FileUploadController.java
│   │   │   └── FileDownloadController.java
│   │   ├── service/
│   │   │   ├── FileStorageService.java
│   │   │   ├── FileParseService.java
│   │   │   └── FilePreviewService.java
│   │   ├── parser/                 # 文件解析器
│   │   │   ├── PdfParser.java
│   │   │   ├── DocxParser.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/                 # 外部AI服务客户端
│   │   │   ├── OpenAIClient.java
│   │   │   └── NerServiceClient.java
│   │   └── dto/
│   │       ├── NerRequest.java
│   │       ├── NerResult.java
│   │       └── LLMRequest.java
│   │
│   └── websocket/                  # WebSocket模块
│       ├── handler/
│       │   ├── ParseProgressHandler.java
│       │   ├── AIAssistantHandler.java
│       │   └── NotificationHandler.java
│       └── config/
│           └── WebSocketConfig.java
│
└── Application.java                # 启动类

三、核心业务流程设计

3.1 创建项目流程（简化）

用户操作: 新建项目
    ↓
1. 创建 PROJECT 节点
   - 可选择预设模板类型
   - 或选择"从样本创建"
    ↓
2. 如果选择预设模板:
   - 自动创建要素定义（ELEMENT节点）
   - 创建空的要素值（VALUE节点）
   - 建立关系: PROJECT --HAS_ELEMENT--> ELEMENT
   - 建立关系: PROJECT --HAS_VALUE--> VALUE
    ↓
3. 如果选择从样本创建:
   - 上传样本文档作为附件
   - 解析文档，提取要素定义
   - 创建ELEMENT和VALUE节点
    ↓
4. 返回项目ID，跳转到编辑器

接口设计:

POST /api/v1/projects
{
  "title": "成都院2024年复审报告",
  "description": "成都院电力安全生产标准化复审报告",
  "templateType": "电力安全生产标准化复审报告",  // 可选
  "sampleFileId": null  // 或提供样本文件ID
}

Response:
{
  "code": 200,
  "data": {
    "id": 10,
    "title": "成都院2024年复审报告",
    "status": "draft",
    "templateType": "电力安全生产标准化复审报告",
    "elementCount": 8,
    "filledCount": 1
  }
}

3.2 附件上传与解析流程

用户操作: 上传附件
    ↓
1. 文件上传到 OSS/本地存储
    ↓
2. 创建 ATTACHMENT 节点
   - 保存文件路径、类型、大小等
   - 建立 PROJECT --HAS_ATTACHMENT--> ATTACHMENT
    ↓
3. 异步解析任务:
   a. 文档解析（提取文本）
   b. NER实体识别
   c. 创建 ENTITY 节点
   d. 建立 ATTACHMENT --HAS_ENTITY--> ENTITY
    ↓
4. WebSocket推送解析进度
    ↓
5. 解析完成，返回实体列表

接口设计:

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

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

3.3 规则创建与执行流程

用户操作: 从附件实体添加规则
    ↓
1. 选择实体（如"BZ-0092-2024"）
2. 选择目标要素（如"项目编号"）
    ↓
3. 创建 RULE 节点:
   - rule_type: "direct_entity"
   - action_type: "use_entity_value"
    ↓
4. 建立关系:
   - PROJECT --HAS_RULE--> RULE
   - RULE --FOR_ELEMENT--> ELEMENT
   - RULE --INPUT_FROM--> ENTITY
    ↓
5. 执行规则:
   - 获取 ENTITY.name
   - 更新 VALUE 节点的 value_text
   - 更新 is_filled = true
    ↓
6. 返回执行结果

接口设计:

POST /api/v1/projects/{projectId}/rules
{
  "elementKey": "basicInfo.projectCode",
  "ruleType": "direct_entity",
  "actionType": "use_entity_value",
  "inputs": [
    {
      "inputKey": "entity",
      "sourceType": "entity",
      "sourceId": 502
    }
  ]
}

Response:
{
  "code": 200,
  "data": {
    "id": 600,
    "elementKey": "basicInfo.projectCode",
    "executeStatus": "success",
    "outputValue": "BZ-0092-2024"
  }
}

四、核心接口设计

4.1 用户管理接口

参考原设计文档，包含：

认证接口（7个）
用户管理接口（11个）
角色管理接口（8个）
权限管理接口（6个）
数据字典接口（8个）
系统配置接口（4个）
操作日志接口（4个）
登录日志接口（2个）

4.2 项目管理接口

方法	路径	说明
GET	`/api/v1/projects`	获取项目列表（分页）
GET	`/api/v1/projects/{id}`	获取项目详情
POST	`/api/v1/projects`	创建项目
PUT	`/api/v1/projects/{id}`	更新项目
DELETE	`/api/v1/projects/{id}`	删除项目
POST	`/api/v1/projects/{id}/copy`	复制项目
POST	`/api/v1/projects/{id}/archive`	归档项目
POST	`/api/v1/projects/{id}/export`	导出项目

4.3 要素管理接口

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

4.4 要素值接口

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

4.5 附件管理接口

方法	路径	说明
POST	`/api/v1/projects/{id}/attachments/upload`	上传附件
GET	`/api/v1/projects/{id}/attachments`	获取附件列表
GET	`/api/v1/attachments/{id}`	获取附件详情
POST	`/api/v1/attachments/{id}/parse`	触发附件解析
DELETE	`/api/v1/attachments/{id}`	删除附件
GET	`/api/v1/attachments/{id}/entities`	获取附件实体列表

4.6 实体管理接口

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

4.7 规则管理接口

方法	路径	说明
GET	`/api/v1/projects/{projectId}/rules`	获取项目规则列表
GET	`/api/v1/rules/{id}`	获取规则详情
POST	`/api/v1/projects/{projectId}/rules`	创建规则
PUT	`/api/v1/rules/{id}`	更新规则
DELETE	`/api/v1/rules/{id}`	删除规则
POST	`/api/v1/rules/{id}/execute`	执行规则
POST	`/api/v1/projects/{projectId}/rules/execute-all`	批量执行规则

4.8 AI服务接口

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

五、数据访问层设计

5.1 图数据库基础服务

/**
 * 节点服务基类
 */
@Service
public class NodeService {
    
    @Autowired
    private NodeMapper nodeMapper;
    
    @Autowired
    private NodePropertyMapper propertyMapper;
    
    /**
     * 创建节点
     */
    public Long createNode(String nodeType, String nodeKey, String name, Long createdBy) {
        Node node = new Node();
        node.setNodeType(nodeType);
        node.setNodeKey(nodeKey);
        node.setName(name);
        node.setCreatedBy(createdBy);
        nodeMapper.insert(node);
        return node.getId();
    }
    
    /**
     * 设置节点属性
     */
    public void setProperty(Long nodeId, String propKey, Object value) {
        NodeProperty property = new NodeProperty();
        property.setNodeId(nodeId);
        property.setPropKey(propKey);
        
        if (value instanceof String) {
            property.setPropValue((String) value);
        } else if (value instanceof Number) {
            property.setPropNumber(new BigDecimal(value.toString()));
        } else if (value instanceof Date) {
            property.setPropDate((Date) value);
        } else {
            property.setPropJson(JSON.toJSONString(value));
        }
        
        propertyMapper.insertOrUpdate(property);
    }
}

5.2 项目查询服务（基于视图）

/**
 * 项目查询服务（基于视图）
 */
@Service
public class ProjectQueryService {
    
    @Autowired
    private ProjectViewMapper projectViewMapper;
    
    /**
     * 获取项目列表
     */
    public Page<ProjectVO> listProjects(ProjectQueryDTO query) {
        return projectViewMapper.selectProjectPage(query);
    }
    
    /**
     * 获取项目详情
     */
    public ProjectDetailVO getProjectDetail(Long projectId) {
        // 查询项目基本信息（v_projects视图）
        ProjectVO project = projectViewMapper.selectById(projectId);
        
        // 查询要素定义列表（v_project_elements视图）
        List<ElementVO> elements = projectViewMapper.selectElementsByProjectId(projectId);
        
        // 查询要素值列表（v_project_values视图）
        List<ValueVO> values = projectViewMapper.selectValuesByProjectId(projectId);
        
        // 查询附件列表（v_attachments视图）
        List<AttachmentVO> attachments = projectViewMapper.selectAttachmentsByProjectId(projectId);
        
        // 查询规则列表（v_rules视图）
        List<RuleVO> rules = projectViewMapper.selectRulesByProjectId(projectId);
        
        // 组装返回
        ProjectDetailVO detail = new ProjectDetailVO();
        detail.setProject(project);
        detail.setElements(elements);
        detail.setValues(values);
        detail.setAttachments(attachments);
        detail.setRules(rules);
        
        return detail;
    }
}

六、技术选型

6.1 核心框架

Spring Boot: 3.2.x
MyBatis-Plus: 3.5.x
PostgreSQL: 15.x
Redis: 7.x

6.2 文件处理

Apache POI: Word/Excel解析
PDFBox: PDF解析
Tika: 通用文件解析

6.3 AI服务

OpenAI API: GPT-4调用
Python NER服务: 实体识别（独立服务）
Feign: 服务间调用

6.4 实时通信

Spring WebSocket: 实时推送
STOMP: 消息协议

6.5 任务调度

Spring Task: 异步任务
XXL-Job: 分布式任务调度（可选）

6.6 文件存储

本地存储: 开发环境
MinIO/OSS: 生产环境

七、总结

7.1 核心变化

维度	原设计	简化设计
概念层级	3层（项目/模板/报告）	1层（项目）
节点类型	9种	6种
关系类型	11种	8种
核心模块	3个（项目/模板/报告）	1个（项目）
接口数量	~100个	~80个

7.2 优势

✅ 用户体验: 概念简单，操作直观
✅ 开发效率: 前后端代码量减少30%
✅ 维护成本: 状态管理简化，Bug更少
✅ 灵活性: 保留图数据库优势，扩展性不减

7.3 模板功能实现方式

虽然前端不区分模板，但可以通过以下方式实现模板功能：

系统预设模板: 在项目创建时选择模板类型
用户自定义模板: 将项目"保存为模板"（设置is_template=true）
从模板创建: 复制模板项目，清空要素值

这样既简化了用户理解，又保留了模板复用的能力。

后端开发结构设计-简化版.md 19 KB Pysyvä linkki Historia Raaka

灵越智报 2.0 - 后端开发结构设计（简化版）

一、核心设计理念

1.1 简化的图数据库思想

1.2 前后端分离

二、模块划分

2.1 核心模块结构

三、核心业务流程设计

3.1 创建项目流程（简化）

3.2 附件上传与解析流程

3.3 规则创建与执行流程

四、核心接口设计

4.1 用户管理接口

4.2 项目管理接口

4.3 要素管理接口

4.4 要素值接口

4.5 附件管理接口

4.6 实体管理接口

4.7 规则管理接口

4.8 AI服务接口

五、数据访问层设计

5.1 图数据库基础服务

5.2 项目查询服务（基于视图）

六、技术选型

6.1 核心框架

6.2 文件处理

6.3 AI服务

6.4 实时通信

6.5 任务调度

6.6 文件存储

七、总结

7.1 核心变化

7.2 优势

7.3 模板功能实现方式

后端开发结构设计-简化版.md 19 KB

Pysyvä linkki Historia Raaka