lanyuanxiaoyao/bun-app-template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 引入分层文档体系，删除 DEVELOPMENT.md

Browse Source 
建立 docs/user/ 和 docs/development/ 分层文档结构：
- docs/README.md 文档总路由、归属矩阵、影响分析规则
- docs/user/ 模板使用、配置、部署、故障排查
- docs/development/ 架构、后端、前端、构建发布开发规范
- README.md 轻量化为项目入口和索引
- 删除 DEVELOPMENT.md，内容拆分至专题文档
- 更新 openspec/config.yaml 首读入口和文档影响分析规则
- 修正 docs/prompts/README.md 过时引用和边界说明
This commit is contained in:
兰缘小妖
2026-05-25 19:09:08 +08:00
parent 0d08c914de
commit 763d814543
15 changed files with 941 additions and 1159 deletions
Download Patch File Download Diff File Expand all files Collapse all files

857
DEVELOPMENT.md
View File

@@ -1,857 +0,0 @@
my-app 开发文档
本文档面向 `my-app` 项目的开发者，介绍项目结构、前后端架构、构建流程、测试、代码规范等内容。
用户使用说明请参阅 [README.md](README.md)。
## 目录
- [项目结构](#项目结构)
- [前后端边界](#前后端边界)
- [一、后端开发指引](#一后端开发指引)
- [二、前端开发指引](#二前端开发指引)
- [三、项目运行、集成与打包](#三项目运行集成与打包)
- [代码质量](#代码质量)
- [测试](#测试)
- [已知限制](#已知限制)
---
## 项目结构
```text
src/
server/
bootstrap.ts 后端统一启动引导（loadServerConfig → startServer）
config.ts CLI 参数解析与配置文件加载 facade（可选 YAML configPath，支持 --help/-h）
config/ 配置解析模块（types、issues、variables、normalizer、schema）
dev.ts 开发模式启动入口（mode: "development"）
logger.ts 统一日志接口和运行时实现
main.ts 生产模式启动入口（mode: "production"，安全头启用）
server.ts HTTP server 启动工厂（Bun.serve routes 声明式路由 + fetch fallback 静态资源服务）
static.ts 生产模式静态资源服务（SPA fallback、Content-Type 映射、immutable 缓存）
helpers.ts 共享响应格式化工具（见下方函数清单）
middleware.ts API 参数校验中间件（validateIdParam、validatePagination、validateTimeRange）
routes/ API 路由 handler（按端点拆分）
meta.ts GET /api/meta
version.ts 运行时版本号读取（从 package.json 读取并验证）
shared/
api.ts 前后端共享 TypeScript 类型
app.ts 应用全局常量（name、title、subtitle、description）
web/ React 前端（通过 Vite 构建）
index.html HTML 入口
app.tsx 根组件（Admin 布局：Header + Sidebar + Content + 版本号展示）
main.tsx 入口（BrowserRouter + QueryClient 挂载 + ErrorBoundary + ReactQueryDevtools + TDesign CSS 导入）
routes.tsx 路由配置（定义所有页面路由）
styles.css 全局样式与自定义 CSS 变量
css.d.ts CSS 模块类型声明
pages/ 页面组件
dashboard/
index.tsx 仪表盘页（欢迎语 + /api/meta 联调示例）
users/
index.tsx 用户管理页（占位）
settings/
index.tsx 系统设置页（占位）
404/
index.tsx 404 页面
components/ UI 组件
ErrorBoundary.tsx React 错误边界，捕获渲染异常并展示降级 UI
Sidebar/
index.tsx 侧边栏菜单组件（TDesign Menu + 底部折叠按钮）
hooks/ React hooks
use-theme-preference.ts 主题偏好 hook（system/light/dark，localStorage 记忆 + matchMedia 监听）
use-sidebar-collapsed.ts 侧边栏折叠状态 hook（localStorage 记忆）
utils/ 前端工具函数
time.ts 时间处理（formatCountdown、formatDurationUnit、formatRelativeTime、isOlderThan、subtractHours）
menu.tsx 菜单配置（路由与菜单项统一数据源）
routes.tsx 路由配置（定义所有页面路由）
scripts/
dev.ts 双进程开发服务（Bun API server + Vite dev server）
build.ts Vite → codegen → Bun compile 三步构建流水线（含版本号注入）
generate-config-schema.ts 配置 JSON Schema 生成与同步校验
bump-version-logic.ts 纯版本管理逻辑（parse、validate、bump、format）
bump-version.ts 版本升迁 CLI 脚本
clean.ts 清理构建产物与临时文件
tests/ Bun test 测试（结构镜像 src 目录）
setup.ts 全局测试配置（jsdom、polyfill）
helpers.ts 测试辅助工具（rmRetry）
server/ 后端测试
bootstrap.test.ts
config.test.ts
config/ 配置模块测试
variables.test.ts
schema.test.ts
middleware.test.ts
static.test.ts
web/ 前端测试
App.test.tsx
test-utils.tsx
openspec/ OpenSpec 变更、规格文档与 fast-drive workflow schema
config.example.yaml 配置文件示例（server.listen 布局 + 显式变量引用）
config.schema.json 配置文件 JSON Schema（由 bun run schema 生成）
data/ 运行时数据目录（日志文件、数据库等）
```
---
## 前后端边界
前端只通过 HTTP 调用后端，API 路径为 `/api/*`。共享类型放在 `src/shared`，前端不得 `import src/server` 的运行时实现。
---
## 一、后端开发指引
### 1.1 架构概览
```
启动流程:
dev.ts / main.ts → parseRuntimeArgs(cli args) → 必须指定 config.yaml
→ bootstrap({ configPath, mode, version? })
→ loadServerConfig(configPath)：YAML 解析 → configDir、dataDir、logging
→ createRuntimeLogger(config.logging, mode, version)
→ mkdirSync(config.dataDir, { recursive: true })
→ startServer({ config, logger })：Bun.serve 声明式路由 + fetch fallback
→ logger 记录启动成功；SIGINT/SIGTERM → logger.flush() → exit
HTTP 请求:
Request → Bun.serve routes 声明式匹配 → routes/*.ts(handler)
→ helpers.ts(响应格式化) → Response
前端: fetch fallback → serveStaticAsset (生产) / Vite proxy (开发)
```
### 1.2 库使用优先级
后端代码开发遵循严格的库选择顺序：
| 优先级 | 来源 | 典型用途 |
| ------ | ------------ | --------------------------------------------------------------------------------------------------- |
| 1 | Bun 内置 API | `Bun.serve`、`Bun.file`、`Bun.YAML`、`Bun.spawn`、`bun:sqlite`（如需数据存储） |
| 2 | es-toolkit | 类型判断（`isPlainObject`/`isNil`/`isEmptyObject`）、深度比较（`isEqual`）、并发控制（`Semaphore`） |
| 3 | 标准 Web API | `Object.fromEntries`、`Headers`、`fetch`、`AbortController`、`Response` |
| 4 | 主流三方库 | 按需引入，优先社区活跃、类型完善的库 |
| 5 | 自行实现 | 仅在以上都无法满足时（如 `parseDuration`、`parseSize` 等专项逻辑） |
**原则**：新增依赖前先检查上述每一层级是否已有可用方案。禁止随意引入新依赖。
### 1.3 API 路由开发
路由文件位于 `src/server/routes/`，每个端点一个文件。路由通过 `server.ts` 的 `Bun.serve({ routes })` 声明式注册，使用 per-method handler 对象：
```typescript
// server.ts 中的路由注册
routes: {
"/api/*": () => jsonResponse(createApiError("API route not found", 404), { mode, status: 404 }),
"/api/meta": {
GET: async () => handleMeta(mode, await resolveVersion()),
},
}
```
Handler 函数签名：
```typescript
// 带版本号参数的路由
export function handleMeta(mode: RuntimeMode, version: string): Response;
```
**请求处理流程**：
1. `Bun.serve` 的 `routes` 对象按路径 + HTTP 方法匹配请求
2. 未匹配方法的请求落入 `/api/*` 通配符（返回 404）
3. 各 handler 内部通过 `helpers.ts` 的 `jsonResponse`、`createApiError` 等格式化输出
4. 需要参数校验时使用 `middleware.ts` 提供的校验函数，返回 `Response` 实例表示校验失败（直接返回），返回数据对象表示通过
**新增路由步骤**：
1. 在 `src/server/routes/` 下创建 `<name>.ts`
2. 实现 handler 函数并 export
3. 在 `server.ts` 的 `routes` 对象中注册路径和 method handler
4. 在 `tests/server/` 中添加对应测试
### 1.4 共享工具
- **`helpers.ts`**：跨路由共用的响应工具函数
- `createApiError(error, status)` — 构造 API 错误体
- `createHeaders(mode, init)` — 创建响应 Headers（生产模式附加安全头：`X-Content-Type-Options`、`Referrer-Policy`）
- `createMetaResponse(version)` — 构造应用元信息响应 `{ ok: true, service, timestamp, version }`
- `formatDuration(ms)` — 毫秒转为可读时长字符串
- `jsonResponse(body, options)` — JSON 响应构造
- **`middleware.ts`**：API 参数校验函数
- `validateIdParam(idStr, mode)` — 校验 ID 参数格式（字母数字下划线连字符，字母开头），返回 `{ id }` 或 `Response`
- `validatePagination(pageParam, pageSizeParam, mode)` — 校验分页参数（默认 page=1, pageSize=20，pageSize 上限 200），返回 `{ page, pageSize }` 或 `Response`
- `validateTimeRange(from, to, mode)` — 校验时间范围参数（ISO 格式、from < to），返回 `{ from, to }` 或 `Response`
- **`static.ts`**：生产模式静态资源服务
- `serveStaticAsset(pathname, assets)` — 静态资源分发（文件扩展名路由 → immutable 缓存，无扩展名 → SPA fallback 返回 index.html）
- `hasFileExtension(path)` / `contentTypeFor(path)` / `htmlResponse(html)` — 辅助函数
- **`logger.ts`**：统一日志接口和运行时实现
- `Logger` 接口：`trace`/`debug`/`info`/`warn`/`error`/`fatal`/`child`/`flush`
- `createRuntimeLogger(config)`：生产运行时，基于 Pino 结构化日志，console pretty + file JSONL rolling
- `createConsoleFallback()`：配置加载失败前的降级日志
- `createNoopLogger()` / `createMemoryLogger()`：测试替身
### 1.5 类型定义规范
- **共享类型**以 `src/shared/api.ts` 为唯一源头，前后端共同引用
- **应用常量**以 `src/shared/app.ts` 为唯一源头，定义 `APP` 对象（name、title、subtitle、description），前后端及构建脚本共同引用
- **版本号**以 `package.json.version` 为唯一源头，通过 `src/server/version.ts` 运行时读取或构建时注入字面量
- 前端不得 `import src/server/` 下的任何文件
- **严格联合类型**优先于宽类型：如 `RuntimeMode: "development" | "production" | "test"` 而非 `RuntimeMode: string`
- API 响应类型（`ApiErrorResponse`、`MetaResponse`）定义在 shared 中
- `ResolvedConfig` 类型包含 `configDir`、`dataDir`、`logging`，由配置解析流程产出
### 1.6 配置文件规范
配置采用分层生命周期：`unknown → AuthoringConfig → NormalizedConfig → ValidatedConfig → ServerConfig`。
```
CLI argv → parseRuntimeArgs → { configPath }
→ 必须指定 configPath（无 configPath 启动失败）
→ loadServerConfig(configPath)
→ YAML 解析 → normalize(变量替换) → strict validate → resolve
→ ServerConfig{ host, port, configDir, dataDir, logging }
→ logging 字段用于 createRuntimeLogger；dataDir 字段用于 mkdirSync
```
配置加载流程：
1. **解析 YAML**：`Bun.YAML.parse` 将配置文件解析为 `unknown`
2. **normalize**：提取 `variables`，替换 `${KEY}` / `${KEY|default}` 变量引用，移除 `variables` 段，产出 `NormalizedConfig`
3. **strict validate**：使用 Ajv + TypeBox 生成的 schema 严格校验（拒绝未知字段、校验类型和范围）
4. **resolve**：从校验后的配置中提取 `server.listen.host`、`server.listen.port`、`server.storage.dataDir`、`server.logging` 等字段，填充默认值
`ServerConfig` 包含以下字段：
| 字段 | 来源 | 默认值 |
| --------- | ------------------------------------------ | --------------------- |
| `host` | `server.listen.host`（可含变量引用）→ 默认 | `127.0.0.1` |
| `port` | `server.listen.port`（可含变量引用）→ 默认 | `3000` |
| `dataDir` | `server.storage.dataDir` → 默认 `./data` | 配置文件目录下 `data` |
| `logging` | `server.logging` | 见下方日志配置 |
**日志配置（`server.logging`）**：
| 字段 | 类型 | 说明 | 默认值 |
| ------------------------- | ------ | -------------------------------------------------------------------- | -------------------------------- |
| `level` | string | 全局日志级别（trace/debug/info/warn/error/fatal），未设置时默认 info | `"info"` |
| `console.level` | string | 控制台日志级别，未设置时继承 `level` | 继承 `level` |
| `file.level` | string | 文件日志级别，未设置时继承 `level` | 继承 `level` |
| `file.path` | string | 日志文件路径，相对路径基于配置文件目录，默认基于 `dataDir` | `<dataDir>/logs/${APP.name}.log` |
| `file.rotation.size` | string | 按大小滚动，支持 `B`/`KB`/`MB`/`GB` 单位 | `"50MB"` |
| `file.rotation.frequency` | string | 按时间滚动（`hourly`/`daily`/`weekly`） | `"daily"` |
| `file.rotation.maxFiles` | number | 最大归档文件数 | `14` |
配置文件示例（`config.example.yaml`）：
```yaml
# yaml-language-server: $schema=./config.schema.json
server:
listen:
host: "${HOST|127.0.0.1}"
port: ${PORT|3000}
storage:
dataDir: ${DATA_DIR|./data}
logging:
level: ${LOG_LEVEL|info}
console:
level: info
file:
level: info
path: "./data/logs/my-app.log"
rotation:
size: "50MB"
frequency: daily
maxFiles: 14
```
变量语法：
| 语法 | 说明 |
| --------------- | ------------------------------ |
| `${KEY}` | 引用变量，未定义时报错 |
| `${KEY\|value}` | 引用变量，未定义时使用默认值 |
| `${KEY\|}` | 引用变量，未定义时使用空字符串 |
| `$${KEY}` | 转义，输出 `${KEY}` 原文 |
变量解析优先级：`variables 字段` → `process.env` → `默认值` → `unresolved 报错`
完整变量引用保留原始类型，部分拼接转为 string。环境变量不会隐式覆盖配置。
配置模块结构（`src/server/config/`）：
| 文件 | 职责 |
| --------------------- | -------------------------------------------------------- |
| `types.ts` | AuthoringConfig、NormalizedConfig、ValidatedConfig 类型 |
| `issues.ts` | 结构化配置问题、路径渲染、去重、中文格式化 |
| `variables.ts` | 变量提取、引用解析、默认值、环境变量查找、类型推断 |
| `normalizer.ts` | Authoring → Normalized 转换（变量替换 + 移除 variables） |
| `schema/fragments.ts` | TypeBox schema 片段 |
| `schema/builder.ts` | Authoring/Normalized schema 构建 |
| `schema/validate.ts` | Ajv strict 校验 + 错误映射 |
| `schema/export.ts` | JSON Schema 导出（用于生成 config.schema.json） |
JSON Schema 相关命令：
```bash
bun run schema # 重新生成 config.schema.json
bun run schema:check # 校验 config.schema.json 是否同步
```
运行时依赖 `@sinclair/typebox`（JSON Schema 类型构建）和 `ajv`（JSON Schema 校验），用于配置启动时严格契约校验。
### 1.7 版本管理
项目使用 `package.json.version` 作为版本号唯一来源，严格 `MAJOR.MINOR.PATCH` 格式。
**版本获取方式**：
- 开发模式：`src/server/version.ts` 运行时从 `package.json` 读取版本号
- 生产模式：`scripts/build.ts` 在构建时将版本号烘焙为 `APP_VERSION` 字面量注入 `server-entry.ts`
**版本升迁命令**：
```bash
bun run version:patch # 升迁 patch 版本（0.1.0 → 0.1.1）
bun run version:minor # 升迁 minor 版本（0.1.0 → 0.2.0）
bun run version:major # 升迁 major 版本（0.1.0 → 1.0.0）
bun run version:set 2.0.0 # 显式设置版本号
```
版本升迁仅更新 `package.json.version`，不自动创建 git commit、tag 或 changelog。
**API 暴露**：`GET /api/meta` 返回 `{ ok, service, timestamp, version }`，前端通过此接口获取并展示版本号。
### 1.8 错误模式
- **API 错误**：`{ error: "描述", status: <code> }`，状态码 400/404
- **日志**：后端运行时代码统一通过 `Logger` 接口输出结构化和纯文本日志，禁止直接使用 `console.*`（`src/server/logger.ts` 是唯一例外）。开发环境控制台输出 pretty 格式，生产环境同时输出 JSONL 文件日志并支持大小和时间滚动。敏感字段自动 redaction。启动失败和未初始化场景使用 `ConsoleFallbackLogger` 兜底。
### 1.9 日志模块
`Logger` 接口定义统一的日志抽象，支持以下实现：
| 实现 | 用途 |
| ----------------------- | --------------------------------------------- |
| `PinoLoggerWrapper` | 生产运行时，封装 Pino、pino-pretty、pino-roll |
| `ConsoleFallbackLogger` | 配置加载失败前的降级日志 |
| `NoopLogger` | 静默丢弃日志 |
| `MemoryLogger` | 测试替身，可断言日志内容 |
使用方式：
```typescript
// 生产运行时创建
const logger = createRuntimeLogger(config.logging, mode, version);
// 测试中使用 MemoryLogger
const logger = createMemoryLogger();
// ... 执行被测代码 ...
expect(logger.entries).toContainEqual({ level: "info", msg: "server started" });
```
敏感字段自动 redaction：请求头中的 `authorization`、`cookie`、`x-api-key` 以及请求体中的 `password`、`token`、`secret` 等字段在日志输出时自动替换为 `[redacted]`。
---
## 二、前端开发指引
### 2.1 技术栈概览
| 层面 | 技术 | 用途 |
| ------ | --------------------------------------------------- | ------------------------ |
| 框架 | React 19 | UI 组件开发 |
| 构建 | Vite（开发）+ Bun compile（生产） | 开发服务 HMR 与生产构建 |
| 语言 | TypeScript | 类型安全 |
| UI 库 | TDesign React + tdesign-icons-react | UI 组件与图标 |
| 数据层 | TanStack Query (React Query) + React Query Devtools | 服务端状态管理与自动刷新 |
| 路由 | React Router v7 (Declarative mode) | SPA 路由与页面导航 |
**不引入的依赖**：状态管理库（TanStack Query 即服务端状态层，组件内用 `useState` 足够）
### 2.2 组件树与数据流
```
main.tsx
└── StrictMode
└── ErrorBoundary（React 错误边界）
└── QueryClientProvider（TanStack Query 全局挂载）
└── BrowserRouter（React Router 路由）
├── App（根组件，Admin 布局）
│ ├── useThemePreference() ── Header 主题模式 RadioGroup（系统/明亮/黑暗）
│ ├── useSidebarCollapsed() ── 侧边栏折叠状态（localStorage 记忆）
│ ├── Layout
│ │ ├── Header（品牌名 + 版本号 + 页标题 + 主题切换）
│ │ └── Layout（嵌套）
│ │ ├── Aside
│ │ │ └── Sidebar（TDesign Menu + 底部折叠按钮，菜单项点击导航）
│ │ └── Content
│ │ └── AppRoutes（路由配置）
│ │ ├── / → DashboardPage（欢迎语 + /api/meta 联调）
│ │ ├── /users → UsersPage（占位）
│ │ ├── /settings → SettingsPage（占位）
│ │ └── * → NotFoundPage（404）
└── ReactQueryDevtools（开发工具，仅开发环境）
```
**Hook 架构**：
```
hooks/use-theme-preference.ts（浏览器 UI 偏好）
├── ThemePreference: system / light / dark（RadioGroup 受控值）
├── EffectiveTheme: light / dark（写入 document.documentElement theme-mode）
├── localStorage key: theme.preference（同一浏览器记忆）
└── matchMedia("(prefers-color-scheme: dark)")（系统模式下跟随系统明暗变化）
hooks/use-sidebar-collapsed.ts（侧边栏折叠状态）
├── collapsed: boolean（折叠状态）
├── localStorage key: sidebar.collapsed（同一浏览器记忆）
└── toggleCollapsed()（切换折叠状态）
```
**菜单配置**：
```
utils/menu-config.ts（路由与菜单统一数据源）
├── MENU_ITEMS: MenuItemConfig[]（菜单项配置数组）
│ ├── { value: "dashboard", label: "仪表盘", path: "/", icon: <DashboardIcon /> }
│ ├── { value: "users", label: "用户管理", path: "/users", icon: <UserIcon /> }
│ └── { value: "settings", label: "系统设置", path: "/settings", icon: <SettingIcon /> }
└── Sidebar 和 Routes 共同引用，保证菜单项与路由同步
```
### 2.3 TanStack Query 数据层
#### Query Key 规范
```typescript
// 使用 structured array（非字符串），以便精确匹配和按 prefix 失效
const queryKeys = {
meta: () => ["meta"] as const,
};
```
- Key 使用 **structured array**（非字符串），以便精确匹配和按 prefix 失效
- 使用 `as const` 保持字面量类型
#### 查询配置规范
```typescript
// 全局级查询（需要持续刷新）
useQuery({
queryKey: queryKeys.meta(),
queryFn: () => fetchJson<MetaResponse>("/api/meta"),
refetchInterval: 30000, // 30s 轮询
refetchIntervalInBackground: false, // 切后台不轮询
staleTime: 5000, // 5s 内视为 fresh
});
```
#### fetch 封装
```typescript
async function fetchJson<T>(url: string): Promise<T> {
const response = await fetch(url);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
return response.json() as Promise<T>;
}
```
- 统一使用 `fetch`（不引入 axios），与后端共享 Web API 生态
- 错误抛异常，由 TanStack Query 的 `error` 状态承接
#### QueryClient 全局配置
```typescript
new QueryClient({
defaultOptions: {
queries: {
retry: 1, // 失败重试 1 次
refetchOnWindowFocus: true, // 窗口聚焦时刷新
staleTime: 5000, // 5s 内视为 fresh，避免重复请求
},
},
});
```
### 2.4 组件开发规范
#### 文件命名与导入
- 每个 React 组件一个 `.tsx` 文件，文件名使用 PascalCase（如 `ErrorBoundary.tsx`）
- 组件 props 定义为 `interface XxxProps`，紧邻组件函数声明
- 类型从 `../shared/api` 导入，使用 `type` 导入（`import type { ... }`）
```typescript
import type { MetaResponse } from "../shared/api";
interface AppProps {
title?: string;
}
export function App({ title }: AppProps) {
// ...
}
```
#### 组件拆分原则
- **展示组件**（`components/`）：纯渲染逻辑，通过 props 接收数据，通过回调返回事件
- **容器逻辑**放在 hooks 中，组件只做数据消费
- **工具函数**（时间处理等）放在 `utils/`，保持纯函数无副作用
### 2.5 样式开发规范
前端基于 TDesign React 构建 UI，样式开发遵循以下优先级（从高到低）：
1. **使用 TDesign 组件**：布局、间距、排版优先使用 TDesign 组件（如 Space、Divider、Typography）
2. **使用 TDesign 组件 props**：通过组件的 props 参数控制外观（如 `theme`、`variant`、`size`）
3. **使用 TDesign CSS tokens**：颜色、间距、字体等使用 `--td-*` CSS 变量（如 `--td-success-color`、`--td-comp-margin-xxl`）
4. **在 styles.css 中定义 CSS 类**：无法通过上述方式满足的样式需求，集中定义在 `styles.css` 中
5. **自行开发组件**：仅在 TDesign 无法满足需求时自行开发
**红线**：
- **严禁在组件中使用 `style` 属性内联调整样式**
- **严禁通过 CSS 覆盖 TDesign 组件内部类名**（如 `.t-tab-panel`），如需定制使用组件的 `className` prop
- **严禁使用 `!important`**
- 颜色统一使用 TDesign CSS tokens（`--td-success-color`、`--td-error-color`、`--td-warning-color` 等），不使用硬编码色值
**styles.css 组织**：
- 自定义 CSS 变量定义在 `:root` 中
- 布局类（`.dashboard`、`.dashboard-header-controls`）定义全局页面结构
- 组件修饰类为自定义视觉组件提供样式变体
- 通用工具类（`.full-width`、`.text-disabled`、`.tabular-nums`）提供公用排版能力
### 2.6 前端测试规范
- 测试目录：`tests/web/`，结构对应 `src/web/`
- 重点测试 **纯函数**（时间处理、格式化等）和**组件渲染**
- 使用 `bun:test` 框架
- 组件测试使用 `@testing-library/react` 的语义化查询（getByText、getByRole）而非 CSS 选择器
- 测试用户行为而非实现细节：模拟用户点击、输入等操作，而非直接调用组件方法
- 只 mock 系统边界：mock fetch 返回预设响应，使用真实的 QueryClientProvider 包裹组件
---
## 三、项目运行、集成与打包
### 3.1 开发期运行
```bash
bun run dev [config.yaml]
```
`scripts/dev.ts` 同时启动两个进程：
- **Bun API server**（端口 3000）：后端 API 服务，`--watch` 监听后端文件变更自动重启
- **Vite dev server**（端口 5173）：前端 SPA + HMR 热更新
开发时访问 `http://127.0.0.1:5173`，Vite 自动将 `/api` 请求代理到后端。
也可以单独启动：
```bash
bun run dev:server [config.yaml] # 仅启动后端 API server（--watch 模式）
bun run dev:web # 仅启动 Vite dev server
```
### 3.2 前后端集成方式
#### 双进程开发架构
开发模式下前后端分别由 Vite 和 Bun 服务：
- Vite dev server 负责前端 SPA、HMR、模块热替换
- Bun API server 负责后端 API 路由
- Vite 通过 proxy 配置将 `/api/*` 转发到 Bun
#### 生产模式架构
生产模式下前端通过 Vite 构建为静态资源，通过 `import with { type: "file" }` 嵌入 Bun 可执行文件：
```typescript
// server.ts
const server = Bun.serve({
fetch(req) {
// staticAssets 存在时服务嵌入的前端资源
if (staticAssets) {
return serveStaticAsset(new URL(req.url).pathname, staticAssets);
}
return new Response("Frontend is served by Vite dev server on :5173", { status: 404 });
},
routes: {
"/api/*": () => ...,
"/api/meta": { GET: async () => handleMeta(mode, await resolveVersion()) },
},
});
```
#### 路由优先级
Bun routes 的匹配规则：具体路径 > 通配符。`/api/meta` 优先于 `/api/*`。
未匹配 method 的请求（如 POST /api/meta）会落入 `/api/*` 通配符返回 404；若无该通配符会落入 fetch fallback。
非 API 路径由 fetch fallback 处理：有文件扩展名的返回对应静态资源或 404，无扩展名的返回 SPA index.html。
### 3.3 构建打包
#### 构建命令
```bash
bun run build
```
#### 构建流程
`scripts/build.ts` 执行三步流水线：
```
1. Vite build → dist/web/ (前端静态资源，含 code splitting)
2. Code generation → .build/static-assets.ts + .build/server-entry.ts（含版本号字面量注入）
3. Bun compile → dist/my-app (单可执行文件)
```
- Vite 构建前端资源到 `dist/web/`，自动 code splitting（vendor-react、vendor-tdesign、vendor-chart）
- Code generation 扫描 `dist/web/` 生成 `import with { type: "file" }` 声明，将资源嵌入 binary
- Bun compile 以 `.build/server-entry.ts` 为入口编译最终可执行文件
- `.build/` 临时目录在构建完成后自动清理
#### 产物
| 产物 | 用途 |
| ------------- | ---------------------------------------- |
| `dist/my-app` | 生产可执行文件（含前端资源，单文件部署） |
| `dist/web/` | Vite 构建的前端资源（构建中间产物） |
#### 构建参数
| 环境变量 | 说明 |
| --------------------------- | -------------------------------------- |
| `BUN_TARGET`/`BUILD_TARGET` | 交叉编译目标平台（如 `bun-linux-x64`） |
#### 运行可执行文件
```bash
./dist/my-app [config.yaml]
```
启动后：
- 访问 `http://127.0.0.1:3000/` → 返回前端 SPA
- 访问 `http://127.0.0.1:3000/api/meta` → 返回应用元信息 JSON（含版本号）
#### 清理
```bash
bun run clean
# 清理 dist/ 构建产物和 .build/ 临时文件
```
### 3.4 开发工作流
#### 日常开发循环
```bash
bun run dev [config.yaml] # 启动双进程开发环境（Vite :5173 + API :3000）
# 访问 http://127.0.0.1:5173
# 修改前端代码 → Vite HMR 热更新 / 修改后端代码 → --watch 自动重启
bun run check # 提交前运行完整质量检查
```
#### 完整验证流程
```bash
bun run verify
# = bun run check + bun run build
```
`verify` 适合 CI 或正式提交前，会完整验证类型检查、lint、格式、单元测试和生产构建。
### 3.5 脚本说明
| 脚本 | 文件 | 说明 |
| ----------------------- | ------------------------- | ---------------------------------------- |
| `bun run dev` | `scripts/dev.ts` | 双进程开发服务（Vite :5173 + API :3000） |
| `bun run dev:server` | `src/server/dev.ts` | 仅启动后端 API server（--watch 模式） |
| `bun run dev:web` | Vite CLI | 仅启动 Vite dev server |
| `bun run build` | `scripts/build.ts` | Vite → codegen → Bun compile 三步构建 |
| `bun run clean` | `scripts/clean.ts` | 清理构建缓存与临时文件 |
| `bun run version:patch` | `scripts/bump-version.ts` | 升迁 patch 版本（x.y.Z） |
| `bun run version:minor` | `scripts/bump-version.ts` | 升迁 minor 版本（x.Y.0） |
| `bun run version:major` | `scripts/bump-version.ts` | 升迁 major 版本（X.0.0） |
| `bun run version:set` | `scripts/bump-version.ts` | 显式设置版本号 |
### 3.6 环境变量
| 变量 | 用途 | 默认值 |
| --------------------------- | ----------------------------------------------- | -------- |
| `BUN_TARGET`/`BUILD_TARGET` | 交叉编译目标平台（仅在 `bun run build` 时有效） | 当前平台 |
### 3.7 项目配置文件
| 文件 | 用途 |
| ---------------------- | ------------------------------------------------------------ |
| `package.json` | 项目信息、脚本、依赖声明 |
| `tsconfig.json` | TypeScript 配置（ESNext 模块、严格模式） |
| `eslint.config.js` | ESLint 规则（含前端不得 import server 的检查） |
| `commitlint.config.js` | commitlint 提交信息格式校验 |
| `.prettierrc.json` | Prettier 格式化规则（`printWidth: 120`） |
| `.prettierignore` | Prettier 排除路径 |
| `.lintstagedrc.json` | lint-staged 配置（TS/TSX → ESLint，MD/JSON/YAML → Prettier） |
| `config.example.yaml` | 配置文件示例（server.listen 布局 + 显式变量引用） |
| `config.schema.json` | 配置文件 JSON Schema（由 bun run schema 生成） |
| `vite.config.ts` | Vite 构建配置（React 插件、代码分割、API proxy） |
| `bunfig.toml` | Bun 配置（测试 preload、排除规则） |
| `opencode.json` | OpenCode 工具配置 |
### 3.8 依赖管理
- **包管理器**：仅使用 `bun`，禁止使用 npm、pnpm、yarn
- **安装依赖**：`bun install`
- **运行工具**：使用 `bunx`，禁止使用 `npx`、`pnpx`
- **锁文件**：`bun.lock`
### 3.9 目录约定
| 目录 | 约定 |
| ------------- | ---------------------------------------------------- |
| `src/server/` | 后端代码，不能 import `src/web/`（HTML import 除外） |
| `src/web/` | 前端代码，不能 import `src/server/` |
| `src/shared/` | 前后端共享类型，双向可引用 |
| `scripts/` | 独立运行脚本，可 import 项目源码 |
| `tests/` | 测试目录，结构镜像 src 目录 |
| `dist/` | 构建产物（gitignore） |
| `openspec/` | OpenSpec 变更管理与规格文档 |
---
## 代码质量
项目使用多层代码质量保障体系：ESLint 类型感知规则 + Perfectionist 导入排序 + Prettier 格式化（通过 eslint-plugin-prettier 集成至 ESLint）+ TypeScript 严格模式 + Git hooks 自动化。
```bash
bun run lint # ESLint 检查（含类型感知规则、导入排序、导入验证、Prettier 格式）
bun run format # Prettier 自动格式化
bun run typecheck # TypeScript 类型检查
bun run schema # 生成 config.schema.json
bun run schema:check # 校验 config.schema.json 是否同步
bun test # 运行所有测试
bun run check # 一键运行 schema:check + typecheck + lint + test
bun run verify # 完整验证（check + build）
```
`check` 是日常开发推荐的质量检查命令。
### ESLint 规则
配置文件：`eslint.config.js`
| 配置来源 | 用途 |
| --------------------------------------------------------------- | -------------------------------------------------- |
| `@eslint/js` recommended | JavaScript 基础规则 |
| `typescript-eslint` recommended-type-checked | TypeScript 类型感知规则（no-floating-promises 等） |
| `typescript-eslint` stylistic-type-checked | TypeScript 风格规则（命名规范、语法选择等） |
| `eslint-plugin-perfectionist` recommended-natural | 导入语句和命名导出自动排序 |
| `eslint-plugin-import` | 导入路径验证、循环依赖检测、重复导入合并 |
| `eslint-plugin-react-hooks` recommended | React Hooks 规则（依赖数组完整性检查等） |
| `eslint-plugin-react-refresh` | React Fast Refresh 兼容性检查 |
| `eslint-plugin-prettier` recommended + `eslint-config-prettier` | 将 Prettier 格式集成为 ESLint 规则，禁用冲突规则 |
**前端导入限制**：`src/web/` 下的文件禁止 `import src/server/` 下的运行时实现，通过 `no-restricted-imports` 规则强制执行。
**后端日志限制**：`src/server/**/*.ts` 下的文件（除 `src/server/logger.ts` 外）禁止直接使用 `console.*`，通过 `no-restricted-syntax` 规则强制执行，确保所有日志统一通过 `Logger` 接口输出。
### Prettier 配置
配置文件：`.prettierrc.json`，通过 `eslint-plugin-prettier` 集成为 ESLint 规则（`lint` 命令同时检查格式），也可通过 `format` 命令独立运行。
显式声明所有格式化参数（`printWidth: 120`、`semi: true`、`singleQuote: false`、`trailingComma: "all"`、`endOfLine: "lf"` 等），确保不同开发环境产出完全一致的格式化结果。
### TypeScript 严格标志
| 标志 | 值 | 说明 |
| ------------------------------------ | ----- | ------------------------------------------------ |
| `strict` | true | 全局严格模式 |
| `noUnusedLocals` | true | 未使用局部变量视为错误 |
| `noUnusedParameters` | false | 保留关闭（路由 handler 统一签名需要） |
| `noPropertyAccessFromIndexSignature` | true | 禁止通过点号访问索引签名属性，强制使用括号语法 |
| `noUncheckedIndexedAccess` | true | 数组/Map 访问必须运行时真值检查 |
| `noImplicitOverride` | true | 子类覆盖父类方法时必须显式使用 `override` 关键字 |
| `verbatimModuleSyntax` | true | 强制 `import type` 纯类型导入，与 Bun 构建兼容 |
### Git Hooks
通过 husky 在 commit 阶段自动执行检查：
| Hook | 行为 |
| ------------ | -------------------------------------------------------------------------------------------------------------- |
| `pre-commit` | lint-staged 对变更文件运行 `eslint --fix`（TS/TSX，含 Prettier 格式修复）或 `prettier --write`（MD/JSON/YAML） |
| `commit-msg` | commitlint 校验提交信息格式 `类型: 简短描述` |
提交类型限定：`feat`、`fix`、`refactor`、`docs`、`style`、`test`、`chore`。
`bun install` 时自动初始化 husky hooks，无需手动配置。
### 质量检查完整清单
提交代码前建议运行：
```bash
bun run verify
```
CI 或正式提交前执行完整验证（类型检查 + lint + 格式 + 测试 + 构建），确保代码可编译并通过所有检查。
---
## 测试
项目采用两层测试体系：单元测试 + 组件测试。所有测试使用 `bun:test` 运行。
### 测试分层
| 层级 | 覆盖范围 | 位置 | 命令 |
| -------- | ---------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| 单元测试 | 后端函数、纯函数、常量 | `tests/server/**/*.test.ts`、`tests/scripts/**/*.test.ts`、`tests/web/{utils,hooks}/**/*.test.ts` | `bun test tests/server`、`bun test tests/web` |
| 组件测试 | React 组件渲染和交互 | `tests/web/components/**/*.test.tsx` | `bun test tests/web` |
### 运行命令
```bash
bun test # 运行所有单元测试和组件测试
bun test tests/server # 只运行后端单元测试
bun test tests/web # 只运行前端测试（单元 + 组件）
bun run check # 日常开发（类型检查 + lint + 测试）
bun run verify # 完整验证（check + 构建）
```
### 组件测试环境
组件测试使用 jsdom 模拟浏览器环境，配置位于 `tests/setup.ts`（通过 `bunfig.toml` preload 加载）：
- jsdom 提供完整的 DOM 环境
- TDesign 组件所需的 polyfill：ResizeObserver、IntersectionObserver、MutationObserver、matchMedia、attachEvent
- 全局 `afterEach` 清理 document.body 内容，确保测试隔离
### 编写规范
- **优先使用 `@testing-library/react`** 的语义化查询（getByText、getByRole）而非 CSS 选择器
- **测试用户行为而非实现细节**：模拟用户点击、输入等操作，而非直接调用组件方法
- **只 mock 系统边界**：mock fetch 返回预设响应，使用真实的 QueryClientProvider 包裹组件
- **组件测试文件命名**：`tests/web/ComponentName.test.tsx`
- **测试目录镜像源码目录**：`tests/server/config.test.ts` 对应 `src/server/config.ts`
---
## 已知限制
- 当前仅为单页面应用，不涉及用户认证和权限控制
- 不支持集群部署，单进程运行
- 配置文件仅支持 YAML 格式，不支持热加载
- 变量替换范围仅限 `server` 子树
- 无国际化和多语言支持

311
README.md
View File

@@ -18,305 +18,26 @@ bun run dev config.yaml
## 使用此模板
### 1. 克隆模板
从零创建新项目：[使用模板](docs/user/usage.md)
```bash
git clone <template-repo-url> my-project
cd my-project
rm -rf .git && git init
```
## 文档导航
### 2. 配置应用信息
| 文档 | 内容 |
| -------------------------------------- | ---------------------------------- |
| [docs/README.md](docs/README.md) | 文档总览、归属矩阵、影响分析规则 |
| [docs/user/](docs/user/) | 模板使用、配置、部署、故障排查 |
| [docs/development/](docs/development/) | 架构、后端、前端、构建发布开发规范 |
| [docs/prompts/](docs/prompts/) | AI 提示词资产（不属于常规文档流） |
编辑 `src/shared/app.ts`，修改应用元信息：
## 常用命令
```typescript
export const APP = {
name: "your-app", // 机器标识（kebab-case）
title: "Your App", // 人类可读标题
subtitle: "你的副标题", // 副标题
description: "应用描述", // SEO meta 描述
} as const;
```
同时修改 `package.json` 的 `name` 字段保持一致，`version` 字段管理应用版本号。
> **注意**：localStorage key 已从 `"my-app.theme.preference"` 变更为 `"theme.preference"`。如果从旧版本升级，用户的主题偏好设置将丢失，需重新选择。
### 3. 准备配置文件
```bash
cp config.example.yaml config.yaml
```
按需编辑 `config.yaml` 中的监听地址、日志、存储路径等配置。
### 4. 清理 OpenSpec 历史
删除模板自带的 OpenSpec 变更历史，保留框架配置：
```bash
rm -rf openspec/specs/*
rm -rf openspec/changes/*
```
> `openspec/config.yaml` 和 `openspec/schemas/fast-drive/` 需要保留，其中包含项目开发规范配置与自定义 OpenSpec workflow schema。
### 5. 安装依赖
```bash
bun install
```
### 6. 开始开发
```bash
bun run dev config.yaml
```
## 项目管理
| 命令 | 说明 |
| ----------------------- | ------------------------------------------------------------------- |
| `bun run dev <config>` | 启动开发模式（并行启动后端 + 前端 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 schema` | 生成 config.schema.json |
| `bun run schema:check` | 校验 config.schema.json 是否同步 |
| `bun run check` | 完整质量检查：schema:check + typecheck + lint + test |
| `bun run verify` | 验证构建流程：check + build |
| `bun run clean` | 清理构建产物和临时文件 |
| `bun run version:patch` | 升迁 patch 版本（x.y.Z） |
| `bun run version:minor` | 升迁 minor 版本（x.Y.0） |
| `bun run version:major` | 升迁 major 版本（X.0.0） |
| `bun run version:set` | 显式设置版本号 |
## 项目结构
```text
.
├── data/ # 运行时数据目录（日志等）
├── config.example.yaml # 配置文件示例（server.listen 布局 + 显式变量引用）
├── config.schema.json # 配置文件 JSON Schema（由 bun run schema 生成）
├── 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，含版本号注入）
│ ├── generate-config-schema.ts # 配置 JSON Schema 生成与同步校验脚本
│ ├── bump-version-logic.ts # 纯版本管理逻辑（parse、validate、bump、format）
│ ├── bump-version.ts # 版本升迁 CLI 脚本
│ └── clean.ts # 清理脚本
├── src/
│ ├── server/ # 后端代码
│ │ ├── bootstrap.ts # 统一启动引导（配置加载 → 服务启动 → 优雅关闭）
│ │ ├── config.ts # CLI 参数解析 + YAML 配置加载 facade
│ │ ├── config/ # 配置解析模块（types、issues、variables、normalizer、schema）
│ │ ├── dev.ts # 开发模式入口
│ │ ├── main.ts # 生产模式入口
│ │ ├── server.ts # HTTP 服务器（Bun.serve routes 声明式路由）
│ │ ├── helpers.ts # 共享响应工具（健康检查、JSON 响应）
│ │ ├── logger.ts # 结构化日志（基于 pino + pino-roll）
│ │ ├── middleware.ts # API 参数校验中间件
│ │ ├── static.ts # 静态资源服务
│ │ └── routes/ # API 路由处理器
│ │ ├── meta.ts # 应用元信息端点（GET /api/meta）
│ │ └── version.ts # 版本号读取
│ ├── shared/
│ │ ├── api.ts # 前后端共享 TypeScript 类型定义
│ │ └── app.ts # 应用全局常量（name、title、subtitle、description）
│ └── web/ # 前端代码
│ ├── index.html # HTML 入口
│ ├── main.tsx # React 入口（BrowserRouter + QueryClient + ErrorBoundary）
│ ├── app.tsx # 根组件（Admin 布局：Header + Sidebar + Content + 版本号展示）
│ ├── routes.tsx # 路由配置
│ ├── styles.css # 全局样式
│ ├── css.d.ts # CSS 模块类型声明
│ ├── pages/ # 页面组件
│ │ ├── dashboard/ # 仪表盘页
│ │ ├── users/ # 用户管理页
│ │ ├── settings/ # 系统设置页
│ │ └── 404/ # 404 页面
│ ├── components/ # UI 组件
│ │ ├── ErrorBoundary.tsx
│ │ └── Sidebar/ # 侧边栏组件
│ ├── hooks/ # React Hooks
│ ├── utils/ # 前端工具函数
│ ├── menu.tsx # 菜单配置
│ └── routes.tsx # 路由配置
├── tests/ # 测试文件（镜像 src 目录结构）
├── openspec/ # OpenSpec 规格、变更与 fast-drive workflow schema
└── docs/ # 项目文档
```
## 配置
项目使用 YAML 配置文件，配置文件为**必传参数**，支持通过 JSON Schema 编辑器提示和显式变量引用。配置中的相对路径均基于配置文件所在目录解析，绝对路径保持不变。
### 配置文件
复制 `config.example.yaml` 为 `config.yaml`（或任意名称），根据需要修改：
```yaml
# yaml-language-server: $schema=./config.schema.json
server:
listen:
host: "${HOST|127.0.0.1}"
port: ${PORT|3000}
storage:
dataDir: ./data
logging:
level: info
console:
level: info
file:
level: info
path: "./logs/${APP.name}.log"
rotation:
size: 50MB
frequency: daily
maxFiles: 14
```
### 配置字段说明
#### server.listen
| 字段 | 类型 | 说明 |
| ---- | ------ | -------------------------- |
| host | string | 监听地址，默认 `127.0.0.1` |
| port | number | 监听端口，默认 `3000` |
#### server.storage
| 字段 | 类型 | 说明 |
| ------- | ------ | --------------------------------------------------------- |
| dataDir | string | 数据目录，默认 `./data`，相对路径基于配置文件所在目录解析 |
#### server.logging
| 字段 | 类型 | 说明 |
| ----- | ------ | ------------------------------------------------------------------------------------ |
| level | string | 全局日志级别（`trace` / `debug` / `info` / `warn` / `error` / `fatal`），默认 `info` |
##### server.logging.console
| 字段 | 类型 | 说明 |
| ----- | ------ | --------------------------------------------------- |
| level | string | 控制台日志级别，未设置时继承 `server.logging.level` |
##### server.logging.file
| 字段 | 类型 | 说明 |
| ----- | ------ | --------------------------------------------------- |
| level | string | 文件日志级别，未设置时继承 `server.logging.level` |
| path | string | 日志文件路径，默认 `<dataDir>/logs/${APP.name}.log` |
##### server.logging.file.rotation
| 字段 | 类型 | 说明 |
| --------- | ------ | ----------------------------------------------------------- |
| size | string | 按大小轮转，支持 `B` / `KB` / `MB` / `GB` 单位，默认 `50MB` |
| frequency | string | 按时间轮转（`hourly` / `daily` / `weekly`），默认 `daily` |
| maxFiles | number | 最大归档文件数，默认 `14` |
### JSON Schema
根目录 `config.schema.json` 为配置文件的 JSON Schema，支持 IDE 自动补全和校验。通过 `# yaml-language-server: $schema=./config.schema.json` 注释启用。
```bash
bun run schema # 重新生成 config.schema.json
bun run schema:check # 校验 schema 是否同步
```
### 变量语法
YAML 配置中支持显式变量引用：
| 语法 | 说明 |
| --------------- | ------------------------------ |
| `${KEY}` | 引用变量，未定义时报错 |
| `${KEY\|value}` | 引用变量，未定义时使用默认值 |
| `${KEY\|}` | 引用变量，未定义时使用空字符串 |
| `$${KEY}` | 转义，输出 `${KEY}` 原文字面量 |
变量解析优先级：`variables 字段` → `process.env` → `默认值` → `unresolved 报错`
完整变量引用（整个值只有 `${...}`）保留原始类型：`${PORT|3000}` 解析为 number `3000`。部分拼接统一转为 string。
### 配置优先级
```
variables 字段 > 环境变量 > 默认值 > unresolved 报错
```
环境变量**不会隐式覆盖**配置，只有通过 `${KEY}` 显式引用时才生效。
### 使用自定义配置
```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 配置文件解析 |
| [@sinclair/typebox](https://github.com/sinclairzx81/typebox) | JSON Schema 类型构建器 |
| [Ajv](https://ajv.js.org/) | JSON Schema 运行时校验 |
| [es-toolkit](https://es-toolkit.slash.page/) | 高性能工具库（推荐优先使用） |
| [pino](https://getpino.io/) | 结构化日志库 |
| [pino-pretty](https://github.com/pinojs/pino-pretty) | 开发环境日志美化输出 |
| [pino-roll](https://github.com/feugy/pino-roll) | 日志文件轮转 |
### 前端
| 技术 | 说明 |
| --------------------------------------------------- | ------------------------ |
| [React 19](https://react.dev/) | UI 组件框架 |
| [React Router](https://reactrouter.com/) | SPA 路由与页面导航 |
| [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 环境模拟 |
| 命令 | 说明 |
| ---------------------- | ------------ |
| `bun run dev <config>` | 启动开发模式 |
| `bun run build` | 生产构建 |
| `bun test` | 运行测试 |
| `bun run check` | 完整质量检查 |
| `bun run verify` | 验证构建流程 |
## 开源协议

115
docs/README.md Normal file
View File

@@ -0,0 +1,115 @@
# my-app 文档
本文档是 my-app 的文档路由入口。AI 工具和开发者应先阅读本文件判断本次任务需要读取和更新哪些专题文档，再按任务类型读取最小必要上下文。
## 目录索引
```text
docs/
README.md
development/
README.md
architecture.md
backend.md
frontend.md
release.md
user/
README.md
usage.md
config.md
deploy.md
troubleshoot.md
prompts/
README.md
prompt-smart-merge.md
prompt-proposal-review.md
prompt-apply-review.md
```
`docs/prompts/` 是提示词资产目录，不属于常规开发流程和用户使用文档。代码、配置或部署变更不需要更新该目录，除非任务明确要求维护提示词资产。
## 入口文档
| 入口 | 定位 |
| --------------------------------- | -------------------------------------- |
| [项目 README](../README.md) | 项目整体介绍、快速开始、文档引导 |
| [开发文档](development/README.md) | 开发入口、全局规则、常用命令、质量门禁 |
| [用户文档](user/README.md) | 模板使用、配置、部署、排障入口 |
## 按任务阅读路径
| 任务 | 必读文档 |
| -------------------------------- | ----------------------------------------------------------------------------------- |
| 修改项目介绍或快速开始 | [项目 README](../README.md)、本文档 |
| 修改开发流程、质量门禁或工程规则 | [开发文档](development/README.md)、本文档、[OpenSpec 配置](../openspec/config.yaml) |
| 修改架构边界或启动流程 | [开发文档](development/README.md)、[架构与边界](development/architecture.md) |
| 修改后端 API、配置加载、日志 | [开发文档](development/README.md)、[后端开发](development/backend.md) |
| 修改前端 | [开发文档](development/README.md)、[前端开发](development/frontend.md) |
| 修改构建、脚本、发布 | [构建与发布](development/release.md)、[部署文档](user/deploy.md) |
| 修改配置 schema | [配置文件](user/config.md)、[后端开发](development/backend.md) |
| 修改文档规则或文档目录结构 | 本文档、[OpenSpec 配置](../openspec/config.yaml) |
| 使用模板创建新项目 | [使用模板](user/usage.md)、[配置文件](user/config.md) |
| 排查运行或构建问题 | [故障排查](user/troubleshoot.md) |
## 文档归属矩阵
| 变更类型 | 默认更新位置 |
| --------------------------------------------------------- | ---------------------------------------- |
| 项目定位、核心能力、快速开始、顶层文档导航 | `README.md` |
| 文档路由、文档更新规则、文档归属矩阵 | `docs/README.md`、`openspec/config.yaml` |
| 开发入口、常用命令、质量门禁、全局工程规则、OpenSpec 约定 | `docs/development/README.md` |
| 架构边界、启动流程、运行时流程、前后端边界 | `docs/development/architecture.md` |
| 后端 API、配置加载、logger、helpers、类型规范、后端测试 | `docs/development/backend.md` |
| 前端技术栈、组件、样式、数据层、前端测试 | `docs/development/frontend.md` |
| 构建、发布、脚本、前后端静态资源集成 | `docs/development/release.md` |
| 使用模板、配置应用信息、清理 OpenSpec 历史 | `docs/user/usage.md` |
| YAML 配置、变量语法、server/storage/logging、JSON Schema | `docs/user/config.md` |
| 生产构建、可执行文件运行、运行时配置 | `docs/user/deploy.md` |
| 常见运行问题、配置校验、变量解析、构建失败 | `docs/user/troubleshoot.md` |
## development 文档如何更新
开发文档解释"如何实现和维护"。代码变更影响开发者理解、开发流程、测试方式或架构边界时，必须更新 `docs/development/` 对应文档。
- 全局规则、常用命令、质量门禁、目录边界、OpenSpec 约定更新到 `docs/development/README.md`。
- 架构图、启动链路、运行时流程、前后端边界更新到 `docs/development/architecture.md`。
- 后端 API、配置加载、logger、helpers、类型规范和后端测试规范更新到 `docs/development/backend.md`。
- 前端技术栈、组件边界、数据流、样式规则和前端测试规范更新到 `docs/development/frontend.md`。
- 构建、脚本和发布验证更新到 `docs/development/release.md`。
- 不新增"杂项"开发文档；优先把内容放入上述最贴近的专题，确需新增专题时先更新本文档和 `openspec/config.yaml`。
## user 文档如何更新
用户文档解释"如何使用"和"用户能观察到什么"。变更影响模板使用方式、配置、部署或运行行为时，必须更新 `docs/user/` 对应文档。
- 使用模板流程、应用信息配置、初始化步骤更新到 `docs/user/usage.md`。
- 配置结构、变量语法、server/storage/logging 字段更新到 `docs/user/config.md`。
- 生产构建、可执行文件运行、运行时依赖更新到 `docs/user/deploy.md`。
- 常见错误和排查路径更新到 `docs/user/troubleshoot.md`。
- 用户文档避免解释内部实现细节，需要实现细节时链接到 `docs/development/`。
## 文档影响分析
每次代码变更都必须执行文档影响分析。
```text
代码或配置变更
-> 用户能感知吗？更新 docs/user/ 或 README.md
-> 开发者需要知道吗？更新 docs/development/
-> 文档规则变化吗？更新 docs/README.md 和 openspec/config.yaml
-> 都不是？收尾说明写明无需更新文档及原因
```
同一事实只在最贴近读者的文档中完整展开，其他文档使用链接引用。根目录 README 保持轻量，不承载完整配置参考或实现教程。
## 收尾说明示例
```text
文档影响分析：本次修改了后端日志配置字段，已更新 docs/development/backend.md 和 docs/user/config.md。
```
无需更新文档时：
```text
文档影响分析：本次仅调整内部测试 helper，未改变用户可见行为、配置、架构边界或开发流程，因此无需更新文档。
```

115
docs/development/README.md Normal file
View File

@@ -0,0 +1,115 @@
# 开发文档
本文档是 my-app 的开发入口。AI 工具和开发者应先阅读 [`../README.md`](../README.md) 判断文档归属，再阅读本文和最小必要专题。
适用场景：修改源码、测试、构建脚本、开发流程、架构边界或项目工程规则。
## 专题索引
| 文档 | 内容 |
| ---------------------------------- | ---------------------------------------------------------------- |
| [architecture.md](architecture.md) | 项目结构、启动流程、运行时流程、HTTP 请求流程、前后端边界 |
| [backend.md](backend.md) | 后端库优先级、API 路由、共享工具、类型规范、配置契约、日志、测试 |
| [frontend.md](frontend.md) | React、TDesign、TanStack Query、组件、样式和前端测试规范 |
| [release.md](release.md) | 开发服务、前后端集成、构建、脚本、环境变量 |
| [../README.md](../README.md) | 文档路由、文档归属矩阵、development/user 文档更新规则 |
## 常用命令
| 命令 | 说明 |
| -------------------------------- | -------------------------------------- |
| `bun install` | 安装依赖 |
| `bun run dev config.yaml` | 启动双进程开发环境 |
| `bun run dev:server config.yaml` | 仅启动后端 API server |
| `bun run dev:web` | 仅启动 Vite dev server |
| `bun run schema` | 生成 config.schema.json |
| `bun run schema:check` | 检查导出 schema 是否同步 |
| `bun run typecheck` | TypeScript 类型检查 |
| `bun run lint` | ESLint 和 Prettier 格式检查 |
| `bun run format` | Prettier 自动格式化 |
| `bun test` | 运行全部测试 |
| `bun run check` | schema:check + typecheck + lint + test |
| `bun run build` | 构建生产可执行文件 |
| `bun run verify` | check + build 完整验证 |
| `bun run clean` | 清理构建缓存与临时文件 |
| `bun run version:patch` | 升迁 patch 版本（x.y.Z） |
| `bun run version:minor` | 升迁 minor 版本（x.Y.0） |
| `bun run version:major` | 升迁 major 版本（X.0.0） |
| `bun run version:set` | 显式设置版本号 |
## 质量门禁
代码变更必须按影响范围执行验证。
| 变更类型 | 必跑命令 |
| -------------------------- | --------------------------------------------------------- |
| 常规代码变更 | `bun run check` |
| 构建、部署、前后端集成变更 | `bun run verify` |
| 配置 schema 变化 | `bun run schema`、`bun run schema:check`、`bun run check` |
| 仅文档变更 | 检查链接、索引和文档归属一致性 |
正式提交或影响构建产物时优先运行 `bun run verify`。如果因环境限制无法执行完整验证，必须在收尾说明中记录未执行项和原因。
## 全局工程规则
- 使用中文编写注释、文档和项目内交流内容。
- 仅使用 bun 作为包管理器，禁止使用 npm、pnpm、yarn。
- 运行工具使用 bunx，禁止使用 npx、pnpx。
- 新增代码优先复用已有组件、工具和依赖库，不引入新依赖；确需新增依赖时先说明原因。
- 后端优先使用 Bun 内置 API，其次是 es-toolkit、标准 Web API、主流三方库，最后才自行实现。
- 前端样式优先使用 TDesign 组件、组件 props、TDesign CSS tokens、styles.css CSS 类，最后才自行开发组件。
- 前端禁止组件内联 style、覆盖 TDesign 内部类名、使用 !important、硬编码色值。
- 当前项目为模板参考项目，不需要考虑向前兼容。
## 包管理、依赖与提交
- 仅使用 bun 安装依赖和运行项目脚本，锁文件为 bun.lock。
- 新增依赖前先确认 Bun 内置 API、es-toolkit、标准 Web API、现有三方库和项目公共工具是否已满足需求。
- Git 提交信息使用中文，格式为"类型: 简短描述"。
- 提交类型限定为 feat、fix、refactor、docs、style、test、chore。
- 多行提交描述时，标题和正文之间空一行。
## 目录边界
| 目录 | 约定 |
| ------------------- | -------------------------------------------------------- |
| `src/server/` | Bun 后端代码，不能 import src/web/，HTML import 集成除外 |
| `src/web/` | React 前端，不能 import src/server/ 运行时实现 |
| `src/shared/` | 前后端共享 TypeScript 类型 |
| `scripts/` | 独立运行脚本，可 import 项目源码 |
| `tests/` | 测试目录，结构镜像 src/ |
| `docs/user/` | 模板使用、配置、部署和排障文档 |
| `docs/development/` | 架构、后端、前端、发布开发文档 |
| `openspec/` | OpenSpec 变更管理与规格文档 |
## 文档影响分析
每次代码变更都必须执行文档影响分析。
| 如果变更影响 | 更新 |
| ------------------------------------------ | ------------------------------------------ |
| 用户可见行为、配置、部署、运行行为 | `docs/user/` 对应文档 |
| 开发流程、架构、测试、构建发布流程 | `docs/development/` 对应文档 |
| 项目定位、快速开始、核心能力列表、文档导航 | `README.md` |
| 文档同步规则或文档归属矩阵 | `docs/README.md` 和 `openspec/config.yaml` |
如果无需更新文档，必须在收尾说明中说明原因。详细规则见 [文档总览](../README.md)。
## OpenSpec 协作规则
- 本项目 OpenSpec 使用 fast-drive schema，变更文档只包含 design.md 和 tasks.md，不创建 proposal.md 或 specs/\*.md。
- design.md 是 scope、requirements、decisions、guardrails、execution direction 和 verification expectations 的 source of truth。
- tasks.md 必须从 design.md 派生，一行一个 checkbox 任务。
- 实现阶段按 tasks.md 顺序执行，完成后立即标记任务状态。
## 事实来源
| 主题 | 事实来源 |
| -------------- | -------------------------------------------------- |
| 代码结构和实现 | `src/`、`scripts/`、`tests/` |
| 配置 schema | TypeBox fragments、config.schema.json、schema 测试 |
| 项目全局规则 | `openspec/config.yaml`、本文档、本目录专题文档 |
## 更新触发条件
修改常用命令、质量门禁、全局工程规则、目录边界、OpenSpec 协作方式或开发文档索引时，必须更新本文档。

92
docs/development/architecture.md Normal file
View File

@@ -0,0 +1,92 @@
# 架构与边界
本文档说明 my-app 的项目结构、启动链路、运行时流程、HTTP 请求流程和前后端边界。
适用场景：修改目录边界、启动流程、运行时调度、HTTP server、前后端集成方式或主要模块职责。
## 项目结构
```text
src/
server/
bootstrap.ts 统一启动引导（loadServerConfig -> startServer）
config.ts CLI 参数解析与配置文件加载 facade
config/ 配置解析模块（types、issues、variables、normalizer、schema）
dev.ts 开发模式启动入口
main.ts 生产模式启动入口
server.ts HTTP server 启动工厂（Bun.serve routes 声明式路由）
static.ts 生产模式静态资源服务
helpers.ts 共享响应格式化工具
middleware.ts API 参数校验中间件
logger.ts 结构化日志（基于 pino + pino-roll）
version.ts 运行时版本号读取
routes/ API 路由处理器
shared/
api.ts 前后端共享 TypeScript 类型定义
app.ts 应用全局常量（name、title、subtitle、description）
web/ React 前端（通过 Vite 构建）
index.html HTML 入口
main.tsx React 入口
app.tsx 根组件
routes.tsx 路由配置
styles.css 全局样式
pages/ 页面组件
components/ UI 组件
hooks/ React Hooks
utils/ 前端工具函数
scripts/ 独立运行脚本
tests/ 测试文件（镜像 src 目录结构）
docs/ 项目文档
openspec/ OpenSpec 规格、变更与 fast-drive workflow schema
```
## 启动流程
```text
dev.ts / main.ts
-> parseRuntimeArgs(cli args)
-> 必须指定 config.yaml
-> bootstrap({ configPath, mode })
-> loadServerConfig(configPath)
-> createRuntimeLogger(config.logging)
-> startServer({ config, logger })
-> logger 记录启动成功
-> SIGINT/SIGTERM -> logger.flush() -> exit
```
## HTTP 请求流程
```text
Request
-> Bun.serve routes 声明式匹配
-> routes/*.ts handler
-> helpers.ts 响应格式化
-> Response
```
生产模式下，非 API 路径由 fetch fallback 处理：有文件扩展名的返回静态资源或 404，无扩展名的返回 SPA index.html。
开发模式下，Vite proxy 将 /api 请求转发到 Bun API server。
## 前后端边界
- 前端只通过 HTTP 调用后端，API 路径为 /api/\*。
- 共享类型放在 src/shared/。
- 前端不得 import src/server/ 的运行时实现。
- 后端不得依赖 src/web/ 运行时代码，HTML import 集成除外。
## 主要模块职责
| 模块 | 职责 |
| ------------------------- | ---------------------------------------- |
| `src/server/bootstrap.ts` | 统一启动引导和 shutdown 编排 |
| `src/server/server.ts` | Bun HTTP server 和 routes 注册 |
| `src/server/routes/` | API handler，按端点拆分 |
| `src/server/config/` | 配置解析模块（types、variables、schema） |
| `src/web/` | React 前端 |
| `src/shared/api.ts` | 前后端共享 API 类型 |
| `src/shared/app.ts` | 应用全局常量 |
## 更新触发条件
修改项目结构、启动流程、HTTP 请求流程、前后端边界或主要模块职责时，必须更新本文档。

101
docs/development/backend.md Normal file
View File

@@ -0,0 +1,101 @@
# 后端开发
本文档说明 my-app 后端的 API、配置加载、日志、版本管理和后端测试开发约定。
适用场景：修改 src/server/、src/shared/api.ts、后端测试、配置契约、API 响应或日志模块。
## 库使用优先级
| 优先级 | 来源 | 典型用途 |
| ------ | ------------ | ---------------------------------------- |
| 1 | Bun 内置 API | Bun.serve、Bun.file、Bun.YAML、Bun.spawn |
| 2 | es-toolkit | 类型判断、深度比较、并发控制 |
| 3 | 标准 Web API | Headers、fetch、AbortController |
| 4 | 主流三方库 | pino、@sinclair/typebox、ajv |
| 5 | 自行实现 | 仅在以上都无法满足时 |
新增依赖前必须先检查上述每一层是否已有可用方案。
## API 路由开发
路由文件位于 src/server/routes/，每个端点一个文件。路由通过 server.ts 的 Bun.serve({ routes }) 声明式注册。
新增路由步骤：
1. 在 src/server/routes/ 下创建 <name>.ts
2. 实现 handler 函数并 export
3. 在 server.ts 的 routes 对象中注册路径和 method handler
4. 在 tests/server/ 中添加对应测试
## 共享工具
helpers.ts 提供跨路由共用的响应工具：
- createApiError(error, status) — 构造 API 错误体
- createHeaders(mode, init) — 创建响应 Headers
- jsonResponse(body, options) — JSON 响应构造
middleware.ts 提供 API 参数校验函数：
- validateIdParam(idStr, mode) — 校验 ID 参数格式
- validatePagination(pageParam, pageSizeParam, mode) — 校验分页参数
- validateTimeRange(from, to, mode) — 校验时间范围参数
## 类型规范
- 共享类型以 src/shared/api.ts 为唯一源头
- 应用常量以 src/shared/app.ts 为唯一源头
- 版本号以 package.json.version 为唯一源头
- 前端不得 import src/server/ 下的任何文件
- 严格联合类型优先于宽类型
## 配置契约
配置加载流程固定为：unknown -> AuthoringConfig -> NormalizedConfig -> ValidatedConfig -> ServerConfig。
Ajv 保持严格拒绝模式：allErrors: true、不启用类型强制转换、不注入默认值、不自动删除未知字段。
新增或修改配置字段时必须同步更新 TypeBox schema fragments、config.schema.json、测试和对应用户文档。
## 日志模块
后端运行时代码统一通过 Logger 接口输出日志，禁止直接使用 console.\*。
| 实现 | 用途 |
| --------------------- | ------------------------ |
| PinoLoggerWrapper | 生产运行时 |
| ConsoleFallbackLogger | 配置加载失败前的降级日志 |
| NoopLogger | 静默丢弃日志 |
| MemoryLogger | 测试替身 |
敏感信息会自动 redact authorization、cookie、password 等字段。
## 版本管理
项目使用 package.json.version 作为版本号唯一来源。
版本获取方式：
- 开发模式：src/server/version.ts 运行时从 package.json 读取
- 生产模式：scripts/build.ts 在构建时将版本号烘焙为字面量注入
版本升迁命令：
```bash
bun run version:patch # 升迁 patch 版本
bun run version:minor # 升迁 minor 版本
bun run version:major # 升迁 major 版本
bun run version:set # 显式设置版本号
```
## 后端测试
| 变更类型 | 测试重点 |
| ------------------ | --------------------------------- |
| API 路由 | tests/server/app.test.ts 集成行为 |
| 配置 schema | schema 导出、合法/非法配置 |
| helpers/middleware | 单元测试 |
## 更新触发条件
修改后端 API、共享类型、配置契约、日志模块、版本管理或后端测试规范时，必须更新本文档。

73
docs/development/frontend.md Normal file
View File

@@ -0,0 +1,73 @@
# 前端开发
本文档说明 my-app 前端的 React、TDesign、TanStack Query、组件、样式和前端测试约定。
适用场景：修改 src/web/、前端共享类型使用方式、组件结构、样式规则或前端测试。
## 技术栈
| 层面 | 技术 | 用途 |
| ------ | --------------------------------------------------- | ------------------------ |
| 框架 | React 19 | UI 组件开发 |
| 构建 | Vite（开发）+ Bun compile（生产） | 开发服务 HMR 与生产构建 |
| 语言 | TypeScript | 类型安全 |
| UI 库 | TDesign React + tdesign-icons-react | UI 组件与图标 |
| 数据层 | TanStack Query (React Query) + React Query Devtools | 服务端状态管理与自动刷新 |
| 路由 | React Router v7 (Declarative mode) | SPA 路由与页面导航 |
不引入额外状态管理库。TanStack Query 承担服务端状态，组件内状态使用 useState。
## 组件开发规范
- 每个 React 组件一个 .tsx 文件，文件名使用 PascalCase
- 组件 props 定义为 interface XxxProps，紧邻组件函数声明
- 类型从 src/shared/api.ts 导入，使用 import type
- 展示组件放在 components/，通过 props 接收数据，通过回调返回事件
- 容器逻辑放在 hooks 中，组件只做数据消费
- 工具函数放在 utils/，保持纯函数无副作用
## 样式开发规范
前端基于 TDesign React 构建 UI，样式开发优先级：
1. TDesign 组件
2. TDesign 组件 props
3. TDesign CSS tokens（--td-\*）
4. styles.css CSS 类
5. 自行开发组件
红线：
- 严禁在组件中使用 style 属性内联调整样式
- 严禁通过 CSS 覆盖 TDesign 组件内部类名
- 严禁使用 !important
- 颜色统一使用 TDesign CSS tokens，不使用硬编码色值
styles.css 组织：
- 自定义 CSS 变量定义在 :root 中
- 布局类定义全局页面结构
- 组件修饰类为自定义视觉组件提供样式变体
- 通用工具类提供公用排版能力
## TanStack Query 规范
- Query key 使用 structured array，使用 as const 保持字面量类型
- 全局面板级查询可持续刷新，详情级查询必须按状态条件启用
## fetch 封装
统一使用 fetch，不引入 axios。错误抛异常，由 TanStack Query 的 error 状态承接。
## 前端测试
- 测试目录为 tests/web/，结构对应 src/web/
- 单元测试重点覆盖 utils/ 和 hooks 中的纯逻辑
- 组件测试使用 jsdom 和 @testing-library/react
- 测试用户行为而非实现细节
- 只 mock 系统边界，使用真实的 QueryClientProvider 包裹组件
- 组件测试环境由 tests/setup.ts 和 bunfig.toml preload 提供
## 更新触发条件
修改前端技术栈、组件边界、数据流、样式规则、测试环境或前端验证方式时，必须更新本文档。

97
docs/development/release.md Normal file
View File

@@ -0,0 +1,97 @@
# 构建与发布
本文档说明开发服务、前后端集成、生产构建、脚本维护和环境变量。
适用场景：修改 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/server-entry.ts
3. Bun compile -> dist/my-app
```
构建参数：
| 环境变量 | 说明 |
| ------------------------- | ---------------- |
| 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 | 显式设置版本号 |
## 项目配置文件
| 文件 | 用途 |
| -------------------- | --------------------------- |
| 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 配置 |
## 验证期望
| 变更类型 | 验证方式 |
| ---------------- | -------------------- |
| 构建脚本 | bun run verify |
| 静态资源集成 | bun run build |
| 配置 schema 同步 | bun run schema:check |
| 发布前完整验证 | bun run verify |
## 更新触发条件
修改开发服务、前后端集成、构建产物、脚本参数或验证方式时，必须更新本文档。

5
docs/prompts/README.md
View File

@@ -7,10 +7,13 @@
| 文件 | 用途 |
| ------------------------------------------------------ | ------------------------------------------------------------------------- |
| [prompt-smart-merge.md](prompt-smart-merge.md) | 批量合并 `dev*` 分支到目标分支，含规则探测、依赖分析、冲突处理、安全回退 |
| [prompt-spec-review.md](prompt-spec-review.md) | 审查和整理 `openspec/specs/` 下的稳定规范，提升可检索性和一致性 |
| [prompt-proposal-review.md](prompt-proposal-review.md) | 审查 fast-drive design/tasks 与讨论、实际状态、OpenSpec workflow 的一致性 |
| [prompt-apply-review.md](prompt-apply-review.md) | 审查 apply 后实际产物、验证、design/tasks 的一致性，并补齐遗漏或回写文档 |
## 边界说明
本目录为 AI 大模型执行型提示词资产，不属于常规用户文档或开发文档流。文档影响分析不覆盖本目录内容。
## 设计目标
从现有提示词提炼出的共同目标：

31
docs/user/README.md Normal file
View File

@@ -0,0 +1,31 @@
# 用户文档
本文档是 my-app 的用户使用入口，说明如何使用模板、配置、部署和排查问题。
适用场景：使用本模板创建新项目、编写配置、生产部署、排查运行问题。
## 文档索引
| 文档 | 内容 |
| ---------------------------------- | ------------------------------------------- |
| [usage.md](usage.md) | 克隆模板、配置应用信息、准备配置、开始开发 |
| [config.md](config.md) | YAML 结构、变量语法、server/storage/logging |
| [deploy.md](deploy.md) | 生产构建、可执行文件运行、运行时配置 |
| [troubleshoot.md](troubleshoot.md) | 常见问题：配置校验、变量解析、构建失败 |
## 按任务阅读
| 任务 | 建议阅读 |
| -------- | -------------------------------------------------------------- |
| 首次使用 | [项目快速开始](../../README.md#快速开始)、[使用模板](usage.md) |
| 编写配置 | [配置文件](config.md) |
| 生产部署 | [部署](deploy.md)、[故障排查](troubleshoot.md) |
| 排查问题 | [故障排查](troubleshoot.md) |
## 用户文档更新规则
- 使用模板流程、应用信息配置、初始化步骤变化时，更新 [usage.md](usage.md)。
- 配置结构、变量语法、server/storage/logging 字段变化时，更新 [config.md](config.md)。
- 生产构建、可执行文件运行、运行时依赖变化时，更新 [deploy.md](deploy.md)。
- 常见错误、配置校验、构建失败排查方式变化时，更新 [troubleshoot.md](troubleshoot.md)。
- 用户文档只解释"如何使用"和"用户能观察到什么"，实现细节放入 [`../development/`](../development/README.md)。

106
docs/user/config.md Normal file
View File

@@ -0,0 +1,106 @@
# 配置文件
项目使用 YAML 配置文件，配置文件为启动时的必传参数，支持通过 JSON Schema 编辑器提示和显式变量引用。配置中的相对路径均基于配置文件所在目录解析，绝对路径保持不变。
## 配置文件
复制 config.example.yaml 为 config.yaml（或任意名称），根据需要修改：
```yaml
# yaml-language-server: $schema=./config.schema.json
server:
listen:
host: "127.0.0.1"
port: 3000
storage:
dataDir: ./data
logging:
level: info
console:
level: info
file:
level: info
path: "./logs/my-app.log"
rotation:
size: 50MB
frequency: daily
maxFiles: 14
```
## server.listen
| 字段 | 类型 | 说明 |
| ---- | ------ | ------------------------ |
| host | string | 监听地址，默认 127.0.0.1 |
| port | number | 监听端口，默认 3000 |
## server.storage
| 字段 | 类型 | 说明 |
| ------- | ------ | --------------------------------------------------- |
| dataDir | string | 数据目录，默认 ./data，相对路径基于配置文件目录解析 |
## server.logging
| 字段 | 类型 | 说明 |
| ----- | ------ | ------------------------------------------------------------ |
| level | string | 全局日志级别（trace/debug/info/warn/error/fatal），默认 info |
### server.logging.console
| 字段 | 类型 | 说明 |
| ----- | ------ | ------------------------------------------------- |
| level | string | 控制台日志级别，未设置时继承 server.logging.level |
### server.logging.file
| 字段 | 类型 | 说明 |
| ----- | ------ | ----------------------------------------------- |
| level | string | 文件日志级别，未设置时继承 server.logging.level |
| path | string | 日志文件路径，默认 <dataDir>/logs/my-app.log |
### server.logging.file.rotation
| 字段 | 类型 | 说明 |
| --------- | ------ | --------------------------------------------- |
| size | string | 按大小轮转，支持 B/KB/MB/GB 单位，默认 50MB |
| frequency | string | 按时间轮转（hourly/daily/weekly），默认 daily |
| maxFiles | number | 最大归档文件数，默认 14 |
## JSON Schema
根目录 config.schema.json 为配置文件的 JSON Schema，支持 IDE 自动补全和校验。
```bash
bun run schema # 重新生成 config.schema.json
bun run schema:check # 校验 config.schema.json 是否同步
```
## 变量语法
YAML 配置中支持显式变量引用：
```text
${KEY} 引用变量，未定义时报错
${KEY|value} 引用变量，未定义时使用默认值
${KEY|} 引用变量，未定义时使用空字符串
$${KEY} 转义，输出 ${KEY} 原文字面量
```
变量解析优先级：variables 字段 > process.env > 默认值 > unresolved 报错
完整变量引用（整个值只有 ${...}）保留原始类型：${PORT|3000} 解析为 number 3000。部分拼接统一转为 string。
## 配置优先级
```
variables 字段 > 环境变量 > 默认值 > unresolved 报错
```
环境变量不会隐式覆盖配置，只有通过 ${KEY} 显式引用时才生效。
## 使用自定义配置
```bash
bun run dev custom-config.yaml
```

54
docs/user/deploy.md Normal file
View File

@@ -0,0 +1,54 @@
# 生产部署
本文档说明如何构建和运行生产环境的应用。
## 生产构建和运行
```bash
bun run build
./dist/my-app config.yaml
```
启动后：
| 地址 | 行为 |
| ------------------------------ | ------------------- |
| http://127.0.0.1:3000/ | 返回前端 SPA |
| http://127.0.0.1:3000/api/meta | 返回应用元信息 JSON |
| http://127.0.0.1:3000/health | 返回健康检查 |
## 构建流程
scripts/build.ts 执行三步流水线：
```text
1. Vite build -> dist/web/（前端静态资源，含 code splitting）
2. Code generation -> .build/static-assets.ts + .build/server-entry.ts（含版本号字面量注入）
3. Bun compile -> dist/my-app（单可执行文件）
```
- Vite 构建前端资源到 dist/web/，自动 code splitting（vendor-react、vendor-tdesign、vendor-chart）
- Code generation 扫描 dist/web/ 生成 import with { type: "file" } 声明，将资源嵌入 binary
- Bun compile 以 .build/server-entry.ts 为入口编译最终可执行文件
- .build/ 临时目录在构建完成后自动清理
## 产物
| 产物 | 用途 |
| ----------- | ---------------------------------------- |
| dist/my-app | 生产可执行文件（含前端资源，单文件部署） |
| dist/web/ | Vite 构建的前端资源（构建中间产物） |
## 构建参数
| 环境变量 | 说明 |
| ------------------------- | ------------------------------------ |
| BUN_TARGET / BUILD_TARGET | 交叉编译目标平台（如 bun-linux-x64） |
## 清理
```bash
bun run clean
```
清理 dist/ 构建产物和 .build/ 临时文件。

61
docs/user/troubleshoot.md Normal file
View File

@@ -0,0 +1,61 @@
# 故障排查
本文档记录使用模板时的常见问题和排查入口。
## 配置校验失败
启动时会校验 YAML 配置。未知字段会导致启动失败。
排查顺序：
1. 在 YAML 顶部添加 `# yaml-language-server: $schema=./config.schema.json`。
2. 对照 [配置文件](config.md) 检查配置结构。
3. 运行 `bun run schema:check` 确认 JSON Schema 是否同步。
## 变量无法解析
变量解析优先级为 variables 字段 > process.env > 默认值。如果三者均不存在，配置校验会失败。
常见修复：
```text
环境变量未设置 设置环境变量或在 variables 中声明
希望允许空值 使用 ${KEY|}
希望提供默认值 使用 ${KEY|default}
希望输出字面量 使用 $${KEY}
```
## 端口被占用
修改 config.yaml 中的 server.listen.port 字段为可用端口。
## Schema 不同步
config.schema.json 与 TypeBox 定义不一致时会导致校验行为异常。
```bash
bun run schema # 重新生成 config.schema.json
bun run schema:check # 校验是否同步
```
## 构建失败
先运行完整质量检查定位问题：
```bash
bun run check # schema:check + typecheck + lint + test
```
如果 check 通过但仍构建失败：
```bash
bun run verify # check + build 完整验证
```
检查 TypeScript 类型错误和构建脚本输出，确保所有依赖已安装（`bun install`）。
## 前端页面空白
- 确认后端 API server 已启动
- 开发模式下确认 Vite dev server 代理配置正确
- 生产模式下确认前端静态资源已正确嵌入可执行文件

65
docs/user/usage.md Normal file
View File

@@ -0,0 +1,65 @@
# 使用模板
本文档说明如何使用本模板创建新项目。
## 1. 克隆模板
```bash
git clone <template-repo-url> my-project
cd my-project
rm -rf .git && git init
```
## 2. 配置应用信息
编辑 `src/shared/app.ts`，修改应用元信息：
```typescript
export const APP = {
name: "your-app", // 机器标识（kebab-case）
title: "Your App", // 人类可读标题
subtitle: "你的副标题", // 副标题
description: "应用描述", // SEO meta 描述
} as const;
```
同时修改 `package.json` 的 `name` 字段保持一致，`version` 字段管理应用版本号。
## 3. 准备配置文件
```bash
cp config.example.yaml config.yaml
```
按需编辑 `config.yaml` 中的监听地址、日志、存储路径等配置。配置文件为启动时的必传参数。
## 4. 清理 OpenSpec 历史
删除模板自带的 OpenSpec 变更历史，保留框架配置：
```bash
rm -rf openspec/specs/*
rm -rf openspec/changes/*
```
`openspec/config.yaml` 和 `openspec/schemas/fast-drive/` 需要保留，其中包含项目开发规范配置与自定义 OpenSpec workflow schema。
## 5. 安装依赖
```bash
bun install
```
## 6. 开始开发
```bash
bun run dev config.yaml
```
访问 http://127.0.0.1:5173 查看应用。
## 下一步
- [配置文件](config.md) — 了解 YAML 结构、变量语法和配置字段
- [部署文档](deploy.md) — 生产构建和运行方式
- [开发文档](../development/README.md) — 开发规范、架构和质量门禁

17
openspec/config.yaml
View File

@@ -3,8 +3,15 @@ schema: fast-drive
context: |
- 使用中文（注释、文档、交流），面向中文开发者
- openspec文档的关键字按openspec规范使用，不要翻译为中文
- **优先阅读README.md和DEVELOPMENT.md**获取项目概览与开发规范，所有代码风格、命名、注解、依赖、API等规范以DEVELOPMENT.md为准
- 涉及模块结构、API、实体等变更时同步更新README.md
- **优先阅读 docs/README.md** 获取文档路由、归属矩阵和影响分析规则
- **其次阅读 docs/development/README.md** 获取开发规范、常用命令、质量门禁和全局规则
- 文档文件名优先使用单个英文单词（usage.md、config.md、deploy.md、troubleshoot.md），目录上下文足以消歧时不在文件名重复限定词
- 每次代码变更必须执行文档影响分析：
- 用户可见行为、配置、部署、运行行为变更 → 更新 docs/user/ 对应文档
- 开发流程、架构、测试、构建发布流程变更 → 更新 docs/development/ 对应文档
- 项目定位、快速开始、核心能力列表、文档导航变更 → 更新 README.md
- 文档同步规则或文档归属矩阵变更 → 更新 docs/README.md 和本文件
- 无需更新文档时必须在收尾说明中说明原因
- 新增代码优先复用已有组件、工具、依赖库，不引入新依赖
- 新增的逻辑必须编写完善的测试，并保证测试的正确性，不允许跳过任何测试
- 这是基于bun实现的前端后一体化项目，使用bun作为唯一包管理器，严禁使用pnpm、npm，使用bunx运行工具，严禁使用npx、pnpx
@@ -17,16 +24,14 @@ context: |
- 禁止创建git操作task
- 积极使用subagents精心设计并行任务，节省上下文空间，加速任务执行
- 优先使用提问工具对用户进行提问
- 本项目为 Bun 全栈应用模板，README.md记录模板使用方法，DEVELOPMENT.md记录模板使用的技术细节
- 本项目为 Bun 全栈应用模板，docs/user/ 记录模板使用方法，docs/development/ 记录模板开发技术细节
- 本项目为模板参考项目，帮助其他项目快速启动项目，因此开发本项目无需考虑兼容性问题
rules:
explore:
- 本项目openspec使用fast-drive自定义schema，变更文档只包含design.md和tasks.md，无proposal.md和specs
design:
- 先前的讨论技术方案要尽可能体现在设计文档中，便于指导实现阶段不偏离已定的技术路线
tasks:
- 一行一个任务，严禁任务内容跨行
- 如果是代码存在更新必须
- 执行完整的测试、代码检查、格式检查等质量保障手段
- 更新 README.md 和/或 DEVELOPMENT.md
- 执行文档影响分析，更新 README.md 和/或 docs/ 下对应文档