DiAL/openspec/specs/api-route-separation/spec.md

Purpose

定义后端 API 路由的组织规范：按端点拆分为独立 handler、共享响应工具集中管理、路径参数由 Bun routes 解析，静态资源服务由 HTML import manifest 管理。

Requirements

Requirement: 路由按职责拆分

系统 SHALL 将 HTTP 路由处理逻辑按 API 端点拆分为独立模块，每个模块导出 route handler 函数供 routes 对象统一注册。

Scenario: health 端点独立路由

• WHEN 客户端请求 GET /health
• THEN routes/health.ts 导出的 handler 负责处理，返回 HealthResponse JSON

Scenario: summary 端点独立路由

• WHEN 客户端请求 GET /api/summary
• THEN routes/summary.ts 导出的 handler 负责处理，委托 store 查询并返回 SummaryResponse JSON

Scenario: targets 端点独立路由

• WHEN 客户端请求 GET /api/targets
• THEN routes/targets.ts 导出的 handler 负责处理，委托 store 查询并返回 TargetStatus[] JSON

Scenario: history 端点独立路由

• WHEN 客户端请求 GET /api/targets/:id/history?from=ISO&to=ISO
• 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 负责处理，通过 req.params.id 获取路径参数，包含参数校验、store 查询和 TrendPoint[] 返回

Requirement: 共享辅助函数集中管理

系统 SHALL 将跨路由共享的响应格式化函数抽取到 helpers.ts 模块，单一职责、集中管理。

Scenario: createApiError 集中定义

• WHEN 任意路由需要返回 API 错误响应
• THEN 从 helpers.ts 导入 createApiError 函数，提供错误信息和状态码

Scenario: jsonResponse 集中定义

• WHEN 任意路由需要返回 JSON 响应
• THEN 从 helpers.ts 导入 jsonResponse 函数，处理 HEAD 方法、Content-Type 和安全头

Scenario: mapCheckResult 集中定义

• WHEN 需要将 StoredCheckResult 映射为 API CheckResult
• THEN 从 helpers.ts 导入 mapCheckResult 函数，处理 failure JSON 解析和格式转换

Requirement: 静态资源服务独立管理

系统 SHALL 将 SPA fallback 逻辑交给 routes 对象中的 HTML import 通配符处理，静态资源服务由 Bun 内置 manifest 机制自动处理。

Scenario: 根路径返回 index.html

• WHEN 客户端请求 /
• THEN routes 中注册的 HTML import 自动返回 index.html

Scenario: 资源文件返回正确 Content-Type

• WHEN 客户端请求构建后的静态资源
• THEN Bun 内置 manifest 机制自动返回正确的 Content-Type 和缓存头

Scenario: SPA fallback

• WHEN 客户端请求非 API、非资源的路径（如 /dashboard）
• THEN routes 中注册的 "/*" HTML import 通配符返回 index.html 实现 SPA 的客户端路由