lanyuanxiaoyao
57d3a5cfb4
新增 YAML 配置解析（Bun 内置 YAML）、SQLite 数据存储（bun:sqlite）、按 interval 分组并发拨测引擎、REST API（/api/summary、/api/targets、/api/targets/:id/history、/api/targets/:id/trend）、React 前端 Dashboard（统计卡片、目标表格、可展开详情面板、recharts 趋势图）。CLI 简化为仅接受配置文件路径。移除 /api/demo 路由和相关 demo 代码。保留 /health、静态资源服务和 SPA fallback。
79 lines
3.6 KiB
Markdown
79 lines
3.6 KiB
Markdown
## Purpose
|
||
|
||
定义 Vite + React + TypeScript 前端开发工作流、开发期 API 代理和共享契约的行为要求。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: Vite React 开发服务器
|
||
系统 SHALL 提供基于 Vite + React + TypeScript 的前端开发工作流，并支持热模块替换。
|
||
|
||
#### Scenario: 启动前端开发服务器
|
||
- **WHEN** 开发者启动前端开发命令
|
||
- **THEN** 前端 SHALL 由 Vite 提供服务，并启用 React 热模块替换
|
||
|
||
#### Scenario: 构建前端静态资源
|
||
- **WHEN** 开发者运行前端生产构建命令
|
||
- **THEN** 系统 SHALL 产出可由 Bun 后端服务的前端静态资源
|
||
|
||
### Requirement: 前端开发期 API 代理
|
||
前端开发服务器 SHALL 在本地开发期间将 `/api/*` 请求代理到 Bun 后端服务。
|
||
|
||
#### Scenario: 前端开发期调用拨测 API
|
||
- **WHEN** 浏览器从 Vite 开发源请求 `/api/summary`、`/api/targets` 等拨测 API
|
||
- **THEN** Vite SHALL 将请求转发到 Bun 后端服务，且不需要浏览器 CORS 配置
|
||
|
||
#### Scenario: 开发期访问非 API 前端路由
|
||
- **WHEN** 浏览器从 Vite 开发源请求非 API 前端路由
|
||
- **THEN** Vite SHALL 将该请求作为前端应用流量处理，而不是转发到后端
|
||
|
||
### Requirement: 开发期后端端口一致性
|
||
项目 SHALL 保证文档化的全栈开发命令中，Vite proxy 目标端口与 Bun 后端监听端口来自同一配置来源。
|
||
|
||
#### Scenario: 使用默认开发端口
|
||
- **WHEN** 开发者未提供端口覆盖并运行文档化的全栈开发命令
|
||
- **THEN** Bun 后端 SHALL 监听默认端口，且 Vite SHALL 将 `/api/*` 代理到同一端口
|
||
|
||
#### Scenario: 使用 PORT 覆盖开发端口
|
||
- **WHEN** 开发者通过 `PORT` 覆盖后端端口并运行文档化的全栈开发命令
|
||
- **THEN** Bun 后端 SHALL 监听该端口，且 Vite SHALL 将 `/api/*` 代理到同一端口
|
||
|
||
#### Scenario: 避免代理端口与后端端口分叉
|
||
- **WHEN** 开发期脚本需要向 Vite 传递后端端口
|
||
- **THEN** 该代理端口 MUST 从文档化的后端端口配置派生，而不是作为独立对外配置导致分叉
|
||
|
||
### Requirement: 前端使用相对 API 路径
|
||
除非有文档化的部署配置覆盖该行为，前端代码 MUST 通过相对 `/api/*` URL 调用后端 API。
|
||
|
||
#### Scenario: 前端获取后端数据
|
||
- **WHEN** 前端代码调用后端 API
|
||
- **THEN** 请求 URL 默认 MUST 使用相对 `/api/*` 路径
|
||
|
||
#### Scenario: 运行环境变化
|
||
- **WHEN** host 或 port 在开发环境和生产环境之间变化
|
||
- **THEN** 前端 API 调用 SHALL 无需修改源码即可继续工作
|
||
|
||
### Requirement: 集成开发命令
|
||
项目 SHALL 提供一个文档化命令，用于在开发期间同时运行前端和后端。
|
||
|
||
#### Scenario: 启动全栈开发
|
||
- **WHEN** 开发者运行文档化的全栈开发命令
|
||
- **THEN** 系统 SHALL 启动 Vite 前端开发服务器和 Bun 后端服务器
|
||
|
||
### Requirement: 开发质量命令文档化
|
||
项目 SHALL 在前端开发工作流文档中说明日常检查和完整验证命令。
|
||
|
||
#### Scenario: 查阅开发命令
|
||
- **WHEN** 开发者阅读 README 的开发或测试章节
|
||
- **THEN** 文档 SHALL 说明 `check` 用于日常开发检查，`verify` 用于提交前或发布前完整验证
|
||
|
||
### Requirement: 共享 TypeScript 契约
|
||
项目 SHALL 为前端和后端共同使用的请求与响应类型提供共享 TypeScript 边界。
|
||
|
||
#### Scenario: 定义 API 响应结构
|
||
- **WHEN** 前端和后端都需要某个 API 响应类型
|
||
- **THEN** 该类型 SHALL 定义在 shared 模块中，而不是在两端重复定义
|
||
|
||
#### Scenario: 前端导入共享类型
|
||
- **WHEN** 前端代码导入共享 API 类型
|
||
- **THEN** 该导入 SHALL 不要求将后端运行时实现打包进前端
|