lanyuanxiaoyao
d6a77b2c6e
前端性能问题根因在于 Bun bundler 无法有效 code split、CSS
tree-shake 和产出优化的前端资源。经多轮 Bun 原生优化尝试
均无明显效果后，决定将前端构建迁回 Vite。
主要变更：
- 前端构建：从 Bun HTML import bundling 切换为 Vite build
（Rolldown code splitting、vendor chunk、CSS 优化）
- 开发模式：从 Bun fullstack 单进程 HMR 切换为 Vite dev
server + Bun API server 双进程（:5173 + :3000）
- 生产构建：三步流水线（Vite build → code generation →
Bun compile），通过 `import with { type: "file" }` 嵌入前端资源
- 静态资源服务：从 Bun HTML import manifest 切换为自定义
serveStaticAsset 函数，支持 SPA fallback 和正确的 Cache-Control
- Server 接口：BootstrapOptions 和 StartServerOptions 增加
staticAssets? 可选参数
- 文档更新：DEVELOPMENT.md 和 README.md 反映新的开发模式，
主 specs 同步 delta 变更
新增能力：
- static-asset-embedding: 构建时资源扫描与 code generation、
运行时静态资源服务
- vite-frontend-bundling: Vite 构建配置、code splitting 策略、
CSS 处理
69 lines
3.0 KiB
Markdown
69 lines
3.0 KiB
Markdown
## Purpose
|
||
|
||
定义将 Vite 构建的前端资源通过 code generation 嵌入 Bun 后端，打包为单个 standalone executable 的生产构建、运行配置和验证要求。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: 生产构建顺序
|
||
生产构建 MUST 通过三步流水线完成：Vite 前端构建 → code generation → Bun compile。
|
||
|
||
#### Scenario: 运行生产构建
|
||
- **WHEN** 开发者运行生产构建命令
|
||
- **THEN** 系统 MUST 依次执行 Vite build、资源导入 code generation、Bun.build compile，最终输出单可执行文件
|
||
|
||
#### Scenario: Vite 构建失败
|
||
- **WHEN** Vite build 步骤失败
|
||
- **THEN** 系统 MUST 停止后续步骤，不生成 code generation 文件或 executable
|
||
|
||
#### Scenario: Bun compile 失败
|
||
- **WHEN** Bun.build compile 步骤失败
|
||
- **THEN** 系统 MUST 清理 `.build/` 临时目录，不保留 stale executable
|
||
|
||
### Requirement: 单 executable 输出
|
||
生产构建 SHALL 输出一个 standalone executable，其中包含 Bun 后端和通过 `import with { type: "file" }` 嵌入的 Vite 前端产出。
|
||
|
||
#### Scenario: 在目标机器运行 executable
|
||
- **WHEN** 生成的 executable 在兼容目标平台上运行
|
||
- **THEN** 它 SHALL 启动全栈应用，且不要求目标机器安装 Node.js、Bun 或 `node_modules`
|
||
|
||
#### Scenario: 服务嵌入的前端
|
||
- **WHEN** executable 收到前端根路径请求
|
||
- **THEN** 它 SHALL 通过内嵌的 Vite 构建产出服务前端资源，且不需要外部 `dist/` 目录
|
||
|
||
#### Scenario: 服务嵌入 API 和页面
|
||
- **WHEN** 生成的 executable 启动，且浏览器打开前端根路径
|
||
- **THEN** 页面 SHALL 展示同一个 executable 进程中 `/api/summary` 和 `/api/targets` 返回的数据
|
||
|
||
### Requirement: 构建中间产物管理
|
||
构建流程 SHALL 使用 `.build/` 临时目录存放 code generation 产物，构建完成后清理。
|
||
|
||
#### Scenario: 构建成功后清理中间产物
|
||
- **WHEN** 生产构建成功完成并输出 executable
|
||
- **THEN** 系统 SHALL 删除 `.build/` 临时目录
|
||
|
||
#### Scenario: 构建失败时清理中间产物
|
||
- **WHEN** 生产构建在 Bun compile 步骤失败
|
||
- **THEN** 系统 SHALL 删除 `.build/` 临时目录和 stale executable
|
||
|
||
### Requirement: 外部运行时配置
|
||
executable MUST 将环境相关运行时配置保留在嵌入的前端和 server bundle 之外。
|
||
|
||
#### Scenario: 修改监听端口
|
||
- **WHEN** 操作者修改受支持的 port 配置
|
||
- **THEN** 同一个 executable SHALL 在不重新构建的情况下监听新端口
|
||
|
||
#### Scenario: 缺少可选配置
|
||
- **WHEN** 可选运行时配置被省略
|
||
- **THEN** executable SHALL 使用文档化的默认值
|
||
|
||
### Requirement: 构建验证
|
||
项目 SHALL 提供 `verify` 命令执行质量检查和生产构建；原 smoke test 暂时移除，executable 路由验证由后续变更重新设计。
|
||
|
||
#### Scenario: 完整验证重新构建 executable
|
||
- **WHEN** 开发者运行完整验证命令
|
||
- **THEN** 系统 MUST 先执行质量检查，再基于当前源码执行生产构建
|
||
|
||
#### Scenario: 验证失败
|
||
- **WHEN** 质量检查或构建阶段失败
|
||
- **THEN** 验证 SHALL 使命令失败
|