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

建立 docs/user/ 和 docs/development/ 分层文档结构： - docs/README.md 文档总路由、归属矩阵、影响分析规则 - docs/user/ 模板使用、配置、部署、故障排查 - docs/development/ 架构、后端、前端、构建发布开发规范 - README.md 轻量化为项目入口和索引 - 删除 DEVELOPMENT.md，内容拆分至专题文档 - 更新 openspec/config.yaml 首读入口和文档影响分析规则 - 修正 docs/prompts/README.md 过时引用和边界说明
2026-05-25 19:09:08 +08:00
parent 0d08c914de
commit 763d814543
15 changed files with 941 additions and 1159 deletions
--- a/docs/development/architecture.md
+++ b/docs/development/architecture.md
@@ -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 请求流程、前后端边界或主要模块职责时，必须更新本文档。