refactor: 迁移 Bun fullstack 架构

openspec/specs/fullstack-app-runtime/spec.md

@@ -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 在收到终止信号时正确清理资源。