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

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 使构建或测试命令失败