refactor: 迁移 Bun fullstack 架构
This commit is contained in:
@@ -1,12 +1,12 @@
|
||||
## Purpose
|
||||
|
||||
定义后端 API 路由的组织规范：按端点拆分为独立 handler、共享响应工具集中管理、参数校验逻辑抽取为中间件、静态资源服务独立维护。
|
||||
定义后端 API 路由的组织规范：按端点拆分为独立 handler、共享响应工具集中管理、路径参数由 Bun routes 解析，静态资源服务由 HTML import manifest 管理。
|
||||
|
||||
## Requirements
|
||||
|
||||
|
||||
### Requirement: 路由按职责拆分
|
||||
系统 SHALL 将 HTTP 路由处理逻辑按 API 端点拆分为独立模块，每个模块导出一个 handler 函数供 app.ts 统一注册。
|
||||
系统 SHALL 将 HTTP 路由处理逻辑按 API 端点拆分为独立模块，每个模块导出 route handler 函数供 routes 对象统一注册。
|
||||
|
||||
#### Scenario: health 端点独立路由
|
||||
- **WHEN** 客户端请求 `GET /health`
|
||||
@@ -22,11 +22,11 @@
|
||||
|
||||
#### Scenario: history 端点独立路由
|
||||
- **WHEN** 客户端请求 `GET /api/targets/:id/history?from=ISO&to=ISO`
|
||||
- **THEN** `routes/history.ts` 导出的 handler 负责处理，包含参数校验、store 查询和 HistoryResponse 返回
|
||||
- **THEN** `routes/history.ts` 导出的 handler 负责处理，通过 `req.params.id` 获取路径参数，包含参数校验、store 查询和 HistoryResponse 返回
|
||||
|
||||
#### Scenario: trend 端点独立路由
|
||||
- **WHEN** 客户端请求 `GET /api/targets/:id/trend?from=ISO&to=ISO`
|
||||
- **THEN** `routes/trend.ts` 导出的 handler 负责处理，包含参数校验、store 查询和 TrendPoint[] 返回
|
||||
- **THEN** `routes/trend.ts` 导出的 handler 负责处理，通过 `req.params.id` 获取路径参数，包含参数校验、store 查询和 TrendPoint[] 返回
|
||||
|
||||
### Requirement: 共享辅助函数集中管理
|
||||
系统 SHALL 将跨路由共享的响应格式化函数抽取到 helpers.ts 模块，单一职责、集中管理。
|
||||
@@ -43,36 +43,17 @@
|
||||
- **WHEN** 需要将 StoredCheckResult 映射为 API CheckResult
|
||||
- **THEN** 从 `helpers.ts` 导入 `mapCheckResult` 函数，处理 failure JSON 解析和格式转换
|
||||
|
||||
### Requirement: 参数校验逻辑抽取为中间件
|
||||
系统 SHALL 将重复的参数校验逻辑（target ID 解析、时间范围校验、分页参数校验、方法检查）抽取到 middleware.ts 模块。
|
||||
|
||||
#### Scenario: 方法检查中间件
|
||||
- **WHEN** 请求方法不是 GET 或 HEAD
|
||||
- **THEN** `guardGetHead(request, mode)` SHALL 返回 405 Response，否则返回 null 表示放行
|
||||
|
||||
#### Scenario: Target ID 校验
|
||||
- **WHEN** URL 中的 id 参数不是正整数
|
||||
- **THEN** `validateTargetId(idStr)` SHALL 返回 400 ApiError
|
||||
|
||||
#### Scenario: 时间范围参数校验
|
||||
- **WHEN** from 或 to 参数缺失或格式无效
|
||||
- **THEN** `validateTimeRange(from, to)` SHALL 返回 400 ApiError
|
||||
|
||||
#### Scenario: 分页参数校验
|
||||
- **WHEN** page 或 pageSize 参数不是正整数
|
||||
- **THEN** `validatePagination(page, pageSize)` SHALL 返回 400 ApiError
|
||||
|
||||
### Requirement: 静态资源服务独立管理
|
||||
系统 SHALL 将静态资源服务、SPA fallback 和 Content-Type 映射逻辑抽取到 static.ts 模块。
|
||||
系统 SHALL 将 SPA fallback 逻辑交给 routes 对象中的 HTML import 通配符处理，静态资源服务由 Bun 内置 manifest 机制自动处理。
|
||||
|
||||
#### Scenario: 根路径返回 index.html
|
||||
- **WHEN** 客户端请求 `/`
|
||||
- **THEN** `static.ts` 的 handler 返回 index.html，设置正确的 Content-Type 和 Cache-Control
|
||||
- **THEN** routes 中注册的 HTML import 自动返回 index.html
|
||||
|
||||
#### Scenario: 资源文件返回正确 Content-Type
|
||||
- **WHEN** 客户端请求 `/assets/main.js`
|
||||
- **THEN** `static.ts` 的 handler 根据文件扩展名返回正确的 Content-Type（如 `.js` → `text/javascript`）
|
||||
- **WHEN** 客户端请求构建后的静态资源
|
||||
- **THEN** Bun 内置 manifest 机制自动返回正确的 Content-Type 和缓存头
|
||||
|
||||
#### Scenario: SPA fallback
|
||||
- **WHEN** 客户端请求非 API、非资源的路径（如 `/dashboard`）
|
||||
- **THEN** `static.ts` 的 handler 返回 index.html 实现 SPA 的客户端路由
|
||||
- **THEN** routes 中注册的 `"/*"` HTML import 通配符返回 index.html 实现 SPA 的客户端路由
|
||||
|
||||
49
openspec/specs/bun-fullstack-routing/spec.md
Normal file
49
openspec/specs/bun-fullstack-routing/spec.md
Normal file
@@ -0,0 +1,49 @@
|
||||
## Purpose
|
||||
|
||||
定义基于 Bun.serve `routes` 对象的全栈声明式路由注册、路径参数、HTTP method 声明和 fallback 行为。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 声明式路由注册
|
||||
系统 SHALL 使用 Bun.serve 的 `routes` 对象以声明式方式注册所有 HTTP 路由，包括 HTML 页面路由和 API 端点路由。
|
||||
|
||||
#### Scenario: HTML 页面路由注册
|
||||
- **WHEN** server 启动时
|
||||
- **THEN** 系统 SHALL 通过 HTML import 将前端入口注册到 `routes` 对象的 `"/*"` 通配符路径
|
||||
|
||||
#### Scenario: API 端点路由注册
|
||||
- **WHEN** server 启动时
|
||||
- **THEN** 系统 SHALL 将所有 API 端点以 method handler 对象形式注册到 `routes` 对象
|
||||
|
||||
### Requirement: 路径参数支持
|
||||
系统 SHALL 使用 routes 对象的 `:param` 语法声明路径参数，替代手动 regex 匹配。
|
||||
|
||||
#### Scenario: 带路径参数的 API 路由
|
||||
- **WHEN** 客户端请求 `/api/targets/123/history`
|
||||
- **THEN** 系统 SHALL 通过 `routes` 中注册的 `/api/targets/:id/history` 匹配，并通过 `req.params.id` 获取参数值 `"123"`
|
||||
|
||||
#### Scenario: 路径参数类型
|
||||
- **WHEN** route handler 接收到路径参数
|
||||
- **THEN** 参数值 SHALL 为字符串类型，handler 负责进行类型转换和校验
|
||||
|
||||
### Requirement: HTTP Method 声明
|
||||
系统 SHALL 在 routes 对象中为每个 API 端点以 per-method handler 形式声明支持的 HTTP method；未匹配 method 的 API 请求 SHALL 落入 `/api/*` 通配符并返回 JSON 404。
|
||||
|
||||
#### Scenario: 单 method 端点
|
||||
- **WHEN** API 端点只支持 GET 方法
|
||||
- **THEN** 该端点 SHALL 以 `{ GET(req) { ... } }` 形式注册
|
||||
|
||||
#### Scenario: 不支持的 method 请求
|
||||
- **WHEN** 客户端使用未声明的 method 请求 API 端点
|
||||
- **THEN** `/api/*` 通配符 SHALL 返回 JSON 格式的 404 错误响应
|
||||
|
||||
### Requirement: Fetch Fallback 处理
|
||||
系统 SHALL 使用 `fetch` handler 作为兜底，理论上不应被触发（所有路径都被 routes 通配符覆盖）。
|
||||
|
||||
#### Scenario: 未匹配的 API 路由
|
||||
- **WHEN** 请求路径以 `/api/` 开头但未在具体 API 路由中注册
|
||||
- **THEN** `/api/*` 通配符 SHALL 返回 JSON 格式的 404 错误响应
|
||||
|
||||
#### Scenario: 未匹配的非 API 路由
|
||||
- **WHEN** 请求路径不以 `/api/` 开头且未在具体路由中注册
|
||||
- **THEN** `"/*": homepage` 通配符 SHALL 返回前端入口 HTML 文档（带 HMR 注入）
|
||||
@@ -1,6 +1,6 @@
|
||||
## Purpose
|
||||
|
||||
定义项目代码质量门禁、格式化检查、快速检查和完整验证命令的行为要求，确保开发者可以通过文档化命令稳定验证源码质量、基础测试和生产 executable 行为。
|
||||
定义项目代码质量门禁、格式化检查、快速检查和完整验证命令的行为要求，确保开发者可以通过文档化命令稳定验证源码质量、基础测试和生产构建。
|
||||
|
||||
## Requirements
|
||||
|
||||
@@ -108,11 +108,11 @@
|
||||
- **THEN** `check` MUST 以非零状态退出且不静默忽略失败
|
||||
|
||||
### Requirement: 完整验证命令
|
||||
项目 SHALL 提供完整 `verify` 命令，用于提交前或发布前验证当前源码、测试和生产 executable 行为。
|
||||
项目 SHALL 提供完整 `verify` 命令，用于提交前或发布前验证当前源码、测试和生产构建。原 executable smoke test 暂时移除，后续通过独立变更重新设计。
|
||||
|
||||
#### Scenario: 运行完整验证
|
||||
- **WHEN** 开发者运行 `bun run verify`
|
||||
- **THEN** 系统 SHALL 先运行 `check`，再运行生产构建和 executable smoke test
|
||||
- **THEN** 系统 SHALL 先运行 `check`，再运行生产构建
|
||||
|
||||
#### Scenario: 完整验证失败
|
||||
- **WHEN** `verify` 中任一阶段失败
|
||||
|
||||
@@ -1,45 +1,41 @@
|
||||
## Purpose
|
||||
|
||||
定义 Vite + React + TypeScript 前端开发工作流、开发期 API 代理和共享契约的行为要求。
|
||||
定义 Bun.serve fullstack + React + TypeScript 前端开发工作流、开发期 API 访问和共享契约的行为要求。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Vite React 开发服务器
|
||||
系统 SHALL 提供基于 Vite + React + TypeScript 的前端开发工作流，并支持热模块替换。
|
||||
系统 SHALL 提供基于 Bun.serve fullstack 模式的前端开发工作流，并支持热模块替换和 React Fast Refresh。
|
||||
|
||||
#### Scenario: 启动前端开发服务器
|
||||
- **WHEN** 开发者启动前端开发命令
|
||||
- **THEN** 前端 SHALL 由 Vite 提供服务，并启用 React 热模块替换
|
||||
- **WHEN** 开发者启动开发命令
|
||||
- **THEN** 前端 SHALL 由 Bun.serve 的 HTML import 机制提供服务，并通过 `development: { hmr: true, console: true }` 启用 HMR、React Fast Refresh 和浏览器 console 回显
|
||||
|
||||
#### Scenario: 构建前端静态资源
|
||||
- **WHEN** 开发者运行前端生产构建命令
|
||||
- **THEN** 系统 SHALL 产出可由 Bun 后端服务的前端静态资源
|
||||
- **THEN** 系统 SHALL 通过 Bun.build 的 HTML import ahead-of-time bundling 产出可由 Bun 后端服务的前端静态资源
|
||||
|
||||
### Requirement: 前端开发期 API 代理
|
||||
前端开发服务器 SHALL 在本地开发期间将 `/api/*` 请求代理到 Bun 后端服务。
|
||||
前端开发服务器 SHALL 在本地开发期间无需代理配置即可访问后端 API，因为前后端运行在同一进程同一端口。
|
||||
|
||||
#### Scenario: 前端开发期调用拨测 API
|
||||
- **WHEN** 浏览器从 Vite 开发源请求 `/api/summary`、`/api/targets` 等拨测 API
|
||||
- **THEN** Vite SHALL 将请求转发到 Bun 后端服务，且不需要浏览器 CORS 配置
|
||||
- **WHEN** 浏览器从开发服务器请求 `/api/summary`、`/api/targets` 等拨测 API
|
||||
- **THEN** Bun.serve SHALL 直接由 routes 中注册的 API handler 处理请求，无需 proxy 转发
|
||||
|
||||
#### Scenario: 开发期访问非 API 前端路由
|
||||
- **WHEN** 浏览器从 Vite 开发源请求非 API 前端路由
|
||||
- **THEN** Vite SHALL 将该请求作为前端应用流量处理，而不是转发到后端
|
||||
- **WHEN** 浏览器从开发服务器请求非 API 前端路由
|
||||
- **THEN** Bun.serve SHALL 将该请求作为前端应用流量处理（SPA fallback 返回 HTML）
|
||||
|
||||
### Requirement: 开发期后端端口一致性
|
||||
项目 SHALL 保证文档化的全栈开发命令中，Vite proxy 目标端口与 Bun 后端监听端口来自同一配置来源。
|
||||
### Requirement: 开发期单端口运行
|
||||
项目 SHALL 保证开发命令中前端页面、HMR 和后端 API 由同一个 Bun.serve 进程在同一端口提供服务。
|
||||
|
||||
#### Scenario: 使用默认开发端口
|
||||
- **WHEN** 开发者未提供端口覆盖并运行文档化的全栈开发命令
|
||||
- **THEN** Bun 后端 SHALL 监听默认端口，且 Vite SHALL 将 `/api/*` 代理到同一端口
|
||||
- **WHEN** 开发者未提供端口覆盖并运行开发命令
|
||||
- **THEN** Bun.serve SHALL 在默认端口同时提供前端页面、HMR 和后端 API
|
||||
|
||||
#### Scenario: 使用 PORT 覆盖开发端口
|
||||
- **WHEN** 开发者通过 `PORT` 覆盖后端端口并运行文档化的全栈开发命令
|
||||
- **THEN** Bun 后端 SHALL 监听该端口，且 Vite SHALL 将 `/api/*` 代理到同一端口
|
||||
|
||||
#### Scenario: 避免代理端口与后端端口分叉
|
||||
- **WHEN** 开发期脚本需要向 Vite 传递后端端口
|
||||
- **THEN** 该代理端口 MUST 从文档化的后端端口配置派生，而不是作为独立对外配置导致分叉
|
||||
#### Scenario: 使用配置覆盖开发端口
|
||||
- **WHEN** 开发者通过配置文件覆盖端口并运行开发命令
|
||||
- **THEN** Bun.serve SHALL 在配置端口同时提供前端页面、HMR 和后端 API
|
||||
|
||||
### Requirement: 前端使用相对 API 路径
|
||||
除非有文档化的部署配置覆盖该行为，前端代码 MUST 通过相对 `/api/*` URL 调用后端 API。
|
||||
@@ -57,7 +53,7 @@
|
||||
|
||||
#### Scenario: 启动全栈开发
|
||||
- **WHEN** 开发者运行文档化的全栈开发命令
|
||||
- **THEN** 系统 SHALL 启动 Vite 前端开发服务器和 Bun 后端服务器
|
||||
- **THEN** 系统 SHALL 启动单个 Bun.serve 进程，同时提供前端 HMR 和后端 API 服务
|
||||
|
||||
### Requirement: 开发质量命令文档化
|
||||
项目 SHALL 在前端开发工作流文档中说明日常检查和完整验证命令。
|
||||
|
||||
@@ -5,11 +5,11 @@
|
||||
## Requirements
|
||||
|
||||
### Requirement: Bun HTTP 运行时
|
||||
系统 SHALL 运行一个 Bun HTTP server，由单个进程提供后端 API、健康检查、生产静态资源和 SPA fallback 行为。
|
||||
系统 SHALL 运行一个 Bun HTTP server，使用 `routes` 对象声明式注册 HTML 页面路由和 API 端点，由单个进程提供后端 API、健康检查和前端服务。
|
||||
|
||||
#### Scenario: 启动运行时服务器
|
||||
- **WHEN** server 进程成功启动
|
||||
- **THEN** 它 SHALL 监听 YAML 配置文件中指定的 host 和 port，并记录实际 server URL
|
||||
- **THEN** 它 SHALL 监听配置文件中指定的 host 和 port，通过 routes 对象注册所有路由，并记录实际 server URL
|
||||
|
||||
#### Scenario: 通过 YAML 配置提供运行时参数
|
||||
- **WHEN** 通过 YAML 配置文件提供 host、port、数据目录等参数
|
||||
@@ -21,22 +21,18 @@
|
||||
|
||||
#### Scenario: 提供拨测相关 API
|
||||
- **WHEN** server 启动完成
|
||||
- **THEN** 系统 SHALL 提供 `/api/summary`、`/api/targets`、`/api/targets/:id/history`、`/api/targets/:id/trend` 端点
|
||||
- **THEN** 系统 SHALL 通过 routes 对象提供 `/api/summary`、`/api/targets`、`/api/targets/:id/history`、`/api/targets/:id/trend` 端点
|
||||
|
||||
### Requirement: HTTP method 语义
|
||||
系统 SHALL 为运行时端点提供明确的 HTTP method 语义，避免不支持的 method 被错误地当作成功请求处理。
|
||||
系统 SHALL 只为运行时端点声明实际支持的 GET handler；不支持的 API method SHALL 按未匹配 API 路由处理，不再保留自定义 405 和 Allow header 语义。
|
||||
|
||||
#### 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
|
||||
#### Scenario: 不支持的 API method 请求
|
||||
- **WHEN** 客户端使用不支持的 method 请求已存在的 `/api/*` 端点
|
||||
- **THEN** `/api/*` 通配符 SHALL 返回包含 `error` 和 `status` 字段的 JSON 404 响应
|
||||
|
||||
### Requirement: API 路由命名空间
|
||||
系统 MUST 将 `/api/*` 保留给后端 API 路由。
|
||||
@@ -50,15 +46,15 @@
|
||||
- **THEN** Bun server MUST 返回 JSON 404 响应，而不是前端 HTML 文档
|
||||
|
||||
### Requirement: API 错误响应一致性
|
||||
系统 SHALL 为 API 命名空间内的错误返回机器可读 JSON 响应。
|
||||
系统 SHALL 为 API 命名空间内的未匹配路由和未匹配 method 返回机器可读 JSON 404 响应。
|
||||
|
||||
#### Scenario: 未知 API 路由
|
||||
- **WHEN** 客户端请求未知的 `/api/*` 路由
|
||||
- **THEN** Bun server MUST 返回包含 `error` 和 `status` 字段的 JSON 404 响应，而不是前端 HTML 文档
|
||||
|
||||
#### Scenario: API method 不允许
|
||||
#### Scenario: API method 不匹配
|
||||
- **WHEN** 客户端使用不支持的 method 请求已存在的 API 路由
|
||||
- **THEN** Bun server MUST 返回包含 `error` 和 `status` 字段的 JSON 405 响应
|
||||
- **THEN** Bun server MUST 返回包含 `error` 和 `status` 字段的 JSON 404 响应
|
||||
|
||||
### Requirement: 健康检查端点
|
||||
系统 SHALL 在前端 SPA fallback 之外暴露健康检查端点。
|
||||
@@ -68,56 +64,48 @@
|
||||
- **THEN** Bun server SHALL 返回成功的、机器可读的健康检查响应
|
||||
|
||||
### Requirement: 生产静态资源服务
|
||||
系统 SHALL 在生产模式下由 Bun runtime 服务 Vite 生产资源。
|
||||
系统 SHALL 在生产模式下通过 Bun 内置的 HTML import manifest 机制服务前端资源。
|
||||
|
||||
#### Scenario: 请求构建后的资源
|
||||
- **WHEN** 客户端请求构建后的前端资源，例如 `/assets/app.js`
|
||||
- **THEN** Bun server SHALL 返回该资源并带有适当的 content type
|
||||
- **WHEN** 客户端请求构建后的前端资源
|
||||
- **THEN** Bun server SHALL 通过 manifest 自动返回该资源并带有适当的 content type 和 content-addressable hash URL
|
||||
|
||||
#### Scenario: 请求前端根路径
|
||||
- **WHEN** 客户端请求 `/`
|
||||
- **THEN** Bun server SHALL 返回前端入口 HTML 文档
|
||||
- **THEN** Bun server SHALL 通过 routes 中注册的 HTML import 返回前端入口 HTML 文档
|
||||
|
||||
### Requirement: 生产缓存策略
|
||||
系统 SHALL 为生产静态资源和前端入口 HTML 使用明确的缓存策略。
|
||||
系统 SHALL 利用 Bun 内置的缓存机制为生产静态资源提供缓存策略。
|
||||
|
||||
#### Scenario: 请求前端入口 HTML
|
||||
- **WHEN** 生产 Bun server 返回前端入口 HTML 文档
|
||||
- **THEN** 响应 SHALL 使用 `Cache-Control: no-cache`
|
||||
- **THEN** 响应 SHALL 包含 Bun 自动生成的 ETag header
|
||||
|
||||
#### Scenario: 请求构建后的静态资源
|
||||
- **WHEN** 生产 Bun server 返回 Vite 构建后的静态资源
|
||||
- **THEN** 响应 SHALL 使用长缓存策略 `public, max-age=31536000, immutable`
|
||||
|
||||
#### Scenario: 请求未知静态资源
|
||||
- **WHEN** 客户端请求不存在的 `/assets/*` 资源或带文件扩展名的未知路径
|
||||
- **THEN** Bun server MUST 返回 404，且 MUST NOT 返回前端入口 HTML 文档
|
||||
- **WHEN** 生产 Bun server 返回构建后的静态资源
|
||||
- **THEN** 响应 SHALL 包含 Bun 自动生成的 ETag header 和 content-addressable hash URL
|
||||
|
||||
### Requirement: 低风险安全响应头
|
||||
系统 SHALL 在生产运行时响应中附加低风险安全响应头，提升基础安全性且不提前约束未来前端资源策略。
|
||||
|
||||
#### Scenario: 生产 HTML 响应包含安全头
|
||||
- **WHEN** 生产 Bun server 返回前端 HTML 文档
|
||||
- **THEN** 响应 SHALL 包含 `X-Content-Type-Options: nosniff` 和 `Referrer-Policy` headers
|
||||
系统 SHALL 在生产运行时的 JSON API 响应中附加低风险安全响应头；HTML 和静态资源响应由 Bun HTML import manifest 返回其内置 headers。
|
||||
|
||||
#### Scenario: 生产 JSON 响应包含安全头
|
||||
- **WHEN** 生产 Bun server 返回 `/health` 或 `/api/*` JSON 响应
|
||||
- **THEN** 响应 SHALL 包含 `X-Content-Type-Options: nosniff` 和 `Referrer-Policy` headers
|
||||
|
||||
#### Scenario: 生产静态资源响应包含安全头
|
||||
- **WHEN** 生产 Bun server 返回 Vite 构建后的静态资源
|
||||
- **THEN** 响应 SHALL 包含 `X-Content-Type-Options: nosniff` 和 `Referrer-Policy` headers
|
||||
#### Scenario: 生产 HTML 和静态资源响应使用 Bun 内置 headers
|
||||
- **WHEN** 生产 Bun server 返回前端 HTML 文档或构建后的静态资源
|
||||
- **THEN** 响应 SHALL 使用 Bun HTML import manifest 提供的内置 headers，不要求附加自定义安全 headers
|
||||
|
||||
### Requirement: SPA fallback 行为
|
||||
系统 SHALL 在生产环境中为非 API、非静态资源的前端路由返回前端入口 HTML 文档。
|
||||
系统 SHALL 通过 routes 中注册的 `"/*"` HTML import 通配符为非 API 路径返回前端入口 HTML 文档。
|
||||
|
||||
#### Scenario: 刷新前端路由
|
||||
- **WHEN** 客户端请求前端路由，例如 `/dashboard`
|
||||
- **THEN** Bun server SHALL 返回前端入口 HTML 文档
|
||||
- **THEN** routes 中的 `"/*"` 通配符 SHALL 返回前端入口 HTML 文档
|
||||
|
||||
#### Scenario: 保留 API 错误语义
|
||||
- **WHEN** 客户端请求未知的 `/api/*` 路由
|
||||
- **THEN** Bun server MUST NOT 返回前端入口 HTML 文档
|
||||
- **THEN** `/api/*` 通配符 MUST 返回 JSON 404 响应，而不是前端入口 HTML 文档
|
||||
|
||||
### Requirement: 优雅关机
|
||||
系统 SHALL 在收到终止信号时正确清理资源。
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
## Requirements
|
||||
|
||||
### Requirement: Meta 信息 API
|
||||
系统 SHALL 提供 `GET /api/meta` 端点，返回系统运行时元数据。
|
||||
系统 SHALL 提供 `GET /api/meta` 端点，返回系统运行时元数据。未匹配 method SHALL 按 API 通配符处理为 JSON 404，不再保留自定义 HEAD/405 语义。
|
||||
|
||||
#### Scenario: 获取 checker 类型列表
|
||||
- **WHEN** 客户端请求 `GET /api/meta`
|
||||
@@ -15,13 +15,9 @@
|
||||
- **WHEN** 系统启动并注册了 checker
|
||||
- **THEN** `/api/meta` 返回的 `checkerTypes` SHALL 与 `CheckerRegistry.supportedTypes` 完全一致
|
||||
|
||||
#### Scenario: 仅允许 GET/HEAD 方法
|
||||
- **WHEN** 客户端使用 POST/PUT/DELETE 等方法请求 `/api/meta`
|
||||
- **THEN** 系统 SHALL 返回 405 状态码
|
||||
|
||||
#### Scenario: HEAD 请求返回空体
|
||||
- **WHEN** 客户端使用 HEAD 方法请求 `/api/meta`
|
||||
- **THEN** 系统 SHALL 返回 200 状态码和正确的 Content-Type header，body 为空
|
||||
#### Scenario: 不支持的 method 请求
|
||||
- **WHEN** 客户端使用 POST/PUT/DELETE/HEAD 等未声明 method 请求 `/api/meta`
|
||||
- **THEN** `/api/*` 通配符 SHALL 返回 JSON 404 响应
|
||||
|
||||
### Requirement: MetaResponse 共享类型
|
||||
系统 SHALL 在 `src/shared/api.ts` 中定义 `MetaResponse` 类型。
|
||||
|
||||
@@ -132,7 +132,7 @@
|
||||
- **THEN** API SHALL 返回 failure 为 null
|
||||
|
||||
### Requirement: Meta 信息 API
|
||||
系统 SHALL 提供 `GET /api/meta` 端点，返回系统运行时元数据。
|
||||
系统 SHALL 提供 `GET /api/meta` 端点，返回系统运行时元数据。未匹配 method SHALL 按 API 通配符处理为 JSON 404，不再保留自定义 HEAD/405 语义。
|
||||
|
||||
#### Scenario: 获取 checker 类型列表
|
||||
- **WHEN** 客户端请求 `GET /api/meta`
|
||||
@@ -142,13 +142,9 @@
|
||||
- **WHEN** 系统启动并注册了 checker
|
||||
- **THEN** `/api/meta` 返回的 `checkerTypes` SHALL 与 `CheckerRegistry.supportedTypes` 完全一致
|
||||
|
||||
#### Scenario: 仅允许 GET/HEAD 方法
|
||||
- **WHEN** 客户端使用 POST/PUT/DELETE 等方法请求 `/api/meta`
|
||||
- **THEN** 系统 SHALL 返回 405 状态码
|
||||
|
||||
#### Scenario: HEAD 请求返回空体
|
||||
- **WHEN** 客户端使用 HEAD 方法请求 `/api/meta`
|
||||
- **THEN** 系统 SHALL 返回 200 状态码和正确的 Content-Type header，body 为空
|
||||
#### Scenario: 不支持的 method 请求
|
||||
- **WHEN** 客户端使用 POST/PUT/DELETE/HEAD 等未声明 method 请求 `/api/meta`
|
||||
- **THEN** `/api/*` 通配符 SHALL 返回 JSON 404 响应
|
||||
|
||||
### Requirement: MetaResponse 共享类型
|
||||
系统 SHALL 在 `src/shared/api.ts` 中定义 `MetaResponse` 类型。
|
||||
|
||||
@@ -5,15 +5,15 @@ TBD - 统一服务启动引导函数，封装开发和生产模式的完整启
|
||||
## Requirements
|
||||
|
||||
### Requirement: 统一启动引导函数
|
||||
系统 SHALL 提供 `src/server/bootstrap.ts` 导出 `bootstrap(options: BootstrapOptions)` 函数，封装完整的服务启动序列：加载配置、创建 store、同步 targets、创建并启动 engine、启动 HTTP server、注册 shutdown handler。
|
||||
系统 SHALL 提供 `src/server/bootstrap.ts` 导出 `bootstrap(options: BootstrapOptions)` 函数，封装完整的服务启动序列：加载配置、创建 store、同步 targets、创建并启动 engine、启动 HTTP server、注册 shutdown handler。`bootstrap` SHALL 不接收或传递静态资源对象，前端资源由 Bun HTML import manifest 自动接管。
|
||||
|
||||
#### Scenario: 开发模式启动
|
||||
- **WHEN** `dev.ts` 调用 `bootstrap({ configPath, mode: "development" })`
|
||||
- **THEN** 系统 SHALL 完成完整启动序列，不传入 staticAssets
|
||||
|
||||
#### Scenario: 生产模式启动
|
||||
- **WHEN** build entry 调用 `bootstrap({ configPath, mode: "production", staticAssets })`
|
||||
- **THEN** 系统 SHALL 完成完整启动序列，并将 staticAssets 传递给 startServer
|
||||
- **WHEN** `main.ts` 调用 `bootstrap({ configPath, mode: "production" })`
|
||||
- **THEN** 系统 SHALL 完成完整启动序列，并由 `server.ts` 中的 HTML import 路由接管前端资源
|
||||
|
||||
#### Scenario: 启动失败处理
|
||||
- **WHEN** 启动过程中任何步骤抛出异常
|
||||
@@ -24,19 +24,19 @@ TBD - 统一服务启动引导函数，封装开发和生产模式的完整启
|
||||
- **THEN** bootstrap 注册的 shutdown handler SHALL 调用 engine.stop() 和 store.close() 后退出
|
||||
|
||||
### Requirement: BootstrapOptions 接口
|
||||
`bootstrap` 函数 SHALL 接受 `BootstrapOptions` 参数，包含 `configPath: string`、`mode: RuntimeMode`、`staticAssets?: StaticAssets`。
|
||||
`bootstrap` 函数 SHALL 接受 `BootstrapOptions` 参数，仅包含 `configPath: string` 和 `mode: RuntimeMode`。
|
||||
|
||||
#### Scenario: 最小配置
|
||||
- **WHEN** 仅传入 configPath 和 mode
|
||||
- **THEN** 系统 SHALL 正常启动，staticAssets 为 undefined
|
||||
- **THEN** 系统 SHALL 正常启动
|
||||
|
||||
### Requirement: dev.ts 和 build entry 使用 bootstrap
|
||||
`dev.ts` 和 `scripts/build.ts` 生成的 server entry SHALL 调用 `bootstrap()` 而非各自维护启动序列。
|
||||
### Requirement: dev.ts 和生产入口使用 bootstrap
|
||||
`dev.ts` 和 `src/server/main.ts` SHALL 调用 `bootstrap()` 而非各自维护启动序列。
|
||||
|
||||
#### Scenario: dev.ts 调用 bootstrap
|
||||
- **WHEN** 开发者运行 `bun run dev:server`
|
||||
- **WHEN** 开发者运行 `bun run dev`
|
||||
- **THEN** `dev.ts` SHALL 调用 `bootstrap` 完成启动
|
||||
|
||||
#### Scenario: build entry 调用 bootstrap
|
||||
#### Scenario: main.ts 调用 bootstrap
|
||||
- **WHEN** 生产可执行文件启动
|
||||
- **THEN** 生成的 entry SHALL 调用 `bootstrap` 完成启动
|
||||
- **THEN** `main.ts` SHALL 调用 `bootstrap` 完成启动
|
||||
|
||||
@@ -1,61 +1,42 @@
|
||||
## Purpose
|
||||
|
||||
定义将 Vite 前端资源与 Bun 后端打包为单个 standalone executable 的生产构建、运行配置和验证要求。
|
||||
定义将 Bun HTML import 前端资源与 Bun 后端打包为单个 standalone executable 的生产构建、运行配置和验证要求。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 生产构建顺序
|
||||
生产构建 MUST 在编译 Bun 后端 executable 之前先构建 Vite 前端。
|
||||
生产构建 MUST 通过 Bun.build 的 HTML import 识别机制一步完成前端资源打包和后端编译。
|
||||
|
||||
#### Scenario: 运行生产构建
|
||||
- **WHEN** 开发者运行生产构建命令
|
||||
- **THEN** 系统 MUST 在调用 Bun standalone executable 编译之前生成前端静态资源
|
||||
- **THEN** 系统 MUST 调用 Bun.build，自动识别 server 入口中的 HTML import 并完成前端 bundling 和后端编译
|
||||
|
||||
#### Scenario: 前端构建失败
|
||||
- **WHEN** 前端生产构建失败
|
||||
#### Scenario: 前端 bundling 失败
|
||||
- **WHEN** Bun.build 在处理 HTML import 中的前端资源时失败
|
||||
- **THEN** 系统 MUST 停止生产构建，且不能输出 stale executable
|
||||
|
||||
### Requirement: 构建生成确定性
|
||||
生产构建 SHALL 以稳定顺序生成嵌入静态资源清单，减少重复构建产生无意义差异。
|
||||
|
||||
#### Scenario: 生成静态资源清单
|
||||
- **WHEN** 生产构建扫描 Vite 输出目录并生成嵌入资源模块
|
||||
- **THEN** 资源条目 SHALL 按稳定顺序输出
|
||||
|
||||
#### Scenario: 重复构建相同前端产物
|
||||
- **WHEN** Vite 输出内容未变化且生产构建重复运行
|
||||
- **THEN** 生成的嵌入资源模块 SHALL 保持语义一致且不依赖文件系统遍历顺序
|
||||
|
||||
### Requirement: 单 executable 输出
|
||||
生产构建 SHALL 输出一个 standalone executable，其中包含 Bun 后端、必要 server 依赖和构建后的前端资源。构建成功后 SHALL 自动清理中间产物目录（`.build/`），构建失败时 SHALL 保留中间产物以便排查。生成的入口代码 SHALL 通过 import config-loader 模块隐式触发 checker 注册，而非显式调用注册函数。生成的入口 SHALL 注册 SIGINT 和 SIGTERM 信号处理器，在收到信号时依次调用 engine.stop() 和 store.close() 后退出进程。
|
||||
生产构建 SHALL 输出一个 standalone executable，其中包含 Bun 后端和通过 HTML import manifest 嵌入的前端资源。构建流程 SHALL 不再生成项目自定义中间产物目录，构建失败时 SHALL 不保留 stale executable。
|
||||
|
||||
#### Scenario: 在目标机器运行 executable
|
||||
- **WHEN** 生成的 executable 在兼容目标平台上运行
|
||||
- **THEN** 它 SHALL 启动全栈应用，且不要求目标机器安装 Node.js、Bun、Vite 或 `node_modules`
|
||||
- **THEN** 它 SHALL 启动全栈应用，且不要求目标机器安装 Node.js、Bun 或 `node_modules`
|
||||
|
||||
#### Scenario: 服务嵌入的前端
|
||||
- **WHEN** executable 收到前端根路径请求
|
||||
- **THEN** 它 SHALL 从 executable 内包含的资源服务前端，且不需要外部 `dist/` 目录
|
||||
- **THEN** 它 SHALL 通过 Bun 内置的 HTML import manifest 机制服务前端资源，且不需要外部 `dist/` 目录
|
||||
|
||||
#### Scenario: 服务嵌入 API 和页面
|
||||
- **WHEN** 生成的 executable 启动，且浏览器打开前端根路径
|
||||
- **THEN** 页面 SHALL 展示同一个 executable 进程中 `/api/summary` 和 `/api/targets` 返回的数据
|
||||
|
||||
#### Scenario: 构建成功后清理中间产物
|
||||
#### Scenario: 构建成功不生成自定义中间产物
|
||||
- **WHEN** 生产构建成功完成并输出 executable
|
||||
- **THEN** 系统 SHALL 自动删除 `.build/` 目录及其所有内容
|
||||
- **THEN** 系统 SHALL 不生成 `.build/` 静态资源清单或 server entry 中间产物
|
||||
|
||||
#### Scenario: 构建失败时保留中间产物
|
||||
- **WHEN** 生产构建在任意步骤失败（前端构建、中间产物生成、Bun 编译）
|
||||
- **THEN** `.build/` 目录 SHALL 保留在磁盘上以供排查
|
||||
|
||||
#### Scenario: checker 注册通过 import 链触发
|
||||
- **WHEN** 生成的入口代码 import config-loader 模块
|
||||
- **THEN** checkerRegistry 单例 SHALL 通过模块依赖链自动完成注册，入口代码 SHALL NOT 显式调用任何注册函数
|
||||
|
||||
#### Scenario: 生产入口优雅关闭
|
||||
- **WHEN** executable 进程收到 SIGINT 或 SIGTERM 信号
|
||||
- **THEN** 系统 SHALL 调用 engine.stop() 停止所有定时器，调用 store.close() 关闭数据库连接，然后以退出码 0 退出进程
|
||||
#### Scenario: 构建失败时不保留 stale executable
|
||||
- **WHEN** 生产构建在任意步骤失败
|
||||
- **THEN** 系统 SHALL 不输出上一次构建遗留的 stale executable
|
||||
|
||||
### Requirement: 外部运行时配置
|
||||
executable MUST 将环境相关运行时配置保留在嵌入的前端和 server bundle 之外。
|
||||
@@ -69,20 +50,12 @@ executable MUST 将环境相关运行时配置保留在嵌入的前端和 server
|
||||
- **THEN** executable SHALL 使用文档化的默认值
|
||||
|
||||
### Requirement: 构建验证
|
||||
项目 SHALL 提供验证，证明生产 executable 可以服务 API、健康检查、静态资源和 SPA fallback 路由，并且完整验证 MUST 针对当前源码重新构建后的 executable 运行。
|
||||
|
||||
#### Scenario: 验证 executable 路由
|
||||
- **WHEN** 构建验证针对生成的 executable 运行
|
||||
- **THEN** 它 SHALL 检查 `/api/summary`、`/api/targets`、`/health`、前端根路径、静态资源、未知 API、未知静态资源和前端 fallback 请求
|
||||
|
||||
#### Scenario: 验证生产模式和响应头
|
||||
- **WHEN** 构建验证针对生成的 executable 运行
|
||||
- **THEN** 它 SHALL 检查 API 响应处于 production runtime mode，并验证代表性 HTML、JSON 和静态资源响应的缓存或低风险安全 headers
|
||||
项目 SHALL 提供 `verify` 命令执行质量检查和生产构建；原 smoke test 暂时移除，executable 路由验证由后续变更重新设计。
|
||||
|
||||
#### Scenario: 完整验证重新构建 executable
|
||||
- **WHEN** 开发者运行完整验证命令
|
||||
- **THEN** 系统 MUST 先基于当前源码执行生产构建，再对新生成的 executable 运行 smoke test
|
||||
- **THEN** 系统 MUST 先执行质量检查，再基于当前源码执行生产构建
|
||||
|
||||
#### Scenario: 验证失败
|
||||
- **WHEN** 任一代表性生产路由、响应头、生产模式或构建阶段检查失败
|
||||
- **THEN** 验证 SHALL 使构建或测试命令失败
|
||||
- **WHEN** 质量检查或构建阶段失败
|
||||
- **THEN** 验证 SHALL 使命令失败
|
||||
|
||||
Reference in New Issue
Block a user