refactor: 迁移 Bun fullstack 架构

openspec/specs/bun-fullstack-routing/spec.md

@@ -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 注入）