# 前端构建说明

## 目录职责

| 目录 | 说明 |
|------|------|
| `frontend-vue/` | 前端源码（Vue 3 + Vite） |
| `src/main/resources/static/v2/` | **前端构建产物**，由 Vite 生成，不要手工修改 |

> ⚠️ `static/v2/` 是自动生成目录，请勿直接手工编辑其中的文件，  
> 应始终通过构建前端源码来更新。

---

## 本地开发

启动前端开发服务器（热重载，代理到后端 :8080）：

```bash
cd frontend-vue
npm install   # 首次或依赖变更时
npm run dev   # 启动 Vite dev server，访问 http://localhost:5173/v2/
```

---

## Maven 打包（含前端构建）

项目使用 `frontend-maven-plugin` 绑定在 **`prepare-package`** 阶段，  
只有 `mvn package`（及后续阶段）才会触发前端构建：

| 命令 | 前端构建 |
|------|---------|
| `mvn compile` | ❌ 不触发 |
| `mvn test` | ❌ 不触发 |
| `mvn package` | ✅ 自动执行 `install-node（v20 LTS） → npm ci → npm run build` |
```bash
# 完整打包（含前端构建，首次默认自动下载 Node）
mvn clean package -DskipTests

# 如果 nodejs.org 下载极慢或报错（如 Premature end of Content-Length），可指定国内镜像源：
mvn clean package -DskipTests -Dnode.download.root=https://npmmirror.com/mirrors/node/

# 跳过前端构建（前提：static/v2/ 中已存有最新的构建产物）
mvn clean package -DskipTests -Dskip.frontend.build=true
```

### 离线与缓存方案 (CI / 弱网环境)

由于默认全量打包依赖外网 Node.js 下载，当本地/CI环境无法直接访问外网或网络极其不稳定时，建议采用以下优化方案：

1. **手动预缓存 Node.js 包（最稳妥的离线打包方案）**
   您可以直接手动下载对应平台的 Node 压缩包，并放置到本地 Maven 缓存目录中。以 Linux x64 平台为例：
   - 下载对应版本的 Node 包：[node-v20.11.0-linux-x64.tar.gz](https://nodejs.org/dist/v20.11.0/node-v20.11.0-linux-x64.tar.gz)
   - 保存到本地 Maven 仓库缓存路径下：
     `~/.m2/repository/com/github/eirslett/node/20.11.0/node-20.11.0-linux-x64.tar.gz`
   - 再次运行 `mvn package` 时，插件检测到该本地缓存文件存在，将**直接读取该文件进行解压**，不会发起任何外网下载请求。

2. **切换镜像源**
   如果网络通畅但仅访问官方 nodejs.org 受限，可以使用 `-Dnode.download.root` 参数切换至其他镜像源：
   - 阿里云镜像：`-Dnode.download.root=https://npmmirror.com/mirrors/node/`
   - 华为云镜像：`-Dnode.download.root=https://mirrors.huaweicloud.com/nodejs/`

3. **跳过前端构建**
   如果仅变更后端 Java 代码，不需要重新编译前端，可直接通过 `-Dskip.frontend.build=true` 跳过前端：
   `mvn clean package -DskipTests -Dskip.frontend.build=true`

---

## Docker 构建（推荐生产方式）

```bash
make up
```

Dockerfile 使用多阶段构建：
1. Stage 1（`frontend-builder`）：`node:22-alpine` 执行 `npm ci && npm run build`
2. Stage 2（`builder`）：Maven 将前端产物 COPY 进来并打包 jar
3. Stage 3（`runner`）：最小 JRE 运行

---

## 首次配置 API Key 说明

服务启动后，如果未配置 API Key，`/api/settings` 返回：

```json
{
  "apiKeyConfigured": false,
  "apiKeySource": "none"
}
```

这是**正常状态**，请前往设置页配置 DeepSeek API Key 或 OpenAI 兼容 API Key。

也可通过环境变量配置 DeepSeek API Key：

```bash
export DEEPSEEK_API_KEY=sk-xxxxxxxx
```