# 灵越智报 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，跳转到编辑器
```

**接口设计**:
```java
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. 解析完成，返回实体列表
```

**接口设计**:
```java
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. 返回执行结果
```

**接口设计**:
```java
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 图数据库基础服务

```java
/**
 * 节点服务基类
 */
@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 项目查询服务（基于视图）

```java
/**
 * 项目查询服务（基于视图）
 */
@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 模板功能实现方式

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

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

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