smartClean/backend/ARCHITECTURE.md

App 后台架构文档

本文档记录小趣智清洁 App 后台的架构现状、数据访问层设计、冻结规范和新项目开发规范。 维护人：Tony | 创建时间：2026-04-21 | 关联需求：REQ-20260421-0011

1. 模块概览

模块	Java 文件数	groupId	框架	打包	状态
xiaoqu-public	147	me.iiv.xiaoqu	纯 Java	jar	冻结
elasticsearchpublic	21	me.iiv.xiaoqu	Spring 5.0	jar	冻结
xiaoqu-complex	1,176	me.iiv.xiaoqu	Spring 5.0 + 原生 MVC	war	冻结
xiaoqu-mall	1,007	me.iiv.xiaoqu	Spring 5.0 + 原生 MVC	war	冻结
xiaoqu-intellectual-public	537	xiaoqu.home.open	Spring Boot 2.4	jar	持续维护

2. 依赖关系

xiaoqu-app-parent (pom, 统一版本管理)           [冻结]
  ├── xiaoqu-public (jar)                      [冻结]
  ├── ElasticsearchPublic (jar)                [冻结] ── 依赖 xiaoqu-public
  ├── xiaoqu-complex (war)                     [冻结] ── 依赖 xiaoqu-public + ElasticsearchPublic + intellectual-public
  └── xiaoqu-mall (war)                        [冻结] ── 依赖 xiaoqu-public

xiaoqu-intellectual-public (jar)               [持续维护] ── 唯一数据访问层
  ├── 被 Web 后台依赖（intellectual-web/task/base/task-mgmt/attendance）
  ├── 被旧 App（xiaoqu-complex）依赖
  └── 被新项目依赖

构建顺序

# 1. 先安装 intellectual-public（属于 Web 后台父 POM）
cd backend && mvn clean install -pl xiaoqu-intellectual-public -DskipTests

# 2. 构建全部 App 模块
cd backend/xiaoqu-app-parent && mvn clean package -DskipTests

# 3. 验证 Web 后台（可选）
cd backend && mvn clean package -DskipTests

必须使用 Java 8 编译和运行。

3. xiaoqu-complex 三套并行数据访问层

xiaoqu-complex 内部存在三套独立的<E7AB8B><E79A84><EFBFBD>据访问机制，连接两个数据库：

xiaoqu-complex (App 主服务)
┌──────────────────────────────────────────────────────────────────────┐
│                        Controller Layer                              │
│                 (me.iiv.iivframework.controller.*)                   │
└──────┬───────────────────────┬───────────────────────┬───────────────┘
       │                       │                       │
       ▼                       ▼                       ▼
┌──────────────────┐  ┌────────────────────────┐  ┌──────────────────┐
│ ① 自有 DAO 层     │  │ ② intellectual-public   │  │ ③ org.home.open  │
│ (MyBatis)        │  │ (MyBatis-Plus)          │  │ (JdbcTemplate)   │
│                  │  │                        │  │                  │
│ me.iiv.*.dao     │  │ mapper.db1 → 同库       │  │ org.home.open.*  │
│ me.iiv.*.entity  │  │ mapper.db2 → 跨库       │  │ ~48 个文件        │
│ 41 DAO + 151 XML │  │ 51+61 Service          │  │                  │
│                  │  │                        │  │                  │
│ sqlSessionFactory│  │ sqlSessionFactory2(db1) │  │ jdbcTemplate     │
│ → dataSource     │  │ → dataSource (同库)     │  │ → dataSource     │
│                  │  │ sqlSessionFactory1(db2) │  │                  │
│                  │  │ → dataSource1 (跨库)    │  │                  │
└────────┬─────────┘  └─────────┬──────┬───────┘  └────────┬─────────┘
         │                      │      │                    │
         ▼                      ▼      ▼                    ▼
    xiaoqu_complex         xiaoqu_  xiaoqu_           xiaoqu_complex
         库                complex  intellectual           库
                            库       库

数据库连接

