feat: 搭建前后端可执行程序示例

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

@@ -0,0 +1,67 @@
+## Purpose
+
+定义 Vite + React + TypeScript 前端开发工作流、开发期 API 代理、共享契约和端到端 demo 的行为要求。
+
+## Requirements
+
+### Requirement: Vite React 开发服务器
+系统 SHALL 提供基于 Vite + React + TypeScript 的前端开发工作流，并支持热模块替换。
+
+#### Scenario: 启动前端开发服务器
+- **WHEN** 开发者启动前端开发命令
+- **THEN** 前端 SHALL 由 Vite 提供服务，并启用 React 热模块替换
+
+#### Scenario: 构建前端静态资源
+- **WHEN** 开发者运行前端生产构建命令
+- **THEN** 系统 SHALL 产出可由 Bun 后端服务的前端静态资源
+
+### Requirement: 前端开发期 API 代理
+前端开发服务器 SHALL 在本地开发期间将 `/api/*` 请求代理到 Bun 后端服务。
+
+#### Scenario: 前端开发期调用 API
+- **WHEN** 浏览器从 Vite 开发源请求 `/api/demo`
+- **THEN** Vite SHALL 将请求转发到 Bun 后端服务，且不需要浏览器 CORS 配置
+
+#### Scenario: 开发期访问非 API 前端路由
+- **WHEN** 浏览器从 Vite 开发源请求非 API 前端路由
+- **THEN** Vite SHALL 将该请求作为前端应用流量处理，而不是转发到后端
+
+### Requirement: 前端使用相对 API 路径
+除非有文档化的部署配置覆盖该行为，前端代码 MUST 通过相对 `/api/*` URL 调用后端 API。
+
+#### Scenario: 前端获取后端数据
+- **WHEN** 前端代码调用后端 API
+- **THEN** 请求 URL 默认 MUST 使用相对 `/api/*` 路径
+
+#### Scenario: 运行环境变化
+- **WHEN** host 或 port 在开发环境和生产环境之间变化
+- **THEN** 前端 API 调用 SHALL 无需修改源码即可继续工作
+
+### Requirement: 端到端开发 demo
+项目 SHALL 提供一个可见的开发 demo，用于证明 React 前端可以通过 Vite 代理调用 Bun 后端。
+
+#### Scenario: Demo 页面展示后端响应
+- **WHEN** 开发者启动文档化的开发命令并打开前端 URL
+- **THEN** 页面 SHALL 调用 `/api/demo` 并展示 Bun 后端返回的数据
+
+#### Scenario: 开发期后端不可用
+- **WHEN** 前端 demo 无法访问 `/api/demo`
+- **THEN** 页面 SHALL 展示清晰的错误状态，而不是静默显示为成功
+
+### Requirement: 集成开发命令
+项目 SHALL 提供一个文档化命令，用于在 demo 开发期间同时运行前端和后端。
+
+#### Scenario: 启动全栈开发
+- **WHEN** 开发者运行文档化的全栈开发命令
+- **THEN** 系统 SHALL 启动 Vite 前端开发服务器和 `/api/demo` 所需的 Bun 后端服务器
+
+### Requirement: 共享 TypeScript 契约
+项目 SHALL 为前端和后端共同使用的请求与响应类型提供共享 TypeScript 边界。
+
+#### Scenario: 定义 API 响应结构
+- **WHEN** 前端和后端都需要某个 API 响应类型
+- **THEN** 该类型 SHALL 定义在 shared 模块中，而不是在两端重复定义
+
+#### Scenario: 前端导入共享类型
+- **WHEN** 前端代码导入共享 API 类型
+- **THEN** 该导入 SHALL 不要求将后端运行时实现打包进前端

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

