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

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 |
## 更新触发条件
修改开发服务、前后端集成、构建产物、脚本参数或验证方式时，必须更新本文档。