qc-ns/doc/PROJECT_STRUCTURE.md

QC-NS 项目结构说明

项目概述

qc-ns 是基于 QConline 项目重构的新版本，主要针对新国标的质控因子进行识别和质控。

技术栈

• Java 17
• Spring Boot 2.7.18
• MyBatis-Plus
• OpenCV 4.8.0
• MySQL
• Redis

项目结构

模块划分

项目按照功能模块进行划分，每个模块包含以下标准结构：

• controller/ - 控制器层
• service/ - 服务接口层
  • impl/ - 服务实现层
• mapper/ - 数据访问层
  • xml/ - MyBatis XML 映射文件
• entity/ - 实体类
• request/ - 请求 DTO
• response/ - 响应 DTO

核心模块

1. QC 模块 (modules/qc)

质控相关功能模块

Entity:

• QcFactor - 质控因子
• QcStandard - 质控标准
• QcStandardFactor - 质控标准因子关联
• QcTask - 质控任务
• QcResult - 质控结果
• QcResultSummary - 质控结果汇总
• QcPresetConfig - 质控预设配置

子模块:

• ai/ - AI 质控相关
• engine/ - 质控引擎
• preset/ - 预设配置
• task/ - 任务调度

2. Study 模块 (modules/study)

检查数据管理模块

Entity:

• StudyInfo - 检查信息

Service:

• StudyQueryService - 检查查询服务
• DataManageService - 数据管理服务

3. Patient 模块 (modules/patient)

患者信息管理模块

Entity:

• PatientInfo - 患者信息

4. Institution 模块 (modules/institution)

机构管理模块

Entity:

• Institution - 机构信息
• UserInstitution - 用户机构关联

5. System 模块 (modules/system)

系统管理模块

Entity:

• SysUser - 系统用户
• Menu - 菜单
• UserMenu - 用户菜单关联
• SysLog - 系统日志

6. Report 模块 (modules/report)

报告管理模块

Entity:

• ReportInfo - 报告信息

7. DICOM 模块 (modules/dicom)

DICOM 影像处理模块

Entity:

• DicomInstanceInfo - DICOM 实例信息
• SeriesInfo - 序列信息
• StudySplitRecord - 检查拆分记录

Service:

• DicomService - DICOM 服务
• DicomImageService - DICOM 图像服务
• DicomAsyncService - DICOM 异步服务

8. PACS 模块 (modules/pacs)

PACS 对接模块

Service:

• PACS 相关服务

9. User 模块 (modules/user)

用户管理模块

Controller:

• 用户相关控制器

Service:

• 用户服务

10. Auth 模块 (modules/auth)

认证授权模块

Controller:

• 认证相关控制器

公共组件

component 包

• response/ - 统一响应处理
• aop/ - AOP 切面
• jackson/ - Jackson 配置

common 包

• 通用工具类和异常处理

config 包

• 系统配置类

security 包

• 安全相关配置

utils 包

• 工具类

MyBatis 配置

Mapper 扫描路径

mybatis-plus:
  mapper-locations: classpath*:com/zskk/qconline/modules/**/mapper/xml/*.xml
  type-aliases-package: com.zskk.qcns.modules.*.entity

Mapper XML 文件位置

所有 Mapper XML 文件统一放在各模块的 mapper/xml/ 目录下，例如：

• QC 模块: modules/qc/mapper/xml/*.xml
• Study 模块: modules/study/mapper/xml/*.xml
• Patient 模块: modules/patient/mapper/xml/*.xml

开发规范

包命名规范

• Entity: com.zskk.qcns.modules.{模块}.entity
• Mapper: com.zskk.qcns.modules.{模块}.mapper
• Service: com.zskk.qcns.modules.{模块}.service
• Service Impl: com.zskk.qcns.modules.{模块}.service.impl
• Controller: com.zskk.qcns.modules.{模块}.controller

文件组织原则

1. 按功能模块划分，而不是按技术层次
2. 每个模块保持独立性，减少模块间耦合
3. 通用功能放在 common 或 component 包
4. 配置文件统一管理

数据库配置

数据源

• Host: 127.0.0.1:3306
• Database: qconline
• Username: root

Redis

• Host: localhost:6379
• Database: 0

与原项目的差异

结构改进

1. 模块化: 从全局共享的 entity/mapper 改为按模块独立管理
2. 清晰的层次: 每个模块都有完整的 MVC 结构
3. XML 文件管理: 从统一的 resources/mapper 改为各模块的 mapper/xml 目录
4. 包路径优化: 所有 import 语句都指向具体模块，避免命名冲突

优势

1. 模块职责清晰，易于维护
2. 代码组织更规范，符合 DDD 思想
3. 便于团队协作，不同模块可独立开发
4. 降低耦合度，提高代码复用性

下一步工作

1. 业务优化: 实现新国标质控因子的识别和转换
2. 任务调度: 实现周期性质控任务（按周、按月）
3. 性能优化: DICOM 图像转换缓存策略
4. 功能扩展: 质控标准的灵活组合

注意事项

1. 确保所有 Mapper 接口的包名与 XML 文件的 namespace 一致
2. Entity 类的包名要与 MyBatis 的 type-aliases-package 配置匹配
3. 新增模块时遵循现有的目录结构规范
4. Service 实现类统一放在 service/impl 包下