From eee2e47cca0829a57fbfc47d610f7e9ebf87584d Mon Sep 17 00:00:00 2001 From: xqzp2026 Date: Tue, 21 Apr 2026 17:25:41 +0930 Subject: [PATCH] =?UTF-8?q?docs:=20ARCHITECTURE.md=20=E8=A1=A5=E5=85=85=20?= =?UTF-8?q?Web=20=E5=90=8E=E5=8F=B0=E6=9E=B6=E6=9E=84=EF=BC=88=E6=A8=A1?= =?UTF-8?q?=E5=9D=97/=E6=8A=80=E6=9C=AF=E6=A0=88/=E6=95=B0=E6=8D=AE?= =?UTF-8?q?=E5=B1=82/=E6=9C=8D=E5=8A=A1=E8=AF=B4=E6=98=8E=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 (1M context) --- backend/ARCHITECTURE.md | 312 +++++++++++++++++++++++++++++----------- 1 file changed, 226 insertions(+), 86 deletions(-) diff --git a/backend/ARCHITECTURE.md b/backend/ARCHITECTURE.md index 78ae61f..ad2d855 100644 --- a/backend/ARCHITECTURE.md +++ b/backend/ARCHITECTURE.md @@ -1,9 +1,129 @@ -# App 后台架构文档 +# 智慧清洁后台架构文档 -> 本文档记录小趣智清洁 App 后台的架构现状、数据访问层设计、冻结规范和新项目开发规范。 +> 本文档记录小趣智慧清洁系统全部后端项目的架构现状，包括 Web 后台和 App 后台。 > 维护人：Tony | 创建时间：2026-04-21 | 关联需求：REQ-20260421-0011 -## 1. 模块概览 +--- + +## 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 | 框架 | 打包 | 状态 | |------|-----------|---------|------|------|------| @@ -11,9 +131,8 @@ | `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. 依赖关系 +### 3.2 依赖关系 ``` xiaoqu-app-parent (pom, 统一版本管理) [冻结] @@ -21,31 +140,11 @@ xiaoqu-app-parent (pom, 统一版本管理) [冻结] ├── 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）依赖 - └── 被新项目依赖 ``` -### 构建顺序 +### 3.3 xiaoqu-complex 三套并行数据访问层 -```bash -# 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 内部存在三套独立的���据访问机制，连接两个数据库： +xiaoqu-complex 内部存在三套独立的数据访问机制，连接两个数据库： ``` xiaoqu-complex (App 主服务) @@ -75,14 +174,14 @@ xiaoqu-complex (App 主服务) 库 库 ``` -### 数据库连接 +**数据库连接配置（beans.xml + app-db.xml）：** | 数据源 | 连接数据库 | 使用方 | |--------|-----------|--------| | `dataSource` → `${servers.jdbc.jdbcUrl}` | `xiaoqu_complex` | ① 自有 DAO + ② db1 + ③ JdbcTemplate | | `dataSource1` → `${servers.jdbc.jdbcUrl1}` | `xiaoqu_intellectual` | ② db2（保洁任务） | -### SqlSessionFactory 映射 +**SqlSessionFactory 映射：** | SqlSessionFactory | 数据源 | ORM | 扫描包 | |-------------------|--------|-----|--------| @@ -90,7 +189,7 @@ xiaoqu-complex (App 主服务) | `sqlSessionFactory1` | dataSource1 | MyBatis-Plus | `xiaoqu.home.open.mapper.db2` | | `sqlSessionFactory2` | dataSource | MyBatis-Plus | `xiaoqu.home.open.mapper.db1` | -### 文件统计 +**文件统计：** | 层 | 包名 | 文件数 | ORM | 数据库 | 状态 | |----|------|--------|-----|--------|------| @@ -99,7 +198,7 @@ xiaoqu-complex (App 主服务) | ② 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 组件扫描隔离机制 +### 3.4 Spring 组件扫描隔离机制 xiaoqu-complex 使用 Spring XML 配置，组件扫描是**显式声明**的，精确控制只扫描以下 4 个包： @@ -121,7 +220,7 @@ xiaoqu-complex 使用 Spring XML 配置，组件扫描是**显式声明**的， ``` -### 同名 @Component 类的运行时隔离 +### 3.5 同名 @Component 类的运行时隔离 xiaoqu-complex 与 intellectual-public 存在 10 个同名基础设施类。**当前不存在运行时冲突**： @@ -138,11 +237,9 @@ xiaoqu-complex 与 intellectual-public 存在 10 个同名基础设施类。** | 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 的扫描范围内。 +> **重要警告**：旧项目已冻结，不做框架升级。如果升级到 Spring Boot 使用 `@SpringBootApplication` 默认扫描，上述 4 个 @Component 类会导致 Bean 名冲突。 -> **重要警告**：如果未来有人尝试将 xiaoqu-complex 升级到 Spring Boot 并使用 `@SpringBootApplication` 默认扫描，上述 4 个 @Component 类会被自动注册，导致 Bean 名冲突（双实例）。**不要这样做**——旧项目已冻结，不做框架升级。 - -## 5. 同名文件（108 个） +### 3.6 同名文件（108 个） xiaoqu-complex 与 intellectual-public 有 108 个同名 Java 文件。根本原因：**同一张数据库表有两套 ORM 映射**。 @@ -150,13 +247,78 @@ xiaoqu-complex 与 intellectual-public 有 108 个同名 Java 文件。根本原 - `me.iiv.iivframework.entity.User`（complex 自有，MyBatis） - `xiaoqu.home.open.model.db1.User`（intellectual-public，MyBatis-Plus） -两个版本字段集合不完全相同，是各自独立演化的结果。 +**处置方式：冻结原样，不做收敛。** -**处置方式：冻结原样，不做收敛。** 旧项目冻结后同名文件只做 bug 修复。 +### 3.7 包名空间 -## 6. 旧项目冻结规范 +xiaoqu-complex 内部存在三套包名（冻结后不做统一）： -Phase 1（Maven 治理）完成后，以下模块进入冻结状态： +| 包名 | 来源 | 用途 | +|------|------|------| +| `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 个模块进入冻结状态。 ### 允许的变更 @@ -171,14 +333,6 @@ Phase 1（Maven 治理）完成后，以下模块进入冻结状态： - 新增 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 修复（非新功能） @@ -186,7 +340,9 @@ Phase 1（Maven 治理）完成后，以下模块进入冻结状态： 3. 如必须改旧代码：最小化改动，不做"顺手重构" 4. 代码评审时标注"冻结项目 bug 修复" -## 7. 新项目开发规范 +--- + +## 6. 新项目开发规范 ### 技术栈 @@ -208,51 +364,35 @@ Phase 1（Maven 治理）完成后，以下模块进入冻结状态： **不依赖**：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. 环境配置 +## 7. 环境配置 ### 数据库连接 | 数据源 | 测试环境 | 生产环境 | |--------|---------|---------| -| 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` | +| 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 | -### Maven 构建 +### 服务端口 -- App 模块由 `xiaoqu-app-parent/pom.xml` 统一管理 -- Web 后台由 `backend/pom.xml` 统一管理 -- 两套父 POM 互不干扰，intellectual-public 是唯一交叉点 +| 服务 | 测试环境端口 | 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 | -## 9. 包名空间 +### Maven 构建体系 -xiaoqu-complex 内部存在三套包名，历史原因导致，冻结后不做统一： +| 父 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 | -| 包名 | 来源 | 用途 | -|------|------|------| -| `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 | +两套父 POM 互不干扰，`xiaoqu-intellectual-public` 是唯一交叉点。 + +> 必须使用 Java 8 编译和运行。