DiAL/openspec/specs/frontend-development-workflow/spec.md

Purpose

定义 Bun.serve fullstack + React + TypeScript 前端开发工作流、开发期 API 访问和共享契约的行为要求。

Requirements

Requirement: Vite React 开发服务器

系统 SHALL 提供基于 Bun.serve fullstack 模式的前端开发工作流，并支持热模块替换和 React Fast Refresh。

Scenario: 启动前端开发服务器

• WHEN 开发者启动开发命令
• THEN 前端 SHALL 由 Bun.serve 的 HTML import 机制提供服务，并通过 development: { hmr: true, console: true } 启用 HMR、React Fast Refresh 和浏览器 console 回显

Scenario: 构建前端静态资源

• WHEN 开发者运行前端生产构建命令
• THEN 系统 SHALL 通过 Bun.build 的 HTML import ahead-of-time bundling 产出可由 Bun 后端服务的前端静态资源

Requirement: 前端开发期 API 代理

前端开发服务器 SHALL 在本地开发期间无需代理配置即可访问后端 API，因为前后端运行在同一进程同一端口。

Scenario: 前端开发期调用拨测 API

• WHEN 浏览器从开发服务器请求 /api/summary、/api/targets 等拨测 API
• THEN Bun.serve SHALL 直接由 routes 中注册的 API handler 处理请求，无需 proxy 转发

Scenario: 开发期访问非 API 前端路由

• WHEN 浏览器从开发服务器请求非 API 前端路由
• THEN Bun.serve SHALL 将该请求作为前端应用流量处理（SPA fallback 返回 HTML）

Requirement: 开发期单端口运行

项目 SHALL 保证开发命令中前端页面、HMR 和后端 API 由同一个 Bun.serve 进程在同一端口提供服务。

Scenario: 使用默认开发端口

• WHEN 开发者未提供端口覆盖并运行开发命令
• THEN Bun.serve SHALL 在默认端口同时提供前端页面、HMR 和后端 API

Scenario: 使用配置覆盖开发端口

• WHEN 开发者通过配置文件覆盖端口并运行开发命令
• THEN Bun.serve SHALL 在配置端口同时提供前端页面、HMR 和后端 API

Requirement: 前端使用相对 API 路径

除非有文档化的部署配置覆盖该行为，前端代码 MUST 通过相对 /api/* URL 调用后端 API。

Scenario: 前端获取后端数据

• WHEN 前端代码调用后端 API
• THEN 请求 URL 默认 MUST 使用相对 /api/* 路径

Scenario: 运行环境变化

• WHEN host 或 port 在开发环境和生产环境之间变化
• THEN 前端 API 调用 SHALL 无需修改源码即可继续工作

Requirement: 集成开发命令

项目 SHALL 提供一个文档化命令，用于在开发期间同时运行前端和后端。

Scenario: 启动全栈开发

• WHEN 开发者运行文档化的全栈开发命令
• THEN 系统 SHALL 启动单个 Bun.serve 进程，同时提供前端 HMR 和后端 API 服务

Requirement: 开发质量命令文档化

项目 SHALL 在前端开发工作流文档中说明日常检查和完整验证命令。

Scenario: 查阅开发命令

• WHEN 开发者阅读 README 的开发或测试章节
• THEN 文档 SHALL 说明 check 用于日常开发检查，verify 用于提交前或发布前完整验证

Requirement: 共享 TypeScript 契约

项目 SHALL 为前端和后端共同使用的请求与响应类型提供共享 TypeScript 边界。

Scenario: 定义 API 响应结构

• WHEN 前端和后端都需要某个 API 响应类型
• THEN 该类型 SHALL 定义在 shared 模块中，而不是在两端重复定义

Scenario: 前端导入共享类型

• WHEN 前端代码导入共享 API 类型
• THEN 该导入 SHALL 不要求将后端运行时实现打包进前端