# 项目技术方案说明

> 项目：ProjectFrameWork2025（模块：`java/platform`）
> 运行环境：Windows，Java 21（兼容 17+），Spring Boot 3.x

## 1. 项目概述
- 平台型后端服务，基于 Spring Boot 构建，采用分环境配置（`dev`/`server`）。
- 数据访问使用 MyBatis-Plus + Druid 连接池，计划支持 Redis、定时任务（Quartz），并暴露 Swagger UI 便于接口联调。
- 支持 WAR 包运行（内嵌 Tomcat 或外部容器）。

## 2. 技术栈与版本
- 核心框架：`Spring Boot 3.x`
- ORM：`MyBatis-Plus 3.5.6`
- MyBatis 核心：`3.5.16`（与 MP 3.5.6 兼容，解决 `parsePendingResultMaps(boolean)` 缺失）
- 数据源：`Druid`
- 任务调度：`Quartz 2.3.2`
- API 文档：`springdoc-openapi` 或 `Swagger UI`（YAML 中 `swagger-ui.enabled: true`）
- 日志：`Logback`（`logback-spring.xml`，统一 UTF-8 编码）
- 语言与 JDK：推荐 `Java 17+`，当前运行 `Java 21.0.5`

## 3. 模块与目录结构
```
ProjectFrameWork2025/
├── .vscode/launch.json         # VS Code 启动配置（UTF-8 调试）
└── java/
    ├── pom.xml                 # Maven 构建与依赖管理
    ├── src/main/java           # 业务代码（入口：com.yfd.platform.PlatformApplication）
    ├── src/main/resources      # 配置与静态资源
    │   ├── application.yml     # 通用配置（激活 profile）
    │   ├── application-dev.yml # 开发环境配置
    │   ├── application-server.yml # 服务器环境配置
    │   └── logback-spring.xml  # 统一日志编码与输出格式
    └── target/platform-1.0.war # 打包产物（可直接运行）
```

## 4. 配置管理策略
- Profile：通过 `--spring.profiles.active=<dev|server>` 切换。
- 关键属性：
  - `file-space.system`：文件空间根路径，必须在激活的 profile 中配置（已补充到 `application-server.yml`）。
  - `spring.datasource.druid.*`：数据库连接池配置（URL/用户名/密码）。
  - `server.port`：端口（`dev` 默认 8093，`server` 默认 8090）。
- VS Code 与终端编码：
  - 在 `.vscode/launch.json` 中设置：
    - `vmArgs: -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8`
    - `env.JAVA_TOOL_OPTIONS` 与 `env.JDK_JAVA_OPTIONS` 设为 UTF-8
    - `console: integratedTerminal`
  - 终端运行前执行：`chcp 65001`，并确保 PowerShell 输出编码为 UTF-8

## 5. 数据库与数据源
- MySQL 连接示例：
  ```yaml
  spring:
    datasource:
      druid:
        master:
          url: jdbc:mysql://<host>:3306/<db>?useUnicode=true&characterEncoding=UTF8&rewriteBatchedStatements=true&useSSL=false&allowPublicKeyRetrieval=true
          username: <user>
          password: <password>
  ```
- 远程访问与授权建议：
  - 为应用账户授权外部访问：
    ```sql
    CREATE USER 'appuser'@'%' IDENTIFIED BY 'StrongPassword!';
    GRANT ALL PRIVILEGES ON <db>.* TO 'appuser'@'%';
    FLUSH PRIVILEGES;
    ```
  - 确保 MySQL `bind-address` 放开远程，防火墙/安全组放行 `3306`。
- Druid 健壮性配置建议（数据库未就绪时减少报错）：
  ```yaml
  spring:
    datasource:
      druid:
        initial-size: 0
        test-on-borrow: false
        test-while-idle: true
        validation-query: SELECT 1
  ```

## 6. ORM 与持久化
- DAO 层使用 MyBatis-Plus，简化 CRUD；Mapper XML 与注解可共存。
- 版本兼容性已确认：`MP 3.5.6` 依赖 `MyBatis 3.5.16+` 的 `Configuration.parsePendingResultMaps(boolean)`。
- 如遇 `NoSuchMethodError`，优先检查 `pom.xml` 中 MyBatis 版本与依赖冲突。

## 7. 日志方案
- 使用 `logback-spring.xml` 统一控制台与文件日志编码为 UTF-8：
  - 控制台：`ConsoleAppender` + `PatternLayoutEncoder`（`charset: UTF-8`）
  - 文件：`RollingFileAppender` 按日滚动，保留 30 天历史
  - 日志格式：`%d [%thread] %-5level %logger{50} - %msg%n`
- 在 Windows 终端执行：`chcp 65001`，并设置 `JAVA_TOOL_OPTIONS` 保证 JVM 使用 UTF-8。

## 8. 定时任务
- Quartz 持久化策略当前为 `RAMJobStore`（非集群、内存存储）。
- 如需持久化与集群，可改为 `JdbcJobStore` 并配置数据源与表结构。

## 9. 安全与鉴权
- 采用 `JWT` 方案（存在 `jwtAuthenticationTokenFilter` 等 Bean），通过过滤器进行请求鉴权。
- 建议：
  - 将敏感配置（`jwt.secret`、数据库密码）置于环境变量或外部密钥管理。
  - 开发环境使用弱密钥仅限本地，生产需强密钥并开启 HTTPS。

## 10. API 文档与联调
- 启用 Swagger UI（`swagger-ui.enabled: true`）。
- 访问路径通常为：`/swagger-ui/index.html`（具体以 springdoc 配置为准）。

## 11. 构建与运行
- 构建：
  ```bash
  mvn -f java/pom.xml clean package -DskipTests
  ```
- 启动（dev）：
  ```bash
  java -jar java/target/platform-1.0.war --spring.profiles.active=dev
  ```
- 启动（server）：
  ```bash
  java -jar java/target/platform-1.0.war --spring.profiles.active=server
  ```
- VS Code 调试：选择配置 `Spring Boot-PlatformApplication<platform>` 启动。

## 12. 常见问题与排错
- 控制台中文乱码：
  - 终端执行 `chcp 65001`，VS Code 配置 UTF-8，`logback-spring.xml` 强制 UTF-8。
- MyBatis `NoSuchMethodError`：
  - 升级 MyBatis 至 `3.5.16+` 与 MP 版本匹配。
- 数据库 `Access denied`：
  - 校验账户密码与远程授权；必要时新建业务账户并放开 `3306`。
- 占用端口/启动失败：
  - 检查 `server.port` 与端口冲突；查看应用日志根因。

## 13. 运维与监控建议
- 接入 Spring Boot Actuator 暴露健康检查端点（`/actuator/health`）。
- 结合日志轮转与集中采集（ELK/Vector），按环境区分日志路径。
- 数据库连接与线程池指标纳入监控（Druid/Quartz）。

## 14. 后续规划
- 增加 Redis 缓存与会话支持。
- Quartz 改为持久化存储以支持任务恢复与集群。
- 完善 CI/CD 流程，增加测试与安全检查。
- 引入统一配置中心（如 Nacos/Spring Cloud Config）管理多环境配置。

---

如需针对该方案进行扩展（例如新增模块、接口规范或部署拓扑图），可在 `docs/` 下继续补充专题文档。