@@ -0,0 +1,71 @@
+## Purpose
+
+定义 Bun 全栈应用运行时的 HTTP server、API 命名空间、健康检查、生产静态资源服务和 SPA fallback 行为。
+
+## Requirements
+
+### Requirement: Bun HTTP 运行时
+系统 SHALL 运行一个 Bun HTTP server，由单个进程提供后端 API、健康检查、生产静态资源和 SPA fallback 行为。
+
+#### Scenario: 启动运行时服务器
+- **WHEN** server 进程成功启动
+- **THEN** 它 SHALL 监听配置的 host 和 port，并记录实际 server URL
+
+#### Scenario: 提供运行时配置
+- **WHEN** 通过支持的运行时配置提供 host 或 port
+- **THEN** server SHALL 使用该值，且不需要重新构建
+
+### Requirement: API 路由命名空间
+系统 MUST 将 `/api/*` 保留给后端 API 路由。
+
+#### Scenario: API 路由匹配
+- **WHEN** 请求匹配已注册的 `/api/*` 路由
+- **THEN** Bun server SHALL 返回 API handler 的响应
+
+#### Scenario: API 路由未命中
+- **WHEN** 请求访问未注册的 `/api/*` 路由
+- **THEN** Bun server MUST 返回 JSON 404 响应，而不是前端 HTML 文档
+
+### Requirement: Demo API 端点
+系统 SHALL 暴露 `/api/demo` 作为稳定 demo 端点，用于证明前后端集成可用。
+
+#### Scenario: Demo API 成功响应
+- **WHEN** 客户端请求 `/api/demo`
+- **THEN** Bun server SHALL 返回包含可读 message 和 runtime metadata 的 JSON 响应
+
+#### Scenario: Demo API 内容类型
+- **WHEN** 客户端请求 `/api/demo`
+- **THEN** Bun server SHALL 返回 JSON content type 的响应
+
+### Requirement: 健康检查端点
+系统 SHALL 在前端 SPA fallback 之外暴露健康检查端点。
+
+#### Scenario: 健康检查成功
+- **WHEN** 客户端请求 `/health`
+- **THEN** Bun server SHALL 返回成功的、机器可读的健康检查响应
+
+### Requirement: 生产静态资源服务
+系统 SHALL 在生产模式下由 Bun runtime 服务 Vite 生产资源。
+
+#### Scenario: 请求构建后的资源
+- **WHEN** 客户端请求构建后的前端资源，例如 `/assets/app.js`
+- **THEN** Bun server SHALL 返回该资源并带有适当的 content type
+
+#### Scenario: 请求前端根路径
+- **WHEN** 客户端请求 `/`
+- **THEN** Bun server SHALL 返回前端入口 HTML 文档
+
+#### Scenario: 生产 demo 页面调用 API
+- **WHEN** 客户端从生产 Bun runtime 打开前端页面
+- **THEN** demo 页面 SHALL 能够从同源调用 `/api/demo` 并展示后端响应
+
+### Requirement: SPA fallback 行为
+系统 SHALL 在生产环境中为非 API、非静态资源的前端路由返回前端入口 HTML 文档。
+
+#### Scenario: 刷新前端路由
+- **WHEN** 客户端请求前端路由，例如 `/dashboard`
+- **THEN** Bun server SHALL 返回前端入口 HTML 文档
+
+#### Scenario: 保留 API 错误语义
+- **WHEN** 客户端请求未知的 `/api/*` 路由
+- **THEN** Bun server MUST NOT 返回前端入口 HTML 文档

openspec/specs/single-executable-packaging/spec.md

@@ -0,0 +1,53 @@
+## Purpose
+
+定义将 Vite 前端资源与 Bun 后端打包为单个 standalone executable 的生产构建、运行配置和验证要求。
+
+## Requirements
+
+### Requirement: 生产构建顺序
+生产构建 MUST 在编译 Bun 后端 executable 之前先构建 Vite 前端。
+
+#### Scenario: 运行生产构建
+- **WHEN** 开发者运行生产构建命令
+- **THEN** 系统 MUST 在调用 Bun standalone executable 编译之前生成前端静态资源
+
+#### Scenario: 前端构建失败
+- **WHEN** 前端生产构建失败
+- **THEN** 系统 MUST 停止生产构建，且不能输出 stale executable
+
+### Requirement: 单 executable 输出
+生产构建 SHALL 输出一个 standalone executable，其中包含 Bun 后端、必要 server 依赖和构建后的前端资源。
+
+#### Scenario: 在目标机器运行 executable
+- **WHEN** 生成的 executable 在兼容目标平台上运行
+- **THEN** 它 SHALL 启动全栈应用，且不要求目标机器安装 Node.js、Bun、Vite 或 `node_modules`
+
+#### Scenario: 服务嵌入的前端
+- **WHEN** executable 收到前端根路径请求
+- **THEN** 它 SHALL 从 executable 内包含的资源服务前端，且不需要外部 `dist/` 目录
+
+#### Scenario: 服务嵌入 demo API 和页面
+- **WHEN** 生成的 executable 启动，且浏览器打开前端根路径
+- **THEN** 页面 SHALL 展示同一个 executable 进程中 `/api/demo` 返回的数据
+
+### Requirement: 外部运行时配置
+executable MUST 将环境相关运行时配置保留在嵌入的前端和 server bundle 之外。
+
+#### Scenario: 修改监听端口
+- **WHEN** 操作者修改受支持的 port 配置
+- **THEN** 同一个 executable SHALL 在不重新构建的情况下监听新端口
+
+#### Scenario: 缺少可选配置
+- **WHEN** 可选运行时配置被省略
+- **THEN** executable SHALL 使用文档化的默认值
+
+### Requirement: 构建验证
+项目 SHALL 提供验证，证明生产 executable 可以服务 API、健康检查、静态资源和 SPA fallback 路由。
+
+#### Scenario: 验证 executable 路由
+- **WHEN** 构建验证针对生成的 executable 运行
+- **THEN** 它 SHALL 检查 `/api/demo`、`/health`、前端根路径、静态资源和前端 fallback 请求
+
+#### Scenario: 验证失败
+- **WHEN** 任一代表性生产路由检查失败
+- **THEN** 验证 SHALL 使构建或测试命令失败