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。
5.3 KiB
5.3 KiB
Purpose
定义 Bun 全栈应用运行时的 HTTP server、API 命名空间、健康检查、生产静态资源服务和 SPA fallback 行为。
Requirements
Requirement: Bun HTTP 运行时
系统 SHALL 运行一个 Bun HTTP server，由单个进程提供后端 API、健康检查、生产静态资源和 SPA fallback 行为。
Scenario: 启动运行时服务器
- WHEN server 进程成功启动
- THEN 它 SHALL 监听 YAML 配置文件中指定的 host 和 port，并记录实际 server URL
Scenario: 通过 YAML 配置提供运行时参数
- WHEN 通过 YAML 配置文件提供 host、port、数据目录等参数
- THEN server SHALL 使用该值，且不需要重新构建
Scenario: CLI 只接受配置文件路径
- WHEN 用户通过命令行启动程序
- THEN 系统 SHALL 只接受一个命令行参数作为 YAML 配置文件路径
Scenario: 提供拨测相关 API
- WHEN server 启动完成
- THEN 系统 SHALL 提供
/api/summary、/api/targets、/api/targets/:id/history、/api/targets/:id/trend端点
Requirement: HTTP method 语义
系统 SHALL 为运行时端点提供明确的 HTTP method 语义，避免不支持的 method 被错误地当作成功请求处理。
Scenario: GET 请求访问运行时端点
- WHEN 客户端使用
GET请求/health或/api/*端点 - THEN Bun server SHALL 返回对应端点的成功响应
Scenario: HEAD 请求访问运行时端点
- WHEN 客户端使用
HEAD请求/health或/api/*端点 - THEN Bun server SHALL 返回与
GET相同的成功状态和 headers，但 MUST NOT 返回响应体
Scenario: 不支持的 method 访问运行时端点
- WHEN 客户端使用不支持的 method 请求
/health或/api/*端点 - THEN Bun server SHALL 返回 405 状态码和 Allow header
Requirement: API 路由命名空间
系统 MUST 将 /api/* 保留给后端 API 路由。
Scenario: API 路由匹配
- WHEN 请求匹配已注册的
/api/*路由 - THEN Bun server SHALL 返回 API handler 的响应
Scenario: API 路由未命中
- WHEN 请求访问未注册的
/api/*路由 - THEN Bun server MUST 返回 JSON 404 响应，而不是前端 HTML 文档
Requirement: API 错误响应一致性
系统 SHALL 为 API 命名空间内的错误返回机器可读 JSON 响应。
Scenario: 未知 API 路由
- WHEN 客户端请求未知的
/api/*路由 - THEN Bun server MUST 返回包含
error和status字段的 JSON 404 响应，而不是前端 HTML 文档
Scenario: API method 不允许
- WHEN 客户端使用不支持的 method 请求已存在的 API 路由
- THEN Bun server MUST 返回包含
error和status字段的 JSON 405 响应
Requirement: 健康检查端点
系统 SHALL 在前端 SPA fallback 之外暴露健康检查端点。
Scenario: 健康检查成功
- WHEN 客户端请求
/health - THEN Bun server SHALL 返回成功的、机器可读的健康检查响应
Requirement: 生产静态资源服务
系统 SHALL 在生产模式下由 Bun runtime 服务 Vite 生产资源。
Scenario: 请求构建后的资源
- WHEN 客户端请求构建后的前端资源，例如
/assets/app.js - THEN Bun server SHALL 返回该资源并带有适当的 content type
Scenario: 请求前端根路径
- WHEN 客户端请求
/ - THEN Bun server SHALL 返回前端入口 HTML 文档
Requirement: 生产缓存策略
系统 SHALL 为生产静态资源和前端入口 HTML 使用明确的缓存策略。
Scenario: 请求前端入口 HTML
- WHEN 生产 Bun server 返回前端入口 HTML 文档
- THEN 响应 SHALL 使用
Cache-Control: no-cache
Scenario: 请求构建后的静态资源
- WHEN 生产 Bun server 返回 Vite 构建后的静态资源
- THEN 响应 SHALL 使用长缓存策略
public, max-age=31536000, immutable
Scenario: 请求未知静态资源
- WHEN 客户端请求不存在的
/assets/*资源或带文件扩展名的未知路径 - THEN Bun server MUST 返回 404，且 MUST NOT 返回前端入口 HTML 文档
Requirement: 低风险安全响应头
系统 SHALL 在生产运行时响应中附加低风险安全响应头，提升基础安全性且不提前约束未来前端资源策略。
Scenario: 生产 HTML 响应包含安全头
- WHEN 生产 Bun server 返回前端 HTML 文档
- THEN 响应 SHALL 包含
X-Content-Type-Options: nosniff和Referrer-Policyheaders
Scenario: 生产 JSON 响应包含安全头
- WHEN 生产 Bun server 返回
/health或/api/*JSON 响应 - THEN 响应 SHALL 包含
X-Content-Type-Options: nosniff和Referrer-Policyheaders
Scenario: 生产静态资源响应包含安全头
- WHEN 生产 Bun server 返回 Vite 构建后的静态资源
- THEN 响应 SHALL 包含
X-Content-Type-Options: nosniff和Referrer-Policyheaders
Requirement: SPA fallback 行为
系统 SHALL 在生产环境中为非 API、非静态资源的前端路由返回前端入口 HTML 文档。
Scenario: 刷新前端路由
- WHEN 客户端请求前端路由，例如
/dashboard - THEN Bun server SHALL 返回前端入口 HTML 文档
Scenario: 保留 API 错误语义
- WHEN 客户端请求未知的
/api/*路由 - THEN Bun server MUST NOT 返回前端入口 HTML 文档