# {{app-name}}

（替换为你的项目介绍）

Bun 全栈应用模板，基于 Bun + React + TDesign 的前后端一体化开发框架。

## 快速开始

```bash
git clone <your-repo-url> my-project
cd my-project
bun install
bun run dev
```

访问 http://127.0.0.1:5173 查看应用。

## 使用此模板

### 1. 克隆模板

```bash
git clone <template-repo-url> my-project
cd my-project
rm -rf .git && git init
```

### 2. 替换占位符 `{{app-name}}`

在整个项目中全局搜索替换 `{{app-name}}` 为你的项目名称（如 `my-app`）。以下为所有出现位置：

| #   | 文件                                    | 说明                                       |
| --- | --------------------------------------- | ------------------------------------------ |
| 1   | `package.json`                          | `name` 字段                                |
| 2   | `scripts/build.ts`                      | 可执行文件路径                             |
| 3   | `src/server/config.ts`                  | CLI 帮助文本                               |
| 4   | `src/server/helpers.ts`                 | `createHealthResponse()` 的 `service` 字段 |
| 5   | `src/server/server.ts`                  | 服务启动日志消息                           |
| 6   | `src/web/index.html`                    | `<title>` 和 `<meta name="description">`   |
| 7   | `src/web/app.tsx`                       | Header 中的品牌名和欢迎标题                |
| 8   | `src/web/hooks/use-theme-preference.ts` | `localStorage` 键名                        |
| 9   | `tests/web/App.test.tsx`                | 测试中的品牌名断言                         |

> **提示**：可直接在编辑器中全局搜索 `{{app-name}}`，一次性替换。

### 3. 清理 OpenSpec 历史

删除模板自带的 OpenSpec 变更历史，保留框架配置：

```bash
rm -rf openspec/specs/*
rm -rf openspec/changes/*
```

> `openspec/config.yaml` 需要保留，其中包含项目开发规范配置。

### 4. 安装依赖

```bash
bun install
```

### 5. 开始开发

```bash
bun run dev
```

## 项目管理

| 命令                 | 说明                                                       |
| -------------------- | ---------------------------------------------------------- |
| `bun run dev`        | 启动开发模式（并行启动后端 + 前端 Vite 开发服务器）        |
| `bun run dev:server` | 仅启动后端开发服务（`--watch` 热重载）                     |
| `bun run dev:web`    | 仅启动前端 Vite 开发服务器                                 |
| `bun run build`      | 生产构建（Vite 打包前端 → Bun compile 生成独立可执行文件） |
| `bun test`           | 运行全部测试                                               |
| `bun run lint`       | ESLint 代码风格检查                                        |
| `bun run format`     | Prettier 代码格式化                                        |
| `bun run typecheck`  | TypeScript 类型检查                                        |
| `bun run check`      | 完整质量检查：typecheck + lint + test                      |
| `bun run verify`     | 验证构建流程：check + build                                |
| `bun run clean`      | 清理构建产物和临时文件                                     |

## 项目结构

