# 构建与发布

本文档说明开发服务、前后端集成、生产构建、脚本维护和环境变量。

适用场景：修改 scripts/、构建流程、静态资源集成或环境变量。

## 开发期运行

```bash
bun run dev config.yaml
```

scripts/dev.ts 同时启动两个进程：

| 进程            | 用途                                    |
| --------------- | --------------------------------------- |
| Bun API server  | 后端 API 服务，--watch 监听变更自动重启 |
| Vite dev server | 前端 SPA、HMR 热更新                    |

也可以单独启动：

```bash
bun run dev:server config.yaml  # 仅启动后端 API server
bun run dev:web                 # 仅启动 Vite dev server
```

## 前后端集成

开发模式下，Vite 通过 proxy 将 /api/\* 转发到 Bun。

生产模式下，前端通过 Vite 构建为静态资源，通过 import with { type: "file" } 嵌入 Bun 可执行文件。非 API 路径由 fetch fallback 处理。

路由优先级：Bun routes 具体路径 > 通配符。/api/meta 优先于 /api/\*。

## 构建

```bash
bun run build
```

构建流程：

```text
1. Vite build            -> dist/web/
2. Code generation       -> .build/static-assets.ts + .build/migrations-data.ts + .build/server-entry.ts
3. Bun compile           -> dist/alfred
4. Cleanup               -> 清理 .build/ 临时目录
```

构建参数：

| 环境变量                  | 说明             |
| ------------------------- | ---------------- |
| BUN_TARGET / BUILD_TARGET | 交叉编译目标平台 |

## 脚本说明

| 脚本                  | 文件                              | 说明                           |
| --------------------- | --------------------------------- | ------------------------------ |
| bun run dev           | scripts/dev.ts                    | 双进程开发服务                 |
| bun run dev:server    | src/server/dev.ts                 | 仅启动后端 API server          |
| bun run dev:web       | Vite CLI                          | 仅启动 Vite dev server         |
| bun run build         | scripts/build.ts                  | Vite -> codegen -> Bun compile |
| bun run schema        | scripts/generate-config-schema.ts | 生成配置 JSON Schema           |
| bun run schema:check  | scripts/generate-config-schema.ts | 检查配置 JSON Schema 同步      |
| bun run clean         | scripts/clean.ts                  | 清理构建缓存与临时文件         |
| bun run version:patch | scripts/bump-version.ts           | 升迁 patch 版本                |
| bun run version:minor | scripts/bump-version.ts           | 升迁 minor 版本                |
| bun run version:major | scripts/bump-version.ts           | 升迁 major 版本                |
| bun run version:set   | scripts/bump-version.ts           | 显式设置版本号                 |
| bun test              | (Bun 内置)                        | 运行全部测试                   |

内部辅助脚本（不直接对外开放）：

| 文件                                | 说明                                           |
| ----------------------------------- | ---------------------------------------------- |
| scripts/bump-version-logic.ts       | 版本号升迁/设置的逻辑实现                      |
| scripts/generate-migrations-data.ts | 构建时将 drizzle/\*.sql 嵌入为 TypeScript 模块 |

## 项目配置文件

| 文件                 | 用途                        |
| -------------------- | --------------------------- |
| package.json         | 项目信息、脚本、依赖声明    |
| tsconfig.json        | TypeScript 配置             |
| eslint.config.js     | ESLint 规则                 |
| commitlint.config.js | commitlint 提交信息格式校验 |
| .prettierrc.json     | Prettier 格式化规则         |
| .lintstagedrc.json   | lint-staged 配置            |
| config.example.yaml  | 配置文件示例                |
| config.schema.json   | 配置文件 JSON Schema        |
| vite.config.ts       | Vite 构建配置               |
| bunfig.toml          | Bun 配置                    |
| drizzle.config.ts    | Drizzle ORM 配置            |

## 验证期望

| 变更类型         | 验证方式             |
| ---------------- | -------------------- |
| 构建脚本         | bun run verify       |
| 静态资源集成     | bun run build        |
| 配置 schema 同步 | bun run schema:check |
| 发布前完整验证   | bun run verify       |

## 更新触发条件

修改开发服务、前后端集成、构建产物、脚本参数或验证方式时，必须更新本文档。