wangheng/smartClean
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dev
smartClean/backend/ARCHITECTURE.md
xqzp2026 eee2e47cca docs: ARCHITECTURE.md 补充 Web 后台架构（模块/技术栈/数据层/服务说明） 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-21 17:25:41 +09:30

18 KiB
Raw Permalink Blame History

智慧清洁后台架构文档

本文档记录小趣智慧清洁系统全部后端项目的架构现状，包括 Web 后台和 App 后台。 维护人：Tony | 创建时间：2026-04-21 | 关联需求：REQ-20260421-0011

1. 系统全景

                        ┌─────────────────────────────────────────┐
                        │     xiaoqu-intellectual-public (jar)     │
                        │     唯一持续维护的数据访问层                │
                        │     MyBatis-Plus · db1/db2               │
                        └────┬──────────────┬──────────────┬───────┘
                             │              │              │
              ┌──────────────┘              │              └──────────────┐
              ▼                             ▼                             ▼
┌──────────────────────┐     ┌──────────────────────┐     ┌──────────────────────┐
│   Web 后台 (SaaS)     │     │   App 后台 (冻结)      │     │   新项目 (规划中)      │
│   Spring Boot 2.4     │     │   Spring 5.0 + XML    │     │   Spring Boot 2.4     │
│   6 个模块             │     │   4 个模块（冻结）       │     │   仅依赖              │
│   端口: 8095/8097     │     │   端口: 8091/8086      │     │   intellectual-public │
└──────────────────────┘     └──────────────────────┘     └──────────────────────┘

数据库

数据库 用途 使用方
xiaoqu_complex (xiaoqu_comples_d) 核心业务数据（用户/区域/设备/考勤等） Web 后台 + App 后台 + 新项目
xiaoqu_intellectual (xiaoqu_intellectual_d) 保洁任务/巡检/计划/场景等 Web 后台 + App 后台 + 新项目
xiaoqu_mall (xiaoqu_mall_d) 商城/订单 App 后台 xiaoqu-mall
xiaoqu_franchisee (xiaoqu_franchisee_d) 加盟商 App 后台 xiaoqu-mall

2. Web 后台架构

2.1 模块概览

模块 打包 说明 端口
xiaoqu-intellectual-public jar 公共数据访问层（Entity + Mapper + Service） —
xiaoqu-intellectual-base jar 基础信息管理（网格/对象/场景/事项/技能/标签/工具/设备） —
xiaoqu-intellectual-task-mgmt jar 任务调度管理（计划/任务/巡检/参数配置/用户上报/工资） —
xiaoqu-intellectual-attendance jar 考勤打卡（打卡记录/考勤/人效/班组） —
xiaoqu-intellectual-web war (ROOT.war) Web API 主服务，聚合上述所有模块 8095
xiaoqu-intellectual-task jar 定时任务服务（XXL-Job + MQTT + 个推） 8097

2.2 依赖关系

backend/pom.xml (Web 后台父 POM, Spring Boot 2.4.8)
  ├── xiaoqu-intellectual-public (jar)        ← 公共数据层，被所有模块依赖
  ├── xiaoqu-intellectual-base (jar)          → public
  ├── xiaoqu-intellectual-task-mgmt (jar)     → public
  ├── xiaoqu-intellectual-attendance (jar)    → public
  ├── xiaoqu-intellectual-web (war)           → public + base + task-mgmt + attendance
  └── xiaoqu-intellectual-task (jar)          → public

2.3 技术栈

层级 技术
框架 Spring Boot 2.4.8 + Java 8
ORM MyBatis-Plus 3.4 + Druid 连接池
缓存 Redis (Lettuce)
搜索 Elasticsearch (BBoss 6.3，已配置未启用)
定时任务 XXL-Job 2.3
消息 MQTT (Eclipse Paho，task 模块)
推送 个推 SDK（task 模块）
日志 Log4j（排除 Spring Boot 默认 Logback）
文档 Swagger 2.9.2 + swagger-bootstrap-ui
工具 Lombok + Hutool 5.8 + FastJSON + EasyPOI

2.4 数据访问层

Web 后台统一使用 MyBatis-Plus，通过 intellectual-public 的双数据源：

数据源 连接数据库 Mapper 包
db1 xiaoqu_complex xiaoqu.home.open.mapper.db1
db2 xiaoqu_intellectual xiaoqu.home.open.mapper.db2

