# 项目技术文档

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

## 概述
- 平台型后端服务，采用 `Spring Boot 3.x`，区分 `dev` / `server` 两种运行配置。
- 数据访问使用 `MyBatis-Plus 3.5.6` 与 `MyBatis 3.5.16`，连接池为 `Druid`。
- 任务调度使用 `Quartz 2.3.2`；API 文档采用 `springdoc-openapi` / Swagger UI。
- 支持 WAR 包运行，亦可容器化部署；默认开发端口 `8093`（`server` 可使用 `8090`）。

## 目录结构
- 仓库根（当前工作目录）：`D:\Trae_space\ProjectFrameWork2025\app`
- 主要结构：
```
app/
├── .gitignore
├── Dockerfile
├── frontend/                 # 前端说明或资源
│   └── readme.md
├── pom.xml                   # Maven 构建管理
└── src/
    ├── main/
    │   ├── java/             # 业务代码（入口类在 com.yfd.platform.*）
    │   └── resources/        # 配置与静态资源
    └── test/
        └── java/             # 测试代码
```

## 快速开始
- 前置要求：
  - 安装 `JDK 21`（兼容 17+），`Maven 3.9+`，`Git`。
  - Windows 终端执行 `chcp 65001`，确保 UTF-8 编码输出。
- 构建后端：
  - `mvn clean package -DskipTests`
- 本地运行（dev）：
  - `java -jar target/platform-1.0.war --spring.profiles.active=dev`
- 运行（server）：
  - `java -jar target/platform-1.0.war --spring.profiles.active=server`
- API 文档：
  - 默认访问 `http://localhost:8093/swagger-ui/index.html`（以实际配置为准）

## 配置说明
- Profile 切换：
  - 通过 `--spring.profiles.active=<dev|server>` 激活环境。
- 关键属性：
  - `file-space.system`：文件根路径，需在激活的 profile 中配置。
  - `spring.datasource.druid.*`：数据库连接参数与池化配置。
  - `server.port`：端口（`dev` 默认 8093，`server` 可使用 8090）。
- VS Code/终端编码建议：
  - 启动参数加入 `-Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8`。
  - 终端执行 `chcp 65001`，PowerShell 输出设置为 UTF-8。

## 依赖与版本
- `Spring Boot 3.x`
- `MyBatis-Plus 3.5.6`（依赖 `MyBatis 3.5.16+`，需有 `Configuration.parsePendingResultMaps(boolean)`）
- `Druid` 数据源
- `Quartz 2.3.2`
- `springdoc-openapi` / Swagger UI
- 日志：`Logback`（UTF-8 输出，`logback-spring.xml`）

## 数据库配置
- 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;
```
- Druid 健壮性：
```yaml
spring:
  datasource:
    druid:
      initial-size: 0
      test-on-borrow: false
      test-while-idle: true
      validation-query: SELECT 1
```

## 日志
- 控制台与文件统一 UTF-8 输出：
  - 控制台 `ConsoleAppender`，文件 `RollingFileAppender`（按日滚动，保留 30 天）。
  - 推荐日志格式：`%d [%thread] %-5level %logger{50} - %msg%n`。

## 定时任务
- 默认 `RAMJobStore`（非集群、内存存储）。
- 如需持久化与集群，改用 `JdbcJobStore` 并配置数据源与表结构。

## 安全与鉴权
- 使用 `JWT` 过滤器进行鉴权（如 `jwtAuthenticationTokenFilter`）。
- 敏感配置（`jwt.secret`、数据库密码）建议通过环境变量或外部密钥管理。
- 生产环境必须启用 HTTPS 并使用强密钥。

## API 文档
- 启用 `swagger-ui.enabled: true`。
- 访问路径通常为 `http://<host>:<port>/swagger-ui/index.html`。

## Docker 部署
- `Dockerfile` 已暴露端口 `8093`：
  - 构建镜像：`docker build -t projectframework2025-app:latest .`
  - 运行（开发环境）：
    - `docker run -d --name platform-app -p 8093:8093 -e SPRING_PROFILES_ACTIVE=dev projectframework2025-app:latest`
  - 运行（服务器环境）：
    - `docker run -d --name platform-app -p 8090:8090 -e SPRING_PROFILES_ACTIVE=server projectframework2025-app:latest`
- 如需挂载文件空间：
  - `-v D:/data/file-space:/data/file-space -e FILE_SPACE_SYSTEM=/data/file-space`

## 前端
- 前端说明见 `frontend/readme.md`。如需联调，请统一跨域与鉴权策略。

## Git 使用
- 远程仓库：`http://121.37.111.42:3000/ThbTech/ProjectFrameWork2025.git`
- 主分支：`main`
- 常用命令：
  - `git pull`、`git add .`、`git commit -m "<message>"`、`git push`
- 提交署名：
  - `git config user.name "<Your Name>"`
  - `git config user.email "<your@email>"`

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

## 运维与监控
- 建议接入 `Spring Boot Actuator`：`/actuator/health`。
- 配合日志轮转与集中采集（ELK/Vector），区分环境日志路径。
- 监控数据库与线程池指标（Druid/Quartz）。

## CI/CD 建议
- 在 CI 阶段执行：
  - `mvn -B -DskipTests clean package`
  - 单元测试与安全扫描（依赖检查、代码质量）
- 在 CD 阶段：
  - 推送镜像到私有仓库，环境变量注入敏感信息。

## 变更日志（示例模板）
- `feat:` 新增功能说明
- `fix:` 缺陷修复说明
- `docs:` 文档更新说明
- `refactor:` 重构说明
- `perf:` 性能优化说明

---

如需扩展专题文档（接口规范、部署拓扑、参数字典等），建议在 `docs/` 目录继续维护并与版本管理同步。