JavaProjectRepo/系统代码结构框架规划.md

# 系统代码结构框架规划

## 1. 目标与原则

### 1.1 业务目标
- framework 模块：沉淀系统级通用能力（安全、认证、权限、日志、任务调度、文件、缓存、监控、通用工具等），**不依赖任何业务代码**，可被 N 个业务模块复用
- business-css 模块：仅聚焦“临界事故情景分析”业务，**零系统代码**，所有共性能力通过 framework 提供

### 1.2 设计原则
| 原则 | 落地要求 |
|----|----|
| **高内聚低耦合** | 业务模块只依赖 framework，framework 绝不反向依赖业务 |
| **DRY** | 同一能力只在一个地方实现（framework），禁止业务模块重复造轮子 |
| **可演进** | 后续新增业务模块（business-xxx）零改动即可接入现有能力 |
| **可维护** | 通过 Maven 多模块 + 分层分包，让“修改点”收敛到最小范围 |

---

## 2. 多模块 Maven 结构（聚合工程）

```
d:\JavaProjectSpace (root pom, packaging=pom)
├── framework (com.yfd:platform:1.0)
│   ├── src/main/java
│   ├── src/main/resources
│   └── pom.xml
├── business-css (com.yfd:business-css:1.0-SNAPSHOT)
│   ├── src/main/java
│   ├── src/main/resources
│   └── pom.xml
└── pom.xml   ← modules 声明
```

---

## 3. framework 模块职责与目录

### 3.1 职责矩阵
| 能力域 | 是否包含 | 说明 |
|----|----|----|
| 统一配置 | ✅ | 数据源、Redis、Jackson、MyBatis-Plus、Swagger、监控、日志、加解密等 |
| 安全 & 认证 | ✅ | Spring Security + JWT 过滤器、权限注解、匿名访问标记 |
| 系统级 API | ✅ | 用户/角色/菜单/部门/字典/日志/文件/消息/定时任务等 |
| 通用工具 | ✅ | RSA、Excel、IP 归属、验证码、异步线程池、缓存封装 |
| 前端静态 | ✅ | 仅提供全局通用静态（如 404、error、swagger-ui）；**业务页面由业务模块提供** |
| 业务代码 | ❌ | 禁止出现任何与“临界事故”相关的类、表、API |

### 3.2 代码分层
```
src/main/java/com/yfd/platform
├── config               # 自动配置类（DataSource、Security、Async、Redis、MyBatisPlus...）
│   ├── bean             # @ConfigurationProperties 配置属性类
│   ├── thread           # 线程池配置
│   └── ...
├── constant             # 系统级常量
├── exception            # 全局异常 + 自定义业务异常基类
├── annotation           # 系统注解（@Log、@AnonymousAccess 等）
├── aspect               # 系统级 AOP（操作日志、权限校验）
├── datasource           # 动态数据源切换（若业务需要多库）
├── utils                # 通用工具（RSA、Excel、IP、验证码、SpringContextHolder...）
├── system               # 系统管理域（用户/角色/菜单/部门/字典/日志/文件/消息/任务）
│   ├── domain           # PO / DTO / VO（注意：仅系统表）
│   ├── mapper           # MyBatis-Plus Mapper
│   ├── service          # Service 接口 + 实现
│   └── controller       # REST API（/api/system/*）
└── component            # 非业务组件（WebSocket、SSE、任务执行器）
```

### 3.3 资源目录
```
src/main/resources
├── mapper/system/*.xml          # 仅系统表 SQL 映射
├── static                       # 全局通用静态（swagger、error、login 背景图等）
├── banner.txt / logback.xml     # 统一启动 Banner & 日志
└── application*.yml             # 框架级默认配置（数据源、redis、监控、线程池...）
```

> **注意**：framework 绝不放业务 SQL、业务静态页面；业务资源全部下沉到业务模块。

---

## 4. business-css 模块职责与目录

### 4.1 职责矩阵
| 能力域 | 是否包含 | 说明 |
|----|----|----|
| 业务领域代码 | ✅ | 临界事故实体、服务、控制器、DTO、Mapper XML |
| 业务静态页面 | ✅ | 仅与“临界事故”相关的页面、图片、图标 |
| 系统能力 | ❌ | 通过依赖 framework 获得，禁止复制粘贴 |
| 系统表 SQL | ❌ | 系统表由 framework 提供，业务模块只写业务表 |

### 4.2 代码分层
```
src/main/java/com/yfd/business/css
├── model          # 业务实体 / DTO / VO（仅业务表）
├── mapper         # MyBatis-Plus Mapper 接口
├── service        # 业务服务接口 + 实现
├── controller     # REST API（/api/css/* 或 /api/simulation/*）
└── *Application.java
```

### 4.3 资源目录
```
src/main/resources
├── mapper/css/*.xml   # 仅业务表 SQL 映射
├── static/css/*       # 业务静态（页面、图片、图标）
└── application.yml    # 业务个性化配置（端口、数据源 URL、业务开关）
```

