lanyuanxiaoyao/DiAL
1
0
Fork 0
Code Activity

chore: 强化代码质量与风格检查体系

Browse Source 
ESLint 升级到 recommended-type-checked + stylistic-type-checked，
引入 perfectionist 导入排序和 import 插件导入验证。

Prettier 显式声明全部格式化参数，消除跨环境差异。
TypeScript 启用 noUnusedLocals 和 noPropertyAccessFromIndexSignature。
完善 ignore 列表，排除 .agents/、bun.lock、data/ 等。
引入 husky + lint-staged（pre-commit）+ commitlint（commit-msg）。
更新 DEVELOPMENT.md 代码质量章节。
修复所有新增规则检测到的类型和风格违规。
This commit is contained in:
兰缘小妖
2026-05-12 18:44:59 +08:00
parent ce8baae3d1
commit a5cf6065c2
83 changed files with 2654 additions and 1824 deletions
Download Patch File Download Diff File Expand all files Collapse all files

171
DEVELOPMENT.md
View File

@@ -226,15 +226,15 @@ runCommandCheck → 收集观测(exitCode/stdout/stderr/durationMs)
### 2.1 技术栈概览
| 层面 | 技术 | 用途 |
| -------- | ----------------------------------- | ------------------------------ |
| 框架 | React 19 | UI 组件开发 |
| 构建 | Vite 8 | 开发服务与生产构建 |
| 语言 | TypeScript 6 | 类型安全 |
| UI 库 | TDesign React + tdesign-icons-react | UI 组件与图标 |
| 数据层 | TanStack Query (React Query) | 服务端状态管理与自动轮询 |
| 图表 | Recharts | 拨测趋势折线图与状态环状图 |
| 路由 | 无（单页面 Dashboard） | 仅需 Drawer/Tab 做页面内导航 |
| 层面 | 技术 | 用途 |
| ------ | ----------------------------------- | ---------------------------- |
| 框架 | React 19 | UI 组件开发 |
| 构建 | Vite 8 | 开发服务与生产构建 |
| 语言 | TypeScript 6 | 类型安全 |
| UI 库 | TDesign React + tdesign-icons-react | UI 组件与图标 |
| 数据层 | TanStack Query (React Query) | 服务端状态管理与自动轮询 |
| 图表 | Recharts | 拨测趋势折线图与状态环状图 |
| 路由 | 无（单页面 Dashboard） | 仅需 Drawer/Tab 做页面内导航 |
**不引入的依赖**：React Router（单页面场景不需要）、状态管理库（TanStack Query 即服务端状态层，组件内用 `useState` 足够）
@@ -293,7 +293,7 @@ const queryKeys = {
useQuery({
queryKey: queryKeys.summary(),
queryFn: () => fetchJson<SummaryResponse>("/api/summary"),
refetchInterval: 8000, // 自动轮询间隔
refetchInterval: 8000, // 自动轮询间隔
refetchIntervalInBackground: false, // 切后台不轮询
});
@@ -324,9 +324,9 @@ async function fetchJson<T>(url: string): Promise<T> {
new QueryClient({
defaultOptions: {
queries: {
retry: 1, // 失败重试 1 次
retry: 1, // 失败重试 1 次
refetchOnWindowFocus: true, // 窗口聚焦时刷新
staleTime: 5000, // 5s 内视为 fresh，避免重复请求
staleTime: 5000, // 5s 内视为 fresh，避免重复请求
},
},
});
@@ -364,18 +364,18 @@ export function TargetGroup({ name, targets, onTargetClick }: TargetGroupProps)
#### 现有组件清单
| 组件 | 文件 | 用途 |
| ----------------------- | -------------------------- | ---------------------------- |
| `App` | `app.tsx` | 根组件，编排全局状态与布局 |
| `SummaryCards` | `components/SummaryCards.tsx` | 总览统计卡片（全部/正常/异常） |
| `TargetBoard` | `components/TargetBoard.tsx` | 按分组渲染目标表格列表 |
| `TargetGroup` | `components/TargetGroup.tsx` | 单个分组标题 + PrimaryTable |
| `TargetDetailDrawer` | `components/TargetDetailDrawer.tsx` | 目标详情抽屉（概览/记录 Tab） |
| `TrendChart` | `components/TrendChart.tsx` | Recharts 双轴折线图（耗时/可用率） |
| `StatusDonut` | `components/StatusDonut.tsx` | Recharts 环状图（UP/DOWN 分布） |
| `StatusDot` | `components/StatusDot.tsx` | 圆形状态指示点（绿/红） |
| `StatusBar` | `components/StatusBar.tsx` | 最近采样状态条（多色块） |
| `GroupHeader` | `components/GroupHeader.tsx` | 分组标题（名称 + 统计） |
| 组件 | 文件 | 用途 |
| -------------------- | ----------------------------------- | ---------------------------------- |
| `App` | `app.tsx` | 根组件，编排全局状态与布局 |
| `SummaryCards` | `components/SummaryCards.tsx` | 总览统计卡片（全部/正常/异常） |
| `TargetBoard` | `components/TargetBoard.tsx` | 按分组渲染目标表格列表 |
| `TargetGroup` | `components/TargetGroup.tsx` | 单个分组标题 + PrimaryTable |
| `TargetDetailDrawer` | `components/TargetDetailDrawer.tsx` | 目标详情抽屉（概览/记录 Tab） |
| `TrendChart` | `components/TrendChart.tsx` | Recharts 双轴折线图（耗时/可用率） |
| `StatusDonut` | `components/StatusDonut.tsx` | Recharts 环状图（UP/DOWN 分布） |
| `StatusDot` | `components/StatusDot.tsx` | 圆形状态指示点（绿/红） |
| `StatusBar` | `components/StatusBar.tsx` | 最近采样状态条（多色块） |
| `GroupHeader` | `components/GroupHeader.tsx` | 分组标题（名称 + 统计） |
### 2.5 新增功能开发步骤
@@ -491,6 +491,7 @@ server: {
```
SPA fallback 逻辑（`src/server/static.ts`）：
- `/` → index.html
- 匹配 `/assets/*` → 返回对应文件（未匹配则 404）
- 其他路径（如 `/dashboard`）→ fallback 到 index.html（SPA 路由）
@@ -525,16 +526,16 @@ bun run build
#### 产物
| 产物 | 用途 |
| ---------------------------- | ------------------------ |
| `dist/dial-server` | 生产可执行文件 |
| `dist/web/` | Vite 构建产物（中间产物） |
| `.build/` | 临时生成文件（构建后清理） |
| 产物 | 用途 |
| ------------------ | -------------------------- |
| `dist/dial-server` | 生产可执行文件 |
| `dist/web/` | Vite 构建产物（中间产物） |
| `.build/` | 临时生成文件（构建后清理） |
#### 构建参数
| 环境变量 | 说明 |
| ------------------- | ----------------------------------------- |
| 环境变量 | 说明 |
| --------------------------- | -------------------------------------- |
| `BUN_TARGET`/`BUILD_TARGET` | 交叉编译目标平台（如 `bun-linux-x64`） |
#### 运行可执行文件
@@ -587,32 +588,32 @@ bun run test:smoke
### 3.6 脚本说明
| 脚本 | 文件 | 说明 |
| ----------------------- | ------------------ | ---------------------------------- |
| `bun run dev` | `scripts/dev.ts` | 同时启动前后端开发服务 |
| `bun run build` | `scripts/build.ts` | Vite 构建 + Bun 编译可执行文件 |
| `bun run test:smoke` | `scripts/smoke.ts` | 构建后的端到端验证 |
| `bun run clean` | `scripts/clean.ts` | 清理构建缓存与临时文件 |
| 脚本 | 文件 | 说明 |
| -------------------- | ------------------ | ------------------------------ |
| `bun run dev` | `scripts/dev.ts` | 同时启动前后端开发服务 |
| `bun run build` | `scripts/build.ts` | Vite 构建 + Bun 编译可执行文件 |
| `bun run test:smoke` | `scripts/smoke.ts` | 构建后的端到端验证 |
| `bun run clean` | `scripts/clean.ts` | 清理构建缓存与临时文件 |
### 3.7 环境变量
| 变量 | 用途 | 默认值 |
| ----------------------- | ------------------------------------------- | ------ |
| `PORT`/`BACKEND_PORT` | 后端监听端口（开发期 Vite 代理目标、生产期监听端口） | `3000` |
| `BUN_TARGET`/`BUILD_TARGET` | 交叉编译目标平台（仅在 `bun run build` 时有效） | 当前平台 |
| 变量 | 用途 | 默认值 |
| --------------------------- | ---------------------------------------------------- | -------- |
| `PORT`/`BACKEND_PORT` | 后端监听端口（开发期 Vite 代理目标、生产期监听端口） | `3000` |
| `BUN_TARGET`/`BUILD_TARGET` | 交叉编译目标平台（仅在 `bun run build` 时有效） | 当前平台 |
### 3.8 项目配置文件
| 文件 | 用途 |
| --------------------- | -------------------------------------- |
| `package.json` | 项目信息、脚本、依赖声明 |
| `tsconfig.json` | TypeScript 配置（ESNext 模块、严格模式）|
| `vite.config.ts` | Vite 开发代理与构建配置 |
| 文件 | 用途 |
| --------------------- | ---------------------------------------------- |
| `package.json` | 项目信息、脚本、依赖声明 |
| `tsconfig.json` | TypeScript 配置（ESNext 模块、严格模式） |
| `vite.config.ts` | Vite 开发代理与构建配置 |
| `eslint.config.js` | ESLint 规则（含前端不得 import server 的检查） |
| `.prettierrc.json` | Prettier 格式化规则（`printWidth: 120`） |
| `.prettierignore` | Prettier 排除路径 |
| `probes.example.yaml` | 配置文件示例 |
| `opencode.json` | OpenCode 工具配置（TDesign MCP server） |
| `.prettierrc.json` | Prettier 格式化规则（`printWidth: 120`） |
| `.prettierignore` | Prettier 排除路径 |
| `probes.example.yaml` | 配置文件示例 |
| `opencode.json` | OpenCode 工具配置（TDesign MCP server） |
### 3.9 依赖管理
@@ -623,33 +624,77 @@ bun run test:smoke
### 3.10 目录约定
| 目录 | 约定 |
| --------------- | ------------------------------------------ |
| `src/server/` | 后端代码，不能 import `src/web/` |
| `src/web/` | 前端代码，不能 import `src/server/` |
| `src/shared/` | 前后端共享类型，双向可引用 |
| `scripts/` | 独立运行脚本，可 import 项目源码 |
| `tests/` | 测试目录，结构镜像 src 目录 |
| `dist/` | 构建产物（gitignore） |
| `.build/` | 构建临时文件（gitignore） |
| `openspec/` | OpenSpec 变更管理与规格文档 |
| `data/` | 默认数据目录（gitignore，运行期生成 SQLite）|
| 目录 | 约定 |
| ------------- | -------------------------------------------- |
| `src/server/` | 后端代码，不能 import `src/web/` |
| `src/web/` | 前端代码，不能 import `src/server/` |
| `src/shared/` | 前后端共享类型，双向可引用 |
| `scripts/` | 独立运行脚本，可 import 项目源码 |
| `tests/` | 测试目录，结构镜像 src 目录 |
| `dist/` | 构建产物（gitignore） |
| `.build/` | 构建临时文件（gitignore） |
| `openspec/` | OpenSpec 变更管理与规格文档 |
| `data/` | 默认数据目录（gitignore，运行期生成 SQLite） |
---
## 代码质量
项目使用多层代码质量保障体系：ESLint 类型感知规则 + Perfectionist 导入排序 + Prettier 格式化 + TypeScript 严格模式 + Git hooks 自动化。
```bash
bun run lint # ESLint 检查
bun run lint # ESLint 检查（含类型感知规则、导入排序、导入验证）
bun run format:check # Prettier 格式检查
bun run format # Prettier 自动格式化
bun run typecheck # TypeScript 类型检查
bun run typecheck # TypeScript 类型检查（含 noUnusedLocals、noPropertyAccessFromIndexSignature）
bun test # 运行所有测试
bun run check # 一键运行 typecheck + lint + format:check + test
```
`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` | 导入路径验证、循环依赖检测、重复导入合并 |
### Prettier 配置
配置文件：`.prettierrc.json`
显式声明所有格式化参数（`printWidth: 120`、`semi: true`、`singleQuote: false`、`trailingComma: "all"`、`endOfLine: "lf"` 等），确保不同开发环境产出完全一致的格式化结果。
### TypeScript 严格标志
| 标志 | 值 | 说明 |
| ------------------------------------ | ----- | -------------------------------------------------------------------------- |
| `strict` | true | 全局严格模式 |
| `noUnusedLocals` | true | 未使用局部变量视为错误 |
| `noUnusedParameters` | false | 保留关闭（路由 handler 统一签名需要，如 `handleXxx(store, method, mode)`） |
| `noPropertyAccessFromIndexSignature` | true | 禁止通过点号访问索引签名属性，强制使用括号语法 |
| `noUncheckedIndexedAccess` | true | 数组/Map 访问必须运行时真值检查 |
| `verbatimModuleSyntax` | true | 强制 `import type` 纯类型导入 |
### Git Hooks
通过 husky 在 commit 阶段自动执行检查：
| Hook | 行为 |
| ------------ | -------------------------------------------------------------- |
| `pre-commit` | lint-staged 对变更文件运行 `eslint --fix` + `prettier --write` |
| `commit-msg` | commitlint 校验提交信息格式 `类型: 简短描述` |
提交类型限定：`feat`、`fix`、`refactor`、`docs`、`style`、`test`、`chore`。
`bun install` 时自动初始化 husky hooks，无需手动配置。
## 测试
```bash