399 lines
18 KiB
Markdown
399 lines
18 KiB
Markdown
# 智慧清洁后台架构文档
|
||
|
||
> 本文档记录小趣智慧清洁系统全部后端项目的架构现状，包括 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 构建命令
|
||
|
||
```bash
|
||
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:**
|
||
```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:**
|
||
```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 构建命令
|
||
|
||
```bash
|
||
# 先安装 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 编译和运行。
|