Compare commits
9 Commits
4caf502908
...
master
| Author | SHA1 | Date | |
|---|---|---|---|
| c030ee35d9 | |||
| 763d814543 | |||
| 0d08c914de | |||
| 60d50afad1 | |||
| c592f2b97c | |||
| 13d1fea5fb | |||
| 7dc3a270ae | |||
| bc54f8352a | |||
| 1e3269380e |
3
.gitignore
vendored
3
.gitignore
vendored
@@ -403,6 +403,9 @@ cython_debug/
|
||||
!.claude/settings.json
|
||||
.opencode
|
||||
.codex
|
||||
.pi/*
|
||||
!.pi/mcp.json
|
||||
!.pi/extensions
|
||||
openspec/changes/archive
|
||||
temp
|
||||
.agents
|
||||
|
||||
16
.pi/extensions/pi-permission-system/config.json
Normal file
16
.pi/extensions/pi-permission-system/config.json
Normal file
@@ -0,0 +1,16 @@
|
||||
{
|
||||
"$schema": "https://raw.githubusercontent.com/gotgenes/pi-permission-system/main/schemas/permissions.schema.json",
|
||||
"permission": {
|
||||
"*": "allow",
|
||||
"bash": {
|
||||
"npm *": "deny",
|
||||
"npx *": "deny",
|
||||
"pnpm *": "deny",
|
||||
"pnpx *": "deny"
|
||||
},
|
||||
"external_directory": {
|
||||
"*": "ask",
|
||||
"/tmp/*": "allow"
|
||||
}
|
||||
}
|
||||
}
|
||||
8
.pi/mcp.json
Normal file
8
.pi/mcp.json
Normal file
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"mcpServers": {
|
||||
"tdesign-mcp-server": {
|
||||
"command": "bunx",
|
||||
"args": ["tdesign-mcp-server@latest"]
|
||||
}
|
||||
}
|
||||
}
|
||||
709
DEVELOPMENT.md
709
DEVELOPMENT.md
@@ -1,709 +0,0 @@
|
||||
my-app 开发文档
|
||||
|
||||
本文档面向 `my-app` 项目的开发者，介绍项目结构、前后端架构、构建流程、测试、代码规范等内容。
|
||||
|
||||
用户使用说明请参阅 [README.md](README.md)。
|
||||
|
||||
## 目录
|
||||
|
||||
- [项目结构](#项目结构)
|
||||
- [前后端边界](#前后端边界)
|
||||
- [一、后端开发指引](#一后端开发指引)
|
||||
- [二、前端开发指引](#二前端开发指引)
|
||||
- [三、项目运行、集成与打包](#三项目运行集成与打包)
|
||||
- [代码质量](#代码质量)
|
||||
- [测试](#测试)
|
||||
- [已知限制](#已知限制)
|
||||
|
||||
---
|
||||
|
||||
## 项目结构
|
||||
|
||||
```text
|
||||
src/
|
||||
server/
|
||||
bootstrap.ts 后端统一启动引导（loadServerConfig → startServer）
|
||||
config.ts CLI 参数解析与配置文件加载（可选 YAML configPath，支持 --help/-h）
|
||||
dev.ts 开发模式启动入口（mode: "development"）
|
||||
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（按端点拆分）
|
||||
health.ts GET /health
|
||||
shared/
|
||||
api.ts 前后端共享 TypeScript 类型
|
||||
app.ts 应用全局常量（name、title、subtitle、description、version）
|
||||
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 仪表盘页（欢迎语 + /health 联调示例）
|
||||
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 三步构建流水线
|
||||
clean.ts 清理构建产物与临时文件
|
||||
tests/ Bun test 测试（结构镜像 src 目录）
|
||||
setup.ts 全局测试配置（jsdom、polyfill）
|
||||
helpers.ts 测试辅助工具（rmRetry）
|
||||
server/ 后端测试
|
||||
bootstrap.test.ts
|
||||
config.test.ts
|
||||
middleware.test.ts
|
||||
static.test.ts
|
||||
web/ 前端测试
|
||||
App.test.tsx
|
||||
test-utils.tsx
|
||||
openspec/ OpenSpec 变更与规格文档
|
||||
config.example.yaml 配置文件示例
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 前后端边界
|
||||
|
||||
前端只通过 HTTP 调用后端，API 路径为 `/api/*` 和 `/health`。共享类型放在 `src/shared`，前端不得 `import src/server` 的运行时实现。
|
||||
|
||||
---
|
||||
|
||||
## 一、后端开发指引
|
||||
|
||||
### 1.1 架构概览
|
||||
|
||||
```
|
||||
启动流程:
|
||||
dev.ts / main.ts → parseRuntimeArgs(cli args)
|
||||
→ bootstrap({ configPath, mode })
|
||||
→ loadServerConfig(configPath)：可选 YAML 解析 → ServerConfig{ host, port }
|
||||
→ startServer({ config, mode })：Bun.serve routes 声明式路由 + fetch fallback
|
||||
→ 注册 SIGINT/SIGTERM shutdown
|
||||
|
||||
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 }),
|
||||
"/health": {
|
||||
GET: () => handleHealth(mode),
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Handler 函数签名：
|
||||
|
||||
```typescript
|
||||
// 无依赖的路由
|
||||
export function handleHealth(mode: RuntimeMode): 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`）
|
||||
- `createHealthResponse()` — 构造健康检查响应 `{ ok: true, service, timestamp }`
|
||||
- `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)` — 辅助函数
|
||||
|
||||
### 1.5 类型定义规范
|
||||
|
||||
- **共享类型**以 `src/shared/api.ts` 为唯一源头，前后端共同引用
|
||||
- **应用常量**以 `src/shared/app.ts` 为唯一源头，定义 `APP` 对象（name、title、subtitle、description、version），前后端及构建脚本共同引用
|
||||
- 前端不得 `import src/server/` 下的任何文件
|
||||
- **严格联合类型**优先于宽类型：如 `RuntimeMode: "development" | "production" | "test"` 而非 `RuntimeMode: string`
|
||||
- API 响应类型（`ApiErrorResponse`、`HealthResponse`）定义在 shared 中
|
||||
|
||||
### 1.6 配置文件规范
|
||||
|
||||
配置加载流程：
|
||||
|
||||
```
|
||||
CLI argv → parseRuntimeArgs → { configPath? }
|
||||
→ loadServerConfig(configPath)
|
||||
→ 可选 YAML 文件解析 → env 覆盖 → 默认值
|
||||
→ ServerConfig{ host, port }
|
||||
```
|
||||
|
||||
`ServerConfig` 包含以下字段：
|
||||
|
||||
| 字段 | 来源 | 默认值 |
|
||||
| ------ | ------------------------------------------------- | ----------- |
|
||||
| `host` | `process.env["HOST"]` → YAML `server.host` → 默认 | `127.0.0.1` |
|
||||
| `port` | `process.env["PORT"]` → YAML `server.port` → 默认 | `3000` |
|
||||
|
||||
配置文件示例（`config.example.yaml`）：
|
||||
|
||||
```yaml
|
||||
server:
|
||||
host: "127.0.0.1"
|
||||
port: 3000
|
||||
```
|
||||
|
||||
### 1.7 错误模式
|
||||
|
||||
- **API 错误**：`{ error: "描述", status: <code> }`，状态码 400/404
|
||||
- **日志**：非致命异常用 `console.warn`，启动失败用 `console.error` + `process.exit(1)`
|
||||
|
||||
---
|
||||
|
||||
## 二、前端开发指引
|
||||
|
||||
### 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（欢迎语 + /health 联调）
|
||||
│ │ ├── /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 = {
|
||||
health: () => ["health"] as const,
|
||||
};
|
||||
```
|
||||
|
||||
- Key 使用 **structured array**（非字符串），以便精确匹配和按 prefix 失效
|
||||
- 使用 `as const` 保持字面量类型
|
||||
|
||||
#### 查询配置规范
|
||||
|
||||
```typescript
|
||||
// 全局级查询（需要持续刷新）
|
||||
useQuery({
|
||||
queryKey: queryKeys.health(),
|
||||
queryFn: () => fetchJson<HealthResponse>("/health"),
|
||||
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 { HealthResponse } 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` 和 `/health` 请求代理到后端。
|
||||
|
||||
也可以单独启动：
|
||||
|
||||
```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/*` 和 `/health` 转发到 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/*": () => ...,
|
||||
"/health": { GET: () => handleHealth(mode) },
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
#### 路由优先级
|
||||
|
||||
Bun routes 的匹配规则：具体路径 > 通配符。`/health` 优先于 `/*`。
|
||||
|
||||
未匹配 method 的请求（如 POST /health）会落入 `/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/dial-server (单可执行文件)
|
||||
```
|
||||
|
||||
- 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/dial-server` | 生产可执行文件（含前端资源，单文件部署） |
|
||||
| `dist/web/` | Vite 构建的前端资源（构建中间产物） |
|
||||
|
||||
#### 构建参数
|
||||
|
||||
| 环境变量 | 说明 |
|
||||
| --------------------------- | -------------------------------------- |
|
||||
| `BUN_TARGET`/`BUILD_TARGET` | 交叉编译目标平台（如 `bun-linux-x64`） |
|
||||
|
||||
#### 运行可执行文件
|
||||
|
||||
```bash
|
||||
./dist/dial-server [config.yaml]
|
||||
```
|
||||
|
||||
启动后：
|
||||
|
||||
- 访问 `http://127.0.0.1:3000/` → 返回前端 SPA
|
||||
- 访问 `http://127.0.0.1:3000/api/*` → 返回后端 API
|
||||
- 访问 `http://127.0.0.1:3000/health` → 返回健康检查 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` | 清理构建缓存与临时文件 |
|
||||
|
||||
### 3.6 环境变量
|
||||
|
||||
| 变量 | 用途 | 默认值 |
|
||||
| --------------------------- | ----------------------------------------------- | ----------- |
|
||||
| `BUN_TARGET`/`BUILD_TARGET` | 交叉编译目标平台（仅在 `bun run build` 时有效） | 当前平台 |
|
||||
| `HOST` | 服务监听地址 | `127.0.0.1` |
|
||||
| `PORT` | 服务监听端口 | `3000` |
|
||||
|
||||
### 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` | 配置文件示例 |
|
||||
| `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 test # 运行所有测试
|
||||
bun run 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` 规则强制执行。
|
||||
|
||||
### 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/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 格式，不支持热加载
|
||||
- 无国际化和多语言支持
|
||||
212
README.md
212
README.md
@@ -9,211 +9,35 @@ Bun 全栈应用模板，基于 Bun + React + TDesign 的前后端一体化开
|
||||
```bash
|
||||
git clone <your-repo-url> my-project
|
||||
cd my-project
|
||||
cp config.example.yaml config.yaml
|
||||
bun install
|
||||
bun run dev
|
||||
bun run dev config.yaml
|
||||
```
|
||||
|
||||
访问 http://127.0.0.1:5173 查看应用。
|
||||
|
||||
## 使用此模板
|
||||
|
||||
### 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 描述
|
||||
version: "0.1.0", // 版本号
|
||||
} as const;
|
||||
```
|
||||
|
||||
同时修改 `package.json` 的 `name` 字段保持一致。
|
||||
|
||||
> **注意**：localStorage key 已从 `"my-app.theme.preference"` 变更为 `"theme.preference"`。如果从旧版本升级，用户的主题偏好设置将丢失，需重新选择。
|
||||
|
||||
### 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 类型定义
|
||||
│ │ └── app.ts # 应用全局常量（name、title、version 等）
|
||||
│ └── 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 规格与变更管理
|
||||
└── 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 组件框架 |
|
||||
| [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` | 验证构建流程 |
|
||||
|
||||
## 开源协议
|
||||
|
||||
|
||||
77
bun.lock
77
bun.lock
@@ -5,8 +5,13 @@
|
||||
"": {
|
||||
"name": "gateway-checker",
|
||||
"dependencies": {
|
||||
"@sinclair/typebox": "^0.34.49",
|
||||
"@tanstack/react-query": "^5.100.10",
|
||||
"ajv": "^8.20.0",
|
||||
"es-toolkit": "^1.46.1",
|
||||
"pino": "^10.3.1",
|
||||
"pino-pretty": "^13.1.3",
|
||||
"pino-roll": "^4.0.0",
|
||||
"react": "^19.2.6",
|
||||
"react-dom": "^19.2.6",
|
||||
"react-router": "^7.15.1",
|
||||
@@ -184,6 +189,8 @@
|
||||
|
||||
"@oxc-project/types": ["@oxc-project/types@0.130.0", "https://registry.npmmirror.com/@oxc-project/types/-/types-0.130.0.tgz", {}, "sha512-ibD2usx9JRu7f5pu2tMKMI4cpA4NgXJQoYRP4pQ7Pxmn1l6k/53qWtQWZayhYy3X4QZkt90Ot+mJEaeXouio6Q=="],
|
||||
|
||||
"@pinojs/redact": ["@pinojs/redact@0.4.0", "https://registry.npmmirror.com/@pinojs/redact/-/redact-0.4.0.tgz", {}, "sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg=="],
|
||||
|
||||
"@pkgr/core": ["@pkgr/core@0.2.9", "https://registry.npmmirror.com/@pkgr/core/-/core-0.2.9.tgz", {}, "sha512-QNqXyfVS2wm9hweSYD2O7F0G06uurj9kZ96TRQE5Y9hU7+tgdZwIkbAKc5Ocy1HxEY2kuDQa6cQ1WRs/O5LFKA=="],
|
||||
|
||||
"@popperjs/core": ["@popperjs/core@2.11.8", "https://registry.npmmirror.com/@popperjs/core/-/core-2.11.8.tgz", {}, "sha512-P1st0aksCrn9sGZhp8GMYwBnQsbvAWsZAX44oXNNvLHGqAOcoVxmjZiohstwQ7SqKnbR47akdNi+uleWD8+g6A=="],
|
||||
@@ -228,6 +235,8 @@
|
||||
|
||||
"@simple-libs/stream-utils": ["@simple-libs/stream-utils@1.2.0", "https://registry.npmmirror.com/@simple-libs/stream-utils/-/stream-utils-1.2.0.tgz", {}, "sha512-KxXvfapcixpz6rVEB6HPjOUZT22yN6v0vI0urQSk1L8MlEWPDFCZkhw2xmkyoTGYeFw7tWTZd7e3lVzRZRN/EA=="],
|
||||
|
||||
"@sinclair/typebox": ["@sinclair/typebox@0.34.49", "https://registry.npmmirror.com/@sinclair/typebox/-/typebox-0.34.49.tgz", {}, "sha512-brySQQs7Jtn0joV8Xh9ZV/hZb9Ozb0pmazDIASBkYKCjXrXU3mpcFahmK/z4YDhGkQvP9mWJbVyahdtU5wQA+A=="],
|
||||
|
||||
"@standard-schema/spec": ["@standard-schema/spec@1.1.0", "https://registry.npmmirror.com/@standard-schema/spec/-/spec-1.1.0.tgz", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="],
|
||||
|
||||
"@standard-schema/utils": ["@standard-schema/utils@0.3.0", "https://registry.npmmirror.com/@standard-schema/utils/-/utils-0.3.0.tgz", {}, "sha512-e7Mew686owMaPJVNNLs55PUvgz371nKgwsc4vxE49zsODpJEnxgxRo2y/OKrqueavXgZNMDVj3DdHFlaSAeU8g=="],
|
||||
@@ -356,7 +365,7 @@
|
||||
|
||||
"acorn-jsx": ["acorn-jsx@5.3.2", "https://registry.npmmirror.com/acorn-jsx/-/acorn-jsx-5.3.2.tgz", { "peerDependencies": { "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0" } }, "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ=="],
|
||||
|
||||
"ajv": ["ajv@6.15.0", "https://registry.npmmirror.com/ajv/-/ajv-6.15.0.tgz", { "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", "json-schema-traverse": "^0.4.1", "uri-js": "^4.2.2" } }, "sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw=="],
|
||||
"ajv": ["ajv@8.20.0", "https://registry.npmmirror.com/ajv/-/ajv-8.20.0.tgz", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA=="],
|
||||
|
||||
"ansi-escapes": ["ansi-escapes@7.3.0", "https://registry.npmmirror.com/ansi-escapes/-/ansi-escapes-7.3.0.tgz", { "dependencies": { "environment": "^1.0.0" } }, "sha512-BvU8nYgGQBxcmMuEeUEmNTvrMVjJNSH7RgW24vXexN4Ven6qCvy4TntnvlnwnMLTVlcRQQdbRY8NKnaIoeWDNg=="],
|
||||
|
||||
@@ -384,6 +393,8 @@
|
||||
|
||||
"async-function": ["async-function@1.0.0", "https://registry.npmmirror.com/async-function/-/async-function-1.0.0.tgz", {}, "sha512-hsU18Ae8CDTR6Kgu9DYf0EbCr/a5iGL0rytQDobUcdpYOKokk8LEjVphnXkDkgpi0wYVsqrXuP0bZxJaTqdgoA=="],
|
||||
|
||||
"atomic-sleep": ["atomic-sleep@1.0.0", "https://registry.npmmirror.com/atomic-sleep/-/atomic-sleep-1.0.0.tgz", {}, "sha512-kNOjDqAh7px0XWNI+4QbzoiR/nTkHAWNud2uvnJquD1/x5a7EQZMJT0AczqK0Qn67oY/TTQ1LbUKajZpp3I9tQ=="],
|
||||
|
||||
"available-typed-arrays": ["available-typed-arrays@1.0.7", "https://registry.npmmirror.com/available-typed-arrays/-/available-typed-arrays-1.0.7.tgz", { "dependencies": { "possible-typed-array-names": "^1.0.0" } }, "sha512-wvUjBtSGN7+7SjNpq/9M2Tg350UZD3q62IFZLbRAR1bSMlCo1ZaeW+BJ+D090e4hIIZLBcTDWe4Mh4jvUDajzQ=="],
|
||||
|
||||
"balanced-match": ["balanced-match@4.0.4", "https://registry.npmmirror.com/balanced-match/-/balanced-match-4.0.4.tgz", {}, "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA=="],
|
||||
@@ -418,6 +429,8 @@
|
||||
|
||||
"clsx": ["clsx@2.1.1", "https://registry.npmmirror.com/clsx/-/clsx-2.1.1.tgz", {}, "sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA=="],
|
||||
|
||||
"colorette": ["colorette@2.0.20", "https://registry.npmmirror.com/colorette/-/colorette-2.0.20.tgz", {}, "sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w=="],
|
||||
|
||||
"compare-func": ["compare-func@2.0.0", "https://registry.npmmirror.com/compare-func/-/compare-func-2.0.0.tgz", { "dependencies": { "array-ify": "^1.0.0", "dot-prop": "^5.1.0" } }, "sha512-zHig5N+tPWARooBnb0Zx1MFcdfpyJrfTJ3Y5L+IFvUm8rM74hHz66z0gw0x4tijh5CorKkKUCnW82R2vmpeCRA=="],
|
||||
|
||||
"concat-map": ["concat-map@0.0.1", "https://registry.npmmirror.com/concat-map/-/concat-map-0.0.1.tgz", {}, "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg=="],
|
||||
@@ -472,6 +485,10 @@
|
||||
|
||||
"data-view-byte-offset": ["data-view-byte-offset@1.0.1", "https://registry.npmmirror.com/data-view-byte-offset/-/data-view-byte-offset-1.0.1.tgz", { "dependencies": { "call-bound": "^1.0.2", "es-errors": "^1.3.0", "is-data-view": "^1.0.1" } }, "sha512-BS8PfmtDGnrgYdOonGZQdLZslWIeCGFP9tpan0hi1Co2Zr2NKADsvGYA8XxuG/4UWgJ6Cjtv+YJnB6MM69QGlQ=="],
|
||||
|
||||
"date-fns": ["date-fns@4.3.0", "https://registry.npmmirror.com/date-fns/-/date-fns-4.3.0.tgz", {}, "sha512-OYcL+3N/jyWbYdFGqoMAhytDgxP9pbYPUUiRCOgn4Fewaadk9l/Wam4Avciiyp2BgkpfQyBV9B+ehnVJych+eQ=="],
|
||||
|
||||
"dateformat": ["dateformat@4.6.3", "https://registry.npmmirror.com/dateformat/-/dateformat-4.6.3.tgz", {}, "sha512-2P0p0pFGzHS5EMnhdxQi7aJN+iMheud0UhG4dlE1DLAlvL8JHjJJTX/CSm4JXwV0Ka5nGk3zC5mcb5bUQUxxMA=="],
|
||||
|
||||
"dayjs": ["dayjs@1.11.10", "https://registry.npmmirror.com/dayjs/-/dayjs-1.11.10.tgz", {}, "sha512-vjAczensTgRcqDERK0SR2XMwsF/tSvnvlv6VcF2GIhg6Sx4yOIt/irsr1RDJsKiIyBzJDpCoXiWWq28MqH2cnQ=="],
|
||||
|
||||
"debug": ["debug@4.4.3", "https://registry.npmmirror.com/debug/-/debug-4.4.3.tgz", { "dependencies": { "ms": "^2.1.3" } }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],
|
||||
@@ -504,6 +521,8 @@
|
||||
|
||||
"emoji-regex": ["emoji-regex@10.6.0", "https://registry.npmmirror.com/emoji-regex/-/emoji-regex-10.6.0.tgz", {}, "sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A=="],
|
||||
|
||||
"end-of-stream": ["end-of-stream@1.4.5", "https://registry.npmmirror.com/end-of-stream/-/end-of-stream-1.4.5.tgz", { "dependencies": { "once": "^1.4.0" } }, "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg=="],
|
||||
|
||||
"entities": ["entities@8.0.0", "https://registry.npmmirror.com/entities/-/entities-8.0.0.tgz", {}, "sha512-zwfzJecQ/Uej6tusMqwAqU/6KL2XaB2VZ2Jg54Je6ahNBGNH6Ek6g3jjNCF0fG9EWQKGZNddNjU5F1ZQn/sBnA=="],
|
||||
|
||||
"env-paths": ["env-paths@2.2.1", "https://registry.npmmirror.com/env-paths/-/env-paths-2.2.1.tgz", {}, "sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A=="],
|
||||
@@ -570,6 +589,8 @@
|
||||
|
||||
"eventemitter3": ["eventemitter3@5.0.4", "https://registry.npmmirror.com/eventemitter3/-/eventemitter3-5.0.4.tgz", {}, "sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw=="],
|
||||
|
||||
"fast-copy": ["fast-copy@4.0.3", "https://registry.npmmirror.com/fast-copy/-/fast-copy-4.0.3.tgz", {}, "sha512-58apWr0GUiDFM8+3afrO6eYwJBn9ZAhDOzG3L+/9llab/haCARS2UIfffmOurYLwbgDRs8n0rfr6qAAPEAuAQw=="],
|
||||
|
||||
"fast-deep-equal": ["fast-deep-equal@3.1.3", "https://registry.npmmirror.com/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", {}, "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q=="],
|
||||
|
||||
"fast-diff": ["fast-diff@1.3.0", "https://registry.npmmirror.com/fast-diff/-/fast-diff-1.3.0.tgz", {}, "sha512-VxPP4NqbUjj6MaAOafWeUn2cXWLcCtljklUtZf0Ind4XQ+QPtmA0b18zZy0jIQx+ExRVCR/ZQpBmik5lXshNsw=="],
|
||||
@@ -578,6 +599,8 @@
|
||||
|
||||
"fast-levenshtein": ["fast-levenshtein@2.0.6", "https://registry.npmmirror.com/fast-levenshtein/-/fast-levenshtein-2.0.6.tgz", {}, "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw=="],
|
||||
|
||||
"fast-safe-stringify": ["fast-safe-stringify@2.1.1", "https://registry.npmmirror.com/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz", {}, "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA=="],
|
||||
|
||||
"fast-uri": ["fast-uri@3.1.2", "https://registry.npmmirror.com/fast-uri/-/fast-uri-3.1.2.tgz", {}, "sha512-rVjf7ArG3LTk+FS6Yw81V1DLuZl1bRbNrev6Tmd/9RaroeeRRJhAt7jg/6YFxbvAQXUCavSoZhPPj6oOx+5KjQ=="],
|
||||
|
||||
"fdir": ["fdir@6.5.0", "https://registry.npmmirror.com/fdir/-/fdir-6.5.0.tgz", { "peerDependencies": { "picomatch": "^3 || ^4" }, "optionalPeers": ["picomatch"] }, "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg=="],
|
||||
@@ -638,6 +661,8 @@
|
||||
|
||||
"hasown": ["hasown@2.0.3", "https://registry.npmmirror.com/hasown/-/hasown-2.0.3.tgz", { "dependencies": { "function-bind": "^1.1.2" } }, "sha512-ej4AhfhfL2Q2zpMmLo7U1Uv9+PyhIZpgQLGT1F9miIGmiCJIoCgSmczFdrc97mWT4kVY72KA+WnnhJ5pghSvSg=="],
|
||||
|
||||
"help-me": ["help-me@5.0.0", "https://registry.npmmirror.com/help-me/-/help-me-5.0.0.tgz", {}, "sha512-7xgomUX6ADmcYzFik0HzAxh/73YlKR9bmFzf51CZwR+b6YtzU2m0u49hQCqV6SvlqIqsaxovfwdvbnsw3b/zpg=="],
|
||||
|
||||
"hermes-estree": ["hermes-estree@0.25.1", "https://registry.npmmirror.com/hermes-estree/-/hermes-estree-0.25.1.tgz", {}, "sha512-0wUoCcLp+5Ev5pDW2OriHC2MJCbwLwuRx+gAqMTOkGKJJiBCLjtrvy4PWUGn6MIVefecRpzoOZ/UV6iGdOr+Cw=="],
|
||||
|
||||
"hermes-parser": ["hermes-parser@0.25.1", "https://registry.npmmirror.com/hermes-parser/-/hermes-parser-0.25.1.tgz", { "dependencies": { "hermes-estree": "0.25.1" } }, "sha512-6pEjquH3rqaI6cYAXYPcz9MS4rY6R4ngRgrgfDshRptUZIc3lw0MCIJIGDj9++mfySOuPTHB4nrSW99BCvOPIA=="],
|
||||
@@ -728,6 +753,8 @@
|
||||
|
||||
"jiti": ["jiti@2.6.1", "https://registry.npmmirror.com/jiti/-/jiti-2.6.1.tgz", { "bin": { "jiti": "lib/jiti-cli.mjs" } }, "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ=="],
|
||||
|
||||
"joycon": ["joycon@3.1.1", "https://registry.npmmirror.com/joycon/-/joycon-3.1.1.tgz", {}, "sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw=="],
|
||||
|
||||
"js-tokens": ["js-tokens@4.0.0", "https://registry.npmmirror.com/js-tokens/-/js-tokens-4.0.0.tgz", {}, "sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ=="],
|
||||
|
||||
"js-yaml": ["js-yaml@4.1.1", "https://registry.npmmirror.com/js-yaml/-/js-yaml-4.1.1.tgz", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA=="],
|
||||
@@ -740,7 +767,7 @@
|
||||
|
||||
"json-parse-even-better-errors": ["json-parse-even-better-errors@2.3.1", "https://registry.npmmirror.com/json-parse-even-better-errors/-/json-parse-even-better-errors-2.3.1.tgz", {}, "sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w=="],
|
||||
|
||||
"json-schema-traverse": ["json-schema-traverse@0.4.1", "https://registry.npmmirror.com/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz", {}, "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg=="],
|
||||
"json-schema-traverse": ["json-schema-traverse@1.0.0", "https://registry.npmmirror.com/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
|
||||
|
||||
"json-stable-stringify-without-jsonify": ["json-stable-stringify-without-jsonify@1.0.1", "https://registry.npmmirror.com/json-stable-stringify-without-jsonify/-/json-stable-stringify-without-jsonify-1.0.1.tgz", {}, "sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw=="],
|
||||
|
||||
@@ -836,6 +863,10 @@
|
||||
|
||||
"object.values": ["object.values@1.2.1", "https://registry.npmmirror.com/object.values/-/object.values-1.2.1.tgz", { "dependencies": { "call-bind": "^1.0.8", "call-bound": "^1.0.3", "define-properties": "^1.2.1", "es-object-atoms": "^1.0.0" } }, "sha512-gXah6aZrcUxjWg2zR2MwouP2eHlCBzdV4pygudehaKXSGW4v2AsRQUK+lwwXhii6KFZcunEnmSUoYp5CXibxtA=="],
|
||||
|
||||
"on-exit-leak-free": ["on-exit-leak-free@2.1.2", "https://registry.npmmirror.com/on-exit-leak-free/-/on-exit-leak-free-2.1.2.tgz", {}, "sha512-0eJJY6hXLGf1udHwfNftBqH+g73EU4B504nZeKpz1sYRKafAghwxEJunB2O7rDZkL4PGfsMVnTXZ2EjibbqcsA=="],
|
||||
|
||||
"once": ["once@1.4.0", "https://registry.npmmirror.com/once/-/once-1.4.0.tgz", { "dependencies": { "wrappy": "1" } }, "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w=="],
|
||||
|
||||
"onetime": ["onetime@7.0.0", "https://registry.npmmirror.com/onetime/-/onetime-7.0.0.tgz", { "dependencies": { "mimic-function": "^5.0.0" } }, "sha512-VXJjc87FScF88uafS3JllDgvAm+c/Slfz06lorj2uAY34rlUu0Nt+v8wreiImcrgAjjIHp1rXpTDlLOGw29WwQ=="],
|
||||
|
||||
"optionator": ["optionator@0.9.4", "https://registry.npmmirror.com/optionator/-/optionator-0.9.4.tgz", { "dependencies": { "deep-is": "^0.1.3", "fast-levenshtein": "^2.0.6", "levn": "^0.4.1", "prelude-ls": "^1.2.1", "type-check": "^0.4.0", "word-wrap": "^1.2.5" } }, "sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g=="],
|
||||
@@ -864,6 +895,16 @@
|
||||
|
||||
"picomatch": ["picomatch@4.0.4", "https://registry.npmmirror.com/picomatch/-/picomatch-4.0.4.tgz", {}, "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A=="],
|
||||
|
||||
"pino": ["pino@10.3.1", "https://registry.npmmirror.com/pino/-/pino-10.3.1.tgz", { "dependencies": { "@pinojs/redact": "^0.4.0", "atomic-sleep": "^1.0.0", "on-exit-leak-free": "^2.1.0", "pino-abstract-transport": "^3.0.0", "pino-std-serializers": "^7.0.0", "process-warning": "^5.0.0", "quick-format-unescaped": "^4.0.3", "real-require": "^0.2.0", "safe-stable-stringify": "^2.3.1", "sonic-boom": "^4.0.1", "thread-stream": "^4.0.0" }, "bin": { "pino": "bin.js" } }, "sha512-r34yH/GlQpKZbU1BvFFqOjhISRo1MNx1tWYsYvmj6KIRHSPMT2+yHOEb1SG6NMvRoHRF0a07kCOox/9yakl1vg=="],
|
||||
|
||||
"pino-abstract-transport": ["pino-abstract-transport@3.0.0", "https://registry.npmmirror.com/pino-abstract-transport/-/pino-abstract-transport-3.0.0.tgz", { "dependencies": { "split2": "^4.0.0" } }, "sha512-wlfUczU+n7Hy/Ha5j9a/gZNy7We5+cXp8YL+X+PG8S0KXxw7n/JXA3c46Y0zQznIJ83URJiwy7Lh56WLokNuxg=="],
|
||||
|
||||
"pino-pretty": ["pino-pretty@13.1.3", "https://registry.npmmirror.com/pino-pretty/-/pino-pretty-13.1.3.tgz", { "dependencies": { "colorette": "^2.0.7", "dateformat": "^4.6.3", "fast-copy": "^4.0.0", "fast-safe-stringify": "^2.1.1", "help-me": "^5.0.0", "joycon": "^3.1.1", "minimist": "^1.2.6", "on-exit-leak-free": "^2.1.0", "pino-abstract-transport": "^3.0.0", "pump": "^3.0.0", "secure-json-parse": "^4.0.0", "sonic-boom": "^4.0.1", "strip-json-comments": "^5.0.2" }, "bin": { "pino-pretty": "bin.js" } }, "sha512-ttXRkkOz6WWC95KeY9+xxWL6AtImwbyMHrL1mSwqwW9u+vLp/WIElvHvCSDg0xO/Dzrggz1zv3rN5ovTRVowKg=="],
|
||||
|
||||
"pino-roll": ["pino-roll@4.0.0", "https://registry.npmmirror.com/pino-roll/-/pino-roll-4.0.0.tgz", { "dependencies": { "date-fns": "^4.1.0", "sonic-boom": "^4.0.1" } }, "sha512-axI1aQaIxXdw1F4OFFli1EDxIrdYNGLowkw/ZoZogX8oCSLHUghzwVVXUS8U+xD/Savwa5IXpiXmsSGKFX/7Sg=="],
|
||||
|
||||
"pino-std-serializers": ["pino-std-serializers@7.1.0", "https://registry.npmmirror.com/pino-std-serializers/-/pino-std-serializers-7.1.0.tgz", {}, "sha512-BndPH67/JxGExRgiX1dX0w1FvZck5Wa4aal9198SrRhZjH3GxKQUKIBnYJTdj2HDN3UQAS06HlfcSbQj2OHmaw=="],
|
||||
|
||||
"possible-typed-array-names": ["possible-typed-array-names@1.1.0", "https://registry.npmmirror.com/possible-typed-array-names/-/possible-typed-array-names-1.1.0.tgz", {}, "sha512-/+5VFTchJDoVj3bhoqi6UeymcD00DAwb1nJwamzPvHEszJ4FpF6SNNbUbOS8yI56qHzdV8eK0qEfOSiodkTdxg=="],
|
||||
|
||||
"postcss": ["postcss@8.5.14", "https://registry.npmmirror.com/postcss/-/postcss-8.5.14.tgz", { "dependencies": { "nanoid": "^3.3.11", "picocolors": "^1.1.1", "source-map-js": "^1.2.1" } }, "sha512-SoSL4+OSEtR99LHFZQiJLkT59C5B1amGO1NzTwj7TT1qCUgUO6hxOvzkOYxD+vMrXBM3XJIKzokoERdqQq/Zmg=="],
|
||||
@@ -876,10 +917,16 @@
|
||||
|
||||
"pretty-format": ["pretty-format@27.5.1", "https://registry.npmmirror.com/pretty-format/-/pretty-format-27.5.1.tgz", { "dependencies": { "ansi-regex": "^5.0.1", "ansi-styles": "^5.0.0", "react-is": "^17.0.1" } }, "sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ=="],
|
||||
|
||||
"process-warning": ["process-warning@5.0.0", "https://registry.npmmirror.com/process-warning/-/process-warning-5.0.0.tgz", {}, "sha512-a39t9ApHNx2L4+HBnQKqxxHNs1r7KF+Intd8Q/g1bUh6q0WIp9voPXJ/x0j+ZL45KF1pJd9+q2jLIRMfvEshkA=="],
|
||||
|
||||
"prop-types": ["prop-types@15.8.1", "https://registry.npmmirror.com/prop-types/-/prop-types-15.8.1.tgz", { "dependencies": { "loose-envify": "^1.4.0", "object-assign": "^4.1.1", "react-is": "^16.13.1" } }, "sha512-oj87CgZICdulUohogVAR7AjlC0327U4el4L6eAvOqCeudMDVU0NThNaV+b9Df4dXgSP1gXMTnPdhfe/2qDH5cg=="],
|
||||
|
||||
"pump": ["pump@3.0.4", "https://registry.npmmirror.com/pump/-/pump-3.0.4.tgz", { "dependencies": { "end-of-stream": "^1.1.0", "once": "^1.3.1" } }, "sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA=="],
|
||||
|
||||
"punycode": ["punycode@2.3.1", "https://registry.npmmirror.com/punycode/-/punycode-2.3.1.tgz", {}, "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg=="],
|
||||
|
||||
"quick-format-unescaped": ["quick-format-unescaped@4.0.4", "https://registry.npmmirror.com/quick-format-unescaped/-/quick-format-unescaped-4.0.4.tgz", {}, "sha512-tYC1Q1hgyRuHgloV/YXs2w15unPVh8qfu/qCTfhTYamaw7fyhumKa2yGpdSo87vY32rIclj+4fWYQXUMs9EHvg=="],
|
||||
|
||||
"raf": ["raf@3.4.1", "https://registry.npmmirror.com/raf/-/raf-3.4.1.tgz", { "dependencies": { "performance-now": "^2.1.0" } }, "sha512-Sq4CW4QhwOHE8ucn6J34MqtZCeWFP2aQSmrlroYgqAV1PjStIhJXxYuTgUIfkEk7zTLjmIjLmU5q+fbD1NnOJA=="],
|
||||
|
||||
"react": ["react@19.2.6", "https://registry.npmmirror.com/react/-/react-19.2.6.tgz", {}, "sha512-sfWGGfavi0xr8Pg0sVsyHMAOziVYKgPLNrS7ig+ivMNb3wbCBw3KxtflsGBAwD3gYQlE/AEZsTLgToRrSCjb0Q=="],
|
||||
@@ -896,6 +943,8 @@
|
||||
|
||||
"react-transition-group": ["react-transition-group@4.4.5", "https://registry.npmmirror.com/react-transition-group/-/react-transition-group-4.4.5.tgz", { "dependencies": { "@babel/runtime": "^7.5.5", "dom-helpers": "^5.0.1", "loose-envify": "^1.4.0", "prop-types": "^15.6.2" }, "peerDependencies": { "react": ">=16.6.0", "react-dom": ">=16.6.0" } }, "sha512-pZcd1MCJoiKiBR2NRxeCRg13uCXbydPnmB4EOeRrY7480qNWO8IIgQG6zlDkm6uRMsURXPuKq0GWtiM59a5Q6g=="],
|
||||
|
||||
"real-require": ["real-require@0.2.0", "https://registry.npmmirror.com/real-require/-/real-require-0.2.0.tgz", {}, "sha512-57frrGM/OCTLqLOAh0mhVA9VBMHd+9U7Zb2THMGdBUoZVOtGbJzjxsYGDJ3A9AYYCP4hn6y1TVbaOfzWtm5GFg=="],
|
||||
|
||||
"recharts": ["recharts@3.8.1", "https://registry.npmmirror.com/recharts/-/recharts-3.8.1.tgz", { "dependencies": { "@reduxjs/toolkit": "^1.9.0 || 2.x.x", "clsx": "^2.1.1", "decimal.js-light": "^2.5.1", "es-toolkit": "^1.39.3", "eventemitter3": "^5.0.1", "immer": "^10.1.1", "react-redux": "8.x.x || 9.x.x", "reselect": "5.1.1", "tiny-invariant": "^1.3.3", "use-sync-external-store": "^1.2.2", "victory-vendor": "^37.0.2" }, "peerDependencies": { "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-dom": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", "react-is": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" } }, "sha512-mwzmO1s9sFL0TduUpwndxCUNoXsBw3u3E/0+A+cLcrSfQitSG62L32N69GhqUrrT5qKcAE3pCGVINC6pqkBBQg=="],
|
||||
|
||||
"redux": ["redux@5.0.1", "https://registry.npmmirror.com/redux/-/redux-5.0.1.tgz", {}, "sha512-M9/ELqF6fy8FwmkpnF0S3YKOqMyoWJ4+CS5Efg2ct3oY9daQvd/Pc71FpGZsVsbl3Cpb+IIcjBDUnnyBdQbq4w=="],
|
||||
@@ -930,10 +979,14 @@
|
||||
|
||||
"safe-regex-test": ["safe-regex-test@1.1.0", "https://registry.npmmirror.com/safe-regex-test/-/safe-regex-test-1.1.0.tgz", { "dependencies": { "call-bound": "^1.0.2", "es-errors": "^1.3.0", "is-regex": "^1.2.1" } }, "sha512-x/+Cz4YrimQxQccJf5mKEbIa1NzeCRNI5Ecl/ekmlYaampdNLPalVyIcCZNNH3MvmqBugV5TMYZXv0ljslUlaw=="],
|
||||
|
||||
"safe-stable-stringify": ["safe-stable-stringify@2.5.0", "https://registry.npmmirror.com/safe-stable-stringify/-/safe-stable-stringify-2.5.0.tgz", {}, "sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA=="],
|
||||
|
||||
"saxes": ["saxes@6.0.0", "https://registry.npmmirror.com/saxes/-/saxes-6.0.0.tgz", { "dependencies": { "xmlchars": "^2.2.0" } }, "sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA=="],
|
||||
|
||||
"scheduler": ["scheduler@0.27.0", "https://registry.npmmirror.com/scheduler/-/scheduler-0.27.0.tgz", {}, "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q=="],
|
||||
|
||||
"secure-json-parse": ["secure-json-parse@4.1.0", "https://registry.npmmirror.com/secure-json-parse/-/secure-json-parse-4.1.0.tgz", {}, "sha512-l4KnYfEyqYJxDwlNVyRfO2E4NTHfMKAWdUuA8J0yve2Dz/E/PdBepY03RvyJpssIpRFwJoCD55wA+mEDs6ByWA=="],
|
||||
|
||||
"semver": ["semver@6.3.1", "https://registry.npmmirror.com/semver/-/semver-6.3.1.tgz", { "bin": { "semver": "bin/semver.js" } }, "sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA=="],
|
||||
|
||||
"set-cookie-parser": ["set-cookie-parser@2.7.2", "https://registry.npmmirror.com/set-cookie-parser/-/set-cookie-parser-2.7.2.tgz", {}, "sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw=="],
|
||||
@@ -960,10 +1013,14 @@
|
||||
|
||||
"slice-ansi": ["slice-ansi@8.0.0", "https://registry.npmmirror.com/slice-ansi/-/slice-ansi-8.0.0.tgz", { "dependencies": { "ansi-styles": "^6.2.3", "is-fullwidth-code-point": "^5.1.0" } }, "sha512-stxByr12oeeOyY2BlviTNQlYV5xOj47GirPr4yA1hE9JCtxfQN0+tVbkxwCtYDQWhEKWFHsEK48ORg5jrouCAg=="],
|
||||
|
||||
"sonic-boom": ["sonic-boom@4.2.1", "https://registry.npmmirror.com/sonic-boom/-/sonic-boom-4.2.1.tgz", { "dependencies": { "atomic-sleep": "^1.0.0" } }, "sha512-w6AxtubXa2wTXAUsZMMWERrsIRAdrK0Sc+FUytWvYAhBJLyuI4llrMIC1DtlNSdI99EI86KZum2MMq3EAZlF9Q=="],
|
||||
|
||||
"sortablejs": ["sortablejs@1.15.7", "https://registry.npmmirror.com/sortablejs/-/sortablejs-1.15.7.tgz", {}, "sha512-Kk8wLQPlS+yi1ZEf48a4+fzHa4yxjC30M/Sr2AnQu+f/MPwvvX9XjZ6OWejiz8crBsLwSq8GHqaxaET7u6ux0A=="],
|
||||
|
||||
"source-map-js": ["source-map-js@1.2.1", "https://registry.npmmirror.com/source-map-js/-/source-map-js-1.2.1.tgz", {}, "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA=="],
|
||||
|
||||
"split2": ["split2@4.2.0", "https://registry.npmmirror.com/split2/-/split2-4.2.0.tgz", {}, "sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg=="],
|
||||
|
||||
"stable-hash-x": ["stable-hash-x@0.2.0", "https://registry.npmmirror.com/stable-hash-x/-/stable-hash-x-0.2.0.tgz", {}, "sha512-o3yWv49B/o4QZk5ZcsALc6t0+eCelPc44zZsLtCQnZPDwFpDYSWcDnrv2TtMmMbQ7uKo3J0HTURCqckw23czNQ=="],
|
||||
|
||||
"stop-iteration-iterator": ["stop-iteration-iterator@1.1.0", "https://registry.npmmirror.com/stop-iteration-iterator/-/stop-iteration-iterator-1.1.0.tgz", { "dependencies": { "es-errors": "^1.3.0", "internal-slot": "^1.1.0" } }, "sha512-eLoXW/DHyl62zxY4SCaIgnRhuMr6ri4juEYARS8E6sCEqzKpOiE521Ucofdx+KnDZl5xmvGYaaKCk5FEOxJCoQ=="],
|
||||
@@ -982,6 +1039,8 @@
|
||||
|
||||
"strip-bom": ["strip-bom@3.0.0", "https://registry.npmmirror.com/strip-bom/-/strip-bom-3.0.0.tgz", {}, "sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA=="],
|
||||
|
||||
"strip-json-comments": ["strip-json-comments@5.0.3", "https://registry.npmmirror.com/strip-json-comments/-/strip-json-comments-5.0.3.tgz", {}, "sha512-1tB5mhVo7U+ETBKNf92xT4hrQa3pm0MZ0PQvuDnWgAAGHDsfp4lPSpiS6psrSiet87wyGPh9ft6wmhOMQ0hDiw=="],
|
||||
|
||||
"supports-preserve-symlinks-flag": ["supports-preserve-symlinks-flag@1.0.0", "https://registry.npmmirror.com/supports-preserve-symlinks-flag/-/supports-preserve-symlinks-flag-1.0.0.tgz", {}, "sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w=="],
|
||||
|
||||
"symbol-tree": ["symbol-tree@3.2.4", "https://registry.npmmirror.com/symbol-tree/-/symbol-tree-3.2.4.tgz", {}, "sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw=="],
|
||||
@@ -992,6 +1051,8 @@
|
||||
|
||||
"tdesign-react": ["tdesign-react@1.16.9", "https://registry.npmmirror.com/tdesign-react/-/tdesign-react-1.16.9.tgz", { "dependencies": { "@babel/runtime": "~7.26.7", "@popperjs/core": "~2.11.2", "@types/sortablejs": "^1.10.7", "@types/validator": "^13.1.3", "classnames": "~2.5.1", "dayjs": "1.11.10", "hoist-non-react-statics": "~3.3.2", "lodash-es": "^4.17.21", "mitt": "^3.0.0", "raf": "~3.4.1", "react-fast-compare": "^3.2.2", "react-is": "^18.2.0", "react-transition-group": "~4.4.1", "sortablejs": "^1.15.0", "tdesign-icons-react": "^0.6.4", "tslib": "~2.3.1", "validator": "~13.15.0" }, "peerDependencies": { "react": ">=16.13.1", "react-dom": ">=16.13.1" } }, "sha512-C3uZRTkJ1iQ62BrMkuvqvBK+4HEuhl82rABxa6kAHGHL3eBI4DPfzAJGF0T3b+DKCBeJxb0x10elumT6NkQEaw=="],
|
||||
|
||||
"thread-stream": ["thread-stream@4.2.0", "https://registry.npmmirror.com/thread-stream/-/thread-stream-4.2.0.tgz", { "dependencies": { "real-require": "^1.0.0" } }, "sha512-e2zZ96wSChazBsbENf/Pcm/4swHt2cEKQ92rhUjkL9GCKiTDJIaTBenjE/m9DXi0QBmTMDkFDdOomUy20A1tDQ=="],
|
||||
|
||||
"tiny-invariant": ["tiny-invariant@1.3.3", "https://registry.npmmirror.com/tiny-invariant/-/tiny-invariant-1.3.3.tgz", {}, "sha512-+FbBPE1o9QAYvviau/qC5SE3caw21q3xkvWKBtja5vgqOWIHHJ3ioaq1VPfn/Szqctz2bU/oYeKd9/z5BL+PVg=="],
|
||||
|
||||
"tinyexec": ["tinyexec@1.1.2", "https://registry.npmmirror.com/tinyexec/-/tinyexec-1.1.2.tgz", {}, "sha512-dAqSqE/RabpBKI8+h26GfLq6Vb3JVXs30XYQjdMjaj/c2tS8IYYMbIzP599KtRj7c57/wYApb3QjgRgXmrCukA=="],
|
||||
@@ -1068,6 +1129,8 @@
|
||||
|
||||
"wrap-ansi": ["wrap-ansi@10.0.0", "https://registry.npmmirror.com/wrap-ansi/-/wrap-ansi-10.0.0.tgz", { "dependencies": { "ansi-styles": "^6.2.3", "string-width": "^8.2.0", "strip-ansi": "^7.1.2" } }, "sha512-SGcvg80f0wUy2/fXES19feHMz8E0JoXv2uNgHOu4Dgi2OrCy1lqwFYEJz1BLbDI0exjPMe/ZdzZ/YpGECBG/aQ=="],
|
||||
|
||||
"wrappy": ["wrappy@1.0.2", "https://registry.npmmirror.com/wrappy/-/wrappy-1.0.2.tgz", {}, "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="],
|
||||
|
||||
"xml-name-validator": ["xml-name-validator@5.0.0", "https://registry.npmmirror.com/xml-name-validator/-/xml-name-validator-5.0.0.tgz", {}, "sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg=="],
|
||||
|
||||
"xmlchars": ["xmlchars@2.2.0", "https://registry.npmmirror.com/xmlchars/-/xmlchars-2.2.0.tgz", {}, "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw=="],
|
||||
@@ -1092,8 +1155,6 @@
|
||||
|
||||
"@babel/helper-compilation-targets/lru-cache": ["lru-cache@5.1.1", "https://registry.npmmirror.com/lru-cache/-/lru-cache-5.1.1.tgz", { "dependencies": { "yallist": "^3.0.2" } }, "sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w=="],
|
||||
|
||||
"@commitlint/config-validator/ajv": ["ajv@8.20.0", "https://registry.npmmirror.com/ajv/-/ajv-8.20.0.tgz", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA=="],
|
||||
|
||||
"@commitlint/is-ignored/semver": ["semver@7.8.0", "https://registry.npmmirror.com/semver/-/semver-7.8.0.tgz", { "bin": { "semver": "bin/semver.js" } }, "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA=="],
|
||||
|
||||
"@conventional-changelog/git-client/semver": ["semver@7.8.0", "https://registry.npmmirror.com/semver/-/semver-7.8.0.tgz", { "bin": { "semver": "bin/semver.js" } }, "sha512-AcM7dV/5ul4EekoQ29Agm5vri8JNqRyj39o0qpX6vDF2GZrtutZl5RwgD1XnZjiTAfncsJhMI48QQH3sN87YNA=="],
|
||||
@@ -1144,6 +1205,8 @@
|
||||
|
||||
"cliui/wrap-ansi": ["wrap-ansi@9.0.2", "https://registry.npmmirror.com/wrap-ansi/-/wrap-ansi-9.0.2.tgz", { "dependencies": { "ansi-styles": "^6.2.1", "string-width": "^7.0.0", "strip-ansi": "^7.1.0" } }, "sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww=="],
|
||||
|
||||
"eslint/ajv": ["ajv@6.15.0", "https://registry.npmmirror.com/ajv/-/ajv-6.15.0.tgz", { "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", "json-schema-traverse": "^0.4.1", "uri-js": "^4.2.2" } }, "sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw=="],
|
||||
|
||||
"eslint-import-resolver-node/debug": ["debug@3.2.7", "https://registry.npmmirror.com/debug/-/debug-3.2.7.tgz", { "dependencies": { "ms": "^2.1.1" } }, "sha512-CFjzYYAi4ThfiQvizrFQevTTXHtnCqWfe7x1AhgEscTz6ZbLbfoLRLPugTQyBth6f8ZERVUSyWHFD/7Wu4t1XQ=="],
|
||||
|
||||
"eslint-module-utils/debug": ["debug@3.2.7", "https://registry.npmmirror.com/debug/-/debug-3.2.7.tgz", { "dependencies": { "ms": "^2.1.1" } }, "sha512-CFjzYYAi4ThfiQvizrFQevTTXHtnCqWfe7x1AhgEscTz6ZbLbfoLRLPugTQyBth6f8ZERVUSyWHFD/7Wu4t1XQ=="],
|
||||
@@ -1172,14 +1235,14 @@
|
||||
|
||||
"tdesign-react/@babel/runtime": ["@babel/runtime@7.26.10", "https://registry.npmmirror.com/@babel/runtime/-/runtime-7.26.10.tgz", { "dependencies": { "regenerator-runtime": "^0.14.0" } }, "sha512-2WJMeRQPHKSPemqk/awGrAiuFfzBmOIPXKizAsVhWH9YJqLZ0H+HS4c8loHGgW6utJ3E/ejXQUsiGaQy2NZ9Fw=="],
|
||||
|
||||
"thread-stream/real-require": ["real-require@1.0.0", "https://registry.npmmirror.com/real-require/-/real-require-1.0.0.tgz", {}, "sha512-P4nbQYQfePJxRSmY+v/KINxVucm4NF3p3s7pJveMTtom52FR4YGltUQLB8idDXwDDWW+eYrWDFbuzUnjoWHF7g=="],
|
||||
|
||||
"typescript-eslint/@typescript-eslint/utils": ["@typescript-eslint/utils@8.59.3", "https://registry.npmmirror.com/@typescript-eslint/utils/-/utils-8.59.3.tgz", { "dependencies": { "@eslint-community/eslint-utils": "^4.9.1", "@typescript-eslint/scope-manager": "8.59.3", "@typescript-eslint/types": "8.59.3", "@typescript-eslint/typescript-estree": "8.59.3" }, "peerDependencies": { "eslint": "^8.57.0 || ^9.0.0 || ^10.0.0", "typescript": ">=4.8.4 <6.1.0" } }, "sha512-JAvT14goBzRzzzZyqq3P9BLArIxTtQURUtFgQ/V7FO+eU+Gg6ES+5ymOPP1wRxXcxAYeivCk4uS3jCKWI1K8Zg=="],
|
||||
|
||||
"wrap-ansi/ansi-styles": ["ansi-styles@6.2.3", "https://registry.npmmirror.com/ansi-styles/-/ansi-styles-6.2.3.tgz", {}, "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg=="],
|
||||
|
||||
"wrap-ansi/string-width": ["string-width@8.2.1", "https://registry.npmmirror.com/string-width/-/string-width-8.2.1.tgz", { "dependencies": { "get-east-asian-width": "^1.5.0", "strip-ansi": "^7.1.2" } }, "sha512-IIaP0g3iy9Cyy18w3M9YcaDudujEAVHKt3a3QJg1+sr/oX96TbaGUubG0hJyCjCBThFH+tFpcIyoUHUn1ogaLA=="],
|
||||
|
||||
"@commitlint/config-validator/ajv/json-schema-traverse": ["json-schema-traverse@1.0.0", "https://registry.npmmirror.com/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", {}, "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug=="],
|
||||
|
||||
"@typescript-eslint/eslint-plugin/@typescript-eslint/scope-manager/@typescript-eslint/types": ["@typescript-eslint/types@8.59.3", "https://registry.npmmirror.com/@typescript-eslint/types/-/types-8.59.3.tgz", {}, "sha512-ePFoH0g4ludssdRFqqDxQePCxU4WQyRa9+XVwjm7yLn0FKhMeoetC+qBEEI1Eyb1pGSDveTIT09Bvw2WhlGayg=="],
|
||||
|
||||
"@typescript-eslint/eslint-plugin/@typescript-eslint/utils/@typescript-eslint/types": ["@typescript-eslint/types@8.59.3", "https://registry.npmmirror.com/@typescript-eslint/types/-/types-8.59.3.tgz", {}, "sha512-ePFoH0g4ludssdRFqqDxQePCxU4WQyRa9+XVwjm7yLn0FKhMeoetC+qBEEI1Eyb1pGSDveTIT09Bvw2WhlGayg=="],
|
||||
@@ -1198,6 +1261,8 @@
|
||||
|
||||
"eslint-plugin-import/minimatch/brace-expansion": ["brace-expansion@1.1.14", "https://registry.npmmirror.com/brace-expansion/-/brace-expansion-1.1.14.tgz", { "dependencies": { "balanced-match": "^1.0.0", "concat-map": "0.0.1" } }, "sha512-MWPGfDxnyzKU7rNOW9SP/c50vi3xrmrua/+6hfPbCS2ABNWfx24vPidzvC7krjU/RTo235sV776ymlsMtGKj8g=="],
|
||||
|
||||
"eslint/ajv/json-schema-traverse": ["json-schema-traverse@0.4.1", "https://registry.npmmirror.com/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz", {}, "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg=="],
|
||||
|
||||
"log-update/slice-ansi/ansi-styles": ["ansi-styles@6.2.3", "https://registry.npmmirror.com/ansi-styles/-/ansi-styles-6.2.3.tgz", {}, "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg=="],
|
||||
|
||||
"log-update/wrap-ansi/ansi-styles": ["ansi-styles@6.2.3", "https://registry.npmmirror.com/ansi-styles/-/ansi-styles-6.2.3.tgz", {}, "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg=="],
|
||||
|
||||
@@ -1,3 +1,18 @@
|
||||
# yaml-language-server: $schema=./config.schema.json
|
||||
server:
|
||||
host: "127.0.0.1"
|
||||
port: 3000
|
||||
listen:
|
||||
host: "${HOST|127.0.0.1}"
|
||||
port: ${PORT|3000}
|
||||
storage:
|
||||
dataDir: "./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
|
||||
|
||||
254
config.schema.json
Normal file
254
config.schema.json
Normal file
@@ -0,0 +1,254 @@
|
||||
{
|
||||
"additionalProperties": false,
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"server": {
|
||||
"additionalProperties": false,
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"listen": {
|
||||
"additionalProperties": false,
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"host": {
|
||||
"type": "string"
|
||||
},
|
||||
"port": {
|
||||
"anyOf": [
|
||||
{
|
||||
"maximum": 65535,
|
||||
"minimum": 0,
|
||||
"type": "integer"
|
||||
},
|
||||
{
|
||||
"pattern": "^\\$\\{[^}]+\\}$",
|
||||
"type": "string"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"logging": {
|
||||
"additionalProperties": false,
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"console": {
|
||||
"additionalProperties": false,
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"level": {
|
||||
"anyOf": [
|
||||
{
|
||||
"anyOf": [
|
||||
{
|
||||
"const": "trace",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"const": "debug",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"const": "info",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"const": "warn",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"const": "error",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"const": "fatal",
|
||||
"type": "string"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"pattern": "^\\$\\{[^}]+\\}$",
|
||||
"type": "string"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"file": {
|
||||
"additionalProperties": false,
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"level": {
|
||||
"anyOf": [
|
||||
{
|
||||
"anyOf": [
|
||||
{
|
||||
"const": "trace",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"const": "debug",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"const": "info",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"const": "warn",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"const": "error",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"const": "fatal",
|
||||
"type": "string"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"pattern": "^\\$\\{[^}]+\\}$",
|
||||
"type": "string"
|
||||
}
|
||||
]
|
||||
},
|
||||
"path": {
|
||||
"minLength": 1,
|
||||
"type": "string"
|
||||
},
|
||||
"rotation": {
|
||||
"additionalProperties": false,
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"frequency": {
|
||||
"anyOf": [
|
||||
{
|
||||
"anyOf": [
|
||||
{
|
||||
"const": "hourly",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"const": "daily",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"const": "weekly",
|
||||
"type": "string"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"pattern": "^\\$\\{[^}]+\\}$",
|
||||
"type": "string"
|
||||
}
|
||||
]
|
||||
},
|
||||
"maxFiles": {
|
||||
"anyOf": [
|
||||
{
|
||||
"minimum": 1,
|
||||
"type": "integer"
|
||||
},
|
||||
{
|
||||
"pattern": "^\\$\\{[^}]+\\}$",
|
||||
"type": "string"
|
||||
}
|
||||
]
|
||||
},
|
||||
"size": {
|
||||
"anyOf": [
|
||||
{
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"minimum": 0,
|
||||
"type": "integer"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"pattern": "^\\$\\{[^}]+\\}$",
|
||||
"type": "string"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"level": {
|
||||
"anyOf": [
|
||||
{
|
||||
"anyOf": [
|
||||
{
|
||||
"const": "trace",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"const": "debug",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"const": "info",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"const": "warn",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"const": "error",
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"const": "fatal",
|
||||
"type": "string"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"pattern": "^\\$\\{[^}]+\\}$",
|
||||
"type": "string"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"storage": {
|
||||
"additionalProperties": false,
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"dataDir": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"variables": {
|
||||
"type": "object",
|
||||
"patternProperties": {
|
||||
"^[a-zA-Z_][a-zA-Z0-9_]*$": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "number"
|
||||
},
|
||||
{
|
||||
"type": "boolean"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"$id": "https://app.local/config.schema.json",
|
||||
"$schema": "http://json-schema.org/draft-07/schema#"
|
||||
}
|
||||
115
docs/README.md
Normal file
115
docs/README.md
Normal 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
115
docs/development/README.md
Normal 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
92
docs/development/architecture.md
Normal 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
101
docs/development/backend.md
Normal 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
73
docs/development/frontend.md
Normal 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
97
docs/development/release.md
Normal 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 |
|
||||
|
||||
## 更新触发条件
|
||||
|
||||
修改开发服务、前后端集成、构建产物、脚本参数或验证方式时，必须更新本文档。
|
||||
@@ -4,12 +4,15 @@
|
||||
|
||||
## 提示词
|
||||
|
||||
| 文件 | 用途 |
|
||||
| ------------------------------------------------------ | ------------------------------------------------------------------------ |
|
||||
| [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) | 审查 proposal/design/tasks/specs 与讨论、代码现状、OpenSpec 规范的一致性 |
|
||||
| [prompt-apply-review.md](prompt-apply-review.md) | 审查 apply 后代码、测试、变更文档的一致性，并补齐遗漏或回写文档 |
|
||||
| 文件 | 用途 |
|
||||
| ------------------------------------------------------ | ------------------------------------------------------------------------- |
|
||||
| [prompt-smart-merge.md](prompt-smart-merge.md) | 批量合并 `dev*` 分支到目标分支，含规则探测、依赖分析、冲突处理、安全回退 |
|
||||
| [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 大模型执行型提示词资产，不属于常规用户文档或开发文档流。文档影响分析不覆盖本目录内容。
|
||||
|
||||
## 设计目标
|
||||
|
||||
|
||||
@@ -1,15 +1,17 @@
|
||||
审查 OpenSpec apply 完成后以及后续手动修补后的实际实现，判断代码、测试、变更文档是否一致，识别偏离、漏记和可优化点，并将确认后的实际变更同步回变更文档，按以下流程执行。
|
||||
审查 OpenSpec apply 完成后以及后续手动修补后的实际变更，判断实际产物、验证结果和变更文档是否与 `design.md` source of truth 一致，识别偏离、漏记和可优化点，并将确认后的实际变更同步回变更文档，按以下流程执行。
|
||||
|
||||
## 约束
|
||||
|
||||
- 先审查再修复；未经用户确认，不修改代码或变更文档
|
||||
- 默认按 `spec-driven` workflow 审查；识别 change 后先确认 `schemaName`；若实际 schema 不同，说明差异，仅对实际存在的 artifacts 做审查
|
||||
- 禁止同步或修改 `openspec/specs/` 下的主规范——主规范同步属于 archive 阶段，不在此提示词范围内；本次 change 目录下的 `specs/*.md`、代码、测试、README 等均可修改
|
||||
- 优先使用当前会话中的实现说明、测试结论、手动修补记录和已生成的变更文档；仅在无法明确 change、`schemaName`、改动范围或修补来源时，再用提问工具或 OpenSpec 命令补充定位
|
||||
- 不要因为代码已经存在就自动以代码为准；先判断差异属于"文档要求未实现"、"测试后新增修补"还是"意外偏离/回归"
|
||||
- 每批代码或文档修改执行前用提问工具获得用户确认
|
||||
- 先审查再修复；未经用户确认，不修改实际产物或变更文档
|
||||
- 默认按 `fast-drive` workflow 审查；识别 change 后先确认 `schemaName`；若实际 schema 不同，说明差异，仅对实际存在的 artifacts 做审查
|
||||
- 在 `fast-drive` workflow 下，核心 artifacts 是 `design.md` 和 `tasks.md`；不要要求存在 `proposal.md` 或 `specs/*.md`
|
||||
- 在 `fast-drive` workflow 下，`design.md` 是 scope、requirements、decisions、guardrails、execution direction 和 verification expectations 的 source of truth，`tasks.md` 是 apply 进度和验证闭环的 tracking 文件
|
||||
- 禁止同步或修改 `openspec/specs/` 下的主规范；若实际 schema 包含 `specs/*.md`，也只允许修改本次 change 目录下实际存在的 spec artifacts，主规范同步属于 archive 阶段，不在此提示词范围内
|
||||
- 优先使用当前会话中的执行说明、验证结论、手动修补记录和已生成的变更文档；仅在无法明确 change、`schemaName`、改动范围或修补来源时，再用提问工具或 OpenSpec 命令补充定位
|
||||
- 不要因为实际产物已经存在就自动以实际产物为准；先判断差异属于“design 要求未完成”、“验证后新增修补”、“合理落地细化”还是“意外偏离/回归”
|
||||
- 每批实际产物或文档修改执行前用提问工具获得用户确认
|
||||
- 删除/重写前用提问工具获得用户确认，并先备份原文件为 `{file}.bak.{timestamp}`
|
||||
- 若修改代码涉及新逻辑、模块结构、API、实体或用户可见行为，同步更新测试、相关变更文档和 README
|
||||
- 若修改实际产物涉及新行为、流程、接口、内容、数据、配置、责任边界或用户可见结果，同步更新验证材料、相关变更文档和必要的文档/沟通材料
|
||||
|
||||
## 1. 收集
|
||||
|
||||
@@ -22,18 +24,34 @@
|
||||
|
||||
a) 先并行读取核心入口和配置，确定范围：
|
||||
|
||||
- 本次 change 的 `proposal.md`
|
||||
- `openspec/config.yaml`
|
||||
- 本次 change 的 `design.md`
|
||||
- 本次 change 的 `tasks.md`
|
||||
- workflow context/configuration，例如存在时读取 `openspec/config.yaml`
|
||||
- 若可定位到 schema，读取对应 schema；`fast-drive` 下优先读取 `openspec/schemas/fast-drive/schema.yaml`
|
||||
|
||||
b) 从 `proposal.md` 提取 `Capabilities` / `Modified Capabilities`，确定 proposal 已声明的 spec 列表
|
||||
b) 从 `design.md` 提取审查基准：
|
||||
|
||||
c) 并行获取改动范围：`git diff --name-only`、`git diff --name-only --cached`；若工作区已干净，再结合文档和代码模块反推
|
||||
- `Context`
|
||||
- `Discussion Notes`
|
||||
- `Requirements`
|
||||
- `Goals / Non-Goals`
|
||||
- `Execution Guardrails`
|
||||
- `Affected Areas`
|
||||
- `Decisions`
|
||||
- `Execution Plan`
|
||||
- `Verification Plan`
|
||||
- `Risks / Trade-offs`
|
||||
- `Open Questions`
|
||||
|
||||
d) 对比 git diff 涉及的模块与 proposal 已声明的 spec，识别 apply 阶段新增改动触及但 proposal 未覆盖的现有 spec，合并为完整 spec 读取列表；相关性来源还包括：手动修补涉及的受影响能力、`design.md` Impact 中提到的模块、相关代码对应的现有能力
|
||||
c) 从 `tasks.md` 提取任务状态、已完成项、未完成项、验证任务和文档/沟通任务；重点记录所有已标记完成的 `- [x]` 或等价完成状态。
|
||||
|
||||
e) 并行读取完整 spec 列表和其余 artifacts（`design.md`、`tasks.md`、相关源码、测试文件、README、架构文档）
|
||||
d) 获取实际改动范围：若在版本控制工作区中，优先使用 `git diff --name-only`、`git diff --name-only --cached`；若工作区已干净或不适用版本控制，再结合 `design.md`、`tasks.md`、验证记录和执行记录反推。
|
||||
|
||||
f) 收集当前会话中与本次变更相关的实现说明、apply 过程中的偏离、测试失败、手动修补原因、待确认事项
|
||||
e) 并行读取实际改动范围、`Affected Areas`、`Execution Plan`、`Verification Plan` 涉及的实际产物、参考材料、验证材料、流程说明、配置、文档或沟通材料。
|
||||
|
||||
f) 收集当前会话中与本次变更相关的执行说明、apply 过程中的偏离、验证失败、手动修补原因、验证命令或检查结果、待确认事项。
|
||||
|
||||
g) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts；若存在 `proposal.md`、`specs/*.md`，再按该 schema 的要求补充读取和审查。
|
||||
|
||||
若当前上下文无法明确 change 或文档路径：
|
||||
|
||||
@@ -42,66 +60,75 @@ f) 收集当前会话中与本次变更相关的实现说明、apply 过程中
|
||||
|
||||
若已明确 change，但尚未确认 `schemaName`，先读取 change 元数据或执行 `openspec status --change "{name}" --json` 确认。
|
||||
|
||||
若缺少测试结果或手动修补记录，明确说明本次无法可靠判断部分差异的来源，仅能基于代码与文档现状审查。
|
||||
若缺少验证结果或手动修补记录，明确说明本次无法可靠判断部分差异的来源，仅能基于实际产物与文档现状审查。
|
||||
|
||||
## 2. 分析
|
||||
|
||||
按以下优先级检查：
|
||||
|
||||
| 优先级 | 维度 | 检查点 |
|
||||
| ------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| P0 | 实际实现与测试结论 | 当前代码的真实行为是什么；apply 后是否有手动改动或测试后修补；测试是否证明这些实现有效；若缺少测试结果，标记相关结论为"未验证"；检查是否存在回归、未覆盖场景或被掩盖的问题 |
|
||||
| P1 | 文档同步性 | 对本次 change 目录下实际存在的 artifacts 检查：已落地的实现、测试后新增修补、边界处理、异常路径、验证结论是否已同步回变更文档；若影响模块结构、API、实体或用户可见行为，再检查 README 是否同步 |
|
||||
| P2 | Spec 覆盖完整性 | 对比实际代码改动范围与 proposal 中定义的 `Capabilities` / `Modified Capabilities`，识别 apply 阶段新增的功能是否触及了更多现有 spec；若触及，列入补充清单，在本次 change 的 specs 中新增对应的 spec 文件，并更新 `proposal.md` 的 `Modified Capabilities` |
|
||||
| P3 | 文档要求覆盖 | 对实际存在的 artifacts 检查：文档中承诺的目标、方案、Requirement、Scenario 是否都已实现；在 `spec-driven` 下重点检查 `proposal.md`、`design.md`、`specs/*.md`、`tasks.md` |
|
||||
| P4 | 实现质量 | 代码结构、复用、命名、复杂度、错误处理、测试质量、与项目现有模式的一致性是否存在明显问题或可优化点 |
|
||||
| 优先级 | 维度 | 检查点 |
|
||||
| ------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| P0 | 实际变更与验证结论 | 当前实际产物的真实状态是什么；apply 后是否有手动改动或验证后修补；验证是否证明这些变更有效；若缺少验证结果，标记相关结论为“未验证”；检查是否存在回归、未覆盖场景或被掩盖的问题 |
|
||||
| P1 | `design.md` 一致性 | 实际变更是否符合 `Requirements`、`Goals / Non-Goals`、`Execution Guardrails`、`Decisions`、`Execution Plan` 和 `Verification Plan`；`Open Questions` 是否已明确区分 blocking / non-blocking 或写出 `None`；是否违反被明确否决的方案、用户偏好或约束 |
|
||||
| P2 | `tasks.md` 真实性 | 已完成任务是否真的完成并完成必要验证；未完成任务是否仍然必要；apply 或手动修补是否引入了需要补充的新任务、验证任务或文档/沟通任务 |
|
||||
| P3 | 文档回写完整性 | 已落地的实际变更、验证后新增修补、边界处理、异常路径、验证结论、实际触达产物是否已同步回 `design.md` 和 `tasks.md`；若影响行为、流程、接口、内容、数据、配置、责任边界或用户可见结果，再检查必要的文档/沟通材料是否同步 |
|
||||
| P4 | 质量与可维护性 | 实际产物的结构、清晰度、一致性、可维护性、风险处理、移交质量、验证质量、与现有模式的一致性是否存在明显问题或可优化点 |
|
||||
| P5 | Schema 兼容性 | 对实际存在的 artifacts 检查是否符合其 schema；若不是 `fast-drive`，仅按实际 artifacts 检查，不凭空要求 `fast-drive` 专属结构；最终 artifacts 是否仍保留模板注释、空表格行或占位任务文本 |
|
||||
|
||||
分析时区分三类差异：
|
||||
分析时区分四类差异：
|
||||
|
||||
- 文档要求已明确，但代码未实现或实现不完整 → 需补充代码或测试
|
||||
- 代码因测试暴露问题、手动修补或合理落地细化而新增/变更 → 需回写文档
|
||||
- 代码与文档不一致，且无法判断应以哪边为准 → 列入待确认清单
|
||||
- `design.md` 要求已明确，但实际变更未完成或完成不充分 → 需补充实际工作或验证
|
||||
- 实际变更因验证暴露问题、手动修补或合理落地细化而新增/变更 → 需回写 `design.md` 和/或 `tasks.md`
|
||||
- 实际变更与 `design.md` 不一致，且无法判断应以哪边为准 → 列入待确认清单
|
||||
- `tasks.md` 状态与实际完成情况或验证结果不一致 → 修正任务状态或补充任务
|
||||
|
||||
不要把以下情况直接视为合理修补：
|
||||
|
||||
- 通过 `skip`、`only`、弱化断言、绕过错误处理来让测试通过
|
||||
- 为了贴合现有代码而降低已确认的 Requirement 或行为约束
|
||||
- 未经过讨论和验证就扩大功能范围
|
||||
- 通过跳过、弱化或绕过验证来声称变更完成
|
||||
- 为了贴合当前实际产物而降低已确认的 requirement、acceptance criteria 或 guardrail
|
||||
- 未经过讨论和验证就扩大功能、流程、内容或责任范围
|
||||
- 违反 `Execution Guardrails`、被拒绝方案或 `Open Questions` 中尚未解决的 blocker
|
||||
|
||||
重点识别：
|
||||
|
||||
- 文档要求但未落地的功能、场景、异常处理或验证步骤
|
||||
- apply 完成后新增的代码修补、边界处理、接口调整、行为变化未同步到文档
|
||||
- `tasks.md` 标记完成，但代码、测试或文档未闭环
|
||||
- `Modified Capabilities` 在本次 change 的 specs 中是否已更新（注意：仅更新 change 目录下的 specs，不动 `openspec/specs/`）；apply 阶段新增功能触及的未覆盖 spec 是否已补充到本次 change 的 `specs/` 目录
|
||||
- 代码存在明显的重复、复杂度过高、命名不清、错误处理薄弱、测试质量不足等问题
|
||||
- `design.md` 要求但未落地的结果、流程、内容、场景、异常处理、文档/沟通更新或验证步骤
|
||||
- 实际变更偏离 `Goals / Non-Goals`、`Execution Guardrails`、`Decisions` 或 `Execution Plan` 的地方
|
||||
- apply 完成后新增的修补、边界处理、接口调整、行为变化、流程变化或内容变化未同步到 `design.md`
|
||||
- `Affected Areas` 与实际改动范围不一致，导致新会话无法复盘真实影响面
|
||||
- `Verification Plan` 中要求的验证、质量检查、审阅、批准、沟通检查或 manual checks 未执行或未记录
|
||||
- `tasks.md` 标记完成，但实际产物、验证、文档或沟通未闭环
|
||||
- `design.md` 或 `tasks.md` 仍保留 `<!-- ... -->` 模板注释、空表格行、`Replace with...`、`TBD`、`TODO` 等未解决占位内容
|
||||
- 必要的文档/沟通材料未同步影响行为、流程、接口、内容、数据、配置、责任边界或用户可见结果的变更
|
||||
- 实际产物存在明显的重复、复杂度过高、表达不清、责任不明、风险处理薄弱、验证质量不足等问题
|
||||
- `fast-drive` change 中仍错误依赖 `proposal.md`、`specs/*.md`、`Capabilities` 或 `Modified Capabilities` 的内容
|
||||
|
||||
输出审查结果：
|
||||
|
||||
1. **问题总览表**：问题类型 × 涉及文件数
|
||||
2. **实际改动与修补清单**：本次实现中已落地的主要功能、后续修补和验证结论；若缺少测试结果，对未验证部分单独标记
|
||||
3. **未覆盖清单**：文档要求但未在代码中实现或未充分验证的内容
|
||||
4. **需回写文档清单**：代码和测试中已确认、但文档未体现的实现、修补或约束变化
|
||||
5. **方向待确认清单**：代码与文档不一致，且无法判断应以哪边为准的事项
|
||||
6. **Spec 补充清单**：apply 阶段新增功能触及但 proposal 未覆盖的现有 spec，列出需新增的 spec 文件名、对应的主 spec 路径、需描述的变更内容
|
||||
7. **任务状态问题清单**：未真正完成、状态错误或需补充的新任务
|
||||
8. **测试问题清单**：缺失覆盖、掩盖错误、验证不足或修补后未回归验证的测试问题
|
||||
9. **代码质量/优化清单**：可优化的实现问题和建议
|
||||
2. **实际变更与修补清单**：本次已落地的主要变更、后续修补和验证结论；若缺少验证结果，对未验证部分单独标记
|
||||
3. **Design 偏离清单**：实际变更未完成、完成不充分或偏离 `design.md` 的内容
|
||||
4. **需回写文档清单**：实际产物和验证中已确认、但 `design.md`、`tasks.md` 或相关文档/沟通材料未体现的变更、修补或约束变化
|
||||
5. **方向待确认清单**：实际变更与 `design.md` 不一致，且无法判断应以哪边为准的事项
|
||||
6. **任务状态问题清单**：未真正完成、状态错误或需补充的新任务
|
||||
7. **验证问题清单**：缺失覆盖、掩盖错误、验证不足或修补后未回归验证的问题
|
||||
8. **质量/优化清单**：可优化的实际产物问题和建议
|
||||
9. **Schema 差异清单**：实际 schema 与默认 `fast-drive` 不同时，列出因此跳过或改按实际 artifacts 审查的内容
|
||||
10. **逐项分析**：每个问题说明位置、问题、影响、建议和建议修复方向
|
||||
|
||||
若所有清单均为空，输出"审查通过，未发现问题"，跳至步骤 5。
|
||||
若所有清单均为空，输出“审查通过，未发现问题”，跳至步骤 5。
|
||||
|
||||
## 3. 计划（用户确认）
|
||||
|
||||
先针对"方向待确认清单"用提问工具逐项向用户确认。
|
||||
先针对“方向待确认清单”用提问工具逐项向用户确认。
|
||||
|
||||
再整理完整修复方案，按类别列出：
|
||||
|
||||
- 代码或测试补充：补实现、补异常处理、补回归测试、修复掩盖错误的测试
|
||||
- 文档回写：同步本次 change 目录下的 `proposal.md`、`design.md`、`tasks.md`、`specs/*.md`、README 中遗漏或过时的内容（禁止同步到 `openspec/specs/`）
|
||||
- Spec 补充：将 apply 阶段新增功能触及的现有 spec 复制到本次 change 的 `specs/` 目录并更新，同步更新 `proposal.md` 的 `Modified Capabilities`
|
||||
- 实际工作或验证补充：补完成、补异常处理、补回归验证、修复被弱化或绕过的验证
|
||||
- Design 回写：同步 `design.md` 中遗漏或过时的 requirements、guardrails、affected areas、decisions、execution plan、verification plan、risks 或 open questions
|
||||
- 任务状态修正：修正已完成/未完成状态，补充 apply 后新增但已完成的修补任务或验证任务
|
||||
- 代码质量优化：在不改变目标行为的前提下优化结构、复用、命名或可维护性
|
||||
- 文档/沟通同步：同步行为、流程、接口、内容、数据、配置、责任边界或用户可见结果变化
|
||||
- 质量优化：在不改变目标结果的前提下优化结构、表达、一致性、可维护性或移交质量
|
||||
- Schema 兼容处理：若实际 schema 不是 `fast-drive`，按实际存在的 artifacts 说明额外文档同步项
|
||||
|
||||
对每个拟修改的文件说明：
|
||||
|
||||
@@ -115,36 +142,38 @@ f) 收集当前会话中与本次变更相关的实现说明、apply 过程中
|
||||
|
||||
## 4. 执行
|
||||
|
||||
逐项执行已确认的代码、测试和文档修复。
|
||||
逐项执行已确认的实际产物、验证和文档修复。
|
||||
|
||||
若涉及删除或重写：
|
||||
|
||||
- 先创建备份文件 `{file}.bak.{timestamp}`
|
||||
- 再执行修改
|
||||
|
||||
若修改了代码或测试：
|
||||
若修改了实际产物或验证材料：
|
||||
|
||||
- 同步更新相关变更文档；若影响模块结构、API、实体或用户可见行为，再同步 README
|
||||
- 运行相关测试；若修补影响范围较大，再补充执行受影响的回归测试
|
||||
- 同步更新相关变更文档；若影响行为、流程、接口、内容、数据、配置、责任边界或用户可见结果，再同步必要的文档/沟通材料
|
||||
- 运行或执行相关验证；若修补影响范围较大，再补充执行受影响的回归验证
|
||||
|
||||
若修改了文档：
|
||||
|
||||
- 确认本次 change 目录下的变更文档之间保持一致；重点检查 `proposal.md`、`design.md`、`tasks.md`、`specs/*.md`
|
||||
- 若 apply 后新增修补改变了能力边界或行为约束，同步更新本次 change 的 `Capabilities` / `Modified Capabilities`
|
||||
- 若"Spec 补充清单"中有需新增的 spec：先从 `openspec/specs/` 复制对应的原 spec 到本次 change 的 `specs/` 目录，再基于实际改动更新其内容；禁止修改 `openspec/specs/` 下的原文件
|
||||
- 禁止将本次 change 的 specs 同步到 `openspec/specs/`，该操作属于 archive 阶段
|
||||
- 在 `fast-drive` workflow 下，确认 `design.md` 仍是 source of truth，`tasks.md` 仍从 `design.md` 派生
|
||||
- 确认 `design.md` 的 requirements、guardrails、affected areas、decisions、execution plan、verification plan、risks 和 open questions 与实际变更一致
|
||||
- 确认 `tasks.md` 每个完成任务都有对应实际产物和必要验证，新增修补已补充任务或记录在合适任务中
|
||||
- 禁止将本次 change 内容同步到 `openspec/specs/`，该操作属于 archive 阶段
|
||||
- 在 `fast-drive` workflow 下不创建 `proposal.md` 或 `specs/*.md`；若实际 schema 不是 `fast-drive`，则按实际 schema 的 required artifacts 创建或更新本次 change 目录下的 artifacts
|
||||
|
||||
执行后重新读取所有被修改的代码、测试和文档，并复核：
|
||||
执行后重新读取所有被修改的实际产物、验证材料和文档，并复核：
|
||||
|
||||
- "未覆盖清单" 是否已清空或已标注保留原因
|
||||
- "需回写文档清单" 是否已清空
|
||||
- "Spec 补充清单" 是否已清空或已标注保留原因
|
||||
- "方向待确认清单" 是否已清空或已记录用户决策
|
||||
- "任务状态问题清单" 和 "测试问题清单" 是否已清空或已标注残留原因
|
||||
- "代码质量/优化清单" 中哪些已处理，哪些有意延期
|
||||
- “Design 偏离清单” 是否已清空或已标注保留原因
|
||||
- “需回写文档清单” 是否已清空
|
||||
- “方向待确认清单” 是否已清空或已记录用户决策
|
||||
- “任务状态问题清单” 和 “验证问题清单” 是否已清空或已标注残留原因
|
||||
- “质量/优化清单” 中哪些已处理，哪些有意延期
|
||||
- 必要的文档/沟通材料是否已按影响范围同步
|
||||
- 所有模板注释、空表格行和占位文本是否已清空或替换为有效内容
|
||||
|
||||
## 5. 收尾
|
||||
|
||||
列出所有修改的文件、备份文件、测试命令与结果、文档同步摘要和剩余风险。
|
||||
列出所有修改的文件、备份文件、验证命令或检查结果、文档同步摘要和剩余风险。
|
||||
|
||||
若本次因缺少测试结果、修补记录或上下文而降级执行，或有问题因信息不足暂未处理，单独说明。
|
||||
若本次因缺少验证结果、修补记录或上下文而降级执行，或有问题因信息不足暂未处理，单独说明。
|
||||
|
||||
@@ -1,10 +1,12 @@
|
||||
审查本次 OpenSpec 变更文档是否与前序讨论、当前代码现状和 OpenSpec 文档规范一致，识别遗漏、冲突和不合理假设，并给出可执行的补充建议，按以下流程执行。
|
||||
审查本次 OpenSpec 变更文档是否与前序讨论、当前实际状态和实际 OpenSpec workflow 一致，重点检查 `fast-drive` workflow 下的 `design.md` 是否足以在上下文压缩或新会话中指导后续 `apply`，并识别遗漏、冲突和不合理假设，给出可执行的补充建议，按以下流程执行。
|
||||
|
||||
## 约束
|
||||
|
||||
- 仅修改本次变更文档，不修改源码
|
||||
- 默认按 `spec-driven` workflow 审查；识别 change 后先确认 `schemaName`；若实际 schema 不同，说明差异，仅对实际存在的 artifacts 做审查
|
||||
- 优先使用当前会话中的讨论和已生成的变更文档；仅在无法明确 change、`schemaName` 或文档范围时，再用提问工具或 OpenSpec 命令补充定位
|
||||
- 仅修改本次变更文档，不修改实际产物
|
||||
- 默认按 `fast-drive` workflow 审查；识别 change 后先确认 `schemaName`；若实际 schema 不同，说明差异，仅对实际存在的 artifacts 做审查
|
||||
- 在 `fast-drive` workflow 下，核心 artifacts 是 `design.md` 和 `tasks.md`；不要要求存在 `proposal.md` 或 `specs/*.md`
|
||||
- 在 `fast-drive` workflow 下，`design.md` 是 scope、requirements、decisions、guardrails、execution direction 和 verification expectations 的 source of truth，`tasks.md` 必须从 `design.md` 派生
|
||||
- 优先使用当前会话中的讨论、explore/propose 阶段结论和已生成的变更文档；仅在无法明确 change、`schemaName` 或文档范围时，再用提问工具或 OpenSpec 命令补充定位
|
||||
- 每批文档修改建议执行前用提问工具获得用户确认
|
||||
- 删除/重写前用提问工具获得用户确认，并先备份原文件为 `{file}.bak.{timestamp}`
|
||||
|
||||
@@ -19,12 +21,28 @@
|
||||
|
||||
a) 先并行读取核心入口和配置，确定范围：
|
||||
|
||||
- 本次 change 的 `proposal.md`
|
||||
- `openspec/config.yaml`
|
||||
- 本次 change 的 `design.md`
|
||||
- 本次 change 的 `tasks.md`
|
||||
- workflow context/configuration，例如存在时读取 `openspec/config.yaml`
|
||||
- 若可定位到 schema，读取对应 schema；`fast-drive` 下优先读取 `openspec/schemas/fast-drive/schema.yaml`
|
||||
|
||||
b) 从 `proposal.md` 提取 `Capabilities` / `Modified Capabilities`，确定需要读取的 spec 列表；相关性来源还包括：讨论中提到的受影响能力、`design.md` Impact 中提到的模块、相关代码对应的现有能力
|
||||
b) 从 `design.md` 提取审查基准：
|
||||
|
||||
c) 并行读取已确定的 spec 和其余 artifacts（`design.md`、`tasks.md`、相关源码、测试、README、架构文档）
|
||||
- `Context`
|
||||
- `Discussion Notes`
|
||||
- `Requirements`
|
||||
- `Goals / Non-Goals`
|
||||
- `Execution Guardrails`
|
||||
- `Affected Areas`
|
||||
- `Decisions`
|
||||
- `Execution Plan`
|
||||
- `Verification Plan`
|
||||
- `Risks / Trade-offs`
|
||||
- `Open Questions`
|
||||
|
||||
c) 基于 `Affected Areas`、`Execution Plan`、`Verification Plan`、讨论中提到的受影响范围，并行读取相关实际产物、参考材料、验证材料、流程说明、配置、文档或沟通材料，确认文档是否贴合当前实际状态。
|
||||
|
||||
d) 若实际 schema 不是 `fast-drive`，只读取实际存在的 artifacts；若存在 `proposal.md`、`specs/*.md`，再按该 schema 的要求补充读取和审查。
|
||||
|
||||
若当前上下文无法明确 change 或文档路径：
|
||||
|
||||
@@ -33,47 +51,55 @@ c) 并行读取已确定的 spec 和其余 artifacts（`design.md`、`tasks.md`
|
||||
|
||||
若已明确 change，但尚未确认 `schemaName`，先读取 change 元数据或执行 `openspec status --change "{name}" --json` 确认。
|
||||
|
||||
若缺少讨论记录，明确说明本次降级为"文档 + 代码现状审查"，不做讨论一致性结论。
|
||||
若缺少讨论记录，明确说明本次降级为“文档 + 当前实际状态审查”，不做讨论一致性结论。
|
||||
|
||||
## 2. 分析
|
||||
|
||||
按以下优先级检查：
|
||||
|
||||
| 优先级 | 维度 | 检查点 |
|
||||
| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| P0 | 讨论一致性 | 仅在存在讨论记录时检查：文档是否完整覆盖已确认的目标、范围、非目标、约束、边界条件、风险、决策点、待办事项；若无讨论记录，标记为"跳过" |
|
||||
| P1 | 代码现实性 | 文档对当前模块、接口、数据结构、命名、依赖、目录结构、复用路径的描述是否准确；是否把"计划变更"误写成"当前现状"；是否遗漏真实受影响的现有能力 |
|
||||
| P2 | 文档内部一致性 | 对实际存在的 artifacts 检查是否互相支撑；在 `spec-driven` 下重点检查 `proposal.md`、`design.md`、`tasks.md`、`specs/*.md`；`Capabilities` / `Modified Capabilities` 是否完整；每个 capability 是否有对应 spec；`tasks.md` 是否覆盖 `design.md` 和 `specs/*.md` |
|
||||
| P3 | OpenSpec 合规性 | 对实际存在的 artifacts 检查是否遵循 OpenSpec 格式和术语；`specs/*.md` 是否只描述行为与约束、不混入实现细节；`tasks.md` 是否一行一个任务；是否混入 git 操作任务 |
|
||||
| 优先级 | 维度 | 检查点 |
|
||||
| ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| P0 | 讨论承接性 | 仅在存在讨论记录时检查：`design.md` 是否完整记录已确认的目标、非目标、用户偏好、约束、边界条件、风险、关键决策、被否决方案和待澄清事项；若无讨论记录，标记为“跳过” |
|
||||
| P1 | `design.md` 自包含性 | `design.md` 是否足以让看不到前序对话的执行者继续工作；是否包含完整 required sections；`Open Questions` 是否明确区分 blocking / non-blocking 或写出 `None`；是否存在依赖未记录聊天上下文的隐含要求 |
|
||||
| P2 | 当前状态真实性 | `design.md` 对当前实际产物、流程、接口、内容、数据、配置、依赖、责任边界、参考材料和验证入口的描述是否准确；是否把“计划变更”误写成“当前现状”；`Affected Areas` 是否遗漏真实受影响区域 |
|
||||
| P3 | `tasks.md` 派生性 | `tasks.md` 是否从 `design.md` 派生；是否覆盖 requirements、guardrails、decisions、execution plan 和 verification plan；是否依赖 `proposal.md` 或 `specs/*.md` 中未写入 `design.md` 的内容 |
|
||||
| P4 | OpenSpec 合规性 | 对实际存在的 artifacts 检查是否遵循对应 schema 和 OpenSpec 术语；`tasks.md` 是否一行一个 `- [ ]` checkbox 任务、按 `##` numbered headings 分组、无无关的仓库/版本控制/发布操作任务；`design.md` 是否避免 task checkbox；最终 artifacts 是否仍保留模板注释、空表格行或占位任务文本 |
|
||||
|
||||
分析时区分两类情况：
|
||||
|
||||
- 文档对当前代码现状的描述错误
|
||||
- 文档描述的是预期变更，本来就应当与当前代码不同
|
||||
- 文档对当前实际状态的描述错误
|
||||
- 文档描述的是预期变更，本来就应当与当前状态不同
|
||||
|
||||
重点识别：
|
||||
|
||||
- 讨论中已确定但文档未记录的内容
|
||||
- 文档基于错误现状做出的设计或任务拆分
|
||||
- 文档之间相互冲突的目标、方案、约束、任务
|
||||
- `Modified Capabilities` 在本次 change 的 specs 中是否已更新（注意：仅更新 change 目录下的 specs，不动 `openspec/specs/`）
|
||||
- 讨论中已确定但 `design.md` 未记录的内容
|
||||
- `design.md` 中缺失或含糊的 requirements、acceptance criteria、guardrails、decisions、verification expectations
|
||||
- `Open Questions` 未明确区分 blocking / non-blocking、与 `tasks.md` 冲突，或包含 apply 前必须解决的 blocker
|
||||
- `tasks.md` 未覆盖 `design.md` 的要求、约束、执行计划、验证计划或文档/沟通更新要求
|
||||
- `tasks.md` 标记了无法验证、跨行、过大、顺序错误或包含无关仓库/版本控制/发布操作的任务
|
||||
- 文档仍保留 `<!-- ... -->` 模板注释、空表格行、`Replace with...`、`TBD`、`TODO` 等未解决占位内容
|
||||
- 文档基于错误当前状态做出的设计或任务拆分
|
||||
- 文档之间相互冲突的目标、方案、约束、任务和验证要求
|
||||
- `fast-drive` change 中仍错误依赖 `proposal.md`、`specs/*.md`、`Capabilities` 或 `Modified Capabilities` 的内容
|
||||
|
||||
输出审查结果：
|
||||
|
||||
1. **问题总览表**：问题类型 × 涉及文档数
|
||||
2. **讨论遗漏清单**：讨论已确定但文档未体现的内容；若缺少讨论记录，标记为"未审查"
|
||||
3. **现实性问题清单**：与当前代码现状不符的描述、假设或影响分析
|
||||
4. **文档冲突清单**：proposal、design、tasks、specs 之间的不一致
|
||||
5. **OpenSpec 规范问题清单**：格式、术语、结构问题
|
||||
6. **待澄清清单**：仅靠讨论和代码仍无法判断的事项
|
||||
7. **逐项分析**：每个问题说明位置、问题、影响、建议
|
||||
8. **补充建议方案**：按文件列出建议补充/修正的内容、原因和可选方案
|
||||
2. **讨论遗漏清单**：讨论已确定但 `design.md` 未体现的内容；若缺少讨论记录，标记为“未审查”
|
||||
3. **Design 自包含性问题清单**：缺失、含糊或无法指导新会话 apply 的内容
|
||||
4. **当前状态问题清单**：与当前实际状态不符的描述、假设或影响分析
|
||||
5. **Tasks 派生与覆盖问题清单**：`tasks.md` 未从 `design.md` 正确派生或覆盖不足的内容
|
||||
6. **文档冲突清单**：`design.md`、`tasks.md` 和实际存在的其他 artifacts 之间的不一致
|
||||
7. **OpenSpec 规范问题清单**：格式、术语、结构问题
|
||||
8. **待澄清清单**：仅靠讨论和当前状态仍无法判断的事项
|
||||
9. **逐项分析**：每个问题说明位置、问题、影响、建议
|
||||
10. **补充建议方案**：按文件列出建议补充/修正的内容、原因和可选方案
|
||||
|
||||
若所有清单均为空，输出"审查通过，未发现问题"，跳至步骤 5。
|
||||
若所有清单均为空，输出“审查通过，未发现问题”，跳至步骤 5。
|
||||
|
||||
## 3. 计划（用户确认）
|
||||
|
||||
先针对"待澄清清单"用提问工具逐项向用户确认。
|
||||
先针对“待澄清清单”用提问工具逐项向用户确认。
|
||||
|
||||
再整理完整修复方案，按文件列出：
|
||||
|
||||
@@ -86,7 +112,9 @@ c) 并行读取已确定的 spec 和其余 artifacts（`design.md`、`tasks.md`
|
||||
|
||||
## 4. 执行
|
||||
|
||||
逐项修改已确认的变更文档，不修改源码。
|
||||
逐项修改已确认的变更文档，不修改实际产物。
|
||||
|
||||
在 `fast-drive` workflow 下，通常只修改本次 change 的 `design.md` 和 `tasks.md`；若实际 schema 存在其他 artifacts，仅在确有必要且用户确认后修改实际存在的 artifacts。
|
||||
|
||||
若涉及删除或重写：
|
||||
|
||||
@@ -95,11 +123,14 @@ c) 并行读取已确定的 spec 和其余 artifacts（`design.md`、`tasks.md`
|
||||
|
||||
执行后重新读取所有被修改的文档，并复核：
|
||||
|
||||
- "讨论遗漏清单" 是否已清空或已标注保留原因
|
||||
- "现实性问题清单" 是否已清空或已标注为预期变更
|
||||
- "文档冲突清单" 是否已清空
|
||||
- "OpenSpec 规范问题清单" 是否已清空
|
||||
- "待澄清清单" 是否已清空或已记录用户决策
|
||||
- “讨论遗漏清单” 是否已清空或已标注保留原因
|
||||
- “Design 自包含性问题清单” 是否已清空
|
||||
- “当前状态问题清单” 是否已清空或已标注为预期变更
|
||||
- “Tasks 派生与覆盖问题清单” 是否已清空
|
||||
- “文档冲突清单” 是否已清空
|
||||
- “OpenSpec 规范问题清单” 是否已清空
|
||||
- “待澄清清单” 是否已清空或已记录用户决策
|
||||
- 所有模板注释、空表格行和占位文本是否已清空或替换为有效内容
|
||||
|
||||
## 5. 收尾
|
||||
|
||||
|
||||
@@ -1,142 +0,0 @@
|
||||
请审查并整理 `openspec/specs/` 下的稳定规范，使其成为可搜索、边界清晰、无冗余、与当前业务一致的能力索引，按以下流程执行。
|
||||
|
||||
## 约束
|
||||
|
||||
- `openspec/specs/` 描述长期稳定的业务能力、规则和外部行为，不记录变更过程、迁移说明、实现路径、内部类型名、组件 props、样式数值、层级分层等实现细节
|
||||
- 用户可感知或对外暴露的契约可以保留：公开 API 路径、请求/响应字段、协议名、错误码、数据约束、交互结果
|
||||
- `Requirement` 和 `Scenario` 应描述业务能力、外部行为或稳定约束，不以“使用某层/某组件/某库实现”作为标题或核心表述
|
||||
- 不把当前代码自动视为唯一真相；若代码、README、现有 spec 冲突且无法判断应以哪边为准，列入待确认清单，不直接改写规范
|
||||
- 仅删除内容已被其他规范完整覆盖且无独立检索价值的规范；非冗余内容仅迁移、合并、拆分或重命名
|
||||
- 每批重构执行前用提问工具获得用户确认；删除或重写前先备份原文件为 `{file}.bak.{timestamp}`
|
||||
- 命名、Purpose、Requirement 标题都必须保留用户下一次最可能搜索的业务关键词
|
||||
|
||||
## 1. 收集
|
||||
|
||||
并行读取：
|
||||
|
||||
- `openspec/config.yaml`
|
||||
- `README.md`，以及与模块结构、API、架构相关的 README 或文档
|
||||
- `openspec/specs/*/spec.md`
|
||||
|
||||
默认不读取 `openspec/changes/**`、历史 proposal/design/tasks 作为稳定规范整理依据；仅在用户明确要求“连同历史变更一起校对”时再纳入。
|
||||
|
||||
先建立索引，不直接开始改写：
|
||||
|
||||
| 索引 | 内容 |
|
||||
| -------------- | ----------------------------------------------------------------------------- |
|
||||
| `spec_index[]` | 每个 spec 的目录名、Purpose、Requirement 摘要、关键词、外部契约、疑似重叠对象 |
|
||||
| `domain_map[]` | 从 README、API、模块文档中提炼的核心业务域、横切能力和术语 |
|
||||
| `term_map[]` | 同义词、旧名、缩写和推荐标准术语 |
|
||||
| `suspects[]` | 需要进一步对照代码或测试确认的 spec |
|
||||
|
||||
仅对 `suspects[]` 做定向读取：
|
||||
|
||||
- 读取与该 spec 对应的源码、测试、README 或架构文档
|
||||
- 不对 `backend/`、`frontend/` 做无差别逐文件扫描
|
||||
|
||||
判定依据优先级：
|
||||
|
||||
- 当前稳定 spec 与 README 共同支持的事实，可直接视为高置信度
|
||||
- 仅代码可见但 README 和 spec 未体现的内容，先判断它是稳定外部行为还是临时实现细节
|
||||
- 代码、README、现有 spec 互相冲突且无法自动定夺时，进入 `待确认清单`
|
||||
|
||||
## 2. 审查
|
||||
|
||||
按 spec、Requirement、Scenario 三层检查：
|
||||
|
||||
| 维度 | 检查点 |
|
||||
| --------- | --------------------------------------------------------------------------------- |
|
||||
| 过时 | 描述的能力、术语、外部契约是否仍成立；是否存在 `TBD`、`TODO`、占位说明 |
|
||||
| 冲突 | 不同规范是否对同一行为给出不同约束、命名或边界 |
|
||||
| 重复/重叠 | 是否在文件级、Requirement 级、Scenario 级重复描述同一能力 |
|
||||
| 错位 | 内容是否放错能力域；横切规则是否混入实体规范；平台实现是否混入通用能力规范 |
|
||||
| 粒度 | 是否过大导致难检索，或过碎导致回答一个问题必须同时打开多个 spec |
|
||||
| 术语 | 同一概念是否混用多个名字；旧名、别名、缩写是否需要归一并保留检索入口 |
|
||||
| 命名/检索 | 目录名、Purpose、Requirement 标题是否准确；是否能被 README、API、业务术语直接命中 |
|
||||
| 规范性 | 是否使用 SHALL/WHEN/THEN；是否混入变更记录、迁移说明、内部实现或 UI/代码细节 |
|
||||
| 完整性 | Purpose 是否明确；是否存在空目录、非 spec 噪音文件、无清晰归属的孤立规范 |
|
||||
|
||||
重构判定规则：
|
||||
|
||||
- 若两个 spec 回答的是同一个核心问题，或其中一个只是另一个的子集，优先合并
|
||||
- 若一个 spec 混合多个独立检索意图，或同时包含横切规则与业务流程，优先拆分
|
||||
- 若内容正确但目录名、Purpose 或 Requirement 标题不利于检索，优先重命名或改写标题
|
||||
- 若多个术语指向同一概念，统一到一个标准术语，并在 Purpose 或 Requirement 中保留必要别名以支持搜索
|
||||
- 若某段内容只是内部实现细节，且不影响外部行为理解，删除该段而不是为其单独保留 spec
|
||||
- 若某个具体值同时属于外部契约与内部实现，按“是否对调用方可见、是否影响兼容性”判断是否保留
|
||||
|
||||
### 命名约定
|
||||
|
||||
命名优先复用仓库已存在的稳定术语，如 `provider`、`model`、`stats`、`protocol`、`proxy`、`logging`、`validation`、`migration`、`frontend`、`desktop`、`mysql`。
|
||||
|
||||
| 类型 | 模式 | 示例 |
|
||||
| ------------ | ---------------------------------------------------------- | -------------------------------------------------- |
|
||||
| 实体生命周期 | `{entity}-management` | `provider-management`、`model-management` |
|
||||
| 横切能力 | `{concern}` 或 `{concern}-{qualifier}` | `error-handling`、`structured-logging` |
|
||||
| 协议/适配 | `{protocol}-{capability}` 或 `protocol-adapter-{protocol}` | `openai-protocol-proxy`、`protocol-adapter-openai` |
|
||||
| 运行面/入口 | `{surface}` 或 `{surface}-{capability}` | `frontend`、`desktop-app` |
|
||||
| 基础设施 | `{resource}-{operation}` | `database-migration`、`mysql-driver` |
|
||||
|
||||
命名原则：
|
||||
|
||||
- 1-4 个词，保持单一主题
|
||||
- 优先使用业务名词，不使用 `basic`、`general`、`misc`、`info`、`data` 等泛化词
|
||||
- 不使用 `crud`、`list`、`table`、`display` 等实现模式词，除非它本身就是外部契约的一部分
|
||||
- 同一主题的命名模式保持一致，不同时混用多套前后缀
|
||||
|
||||
## 3. 报告
|
||||
|
||||
输出分析结果：
|
||||
|
||||
1. **问题总览表**：问题类型 × 涉及规范数
|
||||
2. **规范关系表**：每个 spec 的主主题、重叠对象、冲突对象、建议动作
|
||||
3. **术语归一表**：旧术语 / 别名 / 缩写 → 推荐标准术语
|
||||
4. **逐项分析**：每个有问题的规范说明位置、问题、影响、建议和目标规范
|
||||
5. **待确认清单**：代码、README、现有 spec 冲突且无法自动定夺的事项
|
||||
6. **重构方案**：按优先级分批
|
||||
7. **重构后目录结构**：预期的新 `openspec/specs/` 目录树
|
||||
|
||||
优先级建议：
|
||||
|
||||
- P0：删除空目录、非 spec 噪音文件、占位内容
|
||||
- P1：删除完全冗余规范；将其内容映射到主规范
|
||||
- P2：合并重复/子集规范；拆分错位或过大规范
|
||||
- P3：重命名目录、改写 Purpose 和 Requirement 标题以提升检索性
|
||||
- P4：修正过时描述，清理实现细节、迁移说明和变更记录
|
||||
|
||||
若所有问题清单为空，输出“审查通过，未发现问题”，跳至步骤 5。
|
||||
|
||||
## 4. 计划（用户确认）
|
||||
|
||||
先针对 `待确认清单` 用提问工具逐项向用户确认。
|
||||
|
||||
再按批次展示完整重构计划，每批必须包含：
|
||||
|
||||
- 操作类型：删除、重命名、迁移、合并、拆分、改写
|
||||
- 路径变化：源路径 → 目标路径
|
||||
- 内容映射：源 spec 的 Requirement / Scenario 将迁移到哪里
|
||||
- 术语处理：哪些旧词保留为检索入口，哪些词统一替换
|
||||
- 执行原因：为什么这样做更利于检索、去重和边界清晰
|
||||
- 验证方式：如何确认没有丢失约束或引入新的冲突
|
||||
|
||||
用提问工具获得当前批次确认后再执行。
|
||||
|
||||
## 5. 执行
|
||||
|
||||
按 P0 → P4 逐批执行已确认的重构。
|
||||
|
||||
执行要求：
|
||||
|
||||
- 合并或拆分时先写目标 spec，再删除或重命名源 spec
|
||||
- 删除前确认其 Requirement 和 Scenario 已被完整保留、迁移或判定为纯冗余
|
||||
- 每批执行后重新读取受影响的 spec，并复核结构和内容
|
||||
|
||||
每批执行后至少验证：
|
||||
|
||||
- 目录结构完整，`openspec/specs/*/spec.md` 可正常读取
|
||||
- 不存在未承接的 Requirement 或 Scenario
|
||||
- Purpose、Requirement 标题、目录名可以直接表达主能力
|
||||
- 不再包含 `TBD`、变更记录、迁移说明、内部实现细节或噪音文件
|
||||
- 若本批涉及代码对照项，相关外部契约描述与当前仓库现状一致，或已列入残留待确认
|
||||
|
||||
收尾时输出：修改文件清单、备份文件清单、最终目录树、残留待确认事项和整理摘要。
|
||||
31
docs/user/README.md
Normal file
31
docs/user/README.md
Normal 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
106
docs/user/config.md
Normal 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
54
docs/user/deploy.md
Normal 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
61
docs/user/troubleshoot.md
Normal 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
65
docs/user/usage.md
Normal 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) — 开发规范、架构和质量门禁
|
||||
@@ -6,6 +6,9 @@ import reactHooks from "eslint-plugin-react-hooks";
|
||||
import reactRefresh from "eslint-plugin-react-refresh";
|
||||
import tseslint from "typescript-eslint";
|
||||
|
||||
const noDirectConsoleMessage =
|
||||
"后端运行时代码禁止直接使用 console.*；请通过注入的 Logger 实例输出日志，配置加载失败前使用 createConsoleFallback()。";
|
||||
|
||||
export default tseslint.config(
|
||||
{
|
||||
ignores: [
|
||||
@@ -44,6 +47,7 @@ export default tseslint.config(
|
||||
"@typescript-eslint/array-type": ["error", { default: "array-simple" }],
|
||||
"@typescript-eslint/consistent-type-assertions": ["error", { assertionStyle: "as" }],
|
||||
"@typescript-eslint/consistent-type-imports": ["error", { prefer: "type-imports" }],
|
||||
"@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
|
||||
"@typescript-eslint/only-throw-error": "error",
|
||||
"@typescript-eslint/prefer-nullish-coalescing": "error",
|
||||
"@typescript-eslint/prefer-optional-chain": "error",
|
||||
@@ -58,6 +62,19 @@ export default tseslint.config(
|
||||
"import/no-named-as-default-member": "off",
|
||||
},
|
||||
},
|
||||
{
|
||||
files: ["src/server/**/*.ts"],
|
||||
ignores: ["src/server/logger.ts"],
|
||||
rules: {
|
||||
"no-restricted-syntax": [
|
||||
"error",
|
||||
{
|
||||
message: noDirectConsoleMessage,
|
||||
selector: "MemberExpression[object.name='console']",
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
{
|
||||
files: ["src/web/**/*.{ts,tsx}"],
|
||||
plugins: {
|
||||
|
||||
@@ -1,2 +0,0 @@
|
||||
schema: spec-driven
|
||||
created: 2026-05-20
|
||||
@@ -1,95 +0,0 @@
|
||||
## Context
|
||||
|
||||
当前前端为单页面应用，`app.tsx` 直接渲染 Header + Content，无路由、无侧边栏。技术栈为 React 19 + TDesign React + TanStack Query + Vite。后端使用 Bun.serve，已支持 SPA fallback（无扩展名路径返回 index.html）。
|
||||
|
||||
目标：重构为经典企业 Admin 后台布局，引入路由，支持多页面导航。
|
||||
|
||||
约束：
|
||||
- 前端样式开发优先使用 TDesign 组件和 CSS tokens，禁止内联 style、硬编码色值
|
||||
- 新增代码需编写完善测试
|
||||
- 后端无需改动
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 引入 React Router v7 (Declarative mode) 实现 SPA 路由
|
||||
- 实现企业 Admin 后台布局：Header + 侧边栏 + 内容区
|
||||
- 侧边栏支持折叠/展开，状态持久化到 localStorage
|
||||
- 路由定义与菜单配置统一为单一数据源
|
||||
- 提供示例页面（仪表盘、用户管理、系统设置、404）
|
||||
|
||||
**Non-Goals:**
|
||||
- 不实现路由守卫/权限控制（预留接口但不启用）
|
||||
- 不实现懒加载（页面少，暂不需要）
|
||||
- 不实现面包屑导航
|
||||
- 不实现用户认证
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. 路由方案：React Router v7 Declarative mode
|
||||
|
||||
**选择**：`react-router` v7，使用 Declarative mode（`BrowserRouter` + `Routes` + `Route`）
|
||||
|
||||
**理由**：
|
||||
- v7 统一了 `react-router` 和 `react-router-dom`，单包导入
|
||||
- Declarative mode 满足当前需求，无需 framework mode 的文件系统路由
|
||||
- 社区成熟，文档完善
|
||||
|
||||
**替代方案**：
|
||||
- TanStack Router：类型安全强，但较新、API 变动风险
|
||||
- 自实现：零依赖但功能有限，扩展成本高
|
||||
|
||||
### 2. Routes 定义位置：独立文件
|
||||
|
||||
**选择**：抽离为 `src/web/routes.tsx`，`app.tsx` 引用
|
||||
|
||||
**理由**：
|
||||
- 路由增删时改动范围小，不污染 app.tsx
|
||||
- 便于后续扩展路由守卫、懒加载
|
||||
|
||||
### 3. 侧边栏折叠按钮位置：Header 左侧
|
||||
|
||||
**选择**：折叠按钮放在 Header 左侧，Sidebar 不使用 Menu 的 operations prop
|
||||
|
||||
**理由**：
|
||||
- Sidebar 折叠变窄后，底部按钮变小且易被忽略
|
||||
- Header 上的按钮始终可见且易触达
|
||||
- 符合 Ant Design Pro 等主流企业后台习惯
|
||||
|
||||
### 4. 页面标题来源：复用 menu label
|
||||
|
||||
**选择**：Header 页面标题直接使用 `menu.tsx` 中的 `label` 字段
|
||||
|
||||
**理由**：
|
||||
- 简单直接，侧边栏标签即页面标题
|
||||
- 如需差异化，后续加 `title` 字段即可
|
||||
|
||||
### 5. Layout 嵌套：保留嵌套结构
|
||||
|
||||
**选择**：`Layout > (Header + Layout > (Aside + Content))`
|
||||
|
||||
**理由**：
|
||||
- 为 Footer 预留位置，将来加 Footer 无需重构
|
||||
- 符合 TDesign 官方组合导航布局示例
|
||||
|
||||
### 6. Vite code splitting：react-router 单独分组
|
||||
|
||||
**选择**：新增 `vendor-router` 组，包含 `react-router`
|
||||
|
||||
**理由**：
|
||||
- 路由库独立于 React 核心，更新节奏不同
|
||||
- 便于缓存隔离
|
||||
|
||||
### 7. 菜单与路由数据源：menu.tsx
|
||||
|
||||
**选择**：`src/web/menu.tsx` 定义菜单项配置，Sidebar 和 Routes 共同引用
|
||||
|
||||
**理由**：
|
||||
- 单一数据源，保证菜单项和路由同步
|
||||
- 便于类型安全（`as const`）
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **路由与菜单配置一致性**：需人工保证 `menu.tsx` 与 `routes.tsx` 中 Route 定义一致 → 测试覆盖路由跳转和菜单点击
|
||||
- **CSS 类名迁移影响**：`.dashboard-*` → `.app-*` 可能影响测试选择器 → 全局搜索确认影响范围，更新测试
|
||||
- **React Router v7 新版本风险**：v7 较新，可能存在未发现的 bug → 使用成熟 API（BrowserRouter/Routes/Route），避免实验性特性
|
||||
@@ -1,36 +0,0 @@
|
||||
## Why
|
||||
|
||||
当前前端为单页面应用，仅有 Header + Content 的简单布局，无路由、无侧边栏，页面结构单一，无法支撑企业级 Admin 后台的多页面导航需求。作为 Bun 全栈应用模板，需要提供更完善的前端布局范例，便于使用者在此基础上扩展业务页面。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 引入 React Router v7 (Declarative mode) 实现前端 SPA 路由
|
||||
- 重构 Layout 为经典企业 Admin 后台布局：Header + 侧边栏 + 内容区
|
||||
- 新增侧边栏菜单组件，支持折叠/展开，折叠状态持久化到 localStorage
|
||||
- 新增多个示例页面（仪表盘、用户管理、系统设置、404）
|
||||
- 将路由定义与菜单配置统一为单一数据源，保证两者同步
|
||||
- 新增 `react-router` 依赖，Vite code splitting 单独分组
|
||||
|
||||
**BREAKING**: 原 `app.tsx` 的 Content 内容迁移至 Dashboard 页面；CSS 类名 `.dashboard-*` 变更为 `.app-*`
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `frontend-routing`: 前端 SPA 路由能力，基于 React Router v7，支持多页面导航、路由匹配、404 处理
|
||||
- `admin-layout`: 企业 Admin 后台布局能力，Header + 侧边栏 + 内容区，侧边栏可折叠
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `app-constants`: 新增 localStorage key `"sidebar.collapsed"` 用于持久化侧边栏折叠状态
|
||||
|
||||
## Impact
|
||||
|
||||
- 新增依赖：`react-router`
|
||||
- 新增目录：`src/web/pages/`、`src/web/components/Sidebar/`
|
||||
- 新增文件：`src/web/routes.tsx`、`src/web/menu.tsx`、`src/web/hooks/use-sidebar-collapsed.ts`
|
||||
- 修改文件：`src/web/app.tsx`（重构 Layout）、`src/web/main.tsx`（+ BrowserRouter）、`src/web/styles.css`（布局样式重写）
|
||||
- 修改配置：`vite.config.ts`（code splitting 新增 vendor-router 组）
|
||||
- 更新文档：`DEVELOPMENT.md`、`README.md`
|
||||
- 新增测试：Sidebar 组件测试、各页面测试、test-utils 增强
|
||||
- 后端无需改动（SPA fallback 已支持）
|
||||
@@ -1,138 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 企业 Admin 后台布局
|
||||
|
||||
系统 SHALL 实现 Header + 侧边栏 + 内容区的企业 Admin 后台布局，使用 TDesign Layout 组件。
|
||||
|
||||
#### Scenario: 布局结构
|
||||
|
||||
- **WHEN** 用户访问应用
|
||||
- **THEN** 系统 SHALL 渲染包含 Header、Aside、Content 的 Layout 结构
|
||||
|
||||
#### Scenario: Layout 嵌套结构
|
||||
|
||||
- **WHEN** 布局渲染
|
||||
- **THEN** 系统 SHALL 使用嵌套 Layout 结构：`Layout > (Header + Layout > (Aside + Content))`
|
||||
|
||||
### Requirement: Header 布局
|
||||
|
||||
Header SHALL 包含折叠按钮、页面标题、主题切换控件。
|
||||
|
||||
#### Scenario: Header 左侧折叠按钮
|
||||
|
||||
- **WHEN** Header 渲染
|
||||
- **THEN** 系统 SHALL 在左侧显示侧边栏折叠/展开按钮
|
||||
|
||||
#### Scenario: Header 页面标题
|
||||
|
||||
- **WHEN** Header 渲染
|
||||
- **THEN** 系统 SHALL 显示当前路由对应的页面标题（从 menu 获取）
|
||||
|
||||
#### Scenario: Header 右侧主题切换
|
||||
|
||||
- **WHEN** Header 渲染
|
||||
- **THEN** 系统 SHALL 在右侧显示主题切换 RadioGroup（系统/明亮/黑暗）
|
||||
|
||||
### Requirement: 侧边栏菜单
|
||||
|
||||
系统 SHALL 提供侧边栏菜单组件（Sidebar），使用 TDesign Menu 组件，支持折叠/展开。
|
||||
|
||||
#### Scenario: 侧边栏渲染菜单项
|
||||
|
||||
- **WHEN** 侧边栏渲染
|
||||
- **THEN** 系统 SHALL 根据 `menu.tsx` 渲染所有菜单项
|
||||
|
||||
#### Scenario: 菜单项点击导航
|
||||
|
||||
- **WHEN** 用户点击菜单项
|
||||
- **THEN** 系统 SHALL 使用 React Router 的 `navigate` 跳转到对应路径
|
||||
|
||||
#### Scenario: 菜单项激活状态
|
||||
|
||||
- **WHEN** 当前路由与菜单项路径匹配
|
||||
- **THEN** 系统 SHALL 高亮显示该菜单项
|
||||
|
||||
### Requirement: 侧边栏折叠
|
||||
|
||||
侧边栏 SHALL 支持折叠/展开，折叠状态持久化到 localStorage。
|
||||
|
||||
#### Scenario: 侧边栏折叠交互
|
||||
|
||||
- **WHEN** 用户点击 Header 左侧的折叠按钮
|
||||
- **THEN** 系统 SHALL 切换侧边栏折叠状态
|
||||
|
||||
#### Scenario: 侧边栏折叠宽度
|
||||
|
||||
- **WHEN** 侧边栏折叠
|
||||
- **THEN** Aside 宽度 SHALL 变为 80px，Menu 仅显示图标
|
||||
|
||||
#### Scenario: 侧边栏展开宽度
|
||||
|
||||
- **WHEN** 侧边栏展开
|
||||
- **THEN** Aside 宽度 SHALL 变为 232px，Menu 显示图标和文字
|
||||
|
||||
#### Scenario: 折叠状态持久化
|
||||
|
||||
- **WHEN** 用户切换侧边栏折叠状态
|
||||
- **THEN** 系统 SHALL 将状态存储到 localStorage key `"sidebar.collapsed"`
|
||||
|
||||
#### Scenario: 折叠状态恢复
|
||||
|
||||
- **WHEN** 应用初始化
|
||||
- **THEN** 系统 SHALL 从 localStorage 读取 `"sidebar.collapsed"` 并恢复折叠状态
|
||||
|
||||
### Requirement: 侧边栏主题跟随全局
|
||||
|
||||
侧边栏 Menu 的主题 SHALL 跟随全局主题设置，不单独设置 `theme` prop。
|
||||
|
||||
#### Scenario: 侧边栏跟随全局主题
|
||||
|
||||
- **WHEN** 全局主题切换为 dark
|
||||
- **THEN** 侧边栏 SHALL 自动应用 dark 主题样式
|
||||
|
||||
### Requirement: 菜单配置单一数据源
|
||||
|
||||
系统 SHALL 在 `src/web/menu.tsx` 定义菜单项配置，包含 `value`、`label`、`path`、`icon` 字段。
|
||||
|
||||
#### Scenario: 菜单配置类型安全
|
||||
|
||||
- **WHEN** 定义菜单配置
|
||||
- **THEN** 系统 SHALL 使用 `as const` 保证字面量类型推断
|
||||
|
||||
#### Scenario: Sidebar 引用菜单配置
|
||||
|
||||
- **WHEN** Sidebar 渲染
|
||||
- **THEN** 系统 SHALL 遍历 `MENU_ITEMS` 渲染 MenuItem
|
||||
|
||||
### Requirement: 示例页面
|
||||
|
||||
系统 SHALL 提供示例页面组件：Dashboard、Users、Settings、NotFound。
|
||||
|
||||
#### Scenario: Dashboard 页面
|
||||
|
||||
- **WHEN** 用户访问 `/`
|
||||
- **THEN** 系统 SHALL 渲染 Dashboard 页面（包含原 app.tsx 的欢迎语和 /health 展示）
|
||||
|
||||
#### Scenario: Users 页面占位
|
||||
|
||||
- **WHEN** 用户访问 `/users`
|
||||
- **THEN** 系统 SHALL 渲染用户管理占位页面
|
||||
|
||||
#### Scenario: Settings 页面占位
|
||||
|
||||
- **WHEN** 用户访问 `/settings`
|
||||
- **THEN** 系统 SHALL 渲染系统设置占位页面
|
||||
|
||||
#### Scenario: NotFound 页面
|
||||
|
||||
- **WHEN** 用户访问未定义路径
|
||||
- **THEN** 系统 SHALL 渲染 404 页面，提供返回首页按钮
|
||||
|
||||
### Requirement: CSS 类名迁移
|
||||
|
||||
原 `.dashboard-*` CSS 类名 SHALL 变更为 `.app-*`。
|
||||
|
||||
#### Scenario: 布局类名
|
||||
|
||||
- **WHEN** 样式应用
|
||||
- **THEN** 系统 SHALL 使用 `.app-layout`、`.app-header`、`.app-content`、`.app-sidebar` 类名
|
||||
@@ -1,15 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 侧边栏折叠状态 localStorage key
|
||||
|
||||
侧边栏折叠状态存储 key SHALL 为 `"sidebar.collapsed"`，不包含应用名前缀。
|
||||
|
||||
#### Scenario: 折叠状态持久化
|
||||
|
||||
- **WHEN** 用户切换侧边栏折叠状态
|
||||
- **THEN** 系统 SHALL 将状态存储到 localStorage key `"sidebar.collapsed"`
|
||||
|
||||
#### Scenario: 折叠状态读取
|
||||
|
||||
- **WHEN** 应用初始化时读取侧边栏折叠状态
|
||||
- **THEN** 系统 SHALL 从 localStorage key `"sidebar.collapsed"` 读取
|
||||
@@ -1,57 +0,0 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 前端 SPA 路由
|
||||
|
||||
系统 SHALL 使用 React Router v7 (Declarative mode) 实现前端 SPA 路由，支持多页面导航。
|
||||
|
||||
#### Scenario: 应用启动时初始化路由
|
||||
|
||||
- **WHEN** 应用启动
|
||||
- **THEN** 系统 SHALL 在 `main.tsx` 中使用 `BrowserRouter` 包裹根组件
|
||||
|
||||
#### Scenario: 路由匹配渲染对应页面
|
||||
|
||||
- **WHEN** 用户访问路径 `/`
|
||||
- **THEN** 系统 SHALL 渲染 Dashboard 页面
|
||||
|
||||
#### Scenario: 用户管理页面路由
|
||||
|
||||
- **WHEN** 用户访问路径 `/users`
|
||||
- **THEN** 系统 SHALL 渲染用户管理页面
|
||||
|
||||
#### Scenario: 系统设置页面路由
|
||||
|
||||
- **WHEN** 用户访问路径 `/settings`
|
||||
- **THEN** 系统 SHALL 渲染系统设置页面
|
||||
|
||||
#### Scenario: 未知路径返回 404 页面
|
||||
|
||||
- **WHEN** 用户访问未定义的路径（如 `/unknown`）
|
||||
- **THEN** 系统 SHALL 渲染 NotFound 页面
|
||||
|
||||
### Requirement: 路由定义独立文件
|
||||
|
||||
路由定义 SHALL 抽离为独立文件 `src/web/routes.tsx`，`app.tsx` 引用该文件。
|
||||
|
||||
#### Scenario: 路由配置集中管理
|
||||
|
||||
- **WHEN** 开发者需要新增或修改路由
|
||||
- **THEN** 系统 SHALL 在 `routes.tsx` 中统一管理所有 `<Route>` 定义
|
||||
|
||||
### Requirement: 路由守卫预留
|
||||
|
||||
系统 SHALL 预留路由守卫接口（`ProtectedRoute` 组件），但暂不实现认证逻辑。
|
||||
|
||||
#### Scenario: 路由守卫组件存在
|
||||
|
||||
- **WHEN** 需要实现认证保护
|
||||
- **THEN** 系统 SHALL 提供 `ProtectedRoute` wrapper 组件供 Routes 使用
|
||||
|
||||
### Requirement: Vite code splitting 包含路由库
|
||||
|
||||
`vite.config.ts` 的 code splitting 配置 SHALL 新增 `vendor-router` 组，包含 `react-router`。
|
||||
|
||||
#### Scenario: 路由库独立分包
|
||||
|
||||
- **WHEN** 执行生产构建
|
||||
- **THEN** `react-router` SHALL 被打包到独立的 `vendor-router` chunk 中
|
||||
@@ -1,56 +0,0 @@
|
||||
## 1. 依赖与配置
|
||||
|
||||
- [x] 1.1 安装 react-router 依赖
|
||||
- [x] 1.2 更新 vite.config.ts code splitting 配置，新增 vendor-router 组
|
||||
|
||||
## 2. 工具与 Hook
|
||||
|
||||
- [x] 2.1 创建 src/web/menu.tsx，定义菜单项配置
|
||||
- [x] 2.2 创建 src/web/hooks/use-sidebar-collapsed.ts，实现侧边栏折叠状态 hook
|
||||
|
||||
## 3. 页面组件
|
||||
|
||||
- [x] 3.1 创建 src/web/pages/dashboard/index.tsx，迁移原 app.tsx 内容区逻辑
|
||||
- [x] 3.2 创建 src/web/pages/users/index.tsx，实现用户管理占位页面
|
||||
- [x] 3.3 创建 src/web/pages/settings/index.tsx，实现系统设置占位页面
|
||||
- [x] 3.4 创建 src/web/pages/404/index.tsx，实现 404 页面
|
||||
|
||||
## 4. 侧边栏组件
|
||||
|
||||
- [x] 4.1 创建 src/web/components/Sidebar/index.tsx，实现侧边栏菜单组件
|
||||
|
||||
## 5. 路由配置
|
||||
|
||||
- [x] 5.1 创建 src/web/routes.tsx，定义所有路由
|
||||
|
||||
## 6. 根组件重构
|
||||
|
||||
- [x] 6.1 重构 src/web/app.tsx，实现 Header + Aside + Content 布局
|
||||
- [x] 6.2 修改 src/web/main.tsx，添加 BrowserRouter 包裹
|
||||
|
||||
## 7. 样式更新
|
||||
|
||||
- [x] 7.1 更新 src/web/styles.css，迁移 .dashboard-* 为 .app-*，新增布局样式
|
||||
|
||||
## 8. 测试工具增强
|
||||
|
||||
- [x] 8.1 增强 tests/web/test-utils.tsx，提供 renderWithProviders 函数
|
||||
|
||||
## 9. 组件测试
|
||||
|
||||
- [x] 9.1 创建 tests/web/components/Sidebar/index.test.tsx
|
||||
- [x] 9.2 创建 tests/web/routes/dashboard.test.tsx
|
||||
- [x] 9.3 创建 tests/web/routes/users.test.tsx
|
||||
- [x] 9.4 创建 tests/web/routes/settings.test.tsx
|
||||
- [x] 9.5 创建 tests/web/routes/404.test.tsx
|
||||
- [x] 9.6 更新 tests/web/App.test.tsx 适配 BrowserRouter
|
||||
|
||||
## 10. 文档更新
|
||||
|
||||
- [x] 10.1 更新 DEVELOPMENT.md，更新技术栈表格、组件树、目录结构说明
|
||||
- [x] 10.2 更新 README.md，更新技术栈表格、项目结构说明
|
||||
|
||||
## 11. 质量保障
|
||||
|
||||
- [x] 11.1 运行 bun run check 确保类型检查、lint、测试通过
|
||||
- [x] 11.2 运行 bun run build 验证构建成功
|
||||
@@ -1,10 +1,17 @@
|
||||
schema: spec-driven
|
||||
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,15 +24,14 @@ context: |
|
||||
- 禁止创建git操作task
|
||||
- 积极使用subagents精心设计并行任务，节省上下文空间，加速任务执行
|
||||
- 优先使用提问工具对用户进行提问
|
||||
- 本项目为 Bun 全栈应用模板，README.md记录模板使用方法，DEVELOPMENT.md记录模板使用的技术细节
|
||||
- 本项目为 Bun 全栈应用模板，docs/user/ 记录模板使用方法，docs/development/ 记录模板开发技术细节
|
||||
- 本项目为模板参考项目，帮助其他项目快速启动项目，因此开发本项目无需考虑兼容性问题
|
||||
|
||||
rules:
|
||||
proposal:
|
||||
- 仔细审查每一个过往spec判断是否存在Modified Capabilities
|
||||
design:
|
||||
- 先前的讨论技术方案要尽可能体现在设计文档中，便于指导实现阶段不偏离已定的技术路线
|
||||
tasks:
|
||||
- 一行一个任务，严禁任务内容跨行
|
||||
- 如果是代码存在更新必须
|
||||
- 执行完整的测试、代码检查、格式检查等质量保障手段
|
||||
- 更新 README.md 和/或 DEVELOPMENT.md
|
||||
- 执行文档影响分析，更新 README.md 和/或 docs/ 下对应文档
|
||||
|
||||
181
openspec/schemas/fast-drive/schema.yaml
Normal file
181
openspec/schemas/fast-drive/schema.yaml
Normal file
@@ -0,0 +1,181 @@
|
||||
name: fast-drive
|
||||
version: 1
|
||||
description: Fast OpenSpec workflow - design -> tasks -> apply
|
||||
artifacts:
|
||||
- id: design
|
||||
generates: design.md
|
||||
description: Self-contained solution brief and execution plan
|
||||
template: design.md
|
||||
instruction: |
|
||||
Create design.md as the self-contained source of truth for what will
|
||||
change, why it is changing, and how the work will be executed.
|
||||
|
||||
This workflow does not use proposal or specs artifacts. design.md MUST
|
||||
preserve the important outcomes from prior exploration and user
|
||||
discussion so a later apply phase can proceed correctly even after
|
||||
context compression or in a new session.
|
||||
|
||||
Write for someone who cannot see the earlier conversation. Keep simple
|
||||
changes concise, but include enough detail to make execution
|
||||
unambiguous. Add more detail when any apply:
|
||||
|
||||
- Cross-cutting change across multiple systems, teams, workstreams, or
|
||||
artifacts
|
||||
|
||||
- New dependency, integration, vendor, tool, policy, or external input
|
||||
|
||||
- Significant information model, process model, data model, or ownership
|
||||
changes
|
||||
|
||||
- Security, privacy, compliance, performance, operational, or migration
|
||||
complexity
|
||||
|
||||
- Ambiguity that benefits from decisions before execution
|
||||
|
||||
- Prior discussion settled non-obvious requirements, constraints, or
|
||||
rejected alternatives
|
||||
|
||||
Required sections:
|
||||
|
||||
- **Context**: Problem, current state, relevant references, and the user
|
||||
request that triggered this change
|
||||
|
||||
- **Discussion Notes**: Key points from exploration or prior discussion
|
||||
that must not be lost. Include agreed conclusions, user preferences,
|
||||
constraints, and important rejected ideas.
|
||||
|
||||
- **Requirements**: Expected outcomes, behavior/process/interface/content
|
||||
changes, continuity expectations, and acceptance criteria.
|
||||
|
||||
- **Goals / Non-Goals**: What this change will achieve and what is
|
||||
explicitly out of scope.
|
||||
|
||||
- **Execution Guardrails**: Must-follow constraints, forbidden approaches,
|
||||
preserved behavior/processes, dependency limits, and project- or
|
||||
workflow-specific boundaries.
|
||||
|
||||
- **Affected Areas**: Concrete artifacts, references, stakeholders,
|
||||
systems, workstreams, documents, configurations, assets, or handoffs that
|
||||
are relevant to the change.
|
||||
|
||||
- **Decisions**: Key choices with rationale (why X over Y?). For each
|
||||
important decision, include alternatives considered and why they were not
|
||||
chosen.
|
||||
|
||||
- **Execution Plan**: Main workstreams or artifacts to change, integration
|
||||
or handoff points, sequencing, and any rollout notes.
|
||||
|
||||
- **Verification Plan**: Validation checks, reviews, approvals,
|
||||
acceptance checks, documentation checks, communication checks, and manual
|
||||
checks needed to prove the change is complete.
|
||||
|
||||
- **Risks / Trade-offs**: Known limitations and things that could go
|
||||
wrong.
|
||||
Format: [Risk] -> Mitigation
|
||||
|
||||
- **Open Questions**: Outstanding decisions, assumptions, or unknowns to
|
||||
resolve before execution. Separate blocking questions that must pause
|
||||
apply from non-blocking follow-ups. Use "None" if there are no open
|
||||
questions.
|
||||
|
||||
Optional sections when relevant:
|
||||
|
||||
- **Migration / Rollout Plan**: Rollout steps, communication, ownership,
|
||||
rollback, or continuity strategy.
|
||||
|
||||
Focus on preserving requirements, rationale, constraints, and approach.
|
||||
Avoid line-by-line or step-by-step details unless a detail is a deliberate
|
||||
decision from the discussion.
|
||||
|
||||
Prefer durable summaries over chat transcripts. Use concrete artifact
|
||||
names, data/information shapes, examples, stakeholders, ownership, and
|
||||
edge cases when they affect execution.
|
||||
|
||||
Do not use task checkboxes in design.md; checkboxes belong only in
|
||||
tasks.md.
|
||||
|
||||
Final design.md must not contain unresolved template comments, empty
|
||||
table rows, or placeholder text.
|
||||
|
||||
If information is missing, state assumptions and open questions instead
|
||||
of inventing hidden requirements. Do not rely on unstated chat context.
|
||||
requires: []
|
||||
- id: tasks
|
||||
generates: tasks.md
|
||||
description: Trackable execution checklist derived from design.md
|
||||
template: tasks.md
|
||||
instruction: |
|
||||
Create tasks.md by breaking design.md into executable work.
|
||||
|
||||
**IMPORTANT: Follow the template below exactly.** The apply phase parses
|
||||
checkbox format to track progress. Tasks not using `- [ ]` will not be
|
||||
tracked.
|
||||
|
||||
Guidelines:
|
||||
|
||||
- Derive tasks from design.md. Do not depend on proposal.md or specs
|
||||
artifacts; any relevant prior discussion must already be captured in
|
||||
design.md.
|
||||
|
||||
- Group related tasks under `##` numbered headings
|
||||
|
||||
- Each task MUST be a single-line checkbox: `- [ ] X.Y Task description`
|
||||
|
||||
- Tasks should be small enough to complete in one session
|
||||
|
||||
- Order tasks by dependency (what must be done first?)
|
||||
|
||||
- Start with context review tasks when execution depends on guardrails,
|
||||
affected areas, or open questions
|
||||
|
||||
- Include validation tasks for checks, reviews, approvals, acceptance,
|
||||
documentation, communication, and manual checks when required
|
||||
|
||||
- Do not include repository, version-control, or release operation tasks
|
||||
unless they are explicitly part of the change scope
|
||||
|
||||
- Final tasks.md must not contain unresolved template comments, empty
|
||||
table rows, or placeholder task text
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
## 1. Context Review
|
||||
|
||||
- [ ] 1.1 Read design.md and identify scope, requirements, decisions, guardrails, and open questions
|
||||
- [ ] 1.2 Review relevant artifacts and references listed in Affected Areas
|
||||
|
||||
## 2. Execution
|
||||
|
||||
- [ ] 2.1 Execute first concrete work item from design.md
|
||||
- [ ] 2.2 Execute next concrete work item from design.md
|
||||
|
||||
## 3. Validation
|
||||
|
||||
- [ ] 3.1 Run required validation from Verification Plan
|
||||
- [ ] 3.2 Perform quality checks required by the project or workflow
|
||||
- [ ] 3.3 Perform required manual review or acceptance checks from Verification Plan
|
||||
|
||||
## 4. Documentation / Communication
|
||||
|
||||
- [ ] 4.1 Update relevant documentation, runbooks, communication materials, or project references if behavior, process, interface, configuration, or usage changed
|
||||
```
|
||||
|
||||
Reference design.md for scope, requirements, decisions, execution
|
||||
direction, and verification expectations.
|
||||
|
||||
Each task should be verifiable: it must be clear when the task is done.
|
||||
requires:
|
||||
- design
|
||||
apply:
|
||||
requires:
|
||||
- design
|
||||
- tasks
|
||||
tracks: tasks.md
|
||||
instruction: |
|
||||
Read design.md first, then tasks.md.
|
||||
Also follow workflow context/configuration, such as openspec/config.yaml when available, and any relevant project or workflow documentation referenced by design.md.
|
||||
Treat design.md as the source of truth for scope, requirements, decisions, guardrails, execution direction, and verification expectations.
|
||||
Work through pending tasks in dependency order and mark complete as you go.
|
||||
Mark a task complete only after its execution and required verification are done.
|
||||
Pause if tasks conflict with design.md, if design.md has blocking open questions, or if clarification is needed.
|
||||
77
openspec/schemas/fast-drive/templates/design.md
Normal file
77
openspec/schemas/fast-drive/templates/design.md
Normal file
@@ -0,0 +1,77 @@
|
||||
## Context
|
||||
|
||||
<!-- Problem, current state, relevant references, and triggering user request -->
|
||||
|
||||
## Discussion Notes
|
||||
|
||||
<!-- Key conclusions from exploration or prior discussion that apply must preserve -->
|
||||
|
||||
- Agreed conclusions:
|
||||
- User preferences:
|
||||
- Constraints:
|
||||
- Rejected ideas:
|
||||
|
||||
## Requirements
|
||||
|
||||
<!-- Expected outcomes, behavior/process/interface/content changes, continuity expectations, and acceptance criteria -->
|
||||
|
||||
| Requirement | Acceptance Criteria |
|
||||
| ----------- | ------------------- |
|
||||
| | |
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
<!-- What this design aims to achieve -->
|
||||
|
||||
**Non-Goals:**
|
||||
<!-- What is explicitly out of scope -->
|
||||
|
||||
## Execution Guardrails
|
||||
|
||||
<!-- Must-follow constraints, forbidden approaches, preserved behavior/processes, dependency limits, and project- or workflow-specific boundaries -->
|
||||
|
||||
- Dependencies:
|
||||
- Constraints:
|
||||
- Quality Bar:
|
||||
- Stakeholders:
|
||||
- Documentation / Communication:
|
||||
- Compatibility / Continuity:
|
||||
|
||||
## Affected Areas
|
||||
|
||||
<!-- Concrete artifacts, references, stakeholders, systems, workstreams, documents, configurations, assets, or handoffs relevant to this change -->
|
||||
|
||||
| Area | Artifacts / References | Expected Change | Notes |
|
||||
| ---- | ---------------------- | --------------- | ----- |
|
||||
| <!-- Area --> | <!-- Artifacts / References --> | <!-- Expected Change --> | <!-- Notes --> |
|
||||
|
||||
## Decisions
|
||||
|
||||
<!-- Key decisions, rationale, and alternatives considered -->
|
||||
|
||||
| Decision | Rationale | Alternatives Rejected |
|
||||
| -------- | --------- | --------------------- |
|
||||
| | | |
|
||||
|
||||
## Execution Plan
|
||||
|
||||
<!-- Main workstreams or artifacts to change, integration or handoff points, sequencing, and rollout notes -->
|
||||
|
||||
## Verification Plan
|
||||
|
||||
<!-- Validation checks, reviews, approvals, acceptance checks, documentation checks, communication checks, and manual checks needed -->
|
||||
|
||||
| Requirement / Risk | Verification |
|
||||
| ------------------ | ------------ |
|
||||
| | |
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
<!-- Format: [Risk] -> Mitigation -->
|
||||
|
||||
## Open Questions
|
||||
|
||||
| Status | Question | Decision Needed |
|
||||
| ------ | -------- | --------------- |
|
||||
| None | No open questions. | None |
|
||||
19
openspec/schemas/fast-drive/templates/tasks.md
Normal file
19
openspec/schemas/fast-drive/templates/tasks.md
Normal file
@@ -0,0 +1,19 @@
|
||||
## 1. Context Review
|
||||
|
||||
- [ ] 1.1 Read design.md and identify scope, requirements, decisions, guardrails, and open questions
|
||||
- [ ] 1.2 Review relevant artifacts and references listed in Affected Areas
|
||||
|
||||
## 2. Execution
|
||||
|
||||
- [ ] 2.1 Execute first concrete work item from design.md
|
||||
- [ ] 2.2 Execute next concrete work item from design.md
|
||||
|
||||
## 3. Validation
|
||||
|
||||
- [ ] 3.1 Run required validation from Verification Plan
|
||||
- [ ] 3.2 Perform quality checks required by the project or workflow
|
||||
- [ ] 3.3 Perform required manual review or acceptance checks from Verification Plan
|
||||
|
||||
## 4. Documentation / Communication
|
||||
|
||||
- [ ] 4.1 Update relevant documentation, runbooks, communication materials, or project references if behavior, process, interface, configuration, or usage changed
|
||||
@@ -1,61 +0,0 @@
|
||||
## Purpose
|
||||
|
||||
定义应用全局常量，作为应用元信息（name、title、subtitle、description、version）的唯一真实来源，供前后端及构建脚本统一引用，消除硬编码散落。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 应用元信息唯一来源
|
||||
|
||||
系统 SHALL 在 `src/shared/app.ts` 中定义应用全局常量 `APP`，包含以下字段：
|
||||
- `name`：机器标识（kebab-case 格式）
|
||||
- `title`：人类可读标题
|
||||
- `subtitle`：副标题
|
||||
- `description`：应用描述（用于 SEO meta）
|
||||
- `version`：语义版本号
|
||||
|
||||
`APP` SHALL 使用 `as const` 声明，保证字面量类型推断。
|
||||
|
||||
#### Scenario: 后端引用应用名称
|
||||
|
||||
- **WHEN** 后端代码需要应用名称（如 CLI 帮助文本、health 响应、启动日志）
|
||||
- **THEN** 系统 SHALL 从 `src/shared/app.ts` 导入 `APP.name`
|
||||
|
||||
#### Scenario: 前端引用应用标题
|
||||
|
||||
- **WHEN** 前端代码需要应用标题（如 Header logo、欢迎文本）
|
||||
- **THEN** 系统 SHALL 从 `src/shared/app.ts` 导入 `APP.title`
|
||||
|
||||
#### Scenario: 构建脚本引用应用名称
|
||||
|
||||
- **WHEN** 构建脚本需要确定可执行文件名
|
||||
- **THEN** 系统 SHALL 从 `src/shared/app.ts` 导入 `APP.name`
|
||||
|
||||
### Requirement: 前端 HTML 元信息动态设置
|
||||
|
||||
系统 SHALL 在 React 应用挂载时动态设置 HTML 元信息：
|
||||
- `document.title` SHALL 设置为 `APP.title`
|
||||
- `<meta name="description">` 内容 SHALL 设置为 `APP.description`
|
||||
|
||||
#### Scenario: 页面标题显示应用名称
|
||||
|
||||
- **WHEN** 用户访问应用
|
||||
- **THEN** 浏览器标签页标题 SHALL 显示 `APP.title`
|
||||
|
||||
#### Scenario: meta description 设置
|
||||
|
||||
- **WHEN** 搜索引擎爬取页面
|
||||
- **THEN** meta description SHALL 包含 `APP.description`
|
||||
|
||||
### Requirement: localStorage key 语义化命名
|
||||
|
||||
主题偏好存储 key SHALL 为 `"theme.preference"`，不包含应用名前缀。
|
||||
|
||||
#### Scenario: 主题偏好持久化
|
||||
|
||||
- **WHEN** 用户选择主题偏好（system/light/dark）
|
||||
- **THEN** 系统 SHALL 将偏好值存储到 localStorage key `"theme.preference"`
|
||||
|
||||
#### Scenario: 主题偏好读取
|
||||
|
||||
- **WHEN** 应用初始化时读取用户主题偏好
|
||||
- **THEN** 系统 SHALL 从 localStorage key `"theme.preference"` 读取
|
||||
16
package.json
16
package.json
@@ -1,5 +1,6 @@
|
||||
{
|
||||
"name": "my-app",
|
||||
"version": "0.1.0",
|
||||
"type": "module",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
@@ -9,12 +10,18 @@
|
||||
"build": "bun run scripts/build.ts",
|
||||
"lint": "eslint .",
|
||||
"format": "prettier . --write",
|
||||
"check": "bun run typecheck && bun run lint && bun test",
|
||||
"check": "bun run schema:check && bun run typecheck && bun run lint && bun test",
|
||||
"schema": "bun run scripts/generate-config-schema.ts",
|
||||
"schema:check": "bun run scripts/generate-config-schema.ts -- --check",
|
||||
"verify": "bun run check && bun run build",
|
||||
"test": "bun test",
|
||||
"clean": "bun run scripts/clean.ts",
|
||||
"typecheck": "tsc --noEmit",
|
||||
"prepare": "husky"
|
||||
"prepare": "husky",
|
||||
"version:patch": "bun run scripts/bump-version.ts patch",
|
||||
"version:minor": "bun run scripts/bump-version.ts minor",
|
||||
"version:major": "bun run scripts/bump-version.ts major",
|
||||
"version:set": "bun run scripts/bump-version.ts set"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@commitlint/cli": "^21.0.1",
|
||||
@@ -44,8 +51,13 @@
|
||||
"vite": "^8.0.13"
|
||||
},
|
||||
"dependencies": {
|
||||
"@sinclair/typebox": "^0.34.49",
|
||||
"@tanstack/react-query": "^5.100.10",
|
||||
"ajv": "^8.20.0",
|
||||
"es-toolkit": "^1.46.1",
|
||||
"pino": "^10.3.1",
|
||||
"pino-pretty": "^13.1.3",
|
||||
"pino-roll": "^4.0.0",
|
||||
"react": "^19.2.6",
|
||||
"react-dom": "^19.2.6",
|
||||
"react-router": "^7.15.1",
|
||||
|
||||
@@ -3,11 +3,13 @@ import { join, relative, sep } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
import { APP } from "../src/shared/app";
|
||||
import { validateVersion } from "./bump-version-logic";
|
||||
|
||||
const projectRoot = fileURLToPath(new URL("..", import.meta.url));
|
||||
const distWebDir = join(projectRoot, "dist/web");
|
||||
const buildDir = join(projectRoot, ".build");
|
||||
const executablePath = join(projectRoot, `dist/${APP.name}`);
|
||||
const packageJsonPath = join(projectRoot, "package.json");
|
||||
|
||||
async function build() {
|
||||
try {
|
||||
@@ -62,6 +64,14 @@ async function codeGeneration() {
|
||||
await rm(buildDir, { force: true, recursive: true });
|
||||
await Bun.write(join(buildDir, ".gitkeep"), "");
|
||||
|
||||
const packageJson = (await Bun.file(packageJsonPath).json()) as { version: string };
|
||||
const version = packageJson.version;
|
||||
if (typeof version !== "string") {
|
||||
console.error("package.json does not have a valid version field");
|
||||
process.exit(1);
|
||||
}
|
||||
validateVersion(version);
|
||||
|
||||
const allFiles = await scanDir(distWebDir, "/");
|
||||
const importLines: string[] = [];
|
||||
const fileEntries: string[] = [];
|
||||
@@ -104,15 +114,18 @@ async function codeGeneration() {
|
||||
const serverEntryTs = [
|
||||
`import { bootstrap } from "../src/server/bootstrap";`,
|
||||
`import { parseRuntimeArgs } from "../src/server/config";`,
|
||||
`import { createConsoleFallback } from "../src/server/logger";`,
|
||||
`import { staticAssets } from "./static-assets";`,
|
||||
"",
|
||||
`const APP_VERSION = "${version}" as const;`,
|
||||
"",
|
||||
`async function main() {`,
|
||||
` const { configPath } = parseRuntimeArgs();`,
|
||||
` await bootstrap({ configPath, mode: "production", staticAssets });`,
|
||||
` await bootstrap({ configPath, mode: "production", staticAssets, version: APP_VERSION });`,
|
||||
`}`,
|
||||
"",
|
||||
`void main().catch((error) => {`,
|
||||
` console.error("启动失败:", error instanceof Error ? error.message : error);`,
|
||||
` createConsoleFallback().fatal(\`启动失败: \${error instanceof Error ? error.message : String(error)}\`);`,
|
||||
` process.exit(1);`,
|
||||
`});`,
|
||||
"",
|
||||
|
||||
40
scripts/bump-version-logic.ts
Normal file
40
scripts/bump-version-logic.ts
Normal file
@@ -0,0 +1,40 @@
|
||||
const VERSION_REGEX = /^\d+\.\d+\.\d+$/;
|
||||
|
||||
export function bumpVersion(current: string, command: "major" | "minor" | "patch" | "set", target?: string): string {
|
||||
validateVersion(current);
|
||||
const [major, minor, patch] = parseVersion(current);
|
||||
|
||||
switch (command) {
|
||||
case "major":
|
||||
return formatVersion(major + 1, 0, 0);
|
||||
case "minor":
|
||||
return formatVersion(major, minor + 1, 0);
|
||||
case "patch":
|
||||
return formatVersion(major, minor, patch + 1);
|
||||
case "set": {
|
||||
if (!target) {
|
||||
throw new Error("set command requires a target version");
|
||||
}
|
||||
validateVersion(target);
|
||||
return target;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export function formatVersion(major: number, minor: number, patch: number): string {
|
||||
return `${major}.${minor}.${patch}`;
|
||||
}
|
||||
|
||||
export function parseVersion(version: string): [number, number, number] {
|
||||
const parts = version.split(".").map((p) => parseInt(p, 10));
|
||||
if (parts.length !== 3 || parts.some(isNaN)) {
|
||||
throw new Error(`Invalid version format: ${version}`);
|
||||
}
|
||||
return [parts[0]!, parts[1]!, parts[2]!];
|
||||
}
|
||||
|
||||
export function validateVersion(version: string): void {
|
||||
if (!VERSION_REGEX.test(version)) {
|
||||
throw new Error(`Invalid version format: ${version}. Expected MAJOR.MINOR.PATCH (e.g., 0.1.0)`);
|
||||
}
|
||||
}
|
||||
45
scripts/bump-version.ts
Normal file
45
scripts/bump-version.ts
Normal file
@@ -0,0 +1,45 @@
|
||||
import { writeFileSync } from "node:fs";
|
||||
import { resolve } from "node:path";
|
||||
|
||||
import { bumpVersion, validateVersion } from "./bump-version-logic";
|
||||
|
||||
const PACKAGE_JSON_PATH = resolve(import.meta.dir, "..", "package.json");
|
||||
|
||||
async function main() {
|
||||
const args = process.argv.slice(2);
|
||||
if (args.length === 0) {
|
||||
console.error("Usage: bun run bump-version.ts <patch|minor|major|set> [version]");
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const command = args[0];
|
||||
if (command !== "patch" && command !== "minor" && command !== "major" && command !== "set") {
|
||||
console.error(`Unknown command: ${command}. Expected patch, minor, major, or set`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
if (command === "set" && args.length < 2) {
|
||||
console.error("Usage: bun run bump-version.ts set <version>");
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const packageJson = (await Bun.file(PACKAGE_JSON_PATH).json()) as { version: string };
|
||||
const currentVersion = packageJson.version;
|
||||
|
||||
if (typeof currentVersion !== "string") {
|
||||
console.error("package.json does not have a valid version field");
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
validateVersion(currentVersion);
|
||||
|
||||
const targetVersion = command === "set" ? args[1] : undefined;
|
||||
const nextVersion = bumpVersion(currentVersion, command, targetVersion);
|
||||
|
||||
packageJson.version = nextVersion;
|
||||
writeFileSync(PACKAGE_JSON_PATH, JSON.stringify(packageJson, null, 2) + "\n");
|
||||
|
||||
console.log(`${currentVersion} -> ${nextVersion}`);
|
||||
}
|
||||
|
||||
void main();
|
||||
15
scripts/generate-config-schema.ts
Normal file
15
scripts/generate-config-schema.ts
Normal file
@@ -0,0 +1,15 @@
|
||||
import { createConfigJsonSchema } from "../src/server/config/schema/export";
|
||||
|
||||
const schemaPath = "config.schema.json";
|
||||
const schema = `${JSON.stringify(createConfigJsonSchema(), null, 2)}\n`;
|
||||
|
||||
if (process.argv.includes("--check")) {
|
||||
const existing = await Bun.file(schemaPath)
|
||||
.text()
|
||||
.catch(() => null);
|
||||
if (existing !== schema) {
|
||||
throw new Error(`${schemaPath} 未同步，请运行 bun run schema`);
|
||||
}
|
||||
} else {
|
||||
await Bun.write(schemaPath, schema);
|
||||
}
|
||||
11
src/pino-roll.d.ts
vendored
Normal file
11
src/pino-roll.d.ts
vendored
Normal file
@@ -0,0 +1,11 @@
|
||||
declare module "pino-roll" {
|
||||
interface RollingStreamOptions {
|
||||
file: string;
|
||||
frequency?: string;
|
||||
limit?: { count?: number };
|
||||
mkdir?: boolean;
|
||||
size?: string;
|
||||
}
|
||||
|
||||
export default function build(options: RollingStreamOptions): Promise<NodeJS.WritableStream>;
|
||||
}
|
||||
@@ -1,46 +1,86 @@
|
||||
import { mkdirSync } from "node:fs";
|
||||
|
||||
import type { RuntimeMode } from "../shared/api";
|
||||
import type { ServerConfig } from "./config";
|
||||
import type { ResolvedConfig, ResolvedLoggingConfig } from "./config/types";
|
||||
import type { Logger } from "./logger";
|
||||
import type { StartServerOptions } from "./server";
|
||||
|
||||
import { loadServerConfig } from "./config";
|
||||
import { createConsoleFallback, createRuntimeLogger } from "./logger";
|
||||
import { startServer } from "./server";
|
||||
|
||||
export interface BootstrapDependencies {
|
||||
loadConfig?: (configPath?: string) => Promise<ServerConfig>;
|
||||
logError?: (...data: unknown[]) => void;
|
||||
createLogger?: (config: ResolvedLoggingConfig, mode: string, version?: string) => Promise<Logger>;
|
||||
exit?: (code: number) => never;
|
||||
loadConfig?: (configPath: string) => Promise<ResolvedConfig>;
|
||||
onSignal?: (signal: "SIGINT" | "SIGTERM", handler: () => void) => void;
|
||||
startServer?: (options: StartServerOptions) => unknown;
|
||||
}
|
||||
|
||||
export interface BootstrapOptions {
|
||||
config?: ServerConfig;
|
||||
configPath?: string;
|
||||
configPath: string;
|
||||
mode: RuntimeMode;
|
||||
staticAssets?: StartServerOptions["staticAssets"];
|
||||
version?: string;
|
||||
}
|
||||
|
||||
export async function bootstrap(options: BootstrapOptions, dependencies: BootstrapDependencies = {}): Promise<void> {
|
||||
const load = dependencies.loadConfig ?? loadServerConfig;
|
||||
const buildLogger = dependencies.createLogger ?? createRuntimeLogger;
|
||||
const serve = dependencies.startServer ?? startServer;
|
||||
const onSignal =
|
||||
dependencies.onSignal ??
|
||||
((signal: "SIGINT" | "SIGTERM", handler: () => void) => {
|
||||
process.on(signal, handler);
|
||||
});
|
||||
const logError = dependencies.logError ?? console.error;
|
||||
const exit = dependencies.exit ?? ((code: number) => process.exit(code));
|
||||
|
||||
const createFallback = (): Logger => createConsoleFallback();
|
||||
|
||||
let logger: Logger | undefined;
|
||||
|
||||
try {
|
||||
const config = options.config ?? (await load(options.configPath));
|
||||
const config = await load(options.configPath);
|
||||
|
||||
try {
|
||||
logger = await buildLogger(config.logging, options.mode, options.version);
|
||||
} catch (logInitError) {
|
||||
createFallback().fatal(
|
||||
`日志初始化失败: ${logInitError instanceof Error ? logInitError.message : String(logInitError)}`,
|
||||
);
|
||||
exit(1);
|
||||
}
|
||||
|
||||
logger!.info(
|
||||
{ configDir: config.configDir, configPath: options.configPath, mode: options.mode, version: options.version },
|
||||
"配置加载成功",
|
||||
);
|
||||
|
||||
mkdirSync(config.dataDir, { recursive: true });
|
||||
logger!.info({ dataDir: config.dataDir }, "数据目录就绪");
|
||||
|
||||
const shutdown = () => {
|
||||
process.exit(0);
|
||||
logger?.info("收到退出信号，开始优雅关闭");
|
||||
logger?.flush();
|
||||
exit(0);
|
||||
};
|
||||
onSignal("SIGINT", shutdown);
|
||||
onSignal("SIGTERM", shutdown);
|
||||
|
||||
serve({ config, mode: options.mode, staticAssets: options.staticAssets });
|
||||
serve({
|
||||
config: { host: config.host, port: config.port },
|
||||
logger: logger!.child({ component: "server" }),
|
||||
mode: options.mode,
|
||||
staticAssets: options.staticAssets,
|
||||
version: options.version,
|
||||
});
|
||||
} catch (error) {
|
||||
logError("启动失败:", error instanceof Error ? error.message : error);
|
||||
process.exit(1);
|
||||
if (logger) {
|
||||
logger.fatal({ error: error instanceof Error ? error.message : String(error) }, "启动失败");
|
||||
logger.flush();
|
||||
} else {
|
||||
createFallback().fatal(`启动失败: ${error instanceof Error ? error.message : String(error)}`);
|
||||
}
|
||||
exit(1);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,53 +1,241 @@
|
||||
import { APP } from "../shared/app";
|
||||
import { isNumber, isString } from "es-toolkit";
|
||||
import { dirname, isAbsolute, resolve } from "node:path";
|
||||
|
||||
export interface ServerConfig {
|
||||
host: string;
|
||||
port: number;
|
||||
}
|
||||
import type { ConfigValidationIssue } from "./config/issues";
|
||||
import type { LoggingConfig, LogLevel, ResolvedConfig, ResolvedLoggingConfig, RotationFrequency } from "./config/types";
|
||||
|
||||
import { APP } from "../shared/app";
|
||||
import { dedupeIssues, issue, throwConfigIssues } from "./config/issues";
|
||||
import { normalizeAuthoringConfig } from "./config/normalizer";
|
||||
import { validateConfigContract } from "./config/schema/validate";
|
||||
|
||||
const DEFAULT_HOST = "127.0.0.1";
|
||||
const DEFAULT_PORT = 3000;
|
||||
const DEFAULT_DATA_DIR = "./data";
|
||||
const DEFAULT_LOG_LEVEL: LogLevel = "info";
|
||||
const DEFAULT_ROTATION_SIZE = "50MB";
|
||||
const DEFAULT_ROTATION_FREQUENCY: RotationFrequency = "daily";
|
||||
const DEFAULT_ROTATION_MAX_FILES = 14;
|
||||
|
||||
interface YAMLConfigFile {
|
||||
server?: YAMLServerBlock;
|
||||
}
|
||||
const VALID_LOG_LEVELS: LogLevel[] = ["trace", "debug", "info", "warn", "error", "fatal"];
|
||||
const VALID_ROTATION_FREQUENCIES: RotationFrequency[] = ["hourly", "daily", "weekly"];
|
||||
|
||||
interface YAMLServerBlock {
|
||||
host?: string;
|
||||
port?: number;
|
||||
}
|
||||
const SIZE_REGEX = /^(\d+(?:\.\d+)?)(B|KB|MB|GB)$/;
|
||||
|
||||
export async function loadServerConfig(configPath?: string): Promise<ServerConfig> {
|
||||
const fileConfig: { host?: string; port?: number } = {};
|
||||
|
||||
if (configPath) {
|
||||
const file = Bun.file(configPath);
|
||||
if (!(await file.exists())) {
|
||||
throw new Error(`配置文件不存在: ${configPath}`);
|
||||
}
|
||||
const content = await file.text();
|
||||
const parsed = Bun.YAML.parse(content) as YAMLConfigFile;
|
||||
if (parsed.server) {
|
||||
if (parsed.server.host !== undefined) fileConfig.host = parsed.server.host;
|
||||
if (parsed.server.port !== undefined) fileConfig.port = parsed.server.port;
|
||||
}
|
||||
export async function loadServerConfig(configPath: string): Promise<ResolvedConfig> {
|
||||
const file = Bun.file(configPath);
|
||||
if (!(await file.exists())) {
|
||||
throw new Error(`配置文件不存在: ${configPath}`);
|
||||
}
|
||||
|
||||
const envPortNum = parseInt(process.env["PORT"] ?? "", 10);
|
||||
const content = await file.text();
|
||||
const parsed = Bun.YAML.parse(content);
|
||||
|
||||
const normalizeResult = normalizeAuthoringConfig(parsed);
|
||||
if (normalizeResult.issues.length > 0) {
|
||||
throwConfigIssues(dedupeIssues(normalizeResult.issues));
|
||||
}
|
||||
|
||||
const normalizedConfig = normalizeResult.config;
|
||||
const contractResult = validateConfigContract(normalizedConfig);
|
||||
if (contractResult.config === null) {
|
||||
throwConfigIssues(dedupeIssues(contractResult.issues));
|
||||
}
|
||||
|
||||
const allIssues: ConfigValidationIssue[] = [...contractResult.issues];
|
||||
const runtimeIssues = validateRuntimeConfig(contractResult.config);
|
||||
allIssues.push(...runtimeIssues);
|
||||
|
||||
const configDir = dirname(resolve(configPath));
|
||||
|
||||
const configRecord = contractResult.config as Record<string, unknown>;
|
||||
const server = configRecord["server"] as Record<string, unknown> | undefined;
|
||||
const listen = server?.["listen"] as Record<string, unknown> | undefined;
|
||||
const storage = server?.["storage"] as Record<string, unknown> | undefined;
|
||||
|
||||
const host = (listen?.["host"] as string | undefined) ?? DEFAULT_HOST;
|
||||
const port = (listen?.["port"] as number | undefined) ?? DEFAULT_PORT;
|
||||
const dataDir = resolveDataDir(storage, configDir);
|
||||
|
||||
const rawLogging = server?.["logging"] as LoggingConfig | undefined;
|
||||
const logging = resolveLogging(rawLogging ?? {}, dataDir, configDir);
|
||||
validateLoggingConfig(rawLogging, allIssues);
|
||||
|
||||
if (allIssues.length > 0) {
|
||||
throwConfigIssues(dedupeIssues(allIssues));
|
||||
}
|
||||
|
||||
return { configDir, dataDir, host, logging, port };
|
||||
}
|
||||
|
||||
export function parseRuntimeArgs(argv: string[] = Bun.argv.slice(2)): { configPath: string } {
|
||||
if (argv.length === 0) {
|
||||
throw new Error(`需要指定 YAML 配置文件路径\n用法: ${APP.name} <config.yaml>`);
|
||||
}
|
||||
const firstArg = argv[0];
|
||||
if (firstArg === "--help" || firstArg === "-h") {
|
||||
throw new Error(`用法: ${APP.name} <config.yaml>`);
|
||||
}
|
||||
return { configPath: firstArg! };
|
||||
}
|
||||
|
||||
export function parseSize(value: number | string): number {
|
||||
if (isNumber(value)) {
|
||||
if (!Number.isInteger(value) || value < 0 || !Number.isSafeInteger(value)) {
|
||||
throw new Error(`无效的 size 数值: ${value}，必须为非负安全整数`);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
const match = SIZE_REGEX.exec(value);
|
||||
if (!match) {
|
||||
throw new Error(`无效的 size 格式: "${value}"，支持格式如 "100MB"、"512KB"、"1GB"、"1024B"`);
|
||||
}
|
||||
|
||||
const num = parseFloat(match[1]!);
|
||||
const unit = match[2]!;
|
||||
|
||||
const bytes =
|
||||
unit === "B" ? num : unit === "KB" ? num * 1024 : unit === "MB" ? num * 1024 * 1024 : num * 1024 * 1024 * 1024;
|
||||
if (!Number.isInteger(bytes) || bytes < 0 || !Number.isSafeInteger(bytes)) {
|
||||
throw new Error(`无效的 size 数值: ${value}，必须解析为非负安全整数字节数`);
|
||||
}
|
||||
return bytes;
|
||||
}
|
||||
|
||||
function resolveDataDir(storage: Record<string, unknown> | undefined, configDir: string): string {
|
||||
const raw = storage?.["dataDir"];
|
||||
if (isString(raw) && raw.trim() !== "") {
|
||||
return isAbsolute(raw) ? resolve(raw) : resolve(configDir, raw);
|
||||
}
|
||||
return resolve(configDir, DEFAULT_DATA_DIR);
|
||||
}
|
||||
|
||||
function resolveLogging(logging: LoggingConfig, dataDir: string, configDir: string): ResolvedLoggingConfig {
|
||||
const globalLevel = resolveLogLevel(logging.level, DEFAULT_LOG_LEVEL);
|
||||
const consoleLevel = resolveLogLevel(logging.console?.level, globalLevel);
|
||||
const fileLevel = resolveLogLevel(logging.file?.level, globalLevel);
|
||||
|
||||
const rawPath = logging.file?.path;
|
||||
const filePath = rawPath
|
||||
? isAbsolute(rawPath)
|
||||
? resolve(rawPath)
|
||||
: resolve(configDir, rawPath)
|
||||
: resolve(dataDir, "logs", `${APP.name}.log`);
|
||||
|
||||
const rotationRaw = logging.file?.rotation;
|
||||
const rotationSizeRaw = rotationRaw?.size ?? DEFAULT_ROTATION_SIZE;
|
||||
const rotationSizeBytes = parseSize(rotationSizeRaw);
|
||||
const rotationFrequency = rotationRaw?.frequency ?? DEFAULT_ROTATION_FREQUENCY;
|
||||
const rotationMaxFiles = rotationRaw?.maxFiles ?? DEFAULT_ROTATION_MAX_FILES;
|
||||
|
||||
return {
|
||||
host: process.env["HOST"] ?? fileConfig.host ?? DEFAULT_HOST,
|
||||
port: !isNaN(envPortNum) ? envPortNum : (fileConfig.port ?? DEFAULT_PORT),
|
||||
consoleLevel,
|
||||
fileLevel,
|
||||
filePath,
|
||||
rotationFrequency,
|
||||
rotationMaxFiles,
|
||||
rotationSizeBytes,
|
||||
rotationSizeRaw,
|
||||
};
|
||||
}
|
||||
|
||||
export function parseRuntimeArgs(argv: string[] = Bun.argv.slice(2)): { configPath?: string } {
|
||||
if (argv.length === 0) return {};
|
||||
const firstArg = argv[0];
|
||||
if (firstArg === "--help" || firstArg === "-h") {
|
||||
console.log(`用法: ${APP.name} [config.yaml]`);
|
||||
console.log(" config.yaml 可选 YAML 配置文件路径（不存在时使用默认配置）");
|
||||
process.exit(0);
|
||||
}
|
||||
return { configPath: firstArg };
|
||||
function resolveLogLevel(level: unknown, fallback: LogLevel): LogLevel {
|
||||
if (!isString(level)) return fallback;
|
||||
if (VALID_LOG_LEVELS.includes(level as LogLevel)) return level as LogLevel;
|
||||
return fallback;
|
||||
}
|
||||
|
||||
function validateLoggingConfig(logging: LoggingConfig | undefined, issues: ConfigValidationIssue[]): void {
|
||||
if (logging === undefined) return;
|
||||
|
||||
if (logging.level !== undefined && !VALID_LOG_LEVELS.includes(logging.level)) {
|
||||
issues.push(
|
||||
issue(
|
||||
"invalid-value",
|
||||
"server.logging.level",
|
||||
`日志等级非法: "${logging.level}"，支持: ${VALID_LOG_LEVELS.join(", ")}`,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
if (logging.console?.level !== undefined && !VALID_LOG_LEVELS.includes(logging.console.level)) {
|
||||
issues.push(
|
||||
issue(
|
||||
"invalid-value",
|
||||
"server.logging.console.level",
|
||||
`日志等级非法: "${logging.console.level}"，支持: ${VALID_LOG_LEVELS.join(", ")}`,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
if (logging.file?.level !== undefined && !VALID_LOG_LEVELS.includes(logging.file.level)) {
|
||||
issues.push(
|
||||
issue(
|
||||
"invalid-value",
|
||||
"server.logging.file.level",
|
||||
`日志等级非法: "${logging.file.level}"，支持: ${VALID_LOG_LEVELS.join(", ")}`,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
if (logging.file?.path !== undefined) {
|
||||
if (!isString(logging.file.path) || logging.file.path.trim() === "") {
|
||||
issues.push(issue("invalid-value", "server.logging.file.path", "日志路径不能为空字符串或空白字符串"));
|
||||
}
|
||||
}
|
||||
|
||||
const rotation = logging.file?.rotation;
|
||||
if (rotation?.size !== undefined) {
|
||||
try {
|
||||
const bytes = parseSize(rotation.size);
|
||||
if (bytes <= 0) {
|
||||
issues.push(issue("invalid-value", "server.logging.file.rotation.size", "滚动大小必须为正整数字节数"));
|
||||
}
|
||||
} catch (error) {
|
||||
issues.push(
|
||||
issue(
|
||||
"invalid-value",
|
||||
"server.logging.file.rotation.size",
|
||||
error instanceof Error ? error.message : "size 格式非法",
|
||||
),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
if (rotation?.frequency !== undefined && !VALID_ROTATION_FREQUENCIES.includes(rotation.frequency)) {
|
||||
issues.push(
|
||||
issue(
|
||||
"invalid-value",
|
||||
"server.logging.file.rotation.frequency",
|
||||
`滚动频率非法: "${rotation.frequency}"，支持: ${VALID_ROTATION_FREQUENCIES.join(", ")}`,
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
if (rotation?.maxFiles !== undefined) {
|
||||
if (!isNumber(rotation.maxFiles) || !Number.isInteger(rotation.maxFiles) || rotation.maxFiles <= 0) {
|
||||
issues.push(issue("invalid-value", "server.logging.file.rotation.maxFiles", "maxFiles 必须为正整数"));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function validateRuntimeConfig(config: object): ConfigValidationIssue[] {
|
||||
const issues: ConfigValidationIssue[] = [];
|
||||
const configRecord = config as Record<string, unknown>;
|
||||
const server = configRecord["server"] as Record<string, unknown> | undefined;
|
||||
const listen = server?.["listen"] as Record<string, unknown> | undefined;
|
||||
|
||||
if (listen !== undefined) {
|
||||
const portValue = listen["port"];
|
||||
if (isString(portValue)) {
|
||||
issues.push(
|
||||
issue("invalid-type", "server.listen.port", "端口必须为整数，不能为字符串（如需使用变量请使用 ${VAR} 语法）"),
|
||||
);
|
||||
} else if (isNumber(portValue) && (!Number.isInteger(portValue) || portValue < 0 || portValue > 65535)) {
|
||||
issues.push(issue("invalid-range", "server.listen.port", "端口必须为 0-65535 之间的整数"));
|
||||
}
|
||||
}
|
||||
|
||||
return issues;
|
||||
}
|
||||
|
||||
27
src/server/config/index.ts
Normal file
27
src/server/config/index.ts
Normal file
@@ -0,0 +1,27 @@
|
||||
export { issue, joinPath, renderPath, throwConfigIssues } from "./issues";
|
||||
export { normalizeAuthoringConfig } from "./normalizer";
|
||||
export {
|
||||
createAuthoringConfigSchema,
|
||||
createExternalConfigSchema,
|
||||
createNormalizedConfigSchema,
|
||||
} from "./schema/builder";
|
||||
export { createConfigJsonSchema } from "./schema/export";
|
||||
export { createConfigAjv, issuesFromAjvErrors, validateConfigContract } from "./schema/validate";
|
||||
export type {
|
||||
AuthoringConfig,
|
||||
AuthoringLoggingConfig,
|
||||
AuthoringLoggingFileConfig,
|
||||
AuthoringLoggingFileRotationConfig,
|
||||
AuthoringServer,
|
||||
ConfigVariableValue,
|
||||
LoggingConfig,
|
||||
LogLevel,
|
||||
NormalizedConfig,
|
||||
NormalizedLoggingConfig,
|
||||
NormalizedServer,
|
||||
ResolvedConfig,
|
||||
ResolvedLoggingConfig,
|
||||
RotationFrequency,
|
||||
ValidatedConfig,
|
||||
} from "./types";
|
||||
export { extractVariables, resolveVariables } from "./variables";
|
||||
43
src/server/config/issues.ts
Normal file
43
src/server/config/issues.ts
Normal file
@@ -0,0 +1,43 @@
|
||||
export interface ConfigValidationIssue {
|
||||
code: string;
|
||||
message: string;
|
||||
path: string;
|
||||
}
|
||||
|
||||
export function dedupeIssues(issues: ConfigValidationIssue[]): ConfigValidationIssue[] {
|
||||
const seen = new Set<string>();
|
||||
const result: ConfigValidationIssue[] = [];
|
||||
for (const item of issues) {
|
||||
const key = `${item.code}:${item.path}:${item.message}`;
|
||||
if (seen.has(key)) continue;
|
||||
seen.add(key);
|
||||
result.push(item);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
export function formatConfigIssues(issues: ConfigValidationIssue[]): string {
|
||||
return issues.map(formatConfigIssue).join("\n");
|
||||
}
|
||||
|
||||
export function issue(code: string, path: string, message: string): ConfigValidationIssue {
|
||||
return { code, message, path };
|
||||
}
|
||||
|
||||
export function joinPath(base: string, key: string): string {
|
||||
if (base === "") return key;
|
||||
if (key.startsWith("[")) return `${base}${key}`;
|
||||
return `${base}.${key}`;
|
||||
}
|
||||
|
||||
export function renderPath(path: string): string {
|
||||
return path === "" ? "配置文件" : path;
|
||||
}
|
||||
|
||||
export function throwConfigIssues(issues: ConfigValidationIssue[]): never {
|
||||
throw new Error(formatConfigIssues(issues));
|
||||
}
|
||||
|
||||
function formatConfigIssue(i: ConfigValidationIssue): string {
|
||||
return `${renderPath(i.path)} ${i.message}`;
|
||||
}
|
||||
18
src/server/config/normalizer.ts
Normal file
18
src/server/config/normalizer.ts
Normal file
@@ -0,0 +1,18 @@
|
||||
import { isPlainObject } from "es-toolkit";
|
||||
|
||||
import type { ConfigValidationIssue } from "./issues";
|
||||
|
||||
import { resolveVariables } from "./variables";
|
||||
|
||||
export function normalizeAuthoringConfig(config: unknown): {
|
||||
config: unknown;
|
||||
issues: ConfigValidationIssue[];
|
||||
} {
|
||||
const variableResult = resolveVariables(config);
|
||||
if (!isPlainObject(variableResult.config)) {
|
||||
return variableResult;
|
||||
}
|
||||
|
||||
const normalized = { ...(variableResult.config as Record<string, unknown>) };
|
||||
return { config: normalized, issues: variableResult.issues };
|
||||
}
|
||||
120
src/server/config/schema/builder.ts
Normal file
120
src/server/config/schema/builder.ts
Normal file
@@ -0,0 +1,120 @@
|
||||
import type { TSchema } from "@sinclair/typebox";
|
||||
|
||||
import { Type } from "@sinclair/typebox";
|
||||
|
||||
import { variableValueSchema } from "./fragments";
|
||||
|
||||
type SchemaKind = "authoring" | "normalized";
|
||||
|
||||
const LOG_LEVELS = ["trace", "debug", "info", "warn", "error", "fatal"] as const;
|
||||
const ROTATION_FREQUENCIES = ["hourly", "daily", "weekly"] as const;
|
||||
|
||||
const sizeSchema = Type.Union([Type.String(), Type.Integer({ minimum: 0 })]);
|
||||
|
||||
export function createAuthoringConfigSchema(): TSchema {
|
||||
return createConfigSchemaForKind("authoring");
|
||||
}
|
||||
|
||||
export function createExternalConfigSchema(): Record<string, unknown> {
|
||||
return {
|
||||
...cloneSchema(createAuthoringConfigSchema()),
|
||||
$id: "https://app.local/config.schema.json",
|
||||
$schema: "http://json-schema.org/draft-07/schema#",
|
||||
};
|
||||
}
|
||||
|
||||
export function createNormalizedConfigSchema(): TSchema {
|
||||
return createConfigSchemaForKind("normalized");
|
||||
}
|
||||
|
||||
function cloneSchema(schema: TSchema): Record<string, unknown> {
|
||||
return JSON.parse(JSON.stringify(schema)) as Record<string, unknown>;
|
||||
}
|
||||
|
||||
function createAuthoringFieldSchema(schema: TSchema): TSchema {
|
||||
return Type.Unsafe({ anyOf: [schema, { pattern: "^\\$\\{[^}]+\\}$", type: "string" }] });
|
||||
}
|
||||
|
||||
function createConfigSchemaForKind(kind: SchemaKind): TSchema {
|
||||
const properties: Record<string, TSchema> = {
|
||||
server: Type.Optional(createServerSchema(kind)),
|
||||
};
|
||||
if (kind === "authoring") {
|
||||
properties["variables"] = Type.Optional(
|
||||
Type.Record(Type.String({ pattern: "^[a-zA-Z_][a-zA-Z0-9_]*$" }), variableValueSchema),
|
||||
);
|
||||
}
|
||||
return Type.Object(properties, { additionalProperties: false });
|
||||
}
|
||||
|
||||
function createLoggingSchema(kind: SchemaKind): TSchema {
|
||||
const logLevelSchema = Type.Union(LOG_LEVELS.map((l) => Type.Literal(l)) as unknown as [TSchema, ...TSchema[]]);
|
||||
const logLevel = kind === "authoring" ? createAuthoringFieldSchema(logLevelSchema) : logLevelSchema;
|
||||
const frequency =
|
||||
kind === "authoring"
|
||||
? createAuthoringFieldSchema(
|
||||
Type.Union(ROTATION_FREQUENCIES.map((f) => Type.Literal(f)) as unknown as [TSchema, ...TSchema[]]),
|
||||
)
|
||||
: Type.Union(ROTATION_FREQUENCIES.map((f) => Type.Literal(f)) as unknown as [TSchema, ...TSchema[]]);
|
||||
const rotationSize = kind === "authoring" ? createAuthoringFieldSchema(sizeSchema) : sizeSchema;
|
||||
const rotationMaxFiles =
|
||||
kind === "authoring" ? createAuthoringFieldSchema(Type.Integer({ minimum: 1 })) : Type.Integer({ minimum: 1 });
|
||||
|
||||
return Type.Object(
|
||||
{
|
||||
console: Type.Optional(Type.Object({ level: Type.Optional(logLevel) }, { additionalProperties: false })),
|
||||
file: Type.Optional(
|
||||
Type.Object(
|
||||
{
|
||||
level: Type.Optional(logLevel),
|
||||
path: Type.Optional(Type.String({ minLength: 1 })),
|
||||
rotation: Type.Optional(
|
||||
Type.Object(
|
||||
{
|
||||
frequency: Type.Optional(frequency),
|
||||
maxFiles: Type.Optional(rotationMaxFiles),
|
||||
size: Type.Optional(rotationSize),
|
||||
},
|
||||
{ additionalProperties: false },
|
||||
),
|
||||
),
|
||||
},
|
||||
{ additionalProperties: false },
|
||||
),
|
||||
),
|
||||
level: Type.Optional(logLevel),
|
||||
},
|
||||
{ additionalProperties: false },
|
||||
);
|
||||
}
|
||||
|
||||
function createServerSchema(kind: SchemaKind): TSchema {
|
||||
return Type.Object(
|
||||
{
|
||||
listen: Type.Optional(
|
||||
Type.Object(
|
||||
{
|
||||
host: Type.Optional(Type.String()),
|
||||
port: Type.Optional(integerForKind(kind, { maximum: 65535, minimum: 0 })),
|
||||
},
|
||||
{ additionalProperties: false },
|
||||
),
|
||||
),
|
||||
logging: Type.Optional(createLoggingSchema(kind)),
|
||||
storage: Type.Optional(
|
||||
Type.Object(
|
||||
{
|
||||
dataDir: Type.Optional(Type.String()),
|
||||
},
|
||||
{ additionalProperties: false },
|
||||
),
|
||||
),
|
||||
},
|
||||
{ additionalProperties: false },
|
||||
);
|
||||
}
|
||||
|
||||
function integerForKind(kind: SchemaKind, options?: Parameters<typeof Type.Integer>[0]): TSchema {
|
||||
const schema = Type.Integer(options);
|
||||
return kind === "authoring" ? createAuthoringFieldSchema(schema) : schema;
|
||||
}
|
||||
5
src/server/config/schema/export.ts
Normal file
5
src/server/config/schema/export.ts
Normal file
@@ -0,0 +1,5 @@
|
||||
import { createExternalConfigSchema } from "./builder";
|
||||
|
||||
export function createConfigJsonSchema(): Record<string, unknown> {
|
||||
return createExternalConfigSchema();
|
||||
}
|
||||
3
src/server/config/schema/fragments.ts
Normal file
3
src/server/config/schema/fragments.ts
Normal file
@@ -0,0 +1,3 @@
|
||||
import { Type } from "@sinclair/typebox";
|
||||
|
||||
export const variableValueSchema = Type.Union([Type.String(), Type.Number(), Type.Boolean()]);
|
||||
110
src/server/config/schema/validate.ts
Normal file
110
src/server/config/schema/validate.ts
Normal file
@@ -0,0 +1,110 @@
|
||||
import type { ErrorObject } from "ajv";
|
||||
|
||||
import Ajv from "ajv";
|
||||
|
||||
import type { ConfigValidationIssue } from "../issues";
|
||||
|
||||
import { issue } from "../issues";
|
||||
import { createNormalizedConfigSchema } from "./builder";
|
||||
|
||||
export function createConfigAjv(): Ajv {
|
||||
return new Ajv({ allErrors: true, coerceTypes: false, removeAdditional: false, strict: true, useDefaults: false });
|
||||
}
|
||||
|
||||
export function issuesFromAjvErrors(errors: ErrorObject[], root: unknown, basePath = ""): ConfigValidationIssue[] {
|
||||
return normalizeAjvErrors(errors, basePath).map((error) => issueFromAjvError(error, root, basePath));
|
||||
}
|
||||
|
||||
export function validateConfigContract(
|
||||
config: unknown,
|
||||
): { config: null; issues: ConfigValidationIssue[] } | { config: object; issues: [] } {
|
||||
const ajv = createConfigAjv();
|
||||
const rootValidate = ajv.compile(createNormalizedConfigSchema());
|
||||
if (!rootValidate(config)) {
|
||||
const issues = issuesFromAjvErrors(rootValidate.errors ?? [], config);
|
||||
return { config: null, issues };
|
||||
}
|
||||
|
||||
return { config: config as object, issues: [] as [] };
|
||||
}
|
||||
|
||||
function buildIssuePath(basePath: string, error: ErrorObject): string {
|
||||
const pointerPath = jsonPointerToPath(error.instancePath);
|
||||
let path = basePath ? joinBasePath(basePath, pointerPath) : pointerPath;
|
||||
if (error.keyword === "required" && "missingProperty" in error.params) {
|
||||
path = joinBasePath(path, String(error.params["missingProperty"]));
|
||||
}
|
||||
if (error.keyword === "additionalProperties" && "additionalProperty" in error.params) {
|
||||
path = joinBasePath(path, String(error.params["additionalProperty"]));
|
||||
}
|
||||
return path;
|
||||
}
|
||||
|
||||
function hasMoreSpecificError(keywords: Set<string>): boolean {
|
||||
return ["const", "enum", "maximum", "minimum", "minLength", "pattern"].some((keyword) => keywords.has(keyword));
|
||||
}
|
||||
|
||||
function issueFromAjvError(error: ErrorObject, _root: unknown, basePath: string): ConfigValidationIssue {
|
||||
const path = buildIssuePath(basePath, error);
|
||||
switch (error.keyword) {
|
||||
case "additionalProperties":
|
||||
return issue("unknown-field", path, "是未知字段");
|
||||
case "const":
|
||||
case "enum":
|
||||
return issue("invalid-value", path, "不在允许范围内");
|
||||
case "maximum":
|
||||
case "minimum":
|
||||
return issue("invalid-range", path, "数值范围不合法");
|
||||
case "minLength":
|
||||
return issue("invalid-format", path, "不能为空");
|
||||
case "pattern":
|
||||
return issue("invalid-format", path, "格式不合法");
|
||||
case "required":
|
||||
return issue("required", path, "缺少必填字段");
|
||||
case "type":
|
||||
return issue("invalid-type", path, "类型不合法");
|
||||
default:
|
||||
return issue("invalid-config", path, error.message ?? "配置不合法");
|
||||
}
|
||||
}
|
||||
|
||||
function joinBasePath(basePath: string, path: string): string {
|
||||
if (basePath === "") return path;
|
||||
if (path === "") return basePath;
|
||||
if (path.startsWith("[")) return `${basePath}${path}`;
|
||||
return `${basePath}.${path}`;
|
||||
}
|
||||
|
||||
function jsonPointerToPath(pointer: string): string {
|
||||
if (pointer === "") return "";
|
||||
return pointer
|
||||
.slice(1)
|
||||
.split("/")
|
||||
.map((part) => part.replaceAll("~1", "/").replaceAll("~0", "~"))
|
||||
.reduce((path, part) => (/^\d+$/.test(part) ? `${path}[${part}]` : joinBasePath(path, part)), "");
|
||||
}
|
||||
|
||||
function normalizeAjvErrors(errors: ErrorObject[], basePath: string): ErrorObject[] {
|
||||
const nonCompositeErrors = errors.filter((error) => error.keyword !== "anyOf" && error.keyword !== "oneOf");
|
||||
const candidates = nonCompositeErrors.length > 0 ? nonCompositeErrors : errors;
|
||||
const keywordsByPath = new Map<string, Set<string>>();
|
||||
|
||||
for (const error of candidates) {
|
||||
const path = buildIssuePath(basePath, error);
|
||||
const keywords = keywordsByPath.get(path) ?? new Set<string>();
|
||||
keywords.add(error.keyword);
|
||||
keywordsByPath.set(path, keywords);
|
||||
}
|
||||
|
||||
const seenValueErrors = new Set<string>();
|
||||
return candidates.filter((error) => {
|
||||
const path = buildIssuePath(basePath, error);
|
||||
const keywords = keywordsByPath.get(path) ?? new Set<string>();
|
||||
if (error.keyword === "type" && hasMoreSpecificError(keywords)) return false;
|
||||
if (error.keyword === "const" || error.keyword === "enum") {
|
||||
if (seenValueErrors.has(path)) return false;
|
||||
seenValueErrors.add(path);
|
||||
}
|
||||
return true;
|
||||
});
|
||||
}
|
||||
124
src/server/config/types.ts
Normal file
124
src/server/config/types.ts
Normal file
@@ -0,0 +1,124 @@
|
||||
export interface AuthoringConfig {
|
||||
server?: AuthoringServer;
|
||||
variables?: Record<string, ConfigVariableValue>;
|
||||
}
|
||||
|
||||
export interface AuthoringLoggingConfig {
|
||||
console?: AuthoringLoggingConsoleConfig;
|
||||
file?: AuthoringLoggingFileConfig;
|
||||
level?: string;
|
||||
}
|
||||
|
||||
export interface AuthoringLoggingConsoleConfig {
|
||||
level?: string;
|
||||
}
|
||||
|
||||
export interface AuthoringLoggingFileConfig {
|
||||
level?: string;
|
||||
path?: string;
|
||||
rotation?: AuthoringLoggingFileRotationConfig;
|
||||
}
|
||||
|
||||
export interface AuthoringLoggingFileRotationConfig {
|
||||
frequency?: string;
|
||||
maxFiles?: number | string;
|
||||
size?: string;
|
||||
}
|
||||
|
||||
export interface AuthoringServer {
|
||||
listen?: AuthoringServerListen;
|
||||
logging?: AuthoringLoggingConfig;
|
||||
storage?: AuthoringServerStorage;
|
||||
}
|
||||
|
||||
export interface AuthoringServerListen {
|
||||
host?: string;
|
||||
port?: number | string;
|
||||
}
|
||||
|
||||
export interface AuthoringServerStorage {
|
||||
dataDir?: string;
|
||||
}
|
||||
|
||||
export type ConfigVariableValue = boolean | number | string;
|
||||
|
||||
export interface LoggingConfig {
|
||||
console?: { level?: LogLevel };
|
||||
file?: {
|
||||
level?: LogLevel;
|
||||
path?: string;
|
||||
rotation?: {
|
||||
frequency?: RotationFrequency;
|
||||
maxFiles?: number;
|
||||
size?: string;
|
||||
};
|
||||
};
|
||||
level?: LogLevel;
|
||||
}
|
||||
|
||||
export type LogLevel = "debug" | "error" | "fatal" | "info" | "trace" | "warn";
|
||||
|
||||
export interface NormalizedConfig {
|
||||
server?: NormalizedServer;
|
||||
}
|
||||
|
||||
export interface NormalizedLoggingConfig {
|
||||
console?: NormalizedLoggingConsoleConfig;
|
||||
file?: NormalizedLoggingFileConfig;
|
||||
level?: LogLevel;
|
||||
}
|
||||
|
||||
export interface NormalizedLoggingConsoleConfig {
|
||||
level?: LogLevel;
|
||||
}
|
||||
|
||||
export interface NormalizedLoggingFileConfig {
|
||||
level?: LogLevel;
|
||||
path?: string;
|
||||
rotation?: NormalizedLoggingFileRotationConfig;
|
||||
}
|
||||
|
||||
export interface NormalizedLoggingFileRotationConfig {
|
||||
frequency?: RotationFrequency;
|
||||
maxFiles?: number;
|
||||
size?: string;
|
||||
}
|
||||
|
||||
export interface NormalizedServer {
|
||||
listen?: NormalizedServerListen;
|
||||
logging?: NormalizedLoggingConfig;
|
||||
storage?: NormalizedServerStorage;
|
||||
}
|
||||
|
||||
export interface NormalizedServerListen {
|
||||
host?: string;
|
||||
port?: number;
|
||||
}
|
||||
|
||||
export interface NormalizedServerStorage {
|
||||
dataDir?: string;
|
||||
}
|
||||
|
||||
export interface ResolvedConfig {
|
||||
configDir: string;
|
||||
dataDir: string;
|
||||
host: string;
|
||||
logging: ResolvedLoggingConfig;
|
||||
port: number;
|
||||
}
|
||||
|
||||
export interface ResolvedLoggingConfig {
|
||||
consoleLevel: LogLevel;
|
||||
fileLevel: LogLevel;
|
||||
filePath: string;
|
||||
rotationFrequency: RotationFrequency;
|
||||
rotationMaxFiles: number;
|
||||
rotationSizeBytes: number;
|
||||
rotationSizeRaw: string;
|
||||
}
|
||||
|
||||
export type RotationFrequency = "daily" | "hourly" | "weekly";
|
||||
|
||||
export interface ValidatedConfig {
|
||||
server?: NormalizedServer;
|
||||
}
|
||||
188
src/server/config/variables.ts
Normal file
188
src/server/config/variables.ts
Normal file
@@ -0,0 +1,188 @@
|
||||
import { isBoolean, isNumber, isPlainObject, isString } from "es-toolkit";
|
||||
|
||||
import type { ConfigValidationIssue } from "./issues";
|
||||
import type { ConfigVariableValue } from "./types";
|
||||
|
||||
import { issue, joinPath } from "./issues";
|
||||
|
||||
const VARIABLE_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
|
||||
const VARIABLE_REFERENCE_PATTERN = /\$\{([a-zA-Z_][a-zA-Z0-9_]*)(?:\|([^}]*))?\}/g;
|
||||
const COMPLETE_VARIABLE_REFERENCE_PATTERN = /^\$\{([a-zA-Z_][a-zA-Z0-9_]*)(?:\|([^}]*))?\}$/;
|
||||
const ESCAPED_VARIABLE_PATTERN = /\$\$\{([^}]*)\}/g;
|
||||
|
||||
interface VariableReference {
|
||||
defaultValue?: string;
|
||||
key: string;
|
||||
}
|
||||
|
||||
interface VariableResolutionContext {
|
||||
path: string;
|
||||
}
|
||||
|
||||
export function extractVariables(config: unknown): {
|
||||
issues: ConfigValidationIssue[];
|
||||
variables: Map<string, ConfigVariableValue>;
|
||||
} {
|
||||
const issues: ConfigValidationIssue[] = [];
|
||||
const variables = new Map<string, ConfigVariableValue>();
|
||||
|
||||
if (!isPlainObject(config)) {
|
||||
return { issues, variables };
|
||||
}
|
||||
const configRecord = config as Record<string, unknown>;
|
||||
if (configRecord["variables"] === undefined) {
|
||||
return { issues, variables };
|
||||
}
|
||||
|
||||
const rawVariables: unknown = configRecord["variables"];
|
||||
if (!isPlainObject(rawVariables)) {
|
||||
issues.push(issue("invalid-type", "variables", "必须为对象"));
|
||||
return { issues, variables };
|
||||
}
|
||||
|
||||
for (const [key, value] of Object.entries(rawVariables as Record<string, unknown>)) {
|
||||
const path = joinPath("variables", key);
|
||||
if (!VARIABLE_NAME_PATTERN.test(key)) {
|
||||
issues.push(issue("invalid-format", path, "变量名不符合命名规则"));
|
||||
continue;
|
||||
}
|
||||
if (!isVariableValue(value)) {
|
||||
issues.push(issue("invalid-type", path, `变量值不允许为 ${describeInvalidVariableValue(value)}`));
|
||||
continue;
|
||||
}
|
||||
variables.set(key, value);
|
||||
}
|
||||
|
||||
return { issues, variables };
|
||||
}
|
||||
|
||||
export function resolveVariables(config: unknown): { config: unknown; issues: ConfigValidationIssue[] } {
|
||||
const { issues, variables } = extractVariables(config);
|
||||
if (!isPlainObject(config)) {
|
||||
return { config, issues };
|
||||
}
|
||||
|
||||
return { config: resolveConfigValue(config, variables, issues), issues };
|
||||
}
|
||||
|
||||
function describeInvalidVariableValue(value: unknown): string {
|
||||
if (value === null) return "null";
|
||||
if (Array.isArray(value)) return "array";
|
||||
return typeof value;
|
||||
}
|
||||
|
||||
function inferStringValue(value: string): ConfigVariableValue {
|
||||
if (value === "") return value;
|
||||
const numberValue = Number(value);
|
||||
if (Number.isFinite(numberValue)) return numberValue;
|
||||
if (value === "true") return true;
|
||||
if (value === "false") return false;
|
||||
return value;
|
||||
}
|
||||
|
||||
function isVariableValue(value: unknown): value is ConfigVariableValue {
|
||||
return isString(value) || isNumber(value) || isBoolean(value);
|
||||
}
|
||||
|
||||
function parseVariableReference(match: RegExpExecArray): VariableReference {
|
||||
return { defaultValue: match[2], key: match[1]! };
|
||||
}
|
||||
|
||||
function replaceStringValue(
|
||||
value: string,
|
||||
variables: Map<string, ConfigVariableValue>,
|
||||
issues: ConfigValidationIssue[],
|
||||
context: VariableResolutionContext,
|
||||
): ConfigVariableValue | string {
|
||||
const trimmed = value.trim();
|
||||
const completeMatch = COMPLETE_VARIABLE_REFERENCE_PATTERN.exec(trimmed);
|
||||
if (completeMatch) {
|
||||
const resolved = resolveVariableReference(parseVariableReference(completeMatch), variables, issues, context);
|
||||
return resolved ?? value;
|
||||
}
|
||||
|
||||
const escaped: string[] = [];
|
||||
const protectedValue = value.replace(ESCAPED_VARIABLE_PATTERN, (_match, body: string) => {
|
||||
const token = `\u0000${escaped.length}\u0000`;
|
||||
escaped.push(`\${${body}}`);
|
||||
return token;
|
||||
});
|
||||
|
||||
const replaced = protectedValue.replace(
|
||||
VARIABLE_REFERENCE_PATTERN,
|
||||
(match, key: string, defaultValue: string | undefined) => {
|
||||
const resolved = resolveVariableReference({ defaultValue, key }, variables, issues, context);
|
||||
return resolved === undefined ? match : String(resolved);
|
||||
},
|
||||
);
|
||||
|
||||
return escaped.reduce((result, literal, index) => result.replace(`\u0000${index}\u0000`, literal), replaced);
|
||||
}
|
||||
|
||||
function resolveConfigValue(
|
||||
value: unknown,
|
||||
variables: Map<string, ConfigVariableValue>,
|
||||
issues: ConfigValidationIssue[],
|
||||
): unknown {
|
||||
if (!isPlainObject(value)) return value;
|
||||
|
||||
const result: Record<string, unknown> = {};
|
||||
for (const [key, item] of Object.entries(value)) {
|
||||
if (key === "variables") {
|
||||
continue;
|
||||
}
|
||||
const itemPath = joinPath("", key);
|
||||
result[key] = key === "server" ? resolveValue(item, itemPath, variables, issues) : item;
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
function resolveValue(
|
||||
value: unknown,
|
||||
path: string,
|
||||
variables: Map<string, ConfigVariableValue>,
|
||||
issues: ConfigValidationIssue[],
|
||||
): unknown {
|
||||
if (isString(value)) {
|
||||
return replaceStringValue(value, variables, issues, { path });
|
||||
}
|
||||
if (Array.isArray(value)) {
|
||||
return value.map((item, index) => resolveValue(item, `${path}[${index}]`, variables, issues));
|
||||
}
|
||||
if (!isPlainObject(value)) return value;
|
||||
|
||||
const result: Record<string, unknown> = {};
|
||||
for (const [key, item] of Object.entries(value)) {
|
||||
const itemPath = joinPath(path, key);
|
||||
result[key] = resolveValue(item, itemPath, variables, issues);
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
function resolveVariableReference(
|
||||
reference: VariableReference,
|
||||
variables: Map<string, ConfigVariableValue>,
|
||||
issues: ConfigValidationIssue[],
|
||||
context: VariableResolutionContext,
|
||||
): ConfigVariableValue | undefined {
|
||||
if (variables.has(reference.key)) {
|
||||
return variables.get(reference.key);
|
||||
}
|
||||
|
||||
if (Object.prototype.hasOwnProperty.call(process.env, reference.key)) {
|
||||
return inferStringValue(process.env[reference.key] ?? "");
|
||||
}
|
||||
|
||||
if (reference.defaultValue !== undefined) {
|
||||
return inferStringValue(reference.defaultValue);
|
||||
}
|
||||
|
||||
issues.push(
|
||||
issue(
|
||||
"unresolved-variable",
|
||||
context.path,
|
||||
`引用了未定义的变量 "${reference.key}"，且环境变量中也不存在，未设置默认值`,
|
||||
),
|
||||
);
|
||||
return undefined;
|
||||
}
|
||||
@@ -1,5 +1,6 @@
|
||||
import { bootstrap } from "./bootstrap";
|
||||
import { parseRuntimeArgs } from "./config";
|
||||
import { createConsoleFallback } from "./logger";
|
||||
|
||||
async function main() {
|
||||
const { configPath } = parseRuntimeArgs();
|
||||
@@ -7,6 +8,6 @@ async function main() {
|
||||
}
|
||||
|
||||
void main().catch((error) => {
|
||||
console.error("启动失败:", error instanceof Error ? error.message : error);
|
||||
createConsoleFallback().fatal(`启动失败: ${error instanceof Error ? error.message : String(error)}`);
|
||||
process.exit(1);
|
||||
});
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
import type { ApiErrorResponse, HealthResponse, RuntimeMode } from "../shared/api";
|
||||
import type { ApiErrorResponse, MetaResponse, RuntimeMode } from "../shared/api";
|
||||
|
||||
import { APP } from "../shared/app";
|
||||
|
||||
@@ -17,11 +17,12 @@ export function createHeaders(mode: RuntimeMode, init: HeadersInit): Headers {
|
||||
return headers;
|
||||
}
|
||||
|
||||
export function createHealthResponse(): HealthResponse {
|
||||
export function createMetaResponse(version: string): MetaResponse {
|
||||
return {
|
||||
ok: true,
|
||||
service: APP.name,
|
||||
timestamp: new Date().toISOString(),
|
||||
version,
|
||||
};
|
||||
}
|
||||
|
||||
|
||||
279
src/server/logger.ts
Normal file
279
src/server/logger.ts
Normal file
@@ -0,0 +1,279 @@
|
||||
import type pino from "pino";
|
||||
|
||||
import { mkdirSync } from "node:fs";
|
||||
import { dirname, resolve } from "node:path";
|
||||
|
||||
import type { LogLevel, ResolvedLoggingConfig } from "./config/types";
|
||||
|
||||
import { APP } from "../shared/app";
|
||||
|
||||
export interface Logger {
|
||||
child(bindings: Record<string, unknown>): Logger;
|
||||
debug(obj: Record<string, unknown>, msg?: string): void;
|
||||
debug(msg: string): void;
|
||||
error(obj: Record<string, unknown>, msg?: string): void;
|
||||
error(msg: string): void;
|
||||
fatal(obj: Record<string, unknown>, msg?: string): void;
|
||||
fatal(msg: string): void;
|
||||
flush(): void;
|
||||
info(obj: Record<string, unknown>, msg?: string): void;
|
||||
info(msg: string): void;
|
||||
trace(obj: Record<string, unknown>, msg?: string): void;
|
||||
trace(msg: string): void;
|
||||
warn(obj: Record<string, unknown>, msg?: string): void;
|
||||
warn(msg: string): void;
|
||||
}
|
||||
|
||||
export const REDACT_PATHS = [
|
||||
"authorization",
|
||||
"cookie",
|
||||
"set-cookie",
|
||||
"*.set-cookie",
|
||||
"authToken",
|
||||
"key",
|
||||
"password",
|
||||
"token",
|
||||
"apiKey",
|
||||
"*.authorization",
|
||||
"*.cookie",
|
||||
"*.authToken",
|
||||
"*.key",
|
||||
"*.password",
|
||||
"*.token",
|
||||
"*.apiKey",
|
||||
];
|
||||
|
||||
const LOG_LEVEL_MAP: Record<LogLevel, string> = {
|
||||
debug: "debug",
|
||||
error: "error",
|
||||
fatal: "fatal",
|
||||
info: "info",
|
||||
trace: "trace",
|
||||
warn: "warn",
|
||||
};
|
||||
|
||||
type LogFn = (objOrMsg: Record<string, unknown> | string, msg?: string) => void;
|
||||
|
||||
const voidLog: LogFn = () => undefined;
|
||||
|
||||
class ConsoleFallbackLogger implements Logger {
|
||||
child(_bindings: Record<string, unknown>): Logger {
|
||||
return this;
|
||||
}
|
||||
|
||||
debug(objOrMsg: Record<string, unknown> | string, msg?: string): void {
|
||||
console.log(formatMsg(objOrMsg, msg));
|
||||
}
|
||||
|
||||
error(objOrMsg: Record<string, unknown> | string, msg?: string): void {
|
||||
console.error(formatMsg(objOrMsg, msg));
|
||||
}
|
||||
|
||||
fatal(objOrMsg: Record<string, unknown> | string, msg?: string): void {
|
||||
console.error(formatMsg(objOrMsg, msg));
|
||||
}
|
||||
|
||||
flush: () => void = () => undefined;
|
||||
|
||||
info(objOrMsg: Record<string, unknown> | string, msg?: string): void {
|
||||
console.log(formatMsg(objOrMsg, msg));
|
||||
}
|
||||
|
||||
trace(objOrMsg: Record<string, unknown> | string, msg?: string): void {
|
||||
console.log(formatMsg(objOrMsg, msg));
|
||||
}
|
||||
|
||||
warn(objOrMsg: Record<string, unknown> | string, msg?: string): void {
|
||||
console.warn(formatMsg(objOrMsg, msg));
|
||||
}
|
||||
}
|
||||
|
||||
class NoopLogger implements Logger {
|
||||
debug: LogFn = voidLog;
|
||||
error: LogFn = voidLog;
|
||||
fatal: LogFn = voidLog;
|
||||
info: LogFn = voidLog;
|
||||
trace: LogFn = voidLog;
|
||||
warn: LogFn = voidLog;
|
||||
child(_bindings: Record<string, unknown>): Logger {
|
||||
return this;
|
||||
}
|
||||
flush: () => void = () => undefined;
|
||||
}
|
||||
|
||||
class PinoLoggerWrapper implements Logger {
|
||||
private pino: pino.Logger;
|
||||
|
||||
constructor(pinoLogger: pino.Logger) {
|
||||
this.pino = pinoLogger;
|
||||
}
|
||||
|
||||
child(bindings: Record<string, unknown>): Logger {
|
||||
return new PinoLoggerWrapper(this.pino.child(bindings));
|
||||
}
|
||||
|
||||
debug(objOrMsg: Record<string, unknown> | string, msg?: string): void {
|
||||
if (typeof objOrMsg === "string") this.pino.debug(objOrMsg);
|
||||
else this.pino.debug(objOrMsg, msg);
|
||||
}
|
||||
|
||||
error(objOrMsg: Record<string, unknown> | string, msg?: string): void {
|
||||
if (typeof objOrMsg === "string") this.pino.error(objOrMsg);
|
||||
else this.pino.error(objOrMsg, msg);
|
||||
}
|
||||
|
||||
fatal(objOrMsg: Record<string, unknown> | string, msg?: string): void {
|
||||
if (typeof objOrMsg === "string") this.pino.fatal(objOrMsg);
|
||||
else this.pino.fatal(objOrMsg, msg);
|
||||
}
|
||||
|
||||
flush(): void {
|
||||
this.pino.flush();
|
||||
}
|
||||
|
||||
info(objOrMsg: Record<string, unknown> | string, msg?: string): void {
|
||||
if (typeof objOrMsg === "string") this.pino.info(objOrMsg);
|
||||
else this.pino.info(objOrMsg, msg);
|
||||
}
|
||||
|
||||
trace(objOrMsg: Record<string, unknown> | string, msg?: string): void {
|
||||
if (typeof objOrMsg === "string") this.pino.trace(objOrMsg);
|
||||
else this.pino.trace(objOrMsg, msg);
|
||||
}
|
||||
|
||||
warn(objOrMsg: Record<string, unknown> | string, msg?: string): void {
|
||||
if (typeof objOrMsg === "string") this.pino.warn(objOrMsg);
|
||||
else this.pino.warn(objOrMsg, msg);
|
||||
}
|
||||
}
|
||||
|
||||
export class MemoryLogger implements Logger {
|
||||
entries: Array<{ level: string; msg: string; obj?: Record<string, unknown> }> = [];
|
||||
|
||||
child(_bindings: Record<string, unknown>): Logger {
|
||||
return this;
|
||||
}
|
||||
|
||||
debug(objOrMsg: Record<string, unknown> | string, msg?: string): void {
|
||||
this.capture("debug", objOrMsg, msg);
|
||||
}
|
||||
|
||||
error(objOrMsg: Record<string, unknown> | string, msg?: string): void {
|
||||
this.capture("error", objOrMsg, msg);
|
||||
}
|
||||
|
||||
fatal(objOrMsg: Record<string, unknown> | string, msg?: string): void {
|
||||
this.capture("fatal", objOrMsg, msg);
|
||||
}
|
||||
|
||||
flush: () => void = () => undefined;
|
||||
|
||||
info(objOrMsg: Record<string, unknown> | string, msg?: string): void {
|
||||
this.capture("info", objOrMsg, msg);
|
||||
}
|
||||
|
||||
trace(objOrMsg: Record<string, unknown> | string, msg?: string): void {
|
||||
this.capture("trace", objOrMsg, msg);
|
||||
}
|
||||
|
||||
warn(objOrMsg: Record<string, unknown> | string, msg?: string): void {
|
||||
this.capture("warn", objOrMsg, msg);
|
||||
}
|
||||
|
||||
private capture(level: string, objOrMsg: Record<string, unknown> | string, msg?: string): void {
|
||||
if (typeof objOrMsg === "string") {
|
||||
this.entries.push({ level, msg: objOrMsg });
|
||||
} else {
|
||||
this.entries.push({ level, msg: msg ?? "", obj: objOrMsg });
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export function createConsoleFallback(): Logger {
|
||||
return new ConsoleFallbackLogger();
|
||||
}
|
||||
|
||||
export function createMemoryLogger(): MemoryLogger {
|
||||
return new MemoryLogger();
|
||||
}
|
||||
|
||||
export function createNoopLogger(): Logger {
|
||||
return new NoopLogger();
|
||||
}
|
||||
|
||||
export async function createRuntimeLogger(
|
||||
config: ResolvedLoggingConfig,
|
||||
mode: string,
|
||||
version?: string,
|
||||
): Promise<Logger> {
|
||||
const pinoLib = await import("pino");
|
||||
const pinoPretty = await import("pino-pretty");
|
||||
|
||||
mkdirSync(dirname(config.filePath), { recursive: true });
|
||||
|
||||
const rootLevel = resolveRootLevel(config.consoleLevel, config.fileLevel);
|
||||
|
||||
const prettyStream = pinoPretty.default({
|
||||
colorize: true,
|
||||
ignore: "pid,hostname",
|
||||
singleLine: true,
|
||||
translateTime: "SYS:yyyy-mm-dd HH:MM:ss.l",
|
||||
});
|
||||
|
||||
const fileStream = await createRollingFileStream(config);
|
||||
|
||||
const streams: pino.StreamEntry[] = [
|
||||
{ level: toPinoLevel(config.consoleLevel) as pino.Level, stream: prettyStream },
|
||||
{ level: toPinoLevel(config.fileLevel) as pino.Level, stream: fileStream },
|
||||
];
|
||||
|
||||
const base: Record<string, unknown> = { mode, service: APP.name };
|
||||
if (version) base["version"] = version;
|
||||
|
||||
const logger = pinoLib.default(
|
||||
{
|
||||
base,
|
||||
level: rootLevel,
|
||||
redact: { censor: "[Redacted]", paths: REDACT_PATHS },
|
||||
timestamp: pinoLib.stdTimeFunctions.isoTime,
|
||||
},
|
||||
pinoLib.multistream(streams),
|
||||
);
|
||||
|
||||
return new PinoLoggerWrapper(logger);
|
||||
}
|
||||
|
||||
async function createRollingFileStream(config: ResolvedLoggingConfig): Promise<NodeJS.WritableStream> {
|
||||
const dir = dirname(config.filePath);
|
||||
const base = resolve(dir, config.filePath.replace(/^.*[\\/]/, "").replace(/\.log$/, ""));
|
||||
|
||||
try {
|
||||
const buildPinoRoll = (await import("pino-roll")).default;
|
||||
return await buildPinoRoll({
|
||||
file: base,
|
||||
frequency: config.rotationFrequency,
|
||||
limit: { count: config.rotationMaxFiles },
|
||||
mkdir: true,
|
||||
size: config.rotationSizeRaw,
|
||||
});
|
||||
} catch {
|
||||
const fs = await import("node:fs");
|
||||
return fs.createWriteStream(config.filePath, { flags: "a" });
|
||||
}
|
||||
}
|
||||
|
||||
function formatMsg(objOrMsg: Record<string, unknown> | string, msg?: string): string {
|
||||
if (typeof objOrMsg === "string") return objOrMsg;
|
||||
return msg ? `${msg} ${JSON.stringify(objOrMsg)}` : JSON.stringify(objOrMsg);
|
||||
}
|
||||
|
||||
function resolveRootLevel(consoleLevel: LogLevel, fileLevel: LogLevel): string {
|
||||
const order: LogLevel[] = ["trace", "debug", "info", "warn", "error", "fatal"];
|
||||
const ci = order.indexOf(consoleLevel);
|
||||
const fi = order.indexOf(fileLevel);
|
||||
return LOG_LEVEL_MAP[order[Math.min(ci, fi)]!] ?? "info";
|
||||
}
|
||||
|
||||
function toPinoLevel(level: LogLevel): string {
|
||||
return LOG_LEVEL_MAP[level];
|
||||
}
|
||||
@@ -1,5 +1,6 @@
|
||||
import { bootstrap } from "./bootstrap";
|
||||
import { parseRuntimeArgs } from "./config";
|
||||
import { createConsoleFallback } from "./logger";
|
||||
|
||||
async function main() {
|
||||
const { configPath } = parseRuntimeArgs();
|
||||
@@ -7,6 +8,6 @@ async function main() {
|
||||
}
|
||||
|
||||
void main().catch((error) => {
|
||||
console.error("启动失败:", error instanceof Error ? error.message : error);
|
||||
createConsoleFallback().fatal(`启动失败: ${error instanceof Error ? error.message : String(error)}`);
|
||||
process.exit(1);
|
||||
});
|
||||
|
||||
@@ -1,7 +0,0 @@
|
||||
import type { RuntimeMode } from "../../shared/api";
|
||||
|
||||
import { createHealthResponse, jsonResponse } from "../helpers";
|
||||
|
||||
export function handleHealth(mode: RuntimeMode): Response {
|
||||
return jsonResponse(createHealthResponse(), { mode });
|
||||
}
|
||||
7
src/server/routes/meta.ts
Normal file
7
src/server/routes/meta.ts
Normal file
@@ -0,0 +1,7 @@
|
||||
import type { RuntimeMode } from "../../shared/api";
|
||||
|
||||
import { createMetaResponse, jsonResponse } from "../helpers";
|
||||
|
||||
export function handleMeta(mode: RuntimeMode, version: string): Response {
|
||||
return jsonResponse(createMetaResponse(version), { mode });
|
||||
}
|
||||
@@ -1,20 +1,27 @@
|
||||
import type { RuntimeMode } from "../shared/api";
|
||||
import type { ServerConfig } from "./config";
|
||||
import type { Logger } from "./logger";
|
||||
import type { StaticAssets } from "./static";
|
||||
|
||||
import { APP } from "../shared/app";
|
||||
import { createApiError, jsonResponse } from "./helpers";
|
||||
import { handleHealth } from "./routes/health";
|
||||
import { handleMeta } from "./routes/meta";
|
||||
import { serveStaticAsset } from "./static";
|
||||
import { readAppVersion } from "./version";
|
||||
|
||||
export interface StartServerOptions {
|
||||
config: ServerConfig;
|
||||
config: { host: string; port: number };
|
||||
logger: Logger;
|
||||
mode: RuntimeMode;
|
||||
staticAssets?: StaticAssets;
|
||||
version?: string;
|
||||
}
|
||||
|
||||
export function startServer(options: StartServerOptions) {
|
||||
const { config, mode, staticAssets } = options;
|
||||
const { config, logger, mode, staticAssets, version } = options;
|
||||
|
||||
const resolveVersion = (): Promise<string> => {
|
||||
if (version) return Promise.resolve(version);
|
||||
return readAppVersion();
|
||||
};
|
||||
|
||||
const server = Bun.serve({
|
||||
fetch(req) {
|
||||
@@ -27,13 +34,16 @@ export function startServer(options: StartServerOptions) {
|
||||
port: config.port,
|
||||
routes: {
|
||||
"/api/*": () => jsonResponse(createApiError("API route not found", 404), { mode, status: 404 }),
|
||||
"/health": {
|
||||
GET: () => handleHealth(mode),
|
||||
"/api/meta": {
|
||||
GET: async () => {
|
||||
const resolvedVersion = await resolveVersion();
|
||||
return handleMeta(mode, resolvedVersion);
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
console.log(`${APP.name} listening on ${server.url}`);
|
||||
logger.info({ host: config.host, port: config.port, url: server.url.toString() }, "服务启动");
|
||||
|
||||
return server;
|
||||
}
|
||||
|
||||
17
src/server/version.ts
Normal file
17
src/server/version.ts
Normal file
@@ -0,0 +1,17 @@
|
||||
import { resolve } from "node:path";
|
||||
|
||||
import { validateVersion } from "../../scripts/bump-version-logic";
|
||||
|
||||
const PACKAGE_JSON_PATH = resolve(import.meta.dir, "..", "..", "package.json");
|
||||
|
||||
export async function readAppVersion(): Promise<string> {
|
||||
const packageJson = (await Bun.file(PACKAGE_JSON_PATH).json()) as { version: string };
|
||||
const version = packageJson.version;
|
||||
|
||||
if (typeof version !== "string") {
|
||||
throw new Error("package.json does not have a valid version field");
|
||||
}
|
||||
|
||||
validateVersion(version);
|
||||
return version;
|
||||
}
|
||||
@@ -3,10 +3,11 @@ export interface ApiErrorResponse {
|
||||
status: number;
|
||||
}
|
||||
|
||||
export interface HealthResponse {
|
||||
export interface MetaResponse {
|
||||
ok: true;
|
||||
service: string;
|
||||
timestamp: string;
|
||||
version: string;
|
||||
}
|
||||
|
||||
export type RuntimeMode = "development" | "production" | "test";
|
||||
|
||||
@@ -3,5 +3,4 @@ export const APP = {
|
||||
name: "my-app",
|
||||
subtitle: "Bun 全栈应用",
|
||||
title: "My App",
|
||||
version: "0.1.0",
|
||||
} as const;
|
||||
|
||||
@@ -1,7 +1,9 @@
|
||||
import { useQuery } from "@tanstack/react-query";
|
||||
import { useEffect } from "react";
|
||||
import { useLocation } from "react-router";
|
||||
import { ChevronLeftIcon, ChevronRightIcon } from "tdesign-icons-react";
|
||||
import { Button, Layout, RadioGroup } from "tdesign-react";
|
||||
import { Layout, RadioGroup } from "tdesign-react";
|
||||
|
||||
import type { MetaResponse } from "../shared/api";
|
||||
|
||||
import { APP } from "../shared/app";
|
||||
import { Sidebar } from "./components/Sidebar";
|
||||
@@ -22,6 +24,12 @@ export function App() {
|
||||
const { preference: themePreference, setPreference: setThemePreference } = useThemePreference();
|
||||
const { collapsed, toggleCollapsed } = useSidebarCollapsed();
|
||||
const location = useLocation();
|
||||
const { data: meta } = useQuery({
|
||||
queryFn: fetchMeta,
|
||||
queryKey: ["meta"],
|
||||
refetchInterval: 30000,
|
||||
staleTime: 5000,
|
||||
});
|
||||
|
||||
useEffect(() => {
|
||||
document.title = APP.title;
|
||||
@@ -35,15 +43,16 @@ export function App() {
|
||||
const currentPath = location.pathname;
|
||||
const currentItem = MENU_ITEMS.find((item) => item.path === currentPath);
|
||||
const pageTitle = currentItem?.label ?? APP.title;
|
||||
const versionDisplay = meta?.version ? `v${meta.version}` : null;
|
||||
|
||||
return (
|
||||
<Layout className="app-layout">
|
||||
<Header className="app-header">
|
||||
<div className="app-header-left">
|
||||
<Button className="app-sidebar-toggle" onClick={toggleCollapsed} shape="square" variant="text">
|
||||
{collapsed ? <ChevronRightIcon /> : <ChevronLeftIcon />}
|
||||
</Button>
|
||||
<span className="app-brand">{APP.title}</span>
|
||||
<span className="app-brand-group">
|
||||
<span className="app-brand">{APP.title}</span>
|
||||
{versionDisplay && <span className="app-version">{versionDisplay}</span>}
|
||||
</span>
|
||||
<span className="app-page-title">{pageTitle}</span>
|
||||
</div>
|
||||
<div className="app-header-right">
|
||||
@@ -57,8 +66,8 @@ export function App() {
|
||||
</div>
|
||||
</Header>
|
||||
<Layout>
|
||||
<Aside className="app-sidebar" width={collapsed ? "80px" : "232px"}>
|
||||
<Sidebar collapsed={collapsed} />
|
||||
<Aside className="app-sidebar" width={collapsed ? "64px" : "232px"}>
|
||||
<Sidebar collapsed={collapsed} onToggleCollapsed={toggleCollapsed} />
|
||||
</Aside>
|
||||
<Layout>
|
||||
<Content className="app-content">
|
||||
@@ -69,3 +78,9 @@ export function App() {
|
||||
</Layout>
|
||||
);
|
||||
}
|
||||
|
||||
async function fetchMeta(): Promise<MetaResponse> {
|
||||
const response = await fetch("/api/meta");
|
||||
if (!response.ok) throw new Error(`HTTP ${response.status}`);
|
||||
return response.json() as Promise<MetaResponse>;
|
||||
}
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
import { useLocation, useNavigate } from "react-router";
|
||||
import { Menu } from "tdesign-react";
|
||||
import { ChevronLeftIcon, ChevronRightIcon } from "tdesign-icons-react";
|
||||
import { Button, Menu } from "tdesign-react";
|
||||
|
||||
import { MENU_ITEMS } from "../../menu";
|
||||
|
||||
@@ -7,9 +8,10 @@ const { MenuItem } = Menu;
|
||||
|
||||
interface SidebarProps {
|
||||
collapsed: boolean;
|
||||
onToggleCollapsed: () => void;
|
||||
}
|
||||
|
||||
export function Sidebar({ collapsed }: SidebarProps) {
|
||||
export function Sidebar({ collapsed, onToggleCollapsed }: SidebarProps) {
|
||||
const navigate = useNavigate();
|
||||
const location = useLocation();
|
||||
|
||||
@@ -29,8 +31,17 @@ export function Sidebar({ collapsed }: SidebarProps) {
|
||||
className="app-sidebar-menu"
|
||||
collapsed={collapsed}
|
||||
onChange={handleMenuChange}
|
||||
operations={
|
||||
<Button
|
||||
className="app-sidebar-collapse-btn"
|
||||
icon={collapsed ? <ChevronRightIcon /> : <ChevronLeftIcon />}
|
||||
onClick={onToggleCollapsed}
|
||||
shape="square"
|
||||
variant="text"
|
||||
/>
|
||||
}
|
||||
value={activeValue}
|
||||
width={collapsed ? "80px" : "232px"}
|
||||
width={collapsed ? "64px" : "232px"}
|
||||
>
|
||||
{MENU_ITEMS.map((item) => (
|
||||
<MenuItem icon={item.icon} key={item.value} value={item.value}>
|
||||
|
||||
@@ -11,7 +11,7 @@ export function NotFoundPage() {
|
||||
|
||||
return (
|
||||
<Space align="center" className="not-found-page" direction="vertical" size="large">
|
||||
<ErrorCircleIcon size="64px" style={{ color: "var(--td-warning-color)" }} />
|
||||
<ErrorCircleIcon className="not-found-icon" size="64px" />
|
||||
<h1>404</h1>
|
||||
<p>您访问的页面不存在</p>
|
||||
<Button onClick={handleGoHome} theme="primary">
|
||||
|
||||
@@ -1,29 +1,29 @@
|
||||
import { useQuery } from "@tanstack/react-query";
|
||||
import { Space } from "tdesign-react";
|
||||
|
||||
import type { HealthResponse } from "../../../shared/api";
|
||||
import type { MetaResponse } from "../../../shared/api";
|
||||
|
||||
import { APP } from "../../../shared/app";
|
||||
|
||||
export function DashboardPage() {
|
||||
const { data: health } = useQuery({
|
||||
queryFn: fetchHealth,
|
||||
queryKey: ["health"],
|
||||
const { data: meta } = useQuery({
|
||||
queryFn: fetchMeta,
|
||||
queryKey: ["meta"],
|
||||
refetchInterval: 30000,
|
||||
staleTime: 5000,
|
||||
});
|
||||
|
||||
return (
|
||||
<Space direction="vertical" size="large" style={{ width: "100%" }}>
|
||||
<Space className="full-width-space" direction="vertical" size="large">
|
||||
<h2>欢迎使用 {APP.title}</h2>
|
||||
<p>在此构建你的应用。以下是 /health API 的返回数据（前后端联调示例）：</p>
|
||||
{health && <pre className="health-response">{JSON.stringify(health, null, 2)}</pre>}
|
||||
<p>在此构建你的应用。以下是 /api/meta 的返回数据（前后端联调示例）：</p>
|
||||
{meta && <pre className="meta-response">{JSON.stringify(meta, null, 2)}</pre>}
|
||||
</Space>
|
||||
);
|
||||
}
|
||||
|
||||
async function fetchHealth(): Promise<HealthResponse> {
|
||||
const response = await fetch("/health");
|
||||
async function fetchMeta(): Promise<MetaResponse> {
|
||||
const response = await fetch("/api/meta");
|
||||
if (!response.ok) throw new Error(`HTTP ${response.status}`);
|
||||
return response.json() as Promise<HealthResponse>;
|
||||
return response.json() as Promise<MetaResponse>;
|
||||
}
|
||||
|
||||
@@ -2,7 +2,7 @@ import { Card, Space } from "tdesign-react";
|
||||
|
||||
export function SettingsPage() {
|
||||
return (
|
||||
<Space direction="vertical" size="large" style={{ width: "100%" }}>
|
||||
<Space className="full-width-space" direction="vertical" size="large">
|
||||
<h2>系统设置</h2>
|
||||
<Card>
|
||||
<p>页面建设中...</p>
|
||||
|
||||
@@ -2,7 +2,7 @@ import { Card, Space } from "tdesign-react";
|
||||
|
||||
export function UsersPage() {
|
||||
return (
|
||||
<Space direction="vertical" size="large" style={{ width: "100%" }}>
|
||||
<Space className="full-width-space" direction="vertical" size="large">
|
||||
<h2>用户管理</h2>
|
||||
<Card>
|
||||
<p>页面建设中...</p>
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
import type { ReactNode } from "react";
|
||||
|
||||
import { Route, Routes } from "react-router";
|
||||
|
||||
import { NotFoundPage } from "./pages/404";
|
||||
@@ -15,3 +17,7 @@ export function AppRoutes() {
|
||||
</Routes>
|
||||
);
|
||||
}
|
||||
|
||||
export function ProtectedRoute({ children }: { children: ReactNode }) {
|
||||
return children;
|
||||
}
|
||||
|
||||
@@ -30,8 +30,10 @@
|
||||
gap: var(--td-comp-margin-s);
|
||||
}
|
||||
|
||||
.app-sidebar-toggle {
|
||||
padding: var(--td-comp-paddingTB-s) var(--td-comp-paddingLR-s);
|
||||
.app-brand-group {
|
||||
display: inline-flex;
|
||||
align-items: baseline;
|
||||
gap: var(--td-comp-margin-s);
|
||||
}
|
||||
|
||||
.app-brand {
|
||||
@@ -39,6 +41,20 @@
|
||||
color: var(--td-text-color-primary);
|
||||
font-size: calc(var(--td-font-size-title-large) + 6px);
|
||||
font-weight: 700;
|
||||
line-height: 1;
|
||||
}
|
||||
|
||||
.app-version {
|
||||
color: var(--td-text-color-placeholder);
|
||||
font-size: var(--td-font-size-body-small);
|
||||
font-weight: 400;
|
||||
line-height: 1;
|
||||
}
|
||||
|
||||
.app-sidebar-collapse-btn {
|
||||
width: 100%;
|
||||
justify-content: center;
|
||||
color: var(--td-text-color-secondary);
|
||||
}
|
||||
|
||||
.app-page-title {
|
||||
@@ -64,7 +80,7 @@
|
||||
min-height: calc(100vh - 64px);
|
||||
}
|
||||
|
||||
.health-response {
|
||||
.meta-response {
|
||||
background: var(--td-bg-color-component);
|
||||
border-radius: var(--td-radius-default);
|
||||
padding: var(--td-comp-paddingTB-l) var(--td-comp-paddingLR-l);
|
||||
@@ -86,6 +102,14 @@
|
||||
color: var(--td-text-color-disabled);
|
||||
}
|
||||
|
||||
.full-width-space {
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
.not-found-icon {
|
||||
color: var(--td-warning-color);
|
||||
}
|
||||
|
||||
.tabular-nums {
|
||||
font-variant-numeric: tabular-nums;
|
||||
}
|
||||
|
||||
48
tests/scripts/build.test.ts
Normal file
48
tests/scripts/build.test.ts
Normal file
@@ -0,0 +1,48 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
|
||||
import { validateVersion } from "../../scripts/bump-version-logic";
|
||||
|
||||
describe("build 版本注入", () => {
|
||||
test("validateVersion 接受有效版本", () => {
|
||||
expect(() => validateVersion("0.1.0")).not.toThrow();
|
||||
expect(() => validateVersion("1.2.3")).not.toThrow();
|
||||
});
|
||||
|
||||
test("validateVersion 拒绝无效版本", () => {
|
||||
expect(() => validateVersion("invalid")).toThrow();
|
||||
expect(() => validateVersion("1.0.0-beta.1")).toThrow();
|
||||
});
|
||||
|
||||
test("生成的 server-entry 包含版本字面量", () => {
|
||||
const version = "0.1.0";
|
||||
const serverEntryTs = [
|
||||
`import { bootstrap } from "../src/server/bootstrap";`,
|
||||
`import { parseRuntimeArgs } from "../src/server/config";`,
|
||||
`import { staticAssets } from "./static-assets";`,
|
||||
"",
|
||||
`const APP_VERSION = "${version}" as const;`,
|
||||
"",
|
||||
`async function main() {`,
|
||||
` const { configPath } = parseRuntimeArgs();`,
|
||||
` await bootstrap({ configPath, mode: "production", staticAssets, version: APP_VERSION });`,
|
||||
`}`,
|
||||
"",
|
||||
`void main().catch((error) => {`,
|
||||
` console.error("启动失败:", error instanceof Error ? error.message : error);`,
|
||||
` process.exit(1);`,
|
||||
`});`,
|
||||
"",
|
||||
].join("\n");
|
||||
|
||||
expect(serverEntryTs).toContain(`const APP_VERSION = "${version}"`);
|
||||
expect(serverEntryTs).toContain("version: APP_VERSION");
|
||||
});
|
||||
|
||||
test("版本字面量不依赖外部 package.json", () => {
|
||||
const serverEntryTs = [`const APP_VERSION = "0.1.0" as const;`].join("\n");
|
||||
|
||||
expect(serverEntryTs).not.toContain("package.json");
|
||||
expect(serverEntryTs).not.toContain("Bun.file");
|
||||
expect(serverEntryTs).toContain('"0.1.0"');
|
||||
});
|
||||
});
|
||||
73
tests/scripts/bump-version.test.ts
Normal file
73
tests/scripts/bump-version.test.ts
Normal file
@@ -0,0 +1,73 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
|
||||
import { bumpVersion, formatVersion, parseVersion, validateVersion } from "../../scripts/bump-version-logic";
|
||||
|
||||
describe("版本解析与校验", () => {
|
||||
test("parseVersion 解析有效版本", () => {
|
||||
expect(parseVersion("0.1.0")).toEqual([0, 1, 0]);
|
||||
expect(parseVersion("1.2.3")).toEqual([1, 2, 3]);
|
||||
expect(parseVersion("10.20.30")).toEqual([10, 20, 30]);
|
||||
});
|
||||
|
||||
test("parseVersion 拒绝无效版本", () => {
|
||||
expect(() => parseVersion("invalid")).toThrow();
|
||||
expect(() => parseVersion("1.2")).toThrow();
|
||||
expect(() => parseVersion("1.2.3.4")).toThrow();
|
||||
expect(() => parseVersion("1.2.a")).toThrow();
|
||||
});
|
||||
|
||||
test("validateVersion 接受有效版本", () => {
|
||||
expect(() => validateVersion("0.1.0")).not.toThrow();
|
||||
expect(() => validateVersion("1.2.3")).not.toThrow();
|
||||
expect(() => validateVersion("10.20.30")).not.toThrow();
|
||||
});
|
||||
|
||||
test("validateVersion 拒绝无效版本", () => {
|
||||
expect(() => validateVersion("")).toThrow();
|
||||
expect(() => validateVersion("invalid")).toThrow();
|
||||
expect(() => validateVersion("1.2")).toThrow();
|
||||
expect(() => validateVersion("1.2.3.4")).toThrow();
|
||||
expect(() => validateVersion("1.0.0-beta.1")).toThrow();
|
||||
expect(() => validateVersion("v1.0.0")).toThrow();
|
||||
});
|
||||
|
||||
test("formatVersion 格式化版本", () => {
|
||||
expect(formatVersion(0, 1, 0)).toBe("0.1.0");
|
||||
expect(formatVersion(1, 2, 3)).toBe("1.2.3");
|
||||
expect(formatVersion(10, 20, 30)).toBe("10.20.30");
|
||||
});
|
||||
});
|
||||
|
||||
describe("版本升迁逻辑", () => {
|
||||
test("bumpVersion patch 升迁", () => {
|
||||
expect(bumpVersion("1.2.3", "patch")).toBe("1.2.4");
|
||||
expect(bumpVersion("0.1.0", "patch")).toBe("0.1.1");
|
||||
expect(bumpVersion("0.0.1", "patch")).toBe("0.0.2");
|
||||
});
|
||||
|
||||
test("bumpVersion minor 升迁", () => {
|
||||
expect(bumpVersion("1.2.3", "minor")).toBe("1.3.0");
|
||||
expect(bumpVersion("0.1.0", "minor")).toBe("0.2.0");
|
||||
expect(bumpVersion("0.0.1", "minor")).toBe("0.1.0");
|
||||
});
|
||||
|
||||
test("bumpVersion major 升迁", () => {
|
||||
expect(bumpVersion("1.2.3", "major")).toBe("2.0.0");
|
||||
expect(bumpVersion("0.1.0", "major")).toBe("1.0.0");
|
||||
expect(bumpVersion("0.0.1", "major")).toBe("1.0.0");
|
||||
});
|
||||
|
||||
test("bumpVersion set 设置版本", () => {
|
||||
expect(bumpVersion("1.2.3", "set", "2.0.0")).toBe("2.0.0");
|
||||
expect(bumpVersion("0.1.0", "set", "0.2.0")).toBe("0.2.0");
|
||||
});
|
||||
|
||||
test("bumpVersion set 拒绝无效版本", () => {
|
||||
expect(() => bumpVersion("1.2.3", "set", "invalid")).toThrow();
|
||||
expect(() => bumpVersion("1.2.3", "set", "1.0.0-beta.1")).toThrow();
|
||||
});
|
||||
|
||||
test("bumpVersion set 缺少目标版本报错", () => {
|
||||
expect(() => bumpVersion("1.2.3", "set")).toThrow("set command requires a target version");
|
||||
});
|
||||
});
|
||||
@@ -1,71 +1,208 @@
|
||||
/* eslint-disable @typescript-eslint/no-empty-function, @typescript-eslint/no-unused-vars, @typescript-eslint/require-await, @typescript-eslint/unbound-method */
|
||||
/* eslint-disable @typescript-eslint/no-empty-function, @typescript-eslint/require-await */
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { mkdirSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
|
||||
import type { ResolvedConfig } from "../../src/server/config/types";
|
||||
import type { Logger } from "../../src/server/logger";
|
||||
import type { StartServerOptions } from "../../src/server/server";
|
||||
|
||||
import { bootstrap, type BootstrapDependencies } from "../../src/server/bootstrap";
|
||||
import { createMemoryLogger } from "../../src/server/logger";
|
||||
|
||||
const origExit = process.exit;
|
||||
function makeTempConfig(overrides: Partial<ResolvedConfig> = {}): ResolvedConfig {
|
||||
const base = join(tmpdir(), `bootstrap-test-${Date.now()}`);
|
||||
mkdirSync(base, { recursive: true });
|
||||
return {
|
||||
configDir: base,
|
||||
dataDir: join(base, "data"),
|
||||
host: "127.0.0.1",
|
||||
logging: {
|
||||
consoleLevel: "info",
|
||||
fileLevel: "info",
|
||||
filePath: join(base, "data", "logs", "test.log"),
|
||||
rotationFrequency: "daily",
|
||||
rotationMaxFiles: 14,
|
||||
rotationSizeBytes: 52428800,
|
||||
rotationSizeRaw: "50MB",
|
||||
},
|
||||
port: 0,
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
describe("bootstrap", () => {
|
||||
test("使用默认依赖启动", async () => {
|
||||
let started = false;
|
||||
let signalRegistered = false;
|
||||
let loggerPassedToServer: Logger | undefined;
|
||||
|
||||
const mockLoadConfig = (async () => ({
|
||||
host: "127.0.0.1",
|
||||
port: 0,
|
||||
})) as unknown as BootstrapDependencies["loadConfig"];
|
||||
const mockLogError = () => {};
|
||||
const cfg = makeTempConfig();
|
||||
const mockLoadConfig = (async () => cfg) as unknown as BootstrapDependencies["loadConfig"];
|
||||
const mockOnSignal = (_signal: string, _handler: () => void) => {
|
||||
signalRegistered = true;
|
||||
};
|
||||
const mockStartServer = (_options: StartServerOptions) => {
|
||||
const mockStartServer = (options: StartServerOptions) => {
|
||||
loggerPassedToServer = options.logger;
|
||||
started = true;
|
||||
return {};
|
||||
};
|
||||
|
||||
const deps: BootstrapDependencies = {
|
||||
createLogger: async () => createMemoryLogger(),
|
||||
loadConfig: mockLoadConfig,
|
||||
logError: mockLogError,
|
||||
onSignal: mockOnSignal,
|
||||
startServer: mockStartServer,
|
||||
};
|
||||
|
||||
await bootstrap({ mode: "production" }, deps);
|
||||
await bootstrap({ configPath: join(cfg.configDir, "config.yaml"), mode: "production" }, deps);
|
||||
|
||||
expect(started).toBe(true);
|
||||
expect(signalRegistered).toBe(true);
|
||||
expect(loggerPassedToServer).toBeDefined();
|
||||
});
|
||||
|
||||
test("启动失败时调用 logError", async () => {
|
||||
let errorLogged = false;
|
||||
|
||||
// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
|
||||
process.exit = ((code?: number) => {
|
||||
throw new Error("process.exit called");
|
||||
}) as unknown as typeof process.exit;
|
||||
test("传递 version 给 startServer", async () => {
|
||||
let receivedVersion: string | undefined;
|
||||
let loggerCreated = false;
|
||||
|
||||
const cfg = makeTempConfig();
|
||||
const deps: BootstrapDependencies = {
|
||||
loadConfig: async () => {
|
||||
throw new Error("test config error");
|
||||
createLogger: async (_logConfig, _mode, version) => {
|
||||
loggerCreated = true;
|
||||
expect(version).toBe("1.2.3");
|
||||
return createMemoryLogger();
|
||||
},
|
||||
logError: () => {
|
||||
errorLogged = true;
|
||||
loadConfig: async () => cfg,
|
||||
onSignal: () => {},
|
||||
startServer: (options: StartServerOptions) => {
|
||||
receivedVersion = options.version;
|
||||
return {};
|
||||
},
|
||||
};
|
||||
|
||||
await bootstrap({ configPath: join(cfg.configDir, "config.yaml"), mode: "production", version: "1.2.3" }, deps);
|
||||
|
||||
expect(receivedVersion).toBe("1.2.3");
|
||||
expect(loggerCreated).toBe(true);
|
||||
});
|
||||
|
||||
test("logger 初始化失败时使用 fallback 并退出", async () => {
|
||||
let exitCode: number | undefined;
|
||||
|
||||
const cfg = makeTempConfig();
|
||||
const deps: BootstrapDependencies = {
|
||||
createLogger: async () => {
|
||||
throw new Error("pino import failed");
|
||||
},
|
||||
exit: (code: number) => {
|
||||
exitCode = code;
|
||||
throw new Error("exit called");
|
||||
},
|
||||
loadConfig: async () => cfg,
|
||||
startServer: () => {
|
||||
throw new Error("should not reach");
|
||||
},
|
||||
};
|
||||
|
||||
try {
|
||||
await bootstrap({ mode: "production" }, deps);
|
||||
await bootstrap({ configPath: join(cfg.configDir, "config.yaml"), mode: "production" }, deps);
|
||||
} catch {
|
||||
// process.exit throws to interrupt flow
|
||||
// expected - exit threw
|
||||
}
|
||||
|
||||
process.exit = origExit;
|
||||
expect(exitCode).toBe(1);
|
||||
});
|
||||
|
||||
expect(errorLogged).toBe(true);
|
||||
test("启动失败时调用 logger.fatal 并 flush", async () => {
|
||||
let fatalCalled = false;
|
||||
let flushCalled = false;
|
||||
let exitCode: number | undefined;
|
||||
|
||||
const mockLogger = createMemoryLogger();
|
||||
const origFatal = mockLogger.fatal.bind(mockLogger);
|
||||
const origFlush = mockLogger.flush.bind(mockLogger);
|
||||
mockLogger.fatal = (objOrMsg, msg?) => {
|
||||
fatalCalled = true;
|
||||
origFatal(objOrMsg, msg);
|
||||
};
|
||||
mockLogger.flush = () => {
|
||||
flushCalled = true;
|
||||
origFlush();
|
||||
};
|
||||
|
||||
const cfg = makeTempConfig();
|
||||
const deps: BootstrapDependencies = {
|
||||
createLogger: async () => mockLogger,
|
||||
exit: (code: number) => {
|
||||
exitCode = code;
|
||||
throw new Error("exit called");
|
||||
},
|
||||
loadConfig: async () => cfg,
|
||||
startServer: () => {
|
||||
throw new Error("server start failed");
|
||||
},
|
||||
};
|
||||
|
||||
try {
|
||||
await bootstrap({ configPath: join(cfg.configDir, "config.yaml"), mode: "production" }, deps);
|
||||
} catch {
|
||||
// expected
|
||||
}
|
||||
|
||||
expect(fatalCalled).toBe(true);
|
||||
expect(flushCalled).toBe(true);
|
||||
expect(exitCode).toBe(1);
|
||||
});
|
||||
|
||||
test("数据目录创建后记录日志", async () => {
|
||||
const cfg = makeTempConfig();
|
||||
let infoDataDir: string | undefined;
|
||||
|
||||
const mockLogger = createMemoryLogger();
|
||||
const origInfo = mockLogger.info.bind(mockLogger);
|
||||
mockLogger.info = (objOrMsg, msg?) => {
|
||||
if (typeof objOrMsg === "object" && "dataDir" in objOrMsg) {
|
||||
infoDataDir = objOrMsg["dataDir"] as string;
|
||||
}
|
||||
origInfo(objOrMsg, msg);
|
||||
};
|
||||
|
||||
const deps: BootstrapDependencies = {
|
||||
createLogger: async () => mockLogger,
|
||||
loadConfig: async () => cfg,
|
||||
startServer: () => ({}),
|
||||
};
|
||||
|
||||
await bootstrap({ configPath: join(cfg.configDir, "config.yaml"), mode: "development" }, deps);
|
||||
|
||||
expect(infoDataDir).toBe(cfg.dataDir);
|
||||
});
|
||||
|
||||
test("shutdown 时 flush logger", async () => {
|
||||
let flushed = false;
|
||||
let shutdownHandler: (() => void) | undefined;
|
||||
|
||||
const mockLogger = createMemoryLogger();
|
||||
mockLogger.flush = () => {
|
||||
flushed = true;
|
||||
};
|
||||
|
||||
const cfg = makeTempConfig();
|
||||
const deps: BootstrapDependencies = {
|
||||
createLogger: async () => mockLogger,
|
||||
loadConfig: async () => cfg,
|
||||
onSignal: (_signal, handler) => {
|
||||
shutdownHandler = handler;
|
||||
},
|
||||
startServer: () => ({}),
|
||||
};
|
||||
|
||||
await bootstrap({ configPath: join(cfg.configDir, "config.yaml"), mode: "production" }, deps);
|
||||
|
||||
expect(shutdownHandler).toBeDefined();
|
||||
shutdownHandler!();
|
||||
expect(flushed).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -1,59 +1,68 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { rm, writeFile } from "node:fs/promises";
|
||||
import { mkdir, rm, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
|
||||
import { loadServerConfig, parseRuntimeArgs } from "../../src/server/config";
|
||||
import { loadServerConfig, parseRuntimeArgs, parseSize } from "../../src/server/config";
|
||||
import { APP } from "../../src/shared/app";
|
||||
|
||||
describe("parseRuntimeArgs", () => {
|
||||
test("无参数返回空对象", () => {
|
||||
const result = parseRuntimeArgs([]);
|
||||
expect(result).toEqual({});
|
||||
test("无参数抛出需要配置文件路径错误", () => {
|
||||
try {
|
||||
parseRuntimeArgs([]);
|
||||
expect.unreachable();
|
||||
} catch (error) {
|
||||
expect((error as Error).message).toContain("需要指定 YAML 配置文件路径");
|
||||
}
|
||||
});
|
||||
|
||||
test("有参数返回 configPath", () => {
|
||||
const result = parseRuntimeArgs(["config.yaml"]);
|
||||
expect(result).toEqual({ configPath: "config.yaml" });
|
||||
});
|
||||
|
||||
test("--help 抛出错误", () => {
|
||||
try {
|
||||
parseRuntimeArgs(["--help"]);
|
||||
expect.unreachable();
|
||||
} catch (error) {
|
||||
expect((error as Error).message).toContain("用法");
|
||||
}
|
||||
});
|
||||
|
||||
test("-h 抛出错误", () => {
|
||||
try {
|
||||
parseRuntimeArgs(["-h"]);
|
||||
expect.unreachable();
|
||||
} catch (error) {
|
||||
expect((error as Error).message).toContain("用法");
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe("parseSize", () => {
|
||||
test("解析数字字节值", () => {
|
||||
expect(parseSize(1024)).toBe(1024);
|
||||
});
|
||||
|
||||
test("解析字符串大小", () => {
|
||||
expect(parseSize("1KB")).toBe(1024);
|
||||
expect(parseSize("50MB")).toBe(52428800);
|
||||
expect(parseSize("1GB")).toBe(1073741824);
|
||||
expect(parseSize("1024B")).toBe(1024);
|
||||
});
|
||||
|
||||
test("非法格式抛出错误", () => {
|
||||
try {
|
||||
parseSize("invalid");
|
||||
expect.unreachable();
|
||||
} catch (error) {
|
||||
expect((error as Error).message).toContain("无效的 size 格式");
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe("loadServerConfig", () => {
|
||||
test("无 configPath 使用默认值", async () => {
|
||||
const config = await loadServerConfig();
|
||||
expect(config.host).toBe("127.0.0.1");
|
||||
expect(config.port).toBe(3000);
|
||||
});
|
||||
|
||||
test("环境变量 HOST 覆盖默认值", async () => {
|
||||
const prev = process.env["HOST"];
|
||||
process.env["HOST"] = "0.0.0.0";
|
||||
try {
|
||||
const config = await loadServerConfig();
|
||||
expect(config.host).toBe("0.0.0.0");
|
||||
} finally {
|
||||
if (prev === undefined) {
|
||||
delete process.env["HOST"];
|
||||
} else {
|
||||
process.env["HOST"] = prev;
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
test("环境变量 PORT 覆盖默认值", async () => {
|
||||
const prev = process.env["PORT"];
|
||||
process.env["PORT"] = "8080";
|
||||
try {
|
||||
const config = await loadServerConfig();
|
||||
expect(config.port).toBe(8080);
|
||||
} finally {
|
||||
if (prev === undefined) {
|
||||
delete process.env["PORT"];
|
||||
} else {
|
||||
process.env["PORT"] = prev;
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
test("YAML 配置文件不存在时报错", async () => {
|
||||
try {
|
||||
await loadServerConfig("/nonexistent/path/config.yaml");
|
||||
@@ -63,31 +72,219 @@ describe("loadServerConfig", () => {
|
||||
}
|
||||
});
|
||||
|
||||
test("YAML 配置文件加载 server 配置", async () => {
|
||||
test("最简配置解析成功", async () => {
|
||||
const temp = tmpdir();
|
||||
const yamlPath = join(temp, "test-config.yaml");
|
||||
const yamlContent = 'server:\n host: "0.0.0.0"\n port: 9999\n';
|
||||
await writeFile(yamlPath, yamlContent);
|
||||
const yamlPath = join(temp, "minimal.yaml");
|
||||
await writeFile(yamlPath, 'server:\n listen:\n host: "0.0.0.0"\n port: 9999\n');
|
||||
|
||||
try {
|
||||
const config = await loadServerConfig(yamlPath);
|
||||
expect(config.host).toBe("0.0.0.0");
|
||||
expect(config.port).toBe(9999);
|
||||
const result = await loadServerConfig(yamlPath);
|
||||
expect(result.host).toBe("0.0.0.0");
|
||||
expect(result.port).toBe(9999);
|
||||
expect(result.configDir).toBe(temp);
|
||||
expect(result.dataDir).toBe(join(temp, "data"));
|
||||
expect(result.logging.filePath).toBe(join(temp, "data", "logs", `${APP.name}.log`));
|
||||
expect(result.logging.consoleLevel).toBe("info");
|
||||
expect(result.logging.fileLevel).toBe("info");
|
||||
} finally {
|
||||
await rm(yamlPath, { force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("YAML 缺少 server 字段时使用默认值", async () => {
|
||||
test("旧布局 server.host/server.port 被拒绝", async () => {
|
||||
const temp = tmpdir();
|
||||
const yamlPath = join(temp, "test-empty.yaml");
|
||||
const yamlContent = "runtime:\n debug: true\n";
|
||||
const yamlPath = join(temp, "test-old-layout.yaml");
|
||||
const yamlContent = 'server:\n host: "0.0.0.0"\n port: 9999\n';
|
||||
await writeFile(yamlPath, yamlContent);
|
||||
|
||||
try {
|
||||
const config = await loadServerConfig(yamlPath);
|
||||
expect(config.host).toBe("127.0.0.1");
|
||||
expect(config.port).toBe(3000);
|
||||
await loadServerConfig(yamlPath);
|
||||
expect.unreachable();
|
||||
} catch (error) {
|
||||
expect((error as Error).message).toContain("未知字段");
|
||||
} finally {
|
||||
await rm(yamlPath, { force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("非法端口被拒绝", async () => {
|
||||
const temp = tmpdir();
|
||||
const yamlPath = join(temp, "test-bad-port.yaml");
|
||||
await writeFile(yamlPath, "server:\n listen:\n port: 99999\n");
|
||||
|
||||
try {
|
||||
await loadServerConfig(yamlPath);
|
||||
expect.unreachable();
|
||||
} catch (error) {
|
||||
expect((error as Error).message).toBeTruthy();
|
||||
} finally {
|
||||
await rm(yamlPath, { force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("显式变量引用环境变量生效", async () => {
|
||||
const prevHost = process.env["HOST"];
|
||||
const prevPort = process.env["PORT"];
|
||||
process.env["HOST"] = "10.0.0.1";
|
||||
process.env["PORT"] = "4000";
|
||||
|
||||
const temp = tmpdir();
|
||||
const yamlPath = join(temp, "test-env-var.yaml");
|
||||
await writeFile(yamlPath, 'server:\n listen:\n host: "${HOST}"\n port: ${PORT}\n');
|
||||
|
||||
try {
|
||||
const result = await loadServerConfig(yamlPath);
|
||||
expect(result.host).toBe("10.0.0.1");
|
||||
expect(result.port).toBe(4000);
|
||||
} finally {
|
||||
await rm(yamlPath, { force: true });
|
||||
if (prevHost === undefined) delete process.env["HOST"];
|
||||
else process.env["HOST"] = prevHost;
|
||||
if (prevPort === undefined) delete process.env["PORT"];
|
||||
else process.env["PORT"] = prevPort;
|
||||
}
|
||||
});
|
||||
|
||||
test("变量带默认值生效", async () => {
|
||||
delete process.env["MY_HOST"];
|
||||
const temp = tmpdir();
|
||||
const yamlPath = join(temp, "test-default.yaml");
|
||||
await writeFile(yamlPath, 'server:\n listen:\n host: "${MY_HOST|0.0.0.0}"\n port: ${MY_PORT|5000}\n');
|
||||
|
||||
try {
|
||||
const result = await loadServerConfig(yamlPath);
|
||||
expect(result.host).toBe("0.0.0.0");
|
||||
expect(result.port).toBe(5000);
|
||||
} finally {
|
||||
await rm(yamlPath, { force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("绝对 dataDir 保持不变", async () => {
|
||||
const temp = tmpdir();
|
||||
const dataDir = join(temp, "absolute-data");
|
||||
await mkdir(dataDir, { recursive: true });
|
||||
const yamlPath = join(temp, "absolute-dir.yaml");
|
||||
await writeFile(yamlPath, `server:\n storage:\n dataDir: ${JSON.stringify(dataDir)}\n`);
|
||||
|
||||
try {
|
||||
const result = await loadServerConfig(yamlPath);
|
||||
expect(result.dataDir).toBe(dataDir);
|
||||
} finally {
|
||||
await rm(yamlPath, { force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("相对 dataDir 基于 configDir", async () => {
|
||||
const temp = tmpdir();
|
||||
const yamlPath = join(temp, "rel-dir.yaml");
|
||||
await writeFile(yamlPath, 'server:\n storage:\n dataDir: "./my-data"\n');
|
||||
|
||||
try {
|
||||
const result = await loadServerConfig(yamlPath);
|
||||
expect(result.dataDir).toBe(join(temp, "my-data"));
|
||||
} finally {
|
||||
await rm(yamlPath, { force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("显式相对日志路径基于 configDir", async () => {
|
||||
const temp = tmpdir();
|
||||
const yamlPath = join(temp, "log-path.yaml");
|
||||
await writeFile(yamlPath, 'server:\n logging:\n file:\n path: "./logs/app.log"\n');
|
||||
|
||||
try {
|
||||
const result = await loadServerConfig(yamlPath);
|
||||
expect(result.logging.filePath).toBe(join(temp, "logs", "app.log"));
|
||||
} finally {
|
||||
await rm(yamlPath, { force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("绝对日志路径保持不变", async () => {
|
||||
const temp = tmpdir();
|
||||
const logPath = join(temp, "my-app.log");
|
||||
const yamlPath = join(temp, "abs-log.yaml");
|
||||
await writeFile(yamlPath, `server:\n logging:\n file:\n path: ${JSON.stringify(logPath)}\n`);
|
||||
|
||||
try {
|
||||
const result = await loadServerConfig(yamlPath);
|
||||
expect(result.logging.filePath).toBe(logPath);
|
||||
} finally {
|
||||
await rm(yamlPath, { force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("非法 logging.level 抛出错误", async () => {
|
||||
const temp = tmpdir();
|
||||
const yamlPath = join(temp, "bad-level.yaml");
|
||||
await writeFile(yamlPath, 'server:\n logging:\n level: "invalid"\n');
|
||||
|
||||
try {
|
||||
await loadServerConfig(yamlPath);
|
||||
expect.unreachable();
|
||||
} catch (error) {
|
||||
expect((error as Error).message).toContain("日志等级");
|
||||
} finally {
|
||||
await rm(yamlPath, { force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("空白 logging.file.path 抛出错误", async () => {
|
||||
const temp = tmpdir();
|
||||
const yamlPath = join(temp, "blank-path.yaml");
|
||||
await writeFile(yamlPath, 'server:\n logging:\n file:\n path: " "\n');
|
||||
|
||||
try {
|
||||
await loadServerConfig(yamlPath);
|
||||
expect.unreachable();
|
||||
} catch (error) {
|
||||
expect((error as Error).message).toContain("日志路径不能为空字符串或空白字符串");
|
||||
} finally {
|
||||
await rm(yamlPath, { force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("非法 rotation.size 抛出错误", async () => {
|
||||
const temp = tmpdir();
|
||||
const yamlPath = join(temp, "bad-size.yaml");
|
||||
await writeFile(yamlPath, 'server:\n logging:\n file:\n rotation:\n size: "99XX"\n');
|
||||
|
||||
try {
|
||||
await loadServerConfig(yamlPath);
|
||||
expect.unreachable();
|
||||
} catch (error) {
|
||||
expect((error as Error).message).toContain("无效的 size 格式");
|
||||
} finally {
|
||||
await rm(yamlPath, { force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("非法 rotation.frequency 抛出错误", async () => {
|
||||
const temp = tmpdir();
|
||||
const yamlPath = join(temp, "bad-freq.yaml");
|
||||
await writeFile(yamlPath, 'server:\n logging:\n file:\n rotation:\n frequency: "yearly"\n');
|
||||
|
||||
try {
|
||||
await loadServerConfig(yamlPath);
|
||||
expect.unreachable();
|
||||
} catch (error) {
|
||||
expect((error as Error).message).toContain("rotation.frequency");
|
||||
} finally {
|
||||
await rm(yamlPath, { force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("非法 rotation.maxFiles 抛出错误", async () => {
|
||||
const temp = tmpdir();
|
||||
const yamlPath = join(temp, "bad-max.yaml");
|
||||
await writeFile(yamlPath, "server:\n logging:\n file:\n rotation:\n maxFiles: 0\n");
|
||||
|
||||
try {
|
||||
await loadServerConfig(yamlPath);
|
||||
expect.unreachable();
|
||||
} catch (error) {
|
||||
expect((error as Error).message).toContain("maxFiles");
|
||||
} finally {
|
||||
await rm(yamlPath, { force: true });
|
||||
}
|
||||
|
||||
171
tests/server/config/schema.test.ts
Normal file
171
tests/server/config/schema.test.ts
Normal file
@@ -0,0 +1,171 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
|
||||
import { createAuthoringConfigSchema, createNormalizedConfigSchema } from "../../../src/server/config/schema/builder";
|
||||
import { createConfigJsonSchema } from "../../../src/server/config/schema/export";
|
||||
import {
|
||||
createConfigAjv,
|
||||
issuesFromAjvErrors,
|
||||
validateConfigContract,
|
||||
} from "../../../src/server/config/schema/validate";
|
||||
|
||||
describe("导出 schema 生成", () => {
|
||||
test("createConfigJsonSchema 返回有效 JSON Schema", () => {
|
||||
const schema = createConfigJsonSchema();
|
||||
expect(schema["$schema"]).toBe("http://json-schema.org/draft-07/schema#");
|
||||
expect(schema["$id"]).toBe("https://app.local/config.schema.json");
|
||||
expect(schema["type"]).toBe("object");
|
||||
});
|
||||
});
|
||||
|
||||
describe("Authoring schema 校验", () => {
|
||||
const ajv = createConfigAjv();
|
||||
const validate = ajv.compile(createAuthoringConfigSchema());
|
||||
|
||||
test("接受空对象", () => {
|
||||
expect(validate({})).toBe(true);
|
||||
});
|
||||
|
||||
test("接受新布局 server.listen", () => {
|
||||
expect(validate({ server: { listen: { host: "127.0.0.1", port: 3000 } } })).toBe(true);
|
||||
});
|
||||
|
||||
test("接受变量引用语法", () => {
|
||||
expect(validate({ server: { listen: { port: "${PORT|3000}" } } })).toBe(true);
|
||||
});
|
||||
|
||||
test("接受 variables 字段", () => {
|
||||
expect(validate({ variables: { HOST: "127.0.0.1" } })).toBe(true);
|
||||
});
|
||||
|
||||
test("接受 server.storage.dataDir", () => {
|
||||
expect(validate({ server: { storage: { dataDir: "./data" } } })).toBe(true);
|
||||
});
|
||||
|
||||
test("接受 server.logging 合法配置", () => {
|
||||
expect(
|
||||
validate({
|
||||
server: {
|
||||
logging: {
|
||||
console: { level: "debug" },
|
||||
file: {
|
||||
level: "warn",
|
||||
path: "/var/log/app.log",
|
||||
rotation: { frequency: "daily", maxFiles: 14, size: "50MB" },
|
||||
},
|
||||
level: "info",
|
||||
},
|
||||
},
|
||||
}),
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
test("接受 server.logging.level 变量引用", () => {
|
||||
expect(validate({ server: { logging: { level: "${LOG_LEVEL|info}" } } })).toBe(true);
|
||||
});
|
||||
|
||||
test("拒绝 server.logging 中未知字段", () => {
|
||||
expect(validate({ server: { logging: { unknownField: true } } })).toBe(false);
|
||||
});
|
||||
|
||||
test("拒绝 server.logging.level 非法枚举值", () => {
|
||||
expect(validate({ server: { logging: { level: "verbose" } } })).toBe(false);
|
||||
});
|
||||
|
||||
test("拒绝 unknown 字段 server.host", () => {
|
||||
expect(validate({ server: { host: "127.0.0.1" } })).toBe(false);
|
||||
const issues = issuesFromAjvErrors(validate.errors ?? [], {});
|
||||
expect(issues.some((i) => i.code === "unknown-field")).toBe(true);
|
||||
});
|
||||
|
||||
test("拒绝未知字段 server.port", () => {
|
||||
expect(validate({ server: { port: 3000 } })).toBe(false);
|
||||
const issues = issuesFromAjvErrors(validate.errors ?? [], {});
|
||||
expect(issues.some((i) => i.code === "unknown-field")).toBe(true);
|
||||
});
|
||||
|
||||
test("拒绝非法类型 port", () => {
|
||||
expect(validate({ server: { listen: { port: "not-a-number" } } })).toBe(false);
|
||||
});
|
||||
|
||||
test("拒绝超出范围的 port", () => {
|
||||
expect(validate({ server: { listen: { port: 70000 } } })).toBe(false);
|
||||
});
|
||||
|
||||
test("拒绝负数 port", () => {
|
||||
expect(validate({ server: { listen: { port: -1 } } })).toBe(false);
|
||||
});
|
||||
|
||||
test("拒绝顶层未知字段", () => {
|
||||
expect(validate({ unknown: true })).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("Normalized schema 校验", () => {
|
||||
const ajv = createConfigAjv();
|
||||
const validate = ajv.compile(createNormalizedConfigSchema());
|
||||
|
||||
test("接受新布局 server.listen", () => {
|
||||
expect(validate({ server: { listen: { host: "127.0.0.1", port: 3000 } } })).toBe(true);
|
||||
});
|
||||
|
||||
test("Normalized 不接受 variables 字段", () => {
|
||||
expect(validate({ variables: { HOST: "127.0.0.1" } })).toBe(false);
|
||||
});
|
||||
|
||||
test("Normalized 不接受变量引用语法", () => {
|
||||
expect(validate({ server: { listen: { port: "${PORT|3000}" } } })).toBe(false);
|
||||
});
|
||||
|
||||
test("接受 server.storage.dataDir", () => {
|
||||
expect(validate({ server: { storage: { dataDir: "./data" } } })).toBe(true);
|
||||
});
|
||||
|
||||
test("接受 server.logging 合法配置", () => {
|
||||
expect(
|
||||
validate({
|
||||
server: {
|
||||
logging: {
|
||||
console: { level: "debug" },
|
||||
file: {
|
||||
level: "warn",
|
||||
path: "/var/log/app.log",
|
||||
rotation: { frequency: "daily", maxFiles: 14, size: "50MB" },
|
||||
},
|
||||
level: "info",
|
||||
},
|
||||
},
|
||||
}),
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
test("接受空对象", () => {
|
||||
expect(validate({})).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("validateConfigContract", () => {
|
||||
test("有效配置通过校验", () => {
|
||||
const result = validateConfigContract({ server: { listen: { host: "0.0.0.0", port: 8080 } } });
|
||||
expect(result.config).not.toBeNull();
|
||||
});
|
||||
|
||||
test("空配置通过校验", () => {
|
||||
const result = validateConfigContract({});
|
||||
expect(result.config).not.toBeNull();
|
||||
});
|
||||
|
||||
test("包含未知字段的配置被拒绝", () => {
|
||||
const result = validateConfigContract({ server: { host: "bad" } });
|
||||
expect(result.config).toBeNull();
|
||||
expect(result.issues.length).toBeGreaterThan(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe("schema 同步测试", () => {
|
||||
test("config.schema.json 与 createConfigJsonSchema() 输出一致", async () => {
|
||||
const file = Bun.file("config.schema.json");
|
||||
const existing = await file.text();
|
||||
const generated = `${JSON.stringify(createConfigJsonSchema(), null, 2)}\n`;
|
||||
expect(existing).toBe(generated);
|
||||
});
|
||||
});
|
||||
171
tests/server/config/variables.test.ts
Normal file
171
tests/server/config/variables.test.ts
Normal file
@@ -0,0 +1,171 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
|
||||
import { extractVariables, resolveVariables } from "../../../src/server/config/variables";
|
||||
|
||||
describe("extractVariables", () => {
|
||||
test("空对象返回空 variables", () => {
|
||||
const result = extractVariables({});
|
||||
expect(result.variables.size).toBe(0);
|
||||
expect(result.issues.length).toBe(0);
|
||||
});
|
||||
|
||||
test("无 variables 字段返回空", () => {
|
||||
const result = extractVariables({ server: {} });
|
||||
expect(result.variables.size).toBe(0);
|
||||
});
|
||||
|
||||
test("variables 非对象报错", () => {
|
||||
const result = extractVariables({ variables: "bad" });
|
||||
expect(result.issues.length).toBe(1);
|
||||
expect(result.issues[0]!.code).toBe("invalid-type");
|
||||
});
|
||||
|
||||
test("提取有效变量", () => {
|
||||
const result = extractVariables({ variables: { HOST: "127.0.0.1", PORT: 3000 } });
|
||||
expect(result.variables.get("HOST")).toBe("127.0.0.1");
|
||||
expect(result.variables.get("PORT")).toBe(3000);
|
||||
});
|
||||
|
||||
test("无效变量名报错", () => {
|
||||
const result = extractVariables({ variables: { "123bad": "val" } });
|
||||
expect(result.issues.length).toBe(1);
|
||||
expect(result.issues[0]!.code).toBe("invalid-format");
|
||||
});
|
||||
|
||||
test("null 值报错", () => {
|
||||
const result = extractVariables({ variables: { KEY: null } });
|
||||
expect(result.issues.length).toBe(1);
|
||||
expect(result.issues[0]!.code).toBe("invalid-type");
|
||||
});
|
||||
|
||||
test("数组值报错", () => {
|
||||
const result = extractVariables({ variables: { KEY: [1, 2] } });
|
||||
expect(result.issues.length).toBe(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe("resolveVariables", () => {
|
||||
test("${KEY} 从 variables 解析", () => {
|
||||
const result = resolveVariables({
|
||||
server: { listen: { host: "${MY_HOST}" } },
|
||||
variables: { MY_HOST: "0.0.0.0" },
|
||||
});
|
||||
const server = (result.config as Record<string, unknown>)["server"] as Record<string, unknown>;
|
||||
const listen = server["listen"] as Record<string, unknown>;
|
||||
expect(listen["host"]).toBe("0.0.0.0");
|
||||
});
|
||||
|
||||
test("${KEY|default} 使用默认值", () => {
|
||||
const result = resolveVariables({
|
||||
server: { listen: { host: "${MY_HOST|0.0.0.0}" } },
|
||||
});
|
||||
const server = (result.config as Record<string, unknown>)["server"] as Record<string, unknown>;
|
||||
const listen = server["listen"] as Record<string, unknown>;
|
||||
expect(listen["host"]).toBe("0.0.0.0");
|
||||
});
|
||||
|
||||
test("${KEY|} 空默认值", () => {
|
||||
const result = resolveVariables({
|
||||
server: { listen: { host: "${MY_HOST|}" } },
|
||||
});
|
||||
const server = (result.config as Record<string, unknown>)["server"] as Record<string, unknown>;
|
||||
const listen = server["listen"] as Record<string, unknown>;
|
||||
expect(listen["host"]).toBe("");
|
||||
});
|
||||
|
||||
test("$${KEY} 转义不解析", () => {
|
||||
const result = resolveVariables({
|
||||
server: { listen: { host: "$${NOT_A_VAR}" } },
|
||||
});
|
||||
const server = (result.config as Record<string, unknown>)["server"] as Record<string, unknown>;
|
||||
const listen = server["listen"] as Record<string, unknown>;
|
||||
expect(listen["host"]).toBe("${NOT_A_VAR}");
|
||||
});
|
||||
|
||||
test("variables 优先于 process.env", () => {
|
||||
const prev = process.env["TEST_PRIORITY"];
|
||||
process.env["TEST_PRIORITY"] = "from-env";
|
||||
try {
|
||||
const result = resolveVariables({
|
||||
server: { listen: { host: "${TEST_PRIORITY}" } },
|
||||
variables: { TEST_PRIORITY: "from-var" },
|
||||
});
|
||||
const server = (result.config as Record<string, unknown>)["server"] as Record<string, unknown>;
|
||||
const listen = server["listen"] as Record<string, unknown>;
|
||||
expect(listen["host"]).toBe("from-var");
|
||||
} finally {
|
||||
if (prev === undefined) delete process.env["TEST_PRIORITY"];
|
||||
else process.env["TEST_PRIORITY"] = prev;
|
||||
}
|
||||
});
|
||||
|
||||
test("process.env fallback", () => {
|
||||
const prev = process.env["TEST_FALLBACK"];
|
||||
process.env["TEST_FALLBACK"] = "from-env";
|
||||
try {
|
||||
const result = resolveVariables({
|
||||
server: { listen: { host: "${TEST_FALLBACK}" } },
|
||||
});
|
||||
const server = (result.config as Record<string, unknown>)["server"] as Record<string, unknown>;
|
||||
const listen = server["listen"] as Record<string, unknown>;
|
||||
expect(listen["host"]).toBe("from-env");
|
||||
} finally {
|
||||
if (prev === undefined) delete process.env["TEST_FALLBACK"];
|
||||
else process.env["TEST_FALLBACK"] = prev;
|
||||
}
|
||||
});
|
||||
|
||||
test("完整引用保留类型 - number", () => {
|
||||
const result = resolveVariables({
|
||||
server: { listen: { port: "${PORT|3000}" } },
|
||||
});
|
||||
const server = (result.config as Record<string, unknown>)["server"] as Record<string, unknown>;
|
||||
const listen = server["listen"] as Record<string, unknown>;
|
||||
expect(listen["port"]).toBe(3000);
|
||||
expect(typeof listen["port"]).toBe("number");
|
||||
});
|
||||
|
||||
test("完整引用保留类型 - boolean", () => {
|
||||
const result = resolveVariables({
|
||||
server: { listen: { host: "${FLAG|false}" } },
|
||||
});
|
||||
const server = (result.config as Record<string, unknown>)["server"] as Record<string, unknown>;
|
||||
const listen = server["listen"] as Record<string, unknown>;
|
||||
expect(listen["host"]).toBe(false);
|
||||
});
|
||||
|
||||
test("部分插值转为 string", () => {
|
||||
const prev = process.env["PARTIAL_HOST"];
|
||||
process.env["PARTIAL_HOST"] = "192.168";
|
||||
try {
|
||||
const result = resolveVariables({
|
||||
server: { listen: { host: "prefix-${PARTIAL_HOST}-suffix" } },
|
||||
});
|
||||
const server = (result.config as Record<string, unknown>)["server"] as Record<string, unknown>;
|
||||
const listen = server["listen"] as Record<string, unknown>;
|
||||
expect(listen["host"]).toBe("prefix-192.168-suffix");
|
||||
expect(typeof listen["host"]).toBe("string");
|
||||
} finally {
|
||||
if (prev === undefined) delete process.env["PARTIAL_HOST"];
|
||||
else process.env["PARTIAL_HOST"] = prev;
|
||||
}
|
||||
});
|
||||
|
||||
test("unresolved-variable 报错", () => {
|
||||
const result = resolveVariables({
|
||||
server: { listen: { host: "${UNDEFINED_VAR}" } },
|
||||
});
|
||||
expect(result.issues.length).toBe(1);
|
||||
expect(result.issues[0]!.code).toBe("unresolved-variable");
|
||||
expect(result.issues[0]!.message).toContain("UNDEFINED_VAR");
|
||||
});
|
||||
|
||||
test("variables 段被移除", () => {
|
||||
const result = resolveVariables({
|
||||
server: { listen: { host: "test" } },
|
||||
variables: { KEY: "val" },
|
||||
});
|
||||
const config = result.config as Record<string, unknown>;
|
||||
expect(config["variables"]).toBeUndefined();
|
||||
});
|
||||
});
|
||||
117
tests/server/logger.test.ts
Normal file
117
tests/server/logger.test.ts
Normal file
@@ -0,0 +1,117 @@
|
||||
import { describe, expect, test } from "bun:test";
|
||||
|
||||
import type { Logger } from "../../src/server/logger";
|
||||
|
||||
import { createConsoleFallback, createMemoryLogger, createNoopLogger, REDACT_PATHS } from "../../src/server/logger";
|
||||
|
||||
describe("NoopLogger", () => {
|
||||
test("所有方法不抛异常", () => {
|
||||
const logger = createNoopLogger();
|
||||
logger.trace("trace");
|
||||
logger.debug("debug");
|
||||
logger.info("info");
|
||||
logger.warn("warn");
|
||||
logger.error("error");
|
||||
logger.fatal("fatal");
|
||||
logger.flush();
|
||||
const child = logger.child({ component: "test" });
|
||||
expect(child).toBeDefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe("MemoryLogger", () => {
|
||||
test("记录所有等级日志", () => {
|
||||
const logger = createMemoryLogger();
|
||||
logger.trace("trace-msg");
|
||||
logger.debug("debug-msg");
|
||||
logger.info("info-msg");
|
||||
logger.warn("warn-msg");
|
||||
logger.error("error-msg");
|
||||
logger.fatal("fatal-msg");
|
||||
|
||||
expect(logger.entries).toHaveLength(6);
|
||||
expect(logger.entries[0]).toEqual({ level: "trace", msg: "trace-msg" });
|
||||
expect(logger.entries[5]).toEqual({ level: "fatal", msg: "fatal-msg" });
|
||||
});
|
||||
|
||||
test("记录结构化日志", () => {
|
||||
const logger = createMemoryLogger();
|
||||
logger.info({ matched: true, targetId: "abc" }, "check complete");
|
||||
|
||||
expect(logger.entries).toHaveLength(1);
|
||||
expect(logger.entries[0]!.level).toBe("info");
|
||||
expect(logger.entries[0]!.msg).toBe("check complete");
|
||||
expect(logger.entries[0]!.obj).toEqual({ matched: true, targetId: "abc" });
|
||||
});
|
||||
|
||||
test("child 返回自身", () => {
|
||||
const logger = createMemoryLogger();
|
||||
const child = logger.child({ component: "test" });
|
||||
child.info("child-msg");
|
||||
expect(logger.entries).toHaveLength(1);
|
||||
});
|
||||
|
||||
test("flush 不抛异常", () => {
|
||||
const logger = createMemoryLogger();
|
||||
logger.flush();
|
||||
});
|
||||
});
|
||||
|
||||
describe("ConsoleFallbackLogger", () => {
|
||||
test("不抛异常", () => {
|
||||
const logger = createConsoleFallback();
|
||||
logger.trace("trace");
|
||||
logger.debug("debug");
|
||||
logger.info("info");
|
||||
logger.warn("warn");
|
||||
logger.error("error");
|
||||
logger.fatal("fatal");
|
||||
logger.flush();
|
||||
const child = logger.child({ component: "test" });
|
||||
expect(child).toBeDefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe("Logger 接口契约", () => {
|
||||
function assertLogger(logger: Logger): void {
|
||||
logger.trace("trace");
|
||||
logger.debug("debug");
|
||||
logger.info("info");
|
||||
logger.warn("warn");
|
||||
logger.error("error");
|
||||
logger.fatal("fatal");
|
||||
logger.info({ key: "value" }, "structured");
|
||||
logger.child({ component: "test" }).info("child");
|
||||
logger.flush();
|
||||
}
|
||||
|
||||
test("NoopLogger 满足 Logger 接口", () => {
|
||||
expect(() => assertLogger(createNoopLogger())).not.toThrow();
|
||||
});
|
||||
|
||||
test("MemoryLogger 满足 Logger 接口", () => {
|
||||
expect(() => assertLogger(createMemoryLogger())).not.toThrow();
|
||||
});
|
||||
|
||||
test("ConsoleFallbackLogger 满足 Logger 接口", () => {
|
||||
expect(() => assertLogger(createConsoleFallback())).not.toThrow();
|
||||
});
|
||||
});
|
||||
|
||||
describe("redaction 敏感信息保护", () => {
|
||||
test("MemoryLogger 不做 redaction（测试用途，仅 Pino 运行时 redact）", () => {
|
||||
const logger = createMemoryLogger();
|
||||
logger.info({ authorization: "Bearer secret", password: "hunter2" }, "test");
|
||||
const entry = logger.entries[0]!;
|
||||
expect(entry.obj!["authorization"]).toBe("Bearer secret");
|
||||
expect(entry.obj!["password"]).toBe("hunter2");
|
||||
});
|
||||
|
||||
test("REDACT_PATHS 覆盖所有敏感字段键名", () => {
|
||||
const sensitiveKeys = ["authorization", "cookie", "set-cookie", "authToken", "key", "password", "token", "apiKey"];
|
||||
for (const key of sensitiveKeys) {
|
||||
expect(REDACT_PATHS).toContain(key);
|
||||
expect(REDACT_PATHS).toContain(`*.${key}`);
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -10,10 +10,13 @@ import { renderWithProviders } from "./test-utils";
|
||||
describe("App", () => {
|
||||
test("渲染 Layout 骨架和品牌名", () => {
|
||||
window.fetch = (async () => {
|
||||
return new Response(JSON.stringify({ ok: true, service: "test-app", timestamp: new Date().toISOString() }), {
|
||||
headers: { "Content-Type": "application/json" },
|
||||
status: 200,
|
||||
});
|
||||
return new Response(
|
||||
JSON.stringify({ ok: true, service: "test-app", timestamp: new Date().toISOString(), version: "0.1.0" }),
|
||||
{
|
||||
headers: { "Content-Type": "application/json" },
|
||||
status: 200,
|
||||
},
|
||||
);
|
||||
}) as unknown as typeof fetch;
|
||||
|
||||
renderWithProviders(createElement(App));
|
||||
@@ -26,10 +29,13 @@ describe("App", () => {
|
||||
|
||||
test("渲染侧边栏菜单项", () => {
|
||||
window.fetch = (async () => {
|
||||
return new Response(JSON.stringify({ ok: true, service: "test-app", timestamp: new Date().toISOString() }), {
|
||||
headers: { "Content-Type": "application/json" },
|
||||
status: 200,
|
||||
});
|
||||
return new Response(
|
||||
JSON.stringify({ ok: true, service: "test-app", timestamp: new Date().toISOString(), version: "0.1.0" }),
|
||||
{
|
||||
headers: { "Content-Type": "application/json" },
|
||||
status: 200,
|
||||
},
|
||||
);
|
||||
}) as unknown as typeof fetch;
|
||||
|
||||
renderWithProviders(createElement(App));
|
||||
@@ -38,4 +44,21 @@ describe("App", () => {
|
||||
expect(screen.getAllByText("用户管理").length).toBeGreaterThan(0);
|
||||
expect(screen.getAllByText("系统设置").length).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
test("Header 不包含侧边栏折叠按钮", () => {
|
||||
window.fetch = (async () => {
|
||||
return new Response(
|
||||
JSON.stringify({ ok: true, service: "test-app", timestamp: new Date().toISOString(), version: "0.1.0" }),
|
||||
{
|
||||
headers: { "Content-Type": "application/json" },
|
||||
status: 200,
|
||||
},
|
||||
);
|
||||
}) as unknown as typeof fetch;
|
||||
|
||||
renderWithProviders(createElement(App));
|
||||
|
||||
const toggleButtons = document.querySelectorAll(".app-sidebar-toggle");
|
||||
expect(toggleButtons.length).toBe(0);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
/* eslint-disable @typescript-eslint/no-empty-function */
|
||||
import { screen } from "@testing-library/react";
|
||||
import { describe, expect, test } from "bun:test";
|
||||
import { createElement } from "react";
|
||||
@@ -7,7 +8,7 @@ import { renderWithProviders } from "../../test-utils";
|
||||
|
||||
describe("Sidebar", () => {
|
||||
test("渲染菜单项", () => {
|
||||
renderWithProviders(createElement(Sidebar, { collapsed: false }));
|
||||
renderWithProviders(createElement(Sidebar, { collapsed: false, onToggleCollapsed: () => {} }));
|
||||
|
||||
expect(screen.getByText("仪表盘")).not.toBeNull();
|
||||
expect(screen.getByText("用户管理")).not.toBeNull();
|
||||
@@ -15,10 +16,53 @@ describe("Sidebar", () => {
|
||||
});
|
||||
|
||||
test("折叠状态下仍渲染菜单项", () => {
|
||||
renderWithProviders(createElement(Sidebar, { collapsed: true }));
|
||||
renderWithProviders(createElement(Sidebar, { collapsed: true, onToggleCollapsed: () => {} }));
|
||||
|
||||
expect(screen.getByText("仪表盘")).not.toBeNull();
|
||||
expect(screen.getByText("用户管理")).not.toBeNull();
|
||||
expect(screen.getByText("系统设置")).not.toBeNull();
|
||||
});
|
||||
|
||||
test("高亮当前路由对应的菜单项", () => {
|
||||
renderWithProviders(createElement(Sidebar, { collapsed: false, onToggleCollapsed: () => {} }), {
|
||||
initialRoute: "/users",
|
||||
});
|
||||
|
||||
const activeItem = document.querySelector(".t-is-active");
|
||||
expect(activeItem).not.toBeNull();
|
||||
expect(activeItem?.textContent).toContain("用户管理");
|
||||
});
|
||||
|
||||
test("展开态底部渲染折叠按钮", () => {
|
||||
renderWithProviders(createElement(Sidebar, { collapsed: false, onToggleCollapsed: () => {} }));
|
||||
|
||||
const collapseBtn = document.querySelector(".app-sidebar-collapse-btn");
|
||||
expect(collapseBtn).not.toBeNull();
|
||||
});
|
||||
|
||||
test("点击底部按钮调用 onToggleCollapsed", () => {
|
||||
let called = false;
|
||||
const onToggle = () => {
|
||||
called = true;
|
||||
};
|
||||
renderWithProviders(createElement(Sidebar, { collapsed: false, onToggleCollapsed: onToggle }));
|
||||
|
||||
const btn = document.querySelector<HTMLButtonElement>(".app-sidebar-collapse-btn");
|
||||
expect(btn).not.toBeNull();
|
||||
btn!.click();
|
||||
expect(called).toBe(true);
|
||||
});
|
||||
|
||||
test("折叠态底部按钮仍渲染且菜单项高亮不变", () => {
|
||||
renderWithProviders(createElement(Sidebar, { collapsed: true, onToggleCollapsed: () => {} }), {
|
||||
initialRoute: "/users",
|
||||
});
|
||||
|
||||
const collapseBtn = document.querySelector(".app-sidebar-collapse-btn");
|
||||
expect(collapseBtn).not.toBeNull();
|
||||
|
||||
const activeItem = document.querySelector(".t-is-active");
|
||||
expect(activeItem).not.toBeNull();
|
||||
expect(activeItem?.textContent).toContain("用户管理");
|
||||
});
|
||||
});
|
||||
|
||||
@@ -13,4 +13,12 @@ describe("NotFoundPage", () => {
|
||||
expect(screen.getByText("您访问的页面不存在")).not.toBeNull();
|
||||
expect(screen.getByText("返回首页")).not.toBeNull();
|
||||
});
|
||||
|
||||
test("返回首页按钮存在且可点击", () => {
|
||||
renderWithProviders(createElement(NotFoundPage));
|
||||
|
||||
const button = screen.getByText("返回首页");
|
||||
expect(button).not.toBeNull();
|
||||
expect(button.closest("button")).not.toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
@@ -9,10 +9,13 @@ import { renderWithProviders } from "../test-utils";
|
||||
describe("DashboardPage", () => {
|
||||
test("渲染欢迎信息", () => {
|
||||
window.fetch = (async () => {
|
||||
return new Response(JSON.stringify({ ok: true, service: "test-app", timestamp: new Date().toISOString() }), {
|
||||
headers: { "Content-Type": "application/json" },
|
||||
status: 200,
|
||||
});
|
||||
return new Response(
|
||||
JSON.stringify({ ok: true, service: "test-app", timestamp: new Date().toISOString(), version: "0.1.0" }),
|
||||
{
|
||||
headers: { "Content-Type": "application/json" },
|
||||
status: 200,
|
||||
},
|
||||
);
|
||||
}) as unknown as typeof fetch;
|
||||
|
||||
renderWithProviders(createElement(DashboardPage));
|
||||
|
||||
@@ -35,7 +35,6 @@ export default defineConfig({
|
||||
server: {
|
||||
proxy: {
|
||||
"/api": "http://127.0.0.1:3000",
|
||||
"/health": "http://127.0.0.1:3000",
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user