数据源	连接数据库	使用方
dataSource → ${servers.jdbc.jdbcUrl}	xiaoqu_complex	① 自有 DAO + ② db1 + ③ JdbcTemplate
dataSource1 → ${servers.jdbc.jdbcUrl1}	xiaoqu_intellectual	② db2（保洁任务）

SqlSessionFactory 映射

SqlSessionFactory	数据源	ORM	扫描包
sqlSessionFactory	dataSource	MyBatis + PageHelper	mappers/*.xml
sqlSessionFactory1	dataSource1	MyBatis-Plus	xiaoqu.home.open.mapper.db2
sqlSessionFactory2	dataSource	MyBatis-Plus	xiaoqu.home.open.mapper.db1

文件统计

层	包名	文件数	ORM	数据库	状态
① 自有 DAO	me.iiv.iivframework.dao + mappers/*.xml	41 DAO + 151 XML	MyBatis + PageHelper	xiaoqu_complex	冻结
② intellectual db1	xiaoqu.home.open.*.db1	51×3 (mapper/service/model)	MyBatis-Plus	xiaoqu_complex（同库）	由 intellectual-public 维护
② intellectual db2	xiaoqu.home.open.*.db2	61×3 (mapper/service/model)	MyBatis-Plus	xiaoqu_intellectual	由 intellectual-public 维护
③ JdbcTemplate	org.home.open.dao	~48	JdbcTemplate	xiaoqu_complex	冻结

4. Spring 组件扫描隔离机制

xiaoqu-complex 使用 Spring XML 配置，组件扫描是显式声明的，精确控制只扫描以下 4 个包：

beans.xml:

<context:component-scan base-package="me.iiv.*"/>                      <!-- ① 自有层 -->
<context:component-scan base-package="xiaoqu.home.open.service.db1.*"/> <!-- ② db1 Service -->
<context:component-scan base-package="xiaoqu.home.open.service.db2.*"/> <!-- ② db2 Service -->
<context:component-scan base-package="org.home.open.*"/>                <!-- ③ JdbcTemplate 层 -->

springmvc.xml:

<context:component-scan base-package="me.iiv.iivframework.controller"/>
<context:component-scan base-package="me.iiv.iivframework.aop.*"/>
<mvc:interceptors>
    <bean class="me.iiv.iivframework.core.SystemInterceptor"/>
    <bean class="me.iiv.iivframework.core.PermissionInterceptor"/>
</mvc:interceptors>

同名 @Component 类的运行时隔离

xiaoqu-complex 与 intellectual-public 存在 10 个同名基础设施类。当前不存在运行时冲突：

文件	intellectual-public 包	complex 包	有 @Component?	被 complex 扫描?
SystemInterceptor	xiaoqu.home.open.config	me.iiv.iivframework.core	是	否
RepeatSubmitAspect	xiaoqu.home.open.aop	me.iiv.iivframework.aop	是	否
RedisDistributedLock	xiaoqu.home.open.redis	me.iiv.iivframework.redis	是	否
RedisService5	xiaoqu.home.open.service	me.iiv.iivframework.redis	是	否
AvoidRepeatSubmit	xiaoqu.home.open.aop	me.iiv.iivframework.aop	注解类	否
Constants	xiaoqu.home.open.constant	me.iiv.iivframework.Constants	无	否
XxlJobInfo	xiaoqu.home.open.config	me.iiv.iivframework.entity	无	否
IpUtils	xiaoqu.home.open.utils	me.iiv.iivframework.utils	无	否
FileUtil	xiaoqu.home.open.utils	me.iiv.iivframework.utils	无	否
UserUtils	xiaoqu.home.open.utils	me.iiv.iivframework.utils	无	否

intellectual-public 的 config、aop、redis、utils、service（父包）均不在 complex 的扫描范围内。

重要警告：如果未来有人尝试将 xiaoqu-complex 升级到 Spring Boot 并使用 @SpringBootApplication 默认扫描，上述 4 个 @Component 类会被自动注册，导致 Bean 名冲突（双实例）。不要这样做——旧项目已冻结，不做框架升级。

5. 同名文件（108 个）

xiaoqu-complex 与 intellectual-public 有 108 个同名 Java 文件。根本原因：同一张数据库表有两套 ORM 映射。

示例：

• me.iiv.iivframework.entity.User（complex 自有，MyBatis）
• xiaoqu.home.open.model.db1.User（intellectual-public，MyBatis-Plus）

两个版本字段集合不完全相同，是各自独立演化的结果。

处置方式：冻结原样，不做收敛。 旧项目冻结后同名文件只做 bug 修复。

6. 旧项目冻结规范

Phase 1（Maven 治理）完成后，以下模块进入冻结状态：

允许的变更

• Bug 修复
• 安全补丁（如依赖版本升级修复 CVE）

禁止的变更

• 新增功能、新增接口
• 重构代码、统一包名
• 框架升级（Spring Boot 等）
• 新增 DAO/Mapper/Entity
• 收敛同名文件

旧 DAO 层冻结说明

DAO 层	冻结说明
① 自有 MyBatis（41 DAO + 151 XML）	仅修复已有查询的 bug，不新增 mapper
② intellectual-public 的 db1/db2	由 intellectual-public 统一维护
③ org.home.open JdbcTemplate（~48 文件）	冻结，不新增 JDBC 直写代码

冻结代码变更流程

1. 确认是 bug 修复（非新功能）
2. 评估是否可在新项目中通过新接口绕过
3. 如必须改旧代码：最小化改动，不做"顺手重构"
4. 代码评审时标注"冻结项目 bug 修复"

7. 新项目开发规范

技术栈

层级	技术
框架	Spring Boot 2.4.8 + Java 8
ORM	MyBatis-Plus 3.4（通过 intellectual-public）
数据访问	仅使用 intellectual-public 的 DAO 层
数据库	xiaoqu_complex + xiaoqu_intellectual（通过 db1/db2）

依赖关系

新项目 (Spring Boot 2.4 + Java 8)
  └── xiaoqu-intellectual-public (jar)
        ├── mapper/service/model.db1 → xiaoqu_complex 库
        └── mapper/service/model.db2 → xiaoqu_intellectual 库

不依赖：xiaoqu-complex、xiaoqu-mall、xiaoqu-public、elasticsearchpublic。

数据库变更维护规则

变更类型	操作位置	说明
新增表	intellectual-public（新增 Entity + Mapper + Service）	新表只在 intellectual-public 中建 ORM 映射
修改已有表（加字段）	intellectual-public（修改 Entity）	旧项目 complex 的同名 Entity 不改
删除表/字段	intellectual-public	旧项目对应代码冻结不删

intellectual-public 变更注意事项

intellectual-public 同时被三方依赖：

依赖方	影响评估
Web 后台（intellectual-web/task 等）	主要消费方，变更需确保兼容
旧 App（xiaoqu-complex）	冻结状态，新增内容对其无影响
新项目	新功能的主要数据访问通道

变更原则：

• 新增 Entity/Mapper/Service → 安全，不影响已有代码
• 修改已有 Entity 字段 → 需评估 Web 后台影响
• 修改已有 Service 方法签名 → 高风险，需评估所有依赖方
• 删除任何内容 → 禁止（除非确认所有依赖方已移除引用）

8. 环境配置

数据库连接

数据源	测试环境	生产环境
dataSource (xiaoqu_complex)	192.168.1.181:3306/xiaoqu_comples_d	Aliyun RDS xiaoqu_complex
dataSource1 (xiaoqu_intellectual)	192.168.1.181:3306/xiaoqu_intellectual_d	Aliyun RDS xiaoqu_intellectual

Maven 构建

• App 模块由 xiaoqu-app-parent/pom.xml 统一管理
• Web 后台由 backend/pom.xml 统一管理
• 两套父 POM 互不干扰，intellectual-public 是唯一交叉点

9. 包名空间

xiaoqu-complex 内部存在三套包名，历史原因导致，冻结后不做统一：

包名	来源	用途
me.iiv.iivframework.*	complex 自有	Controller、DAO、Entity、AOP、拦截器
xiaoqu.home.open.*	intellectual-public	MyBatis-Plus Service/Mapper/Model (db1/db2)
org.home.open.*	complex 内 JdbcTemplate 层	JDBC 直写 DAO