```text
.
├── config.example.yaml         # 配置文件示例
├── bunfig.toml                 # Bun 配置（测试预加载等）
├── tsconfig.json               # TypeScript 配置
├── vite.config.ts              # Vite 构建配置（代码分包、代理）
├── eslint.config.js            # ESLint 统一配置
├── .prettierrc.json            # Prettier 格式化配置
├── commitlint.config.js        # Commitlint 提交规范配置
├── .lintstagedrc.json          # lint-staged 暂存区检查配置
├── scripts/
│   ├── dev.ts                  # 开发启动脚本（并行启动 API + Vite）
│   ├── build.ts                # 生产构建脚本（Vite → 代码生成 → Bun compile）
│   └── clean.ts                # 清理脚本
├── src/
│   ├── server/                 # 后端代码
│   │   ├── bootstrap.ts        # 统一启动引导（配置加载 → 服务启动 → 优雅关闭）
│   │   ├── config.ts           # CLI 参数解析 + YAML 配置加载
│   │   ├── dev.ts              # 开发模式入口
│   │   ├── main.ts             # 生产模式入口
│   │   ├── server.ts           # HTTP 服务器（Bun.serve routes 声明式路由）
│   │   ├── helpers.ts          # 共享响应工具（健康检查、JSON 响应）
│   │   ├── middleware.ts        # API 参数校验中间件
│   │   ├── static.ts           # 静态资源服务
│   │   └── routes/             # API 路由处理器
│   │       └── health.ts       # 健康检查端点
│   ├── shared/
│   │   └── api.ts              # 前后端共享 TypeScript 类型定义
│   └── web/                    # 前端代码
│       ├── index.html          # HTML 入口
│       ├── main.tsx            # React 入口（QueryClient + ErrorBoundary）
│       ├── app.tsx             # 根组件（Layout + 主题切换 + /health 展示）
│       ├── styles.css          # 全局样式
│       ├── css.d.ts            # CSS 模块类型声明
│       ├── components/         # UI 组件
│       ├── hooks/              # React Hooks
│       └── utils/              # 前端工具函数
├── tests/                      # 测试文件（镜像 src 目录结构）
├── openspec/                   # OpenSpec 规格与变更管理
└── docs/                       # 项目文档
```

## 配置

项目使用 YAML 配置文件，支持环境变量覆盖。

### 配置文件

复制 `config.example.yaml` 为 `config.yaml`（或任意名称），根据需要修改：

```yaml
server:
  host: "127.0.0.1"
  port: 3000
```

### 环境变量覆盖

| 环境变量 | 对应配置字段  | 默认值      |
| -------- | ------------- | ----------- |
| `HOST`   | `server.host` | `127.0.0.1` |
| `PORT`   | `server.port` | `3000`      |

### 配置优先级

```
环境变量 > YAML 配置文件 > 代码默认值
```

### 使用自定义配置

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

## 技术栈

### 运行时

| 技术                                          | 说明                                           |
| --------------------------------------------- | ---------------------------------------------- |
| [Bun](https://bun.sh)                         | JavaScript/TypeScript 运行时、包管理器、打包器 |
| [TypeScript](https://www.typescriptlang.org/) | 类型安全的 JavaScript 超集                     |

### 后端

| 技术                                         | 说明                         |
| -------------------------------------------- | ---------------------------- |
| `Bun.serve`                                  | HTTP 服务器，声明式路由匹配  |
| `Bun.YAML`                                   | YAML 配置文件解析            |
| [es-toolkit](https://es-toolkit.slash.page/) | 高性能工具库（推荐优先使用） |

### 前端

| 技术                                                | 说明                     |
| --------------------------------------------------- | ------------------------ |
| [React 19](https://react.dev/)                      | UI 组件框架              |
| [TDesign React](https://tdesign.tencent.com/react/) | 企业级 UI 组件库         |
| [@tanstack/react-query](https://tanstack.com/query) | 服务端状态管理与数据获取 |
| [Recharts](https://recharts.org/)                   | 图表可视化（推荐使用）   |
| [Vite](https://vitejs.dev/)                         | 前端构建工具             |

### 工程化

| 技术                                       | 说明             |
| ------------------------------------------ | ---------------- |
| [ESLint](https://eslint.org/)              | 代码规范检查     |
| [Prettier](https://prettier.io/)           | 代码格式化       |
| [Husky](https://typicode.github.io/husky/) | Git hooks 管理   |
| [Commitlint](https://commitlint.js.org/)   | Git 提交消息校验 |

### 测试

| 技术                                                        | 说明             |
| ----------------------------------------------------------- | ---------------- |
| [bun:test](https://bun.sh/docs/cli/test)                    | Bun 内置测试框架 |
| [@testing-library/react](https://testing-library.com/react) | React 组件测试   |
| [jsdom](https://github.com/jsdom/jsdom)                     | DOM 环境模拟     |

## 开源协议

MIT