# 前后端一体化构建与打包说明

本文档说明如何在 Maven 构建流程中，先编译前端（pnpm），再编译后端（Java），并在 `package` 阶段将两者一起打包，使生成的可运行 `jar/war` 直接可以访问前端首页 `index.html`。

## 前置要求
- 已安装 JDK（推荐 17+）和 Maven（3.6.3+）。
- 已安装 Node.js（推荐 18+）与 pnpm（全局）：`npm i -g pnpm`。
- 当前项目结构：
  - 后端（Spring Boot）：`app/pom.xml`，源码在 `app/src/main/java` 与资源在 `app/src/main/resources`。
  - 前端（Vite/Vue）：位于 `app/frontend`，构建输出目录默认是 `app/frontend/dist`。

## 构建流程概览
在 `pom.xml` 中集成了以下步骤：
1. `generate-resources` 阶段：进入 `frontend` 目录，执行 `pnpm install --frozen-lockfile` 与 `pnpm run build`。
2. `process-resources` 阶段：将前端构建产物从 `frontend/dist` 复制到后端资源目录 `src/main/resources/static`。
3. 随后执行后端 Java 编译与打包，最终产出可运行的 `jar/war`。

这样在运行后端时，Spring Boot 会从类路径的 `static` 目录自动提供 `index.html` 作为欢迎页入口（访问根路径 `/` 即可看到前端页面）。

## 关键 POM 配置（摘要）
已经在 `app/pom.xml` 的 `<build><plugins>` 中加入：
- `exec-maven-plugin`：在 Java 编译前执行 pnpm 安装与构建。
- `maven-resources-plugin`：复制前端构建产物到 `src/main/resources/static`。

无需手动改动目录，只需按下述命令执行即可。

## 常用命令
- 开发运行（跳过测试）：`mvn -DskipTests spring-boot:run`
  - 如需指定开发配置：`mvn -DskipTests -Dspring-boot.run.profiles=dev spring-boot:run`
- 构建打包（跳过测试）：`mvn -DskipTests package`
  - 构建过程中会自动执行前端构建并拷贝到后端资源。

## 运行与访问
- 运行可执行包（以 `war` 为例，`artifactId=platform`，`version=1.0`）：
  - 默认运行：`java -jar target/platform-1.0.war`
  - 指定 dev 配置：`java -Dspring.profiles.active=dev -jar target/platform-1.0.war`
- 访问：
  - 若启用 `dev` 配置并端口为 `8093`：`http://localhost:8093/`
  - 若使用默认端口（例如 `18080`）：`http://localhost:18080/`

> 说明：Spring Boot 会自动将 `classpath:/static/index.html` 作为欢迎页，访问根路径即可进入前端入口页面。

## 注意事项
- 请确保 `pnpm` 可在构建机/开发机的环境变量中直接调用。
- 若前端构建输出目录（`dist`）有自定义，请同步更新 POM 中的复制路径。
- 如前端使用路由的 `history` 模式并期望后端兜底到 `index.html`，可按需添加后端控制器或使用前端服务器侧配置（当前方案以静态欢迎页为主）。

## 故障排查
- 构建失败（找不到 `pnpm`）：确认已安装并可在命令行执行 `pnpm -v`。
- 页面乱码：已在 POM 配置统一 JVM 编码为 `UTF-8`；在 Windows PowerShell 终端也应设置为 `UTF-8`。

完成上述配置后，只需使用 Maven 的标准命令，即可实现前后端一体化构建和打包运行。