2.5 Web 服务 (intellectual-web)

  • 启动类：xiaoqu.home.open.XiaoquIntellectualWebApplication (extends SpringBootServletInitializer)
  • 打包：WAR (warName=ROOT)，排除内嵌 Tomcat，部署到外部 Tomcat
  • 核心功能：REST API、权限管理、数据导出、Swagger 文档
  • 配置：application-{profile}.yml，支持 test/docker/prod 多环境

2.6 Task 服务 (intellectual-task)

  • 启动类：xiaoqu.home.open.XiaoquIntellectualTaskApplication (@EnableScheduling)
  • 打包：可执行 JAR (Spring Boot repackage)
  • 核心功能：
    • XXL-Job 执行器（分布式定时任务）
    • MQTT 监听（设备通信，tcp://host:1883）
    • 个推推送（移动端消息）

2.7 构建命令

cd backend

# 构建全部 Web 后台模块
mvn clean package -DskipTests

# 仅构建 web 服务
mvn clean package -pl xiaoqu-intellectual-web -am -DskipTests

# 仅构建 task 服务
mvn clean package -pl xiaoqu-intellectual-task -am -DskipTests

# 本地运行
mvn spring-boot:run -pl xiaoqu-intellectual-web
mvn spring-boot:run -pl xiaoqu-intellectual-task

3. App 后台架构

3.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 冻结

3.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

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

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

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           库
                            库       库

数据库连接配置（beans.xml + app-db.xml）：

数据源 连接数据库 使用方
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 冻结

3.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>

3.5 同名 @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 无 否

重要警告：旧项目已冻结，不做框架升级。如果升级到 Spring Boot 使用 @SpringBootApplication 默认扫描，上述 4 个 @Component 类会导致 Bean 名冲突。

3.6 同名文件（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）

处置方式：冻结原样，不做收敛。

3.7 包名空间

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

3.8 构建命令

# 先安装 intellectual-public（App 模块依赖它）
cd backend && mvn clean install -pl xiaoqu-intellectual-public -DskipTests

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

# Docker 环境构建（数据库指向 host.docker.internal）
cd backend/xiaoqu-app-parent && mvn clean package -P docker -DskipTests

4. intellectual-public 共享层

4.1 定位

xiaoqu-intellectual-public 是整个系统的唯一持续维护的数据访问层，同时被 Web 后台、旧 App 和新项目依赖。

4.2 包结构

包 文件数 使用方
model/db1 51 App + Web + 新项目
model/db2 61 App + Web + 新项目
mapper/db1 51 App + Web + 新项目
mapper/db2 61 App + Web + 新项目
service/db1 + impl 102 App + Web + 新项目
service/db2 + impl 122 App + Web + 新项目
service（父包） 3 仅 Web（RedisService4/5, PublicService）
publicBean 25 App + Web
utils 17 App + Web
controller/* ~30 仅 Web
aop 3 仅 Web
config 4 仅 Web
redis 1 仅 Web
task 2 仅 Web

4.3 变更原则

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

4.4 数据库变更维护规则

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

5. 旧项目冻结规范

Phase 1（Maven 治理）完成后，App 后台 4 个模块进入冻结状态。

允许的变更

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

禁止的变更

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

冻结代码变更流程

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

6. 新项目开发规范

技术栈

层级 技术
框架 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。

7. 环境配置

数据库连接

数据源 测试环境 生产环境
xiaoqu_complex 192.168.1.181:3306/xiaoqu_comples_d Aliyun RDS
xiaoqu_intellectual 192.168.1.181:3306/xiaoqu_intellectual_d Aliyun RDS
xiaoqu_mall 192.168.1.181:3306/xiaoqu_mall_d Aliyun RDS

服务端口

服务 测试环境端口 Docker 端口
Web 后台 (intellectual-web) 8095 18095
Task 服务 (intellectual-task) 8097 18097
App 主服务 (xiaoqu-complex) 8091 18091
App 商城 (xiaoqu-mall) 8086 18086
前端 (Vue SPA) 8079 (dev) 8280

Maven 构建体系

父 POM 管理范围 路径
backend/pom.xml Web 后台 6 模块 (Spring Boot 2.4.8) xiaoqu-intellectual-*
backend/xiaoqu-app-parent/pom.xml App 后台 4 模块 (Spring 5.0) xiaoqu-public/complex/mall + ElasticsearchPublic

两套父 POM 互不干扰，xiaoqu-intellectual-public 是唯一交叉点。

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

Reference in New Issue View Git Blame Copy Permalink