Java_Dm/PRODUCT_SOURCE_ARCHITECTURE.md

产品源代码整体架构说明

本文档基于当前仓库代码结构整理，用于快速理解 LSERP-MES / WebErp 后端工程的模块边界、请求调用链、数据访问方式和主要扩展点。

1. 工程概览

本项目是一个基于 Spring Boot 的 Java 后端服务，代码主体位于 WebErp/weberp。整体采用 Maven 父子模块结构，当前父工程 WebErp 下只有一个可执行子模块 weberp。

层级	路径	说明
仓库根目录	.	README、历史构建产物和项目根文件
Maven 父工程	WebErp/pom.xml	packaging=pom，聚合 weberp 子模块，统一部分依赖版本
应用子模块	WebErp/weberp	Spring Boot 可执行 JAR 模块，主类为 org.example.WebErpApplication
主源码	WebErp/weberp/src/main/java/org/example	Controller、Handler、Impl、Entity、Utils 等后端源码
配置资源	WebErp/weberp/src/main/resources	application.properties、MyBatis 配置、Mapper XML、语言包
测试代码	WebErp/weberp/src/test/java/org/example	单元/回归测试入口

关键技术栈：

• Spring Boot Web 3.4.3：HTTP 服务和依赖注入。
• Spring Security 3.4.3：接口访问控制。
• MyBatis 3.5.17 / mybatis-spring-boot-starter 3.0.4：Mapper XML 数据访问。
• JdbcTemplate / NamedParameterJdbcTemplate：大量动态 SQL 和存储过程调用。
• HikariCP：数据库连接池。
• PageHelper：分页插件，当前方言配置为 dm。
• JJWT：Token 生成、刷新和校验辅助。
• Redis：缓存或会话相关基础设施。
• Aspose / Spire / iText / JavaCV / ZXing：Office、PDF、音视频、二维码等文件处理能力。

2. 总体架构图

flowchart TB
    Client["Web / App / 桌面前端"]

    subgraph SpringBoot["Spring Boot 应用: weberp"]
        App["WebErpApplication"]
        Security["SecurityConfig<br/>允许 /Api/* 指定入口"]
        Cors["CorsConfig<br/>跨域和凭证配置"]

        subgraph Entry["统一 API 入口层"]
            AuthCtrl["AuthController<br/>/Api/SysUserAjaxApi"]
            ModuleCtrl["ModuleAjaxController<br/>/Api/ModuleAjaxApi"]
            SystemCtrl["SystemAjaxApi<br/>/Api/SystemAjaxApi"]
            FileCtrl["FileUploadController<br/>/Api/FileUploadApi"]
            ToolsCtrl["ToolsHandler<br/>/Api/ToolsHandler"]
        end

        subgraph Handler["公共请求处理层"]
            BaseHandler["BaseHandler<br/>method/action 反射分发<br/>登录校验 / 参数校验 / 响应输出"]
            OptBaseHandler["OptBaseHandler<br/>注入 JdbcTemplate / Mapper / SQL Factory"]
            RequestHandler["RequestHandler<br/>普通参数 / pms / gzip 参数解析"]
        end

        subgraph ServiceImpl["业务服务与实现层"]
            ModuleService["ModuleImplService"]
            AuthService["AuthService"]
            ModuleImpl["ModuleImpl<br/>模块配置 / 数据 / 审核 / 桌面"]
            DataImpl["DataImpl<br/>动态 SQL / 表结构 / 存储过程"]
            SysUserImpl["SysUserImpl<br/>登录 / 用户 / 账套"]
            SystemImpl["SystemImpl<br/>系统菜单 / 系统信息"]
            FileImpl["FileImpl<br/>文件与附件"]
            MapImpl["MapImpl<br/>区域地图"]
            UpdateImpl["UpdateImpl<br/>系统更新脚本"]
        end

        subgraph Domain["领域模型和工具层"]
            Entity["Entity<br/>BaseResponse / Module / Bill / Control / Audit"]
            Utils["Utils<br/>DbOperator / JSON / Cache / JwtHelp / FileUtil / WebConfig"]
            Office["Office<br/>文档处理"]
        end

        subgraph DataAccess["数据访问层"]
            Factory["AllInOneSqlFactory"]
            Provider["AllInOneSqlProvider<br/>dm / kingbase 实现"]
            Mappers["MyBatis Mapper<br/>CRMapper / DMCrmMapper / PageBreaksMapper"]
            Xml["resources/mapper/*.xml"]
            Jdbc["JdbcTemplate<br/>NamedParameterJdbcTemplate"]
        end
    end

    DB[("业务数据库<br/>达梦 / 人大金仓 / SQL Server / MySQL 驱动")]
    Redis[("Redis")]
    FileStore[("文件存储目录")]

    Client --> Security
    Security --> Cors
    Cors --> Entry
    Entry --> BaseHandler
    BaseHandler --> OptBaseHandler
    BaseHandler --> RequestHandler
    OptBaseHandler --> ServiceImpl
    ServiceImpl --> Domain
    ServiceImpl --> Factory
    Factory --> Provider
    Provider --> Mappers
    Mappers --> Xml
    ServiceImpl --> Jdbc
    Mappers --> DB
    Jdbc --> DB
    Utils --> Redis
    FileImpl --> FileStore
    Office --> FileStore