---

## 5. 依赖关系与 Maven 坐标

| 模块 | 坐标 | 依赖 |
|----|----|----|
| framework | com.yfd:platform:1.0 | 无业务依赖，仅技术栈（Spring Boot、MyBatis-Plus、Security、Redis...） |
| business-css | com.yfd:business-css:1.0-SNAPSHOT | com.yfd:platform:1.0（plain classifier） |

> **plain classifier**：framework 通过 `maven-jar-plugin` 额外生成 `platform-1.0-plain.jar`，仅含 classes & resources，不含 Spring-Boot 启动器，避免业务模块引入重复主类。

---

## 6. 配置隔离策略

| 配置项 | 放在哪里 | 示例 |
|----|----|----|
| 数据源、Redis、MyBatis、线程池、监控、日志 | framework | `framework/src/main/resources/application.yml` |
| 业务开关、业务参数、端口、上下文 | business-css | `business-css/src/main/resources/application.yml` |
| 环境差异化（dev/prod） | 各自模块 | `application-dev.yml`、`application-prod.yml` |

> **启动顺序**：业务模块的 `application.yml` 会覆盖 framework 的同名 key，实现“共性 + 个性”组合。

---

## 7. 静态资源隔离策略

| 资源类型 | 放在哪里 | 访问路径 | 说明 |
|----|----|----|----|
| 全局通用（swagger、error、login 背景） | framework | `/error`、`/swagger-ui.html` | 所有业务模块共用 |
| 业务页面（*.html、*.js、*.png） | business-css | `/css/index.html` | 仅当前业务使用 |
| 业务接口 | business-css | `/api/simulation/*` | REST 无静态冲突 |

> **最佳实践**：业务静态统一放在 `/static/{业务简称}/` 目录，避免文件名冲突。

---

## 8. 数据库隔离策略

| 表归属 | 模块 | 说明 |
|----|----|----|
| 系统表（sys_user、sys_role、sys_menu...） | framework | 由 framework 提供 Mapper & XML，业务模块只读/调用 Service |
| 业务表（css_simulation、css_record...） | business-css | 由业务模块自行创建 Mapper & XML，禁止写入系统表 SQL |

> **多业务共享同一库**：系统表前缀 `sys_`，业务表前缀 `css_`、`xxx_`，物理共存但逻辑隔离。

---

## 9. 启动与部署

### 9.1 开发阶段
```bash
# 1. 安装 framework 到本地仓库
mvn -DskipTests clean install -pl framework

# 2. 启动业务模块（自动依赖 framework）
mvn -DskipTests spring-boot:run -pl business-css
```

### 9.2 交付阶段
```bash
# 一次性打包所有模块
mvn -DskipTests clean package

# 产物
framework/target/platform-1.0.jar          # 系统后台服务（可选独立部署）
business-css/target/business-css-1.0-SNAPSHOT.jar  # 业务服务（含内嵌 Tomcat）
```

> **部署方式**：
> - 轻量场景：只部署 `business-css-1.0-SNAPSHOT.jar`，内嵌 framework 能力
> - 分离场景：独立部署 `platform-1.0.jar`（提供统一后台），再部署多个业务 jar，网关统一路由

---

## 10. 横向扩展：新增业务模块（business-xxx）

1. 新建 Maven 模块 `business-xxx`，parent 指向根 pom
2. 依赖 `com.yfd:platform:1.0:plain`
3. 包名 `com.yfd.business.xxx`
4. 表前缀 `xxx_`
5. 静态资源 `/static/xxx/`
6. API 前缀 `/api/xxx/`
7. 端口 `8083`（避免与 css 冲突）

**零改动接入**：无需复制任何系统代码，仅需以上 7 步即可拥有完整的用户/权限/日志/文件/任务能力。

---

## 11. 常见误区与禁止项

| 误区 | 正确做法 |
|----|----|
| 把系统表 SQL 写在业务模块 | 系统 SQL 只能放在 framework/mapper/system |
| 把系统静态页面（login、404）复制到业务模块 | 全局静态统一收敛到 framework/static |
| 业务模块直接依赖 `platform-1.0.jar`（可执行） | 使用 `platform-1.0-plain.jar`（仅 classes） |
| framework 里出现“css”字样 | framework 必须业务无关，出现业务代码即重构 |
| 多个业务模块端口重复 | 每个业务模块独立端口（8082、8083...） |

---

## 12. 演进路线

| 阶段 | 动作 |
|----|----|
| **当前** | 单库多模块，Maven 聚合，静态/配置/表逻辑隔离 |
| **下一步** | 引入 Spring Cloud Gateway，统一路由 & 鉴权，业务模块只关注领域逻辑 |
| **未来** | 业务模块拆分为独立微服务（docker-compose/k8s），framework 作为共享 lib 或 sidecar |

---

> **一句话总结**：framework 做“平台”，business-css 做“产品”；平台沉淀，产品迭代，互不污染，横向复制。