feat: 初始提交

2026-05-26 18:19:42 +08:00
commit 7ebf5ee5dc
107 changed files with 9317 additions and 0 deletions
--- a/docs/user/README.md
+++ b/docs/user/README.md
@@ -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)。
--- a/docs/user/config.md
+++ b/docs/user/config.md
@@ -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
+```
--- a/docs/user/deploy.md
+++ b/docs/user/deploy.md
@@ -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/ 临时文件。
--- a/docs/user/troubleshoot.md
+++ b/docs/user/troubleshoot.md
@@ -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 代理配置正确
+- 生产模式下确认前端静态资源已正确嵌入可执行文件
--- a/docs/user/usage.md
+++ b/docs/user/usage.md
@@ -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) — 开发规范、架构和质量门禁