3. 请求处理架构

项目的 HTTP 入口不是标准的“一个 URL 对应一个业务方法”的 REST 风格，而是多个 Ajax 入口统一接收请求，再由 BaseHandler 根据请求参数中的 method 或 action 反射调用同名业务方法。

sequenceDiagram
    participant C as 前端
    participant Ctrl as Ajax Controller
    participant BH as BaseHandler
    participant BI as OptBaseImpl/BaseImpl
    participant Impl as 业务 Impl
    participant DB as 数据库

    C->>Ctrl: GET/POST /Api/ModuleAjaxApi?method=GetModuleData
    Ctrl->>BH: processRequest(request)
    BH->>BI: initSystemParams / initReqPms
    BH->>BH: 读取 method/action
    BH->>BH: 查找同名 public 方法
    BH->>BH: 读取 @RequestCheck
    BH->>BI: 登录校验 / 参数校验 / 当前用户上下文
    BH->>Impl: 反射调用业务方法
    Impl->>DB: Mapper 或 JdbcTemplate 查询/更新
    DB-->>Impl: 数据结果
    Impl-->>BH: BaseResponse
    BH-->>C: text/plain;charset=UTF-8 JSON 响应

主要机制：

• Controller 只提供统一入口，例如 /Api/ModuleAjaxApi/**、/Api/SystemAjaxApi/**、/Api/SysUserAjaxApi/**。
• BaseHandler#getMethod() 从 method 或 action 参数获取业务方法名。
• BaseHandler#processRequest() 负责参数初始化、登录检查、@RequestCheck 校验、缓存判断、反射调用、日志记录、Token 刷新和响应输出。
• RequestHandler 兼容普通 query/form 参数、pms 加密参数、gzip/deflate 压缩请求体。
• OptBaseHandler 在 BaseHandler 基础上注入 JdbcTemplate、CRMapper、DMCrmMapper 和 AllInOneSqlFactory，并创建 OptBaseImpl 作为业务上下文。

4. 源码包职责

包	主要职责
org.example	Spring Boot 启动入口 WebErpApplication
Api	公共请求处理、统一响应、登录状态、日志、单用户控制
Auth	登录、验证码、密码、Token、安全辅助
Config	CORS 配置
SystemApi	系统信息、系统菜单、账套/系统版本等接口
ModuleApi	核心模块 Ajax 接口、模块 DTO、MyBatis Mapper
FileUploadApi	文件上传、下载、附件权限与附件记录维护
Impl	主要业务实现层，包含模块、数据、用户、系统、文件、地图、短信、更新等实现
Impl.Sql	多数据库 SQL Provider 和工厂，按数据库类型生成 SQL 或调用对应 Mapper
Service	业务接口定义，例如 ModuleImplService、AuthService、IModuleEvent
Entity	响应对象、模块配置对象、单据对象、控件对象、审核对象、异常对象等领域模型
Enums	系统枚举、参数方向、任务类型、登录状态等
Utils	通用工具，包括配置读取、JSON、缓存、JWT、文件、压缩、加密、数据库操作等
Office	Office/Word 文档生成与转换相关工具
PageBreaksApi	分页符相关 Mapper

5. 核心业务模块

5.1 认证与用户

入口：AuthController，路径为 /Api/SysUserAjaxApi。

核心实现：

• SysUserImpl implements AuthService：登录、手机号登录、切换账套、重置密码、验证码、登录状态维护。
• JwtHelp / JwtUtils：Token 创建、刷新、缓存和解析辅助。
• SingleUserHandler：单用户登录控制和会话互斥。
• SafetyUtil：安全辅助逻辑。

典型方法：

• Login
• CheckLogin
• LoginOut
• ChangeServer
• ResetPwd
• GenerateCaptcha
• SendPhoneCode

5.2 系统基础信息

入口：SystemAjaxApi，路径为 /Api/SystemAjaxApi。

核心实现：

• SystemImpl：系统列表、系统信息、登录信息、菜单、数据库服务器、Web 更新信息等。

典型方法：

• GetSystems
• GetSystemInfo
• GetSysMenus
• GetSystemLoginInfo
• GetProSysType
• GetDbServer
• GetWebUpdateInfo

5.3 动态模块与单据

入口：ModuleAjaxController，路径为 /Api/ModuleAjaxApi。

这是项目最核心的业务入口，围绕“模块配置驱动”的 ERP/MES 页面和单据能力展开。前端传入 ModuleId、MenuId、method 等参数后，后端从系统配置表和业务表中组装模块元数据、字段、列表、明细、审核、附件、右键菜单、桌面数据等。

核心实现：

• ModuleImpl implements ModuleImplService：模块初始化、字段数据、模块数据、单据保存、审核、附件、权限、桌面配置。
• DataImpl：动态 SQL、表结构、字段、主键、存储过程、附件权限、模块配置数据读取。
• ModuleEventImpl：模块数据加载、保存、状态变化、附件上传等事件扩展点。
• MapImpl：区域和地图相关接口实现。

典型方法：

• GetModuleIniParams
• GetModuleData
• GetFieldData
• GetBillIniParams
• AddOrUpd
• Delete
• SaveBill
• GetModuleCfg
• GetModuleDetailsData
• GetAuditHistory
• GetRoles / SaveRoles
• GetBSDesktopData

5.4 文件与附件

入口：FileUploadController，路径为 /Api/FileUploadApi。

核心实现：

• FileImpl：文件保存、校验、附件基础记录。
• FileUtil / PathUtil / ZipUtil：路径处理、实际文件保存/删除、批量压缩。
• ModuleImpl / DataImpl：附件权限检查、附件记录入库、模块关联。
• OfficeUtil / CreateWordUtil：文档处理、预览或转换相关能力。

典型方法：

• DoWebUpload
• DownLoadFiels
• DoDelete
• SaveViewModule

6. 数据访问架构

项目同时使用 MyBatis Mapper XML 和 Spring JdbcTemplate。

flowchart LR
    Business["业务实现<br/>ModuleImpl / DataImpl / SysUserImpl / SystemImpl"]
    Factory["AllInOneSqlFactory"]
    Type["custom.database.type<br/>dm / kingbase"]
    DmProvider["DmAllInOneSqlProvider"]
    KbProvider["KingbaseAllInOneSqlProvider"]
    DmMapper["DMCrmMapper<br/>DMCrmMapper.xml"]
    CrMapper["CRMapper<br/>CustomerMapper.xml"]
    PageMapper["PageBreaksMapper<br/>PageBreaks.xml"]
    Jdbc["JdbcTemplate / NamedParameterJdbcTemplate"]
    DB[("数据库")]

    Business --> Factory
    Type --> Factory
    Factory --> DmProvider
    Factory --> KbProvider
    DmProvider --> DmMapper
    KbProvider --> CrMapper
    Business --> PageMapper
    Business --> Jdbc
    DmMapper --> DB
    CrMapper --> DB
    PageMapper --> DB
    Jdbc --> DB

数据访问特点：

• application.properties 通过 custom.database.type 指定当前数据库类型，当前配置为 dm。
• AllInOneSqlFactory#createProvider() 根据数据库类型创建 DmAllInOneSqlProvider 或 KingbaseAllInOneSqlProvider。
• 达梦数据库主要走 DMCrmMapper 和 DMCrmMapper.xml。
• 人大金仓或通用查询主要走 CRMapper 和 CustomerMapper.xml。
• 大量复杂业务仍直接使用 JdbcTemplate 或 NamedParameterJdbcTemplate 拼装动态 SQL。
• mybatis-config.xml 配置了 PageHelper 插件，方言为 dm。

7. 配置与运行边界

主要配置文件：WebErp/weberp/src/main/resources/application.properties。

关键配置项：

• server.port=8088：服务端口。
• custom.database.type=dm：当前 SQL 方言/Provider 选择。
• spring.datasource.*：数据库连接、驱动和 Hikari 连接池配置。
• mybatis.mapper-locations=classpath:mapper/*.xml：Mapper XML 位置。
• pagehelper.helper-dialect=dm：分页方言。
• spring.data.redis.*：Redis 连接配置。
• language=Language_CN：语言包选择。
• jwt.expiration、SingleUser、RestInitPwd、LockErrPwd 等：登录和安全相关开关。

安全边界：

• SecurityConfig 当前只放行指定 /Api/* 入口，其余请求默认拒绝。
• CorsConfig 明确列出允许的前端来源，并允许携带凭证。
• Controller 入口放行后，业务级登录校验主要由 BaseHandler 和 @RequestCheck 决定。

注意：配置文件中包含数据库、Redis 等环境信息，生产环境建议通过环境变量、外部配置中心或部署平台密钥管理注入，避免将敏感连接信息写入源码仓库。

8. 模块配置驱动模型

从代码结构看，系统大量业务并非通过固定 Java DTO 和固定 SQL 完成，而是依赖数据库中的模块配置表、字段配置、控件配置、菜单配置和权限配置动态组装页面与数据。

flowchart TB
    Front["前端请求<br/>ModuleId / MenuId / method"]
    Init["GetModuleIniParams"]
    ConfigTables["模块配置表<br/>字段 / 控件 / 菜单 / 权限 / 审核"]
    EntityBuild["Entity.System / Entity.Control<br/>组装模块模型"]
    DataQuery["DataImpl / ModuleImpl<br/>动态查询业务数据"]
    Response["BaseResponse<br/>模块结构 + 数据 + 权限"]

    Front --> Init
    Init --> ConfigTables
    ConfigTables --> EntityBuild
    EntityBuild --> DataQuery
    DataQuery --> Response
    Response --> Front

这种架构的影响：

• 新增业务模块时，可能更多依赖数据库配置和元数据，而不是新增独立 Controller。
• ModuleId 是贯穿模块初始化、数据查询、附件、审核、权限的核心参数。
• Entity.Control 下的 Field、GridPanel、TreePanel、ComboBox 等对象承担前端控件描述能力。
• BaseModule、BillModule、ModuleBaseEntity 等模型承载基础模块和单据模块配置。

9. 扩展点

常见扩展方式：

1. 新增 Ajax 方法：在对应 Controller 中新增 public 无参方法，通过前端 method 或 action 调用，并按需添加 @RequestCheck。
2. 新增模块能力：优先检查是否能通过模块配置表、字段配置、菜单配置实现，再考虑修改 ModuleImpl 或 DataImpl。
3. 新增数据库方言：实现 AllInOneSqlProvider，并在 AllInOneSqlFactory 中按新的 custom.database.type 分支返回 Provider。
4. 新增 Mapper 查询：在 Mapper 接口中定义方法，并在 resources/mapper/*.xml 中补充对应 SQL。
5. 新增文件处理能力：扩展 FileUploadController、FileImpl、FileUtil 或 Office 工具类。
6. 新增业务事件：通过 ModuleEventImpl 的加载、保存、状态变化、附件上传等事件机制接入。

10. 维护建议

• 优先理解 BaseHandler -> OptBaseHandler -> OptBaseImpl/BaseImpl 这条公共链路，再看具体业务方法。
• 排查接口问题时，先确认请求路径、method/action、ModuleId/MenuId、@RequestCheck 参数校验和登录状态。
• 修改数据访问逻辑时，先确认当前数据库类型和实际使用的是 Mapper XML、SQL Provider 还是 JdbcTemplate 动态 SQL。
• 对涉及附件、审核、权限、单据保存的改动，应同步验证 ModuleImpl、DataImpl 和数据库配置表的联动。
• 生产配置建议外置，尤其是数据库地址、用户名、密码、Redis 地址、JWT 相关配置。