# FastAPI 项目 - 前端（Frontend）

前端基于 [Vite](https://vitejs.dev/)、[React](https://reactjs.org/)、[TypeScript](https://www.typescriptlang.org/)、[TanStack Query](https://tanstack.com/query)、[TanStack Router](https://tanstack.com/router) 与 [Tailwind CSS](https://tailwindcss.com/) 构建。

## 前端开发

在开始之前，请确保系统中安装了 Node 版本管理工具：Node Version Manager（nvm）或 Fast Node Manager（fnm）。

* 安装 fnm 可参考 [官方文档](https://github.com/Schniz/fnm#installation)；如果你更喜欢 nvm，可参考 [nvm 官方文档](https://github.com/nvm-sh/nvm#installing-and-updating)。

* 安装好 nvm 或 fnm 后，进入 `frontend` 目录：

```bash
cd frontend
```

* 如果系统尚未安装 `.nvmrc` 中指定的 Node.js 版本，可以运行对应命令进行安装：

```bash
# 使用 fnm 时
fnm install

# 使用 nvm 时
nvm install
```

* 安装完成后，切换到该版本的 Node.js：

```bash
# 使用 fnm 时
fnm use

# 使用 nvm 时
nvm use
```

* 在 `frontend` 目录中安装依赖：

```bash
npm install
```

* 使用下面的脚本启动本地开发服务器（支持热更新）：

```bash
npm run dev
```

* 然后在浏览器中打开 `http://localhost:5173/`。

注意：这个开发服务器是在本机直接运行的，不在 Docker 容器中。这是推荐的前端开发方式：在本地使用 Vite 的热更新体验进行快速迭代；当前端就绪后，再构建前端 Docker 镜像，在接近生产环境的 Docker 中做最终验证。频繁为每次改动重建 Docker 镜像，会远不如直接用本地开发服务器高效。

更多可用的 npm 脚本与命令可以查看 `package.json`。

### 移除前端

如果你只需要开发纯 API（仅后端），想要彻底移除前端，可以按照下面步骤操作：

* 删除整个 `./frontend` 目录。

* 在 `docker-compose.yml` 中删除 `frontend` 服务（整个 service 区块）。

* 在 `docker-compose.override.yml` 中删除 `frontend` 与 `playwright` 两个服务的配置。

完成后，你就获得了一个“无前端”（仅 API）的应用。🤓

---

如果你愿意，还可以从以下位置删除与 `FRONTEND` 相关的环境变量，仅用于清理配置（保留它们也不会产生实际影响）：

* `.env`
* `./scripts/*.sh`

## 生成前端客户端（API Client）

### 自动方式

* 激活后端虚拟环境。
* 在项目根目录执行脚本：

```bash
./scripts/generate-client.sh
```

* 将生成的变更提交到仓库。

### 手动方式

* 启动 Docker Compose stack。

* 从 `http://localhost/api/v1/openapi.json` 下载 OpenAPI JSON 文件，并将其保存为 `frontend` 目录根下的 `openapi.json`。

* 生成前端客户端：

```bash
npm run generate-client
```

* 将生成的变更提交到仓库。

请注意，每当后端发生影响 OpenAPI Schema 的变更时，都需要重新执行上述步骤以更新前端客户端。

## 使用远程 API

如果你希望前端调用远程环境的 API，可以设置环境变量 `VITE_API_URL` 为远程 API 的基础 URL，例如在 `frontend/.env` 中配置：

```env
VITE_API_URL=https://api.my-domain.example.com
```

之后启动前端时，它会将该地址作为 API 请求的基础 URL。

## 代码结构

前端代码结构大致如下：

* `frontend/src` - 前端主要源代码。
* `frontend/src/assets` - 静态资源。
* `frontend/src/client` - 通过 OpenAPI 生成的前端客户端代码。
* `frontend/src/components` - 各种通用组件与业务组件。
* `frontend/src/hooks` - 自定义 Hooks。
* `frontend/src/routes` - 路由定义及页面组件。

## 使用 Playwright 做端到端测试（E2E）

前端中预置了基于 Playwright 的端到端测试。要运行测试，需要先启动 Docker Compose stack。可以使用如下命令启动（至少需要后端）：

```bash
docker compose up -d --wait backend
```

然后运行 Playwright 测试：

```bash
npx playwright test
```

你也可以使用 UI 模式运行测试，以便查看浏览器界面并与之交互：

```bash
npx playwright test --ui
```

测试完成后，如果希望停止并移除 Docker Compose stack，同时清理测试期间创建的数据，可运行：

```bash
docker compose down -v
```

如需更新或新增 E2E 测试用例，只需到 `frontend/tests` 目录中修改现有测试文件或新增文件。

更多关于编写与运行 Playwright 测试的说明，可参考官方文档：[Playwright documentation](https://playwright.dev/docs/intro)。