## Purpose

定义基于 Vite dev server + Bun API server 的前端开发工作流、开发期 API 访问和共享契约的行为要求。

## Requirements

### Requirement: Vite React 开发服务器
系统 SHALL 提供基于 Vite dev server 的前端开发工作流，支持热模块替换和 React Fast Refresh。

#### Scenario: 启动前端开发服务器
- **WHEN** 开发者启动开发命令
- **THEN** 前端 SHALL 由 Vite dev server 提供服务，支持 HMR 和 React Fast Refresh，监听 :5173 端口

#### Scenario: 构建前端静态资源
- **WHEN** 开发者运行前端生产构建命令
- **THEN** 系统 SHALL 通过 Vite build（Rolldown）产出优化的前端静态资源到 `dist/web/`

### Requirement: 前端开发期 API 代理
前端开发服务器 SHALL 通过 Vite proxy 配置将 API 请求转发到后端 server。

#### Scenario: 前端开发期调用拨测 API
- **WHEN** 浏览器从 Vite dev server 请求 `/api/*` 路径
- **THEN** Vite SHALL 通过 proxy 将请求转发到 Bun API server（默认 :3000）

#### Scenario: 前端开发期访问健康检查
- **WHEN** 浏览器从 Vite dev server 请求 `/health`
- **THEN** Vite SHALL 通过 proxy 将请求转发到 Bun API server

#### Scenario: 开发期访问非 API 前端路由
- **WHEN** 浏览器从 Vite dev server 请求非 API 前端路由
- **THEN** Vite SHALL 将该请求作为前端应用流量处理（SPA fallback 返回 HTML）

### Requirement: 开发期双进程运行
项目 SHALL 在开发命令中同时启动 Vite dev server 和 Bun API server 两个进程。

#### Scenario: 使用默认开发端口
- **WHEN** 开发者运行开发命令
- **THEN** Vite dev server SHALL 监听 :5173，Bun API server SHALL 监听配置文件指定的端口（默认 :3000）

#### Scenario: 开发者访问前端
- **WHEN** 开发者打开浏览器
- **THEN** 开发者 SHALL 访问 Vite dev server 地址（:5173）获取前端页面

### Requirement: 前端使用相对 API 路径
除非有文档化的部署配置覆盖该行为，前端代码 MUST 通过相对 `/api/*` URL 调用后端 API。

#### Scenario: 前端获取后端数据
- **WHEN** 前端代码调用后端 API
- **THEN** 请求 URL 默认 MUST 使用相对 `/api/*` 路径

#### Scenario: 运行环境变化
- **WHEN** host 或 port 在开发环境和生产环境之间变化
- **THEN** 前端 API 调用 SHALL 无需修改源码即可继续工作（开发期通过 Vite proxy，生产期通过同源请求）

### Requirement: 集成开发命令
项目 SHALL 提供一个文档化命令，用于在开发期间同时运行 Vite dev server 和 Bun API server。

#### Scenario: 启动全栈开发
- **WHEN** 开发者运行文档化的全栈开发命令
- **THEN** 系统 SHALL 同时启动 Vite dev server 和 Bun API server，任一进程异常退出时终止另一个

### Requirement: 共享 TypeScript 契约
项目 SHALL 为前端和后端共同使用的请求与响应类型提供共享 TypeScript 边界。

#### Scenario: 定义 API 响应结构
- **WHEN** 前端和后端都需要某个 API 响应类型
- **THEN** 该类型 SHALL 定义在 shared 模块中，而不是在两端重复定义

#### Scenario: 前端导入共享类型
- **WHEN** 前端代码导入共享 API 类型
- **THEN** 该导入 SHALL 不要求将后端运行时实现打包进前端