feat: App 后台 Phase 1 Maven 治理 + Docker 部署

- 创建 xiaoqu-app-parent 统一父 POM，管理 4 个 App 模块依赖版本 - 统一 fastjson(1.2.83)、druid(1.2.27)、jedis(3.1.0) 等版本 - 子模块 POM 改造：继承父 POM，删除硬编码版本号 - 添加 Docker 部署方案（complex + mall 双容器） - 添加 ARCHITECTURE.md 架构文档（三套 DAO 层、冻结规范、新项目规范） - 关联需求：REQ-20260421-0011 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-21 16:56:25 +09:30
parent 49127bb6a7
commit d932a33a75
12 changed files with 2625 additions and 0 deletions
--- a/backend/ARCHITECTURE.md
+++ b/backend/ARCHITECTURE.md
@@ -0,0 +1,258 @@
+# 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）依赖
+  └── 被新项目依赖
+```
+
+### 构建顺序
+
+```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 内部存在三套独立的<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:**
+```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>
+```
+
+### 同名 @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 |