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

README.md

@@ -0,0 +1,102 @@
+# Gateway Checker
+
+基于 Bun + TypeScript 的前后端一体化 demo。开发期使用 Vite + React 提供前端 HMR，后端由 Bun 提供 API；生产期先构建前端静态资源，再将前端资源和 Bun 后端打包为单个 executable。
+
+## 项目结构
+
+```text
+src/
+  server/       Bun 后端运行时、API、静态资源 fallback
+  shared/       前后端共享 TypeScript 类型
+  web/          Vite + React 前端 demo
+scripts/        开发、构建和 smoke test 脚本
+tests/          Bun test 测试
+openspec/       OpenSpec 变更与规格文档
+```
+
+## 开发命令
+
+```bash
+bun install
+bun run dev
+```
+
+`bun run dev` 会同时启动：
+
+- Bun 后端：默认 `http://127.0.0.1:3000`
+- Vite 前端：默认 `http://127.0.0.1:5173`
+
+开发期请打开 Vite 前端地址。前端通过相对路径 `/api/demo` 调用后端，Vite 会把 `/api/*` 代理到 Bun 后端，因此浏览器不需要 CORS 配置。
+
+也可以分别运行：
+
+```bash
+bun run dev:server
+bun run dev:web
+```
+
+## Demo 验证
+
+开发期打开 `http://127.0.0.1:5173`，页面应显示 `/api/demo` 返回的后端 message、Bun 版本、平台和响应时间。
+
+直接验证 API：
+
+```bash
+curl http://127.0.0.1:3000/api/demo
+curl http://127.0.0.1:3000/health
+```
+
+## 构建 executable
+
+```bash
+bun run build
+```
+
+构建流程：
+
+- 运行 `vite build`，输出前端资源到 `dist/web`
+- 生成临时 `.build/static-assets.ts`，用 Bun file import 嵌入 Vite 产物
+- 运行 `Bun.build({ compile })`，输出 `dist/gateway-checker`
+
+运行 executable：
+
+```bash
+./dist/gateway-checker
+```
+
+生产期默认访问 `http://127.0.0.1:3000`。同一个 executable 会服务 `/api/demo`、`/health`、`/assets/*` 和前端 SPA fallback。
+
+## 运行参数
+
+默认配置：
+
+- `HOST=127.0.0.1`
+- `PORT=3000`
+
+可以通过环境变量或 CLI 参数覆盖：
+
+```bash
+PORT=4000 ./dist/gateway-checker
+./dist/gateway-checker --host 0.0.0.0 --port 4000
+```
+
+## 测试
+
+```bash
+bun run typecheck
+bun test
+bun run build
+bun run test:smoke
+```
+
+`test:smoke` 会启动生成的 executable，并检查 `/api/demo`、`/health`、前端根路径、静态资源和 SPA fallback。
+
+## 前后端边界
+
+前端只通过 HTTP 调用后端，默认 API 路径为相对 `/api/*`。共享类型放在 `src/shared`，前端不得 import `src/server` 的运行时实现。
+
+这保证了当前可以单文件部署，也保留未来将前端拆到 CDN 或独立静态站点的路径。
+
+## 已知限制
+
+当前 demo 不包含数据库、认证、SSR、React Router 或 UI 组件库。单 executable 是按目标平台构建的产物，不是一个文件同时覆盖 macOS、Linux 和 Windows。