docs: 重构文档体系
- 合并 DEVELOPMENT.md 至 docs/development/README.md - 合并 CONTRIBUTING.md 至 docs/development/checker.md - 合并 build-release.md 至 release.md - 合并 testing-quality.md 内容至各专题文档 - 合并 status-model.md 至 expectations.md - 新增 docs/user/README.md 用户入口 - 简化 docs/README.md 文档路由 - 各专题文档新增适用场景和更新触发条件 - 更新 openspec/config.yaml 文档规则
This commit is contained in:
@@ -1,25 +1,115 @@
|
||||
# 开发文档
|
||||
|
||||
本目录承载 DiAL 的开发和维护专题。日常开发入口见 [`../../DEVELOPMENT.md`](../../DEVELOPMENT.md)，新增或修改 checker 前先阅读 [`../../CONTRIBUTING.md`](../../CONTRIBUTING.md)。
|
||||
本文档是 DiAL 的开发入口。AI 工具和开发者应先阅读 [`../README.md`](../README.md) 判断文档归属，再阅读本文和最小必要专题。
|
||||
|
||||
适用场景：修改源码、测试、构建脚本、开发流程、架构边界、checker 开发机制或项目工程规则。
|
||||
|
||||
## 专题索引
|
||||
|
||||
| 文档 | 内容 |
|
||||
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
|
||||
| [architecture.md](architecture.md) | 项目结构、启动流程、运行时流程、HTTP 请求流程、前后端边界 |
|
||||
| [backend.md](backend.md) | 后端库优先级、API 路由、共享 helpers、类型规范、配置契约、store、engine、logger、expect、错误模型 |
|
||||
| [frontend.md](frontend.md) | React、TDesign、TanStack Query、组件、样式和前端测试规范 |
|
||||
| [checker-development.md](checker-development.md) | 新增或修改 checker 的实现机制和完整 checklist |
|
||||
| [build-release.md](build-release.md) | 开发服务、前后端集成、构建、Docker、release、脚本、环境变量 |
|
||||
| [testing-quality.md](testing-quality.md) | lint、format、typecheck、test、hooks 和测试编写规范 |
|
||||
| [../../DEVELOPMENT.md](../../DEVELOPMENT.md) | 包管理、依赖、目录、提交、OpenSpec 和项目级约定 |
|
||||
| [../README.md](../README.md) | 文档影响分析、文档归属矩阵和按任务阅读路径 |
|
||||
| 文档 | 内容 |
|
||||
| ---------------------------------- | ------------------------------------------------------------------------------------------------- |
|
||||
| [architecture.md](architecture.md) | 项目结构、启动流程、运行时流程、HTTP 请求流程、前后端边界 |
|
||||
| [backend.md](backend.md) | 后端库优先级、API 路由、共享 helpers、类型规范、配置契约、store、engine、logger、expect、错误模型 |
|
||||
| [frontend.md](frontend.md) | React、TDesign、TanStack Query、组件、样式和前端测试规范 |
|
||||
| [checker.md](checker.md) | 新增或修改 checker 的实现机制、测试要求、文档同步和 checklist |
|
||||
| [release.md](release.md) | 开发服务、前后端集成、构建、Docker、release、脚本、环境变量 |
|
||||
| [../README.md](../README.md) | 文档路由、文档归属矩阵、development/user 文档更新规则 |
|
||||
|
||||
## 常用命令
|
||||
|
||||
| 命令 | 说明 |
|
||||
| -------------------------------- | ---------------------------------------- |
|
||||
| `bun install` | 安装依赖 |
|
||||
| `bun run dev probes.yaml` | 启动双进程开发环境 |
|
||||
| `bun run dev:server probes.yaml` | 仅启动后端 API server |
|
||||
| `bun run dev:web` | 仅启动 Vite dev server |
|
||||
| `bun run schema` | 生成 `probe-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 release` | 跨平台发布打包 |
|
||||
| `bun run clean` | 清理构建缓存与产物 |
|
||||
|
||||
## 质量门禁
|
||||
|
||||
代码变更必须按影响范围执行验证。
|
||||
|
||||
| 变更类型 | 必跑命令 |
|
||||
| -------------------------------- | --------------------------------------------------------- |
|
||||
| 常规代码变更 | `bun run check` |
|
||||
| 构建、部署、发布、前后端集成变更 | `bun run verify` |
|
||||
| 配置 schema 变化 | `bun run schema`、`bun run schema:check`、`bun run check` |
|
||||
| checker 新增或修改 | `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 Dashboard，不能 import `src/server/` 运行时实现 |
|
||||
| `src/shared/` | 前后端共享 TypeScript 类型 |
|
||||
| `scripts/` | 独立运行脚本，可 import 项目源码 |
|
||||
| `tests/` | 测试目录，结构镜像 `src/` |
|
||||
| `docs/user/` | 用户使用、配置、部署、checker 和排障文档 |
|
||||
| `docs/development/` | 架构、后端、前端、发布和 checker 开发文档 |
|
||||
| `openspec/` | OpenSpec 变更管理与规格文档 |
|
||||
|
||||
## 文档影响分析
|
||||
|
||||
每次代码变更都必须执行文档影响分析。
|
||||
|
||||
| 如果变更影响 | 更新 |
|
||||
| --------------------------------------------------- | ------------------------------------------ |
|
||||
| 用户可见行为、配置、checker、expect、部署、状态模型 | `docs/user/` 对应文档 |
|
||||
| 开发流程、架构、测试、构建发布、checker 开发机制 | `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、`probe-config.schema.json`、schema 测试 |
|
||||
| 项目全局规则 | `openspec/config.yaml`、`DEVELOPMENT.md`、本目录专题文档 |
|
||||
| checker 贡献流程 | `CONTRIBUTING.md`、`checker-development.md` |
|
||||
| 主题 | 事实来源 |
|
||||
| -------------- | ---------------------------------------------------------- |
|
||||
| 代码结构和实现 | `src/`、`scripts/`、`tests/` |
|
||||
| 配置 schema | TypeBox fragments、`probe-config.schema.json`、schema 测试 |
|
||||
| 项目全局规则 | `openspec/config.yaml`、本文档、本目录专题文档 |
|
||||
| checker 流程 | [checker.md](checker.md) |
|
||||
|
||||
## 更新触发条件
|
||||
|
||||
修改常用命令、质量门禁、全局工程规则、目录边界、OpenSpec 协作方式或开发文档索引时，必须更新本文档。
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 架构与边界
|
||||
|
||||
本文档说明 DiAL 的项目结构、启动链路、运行时流程、HTTP 请求流程和前后端边界。
|
||||
|
||||
适用场景：修改目录边界、启动流程、运行时调度、HTTP server、前后端集成方式或主要模块职责。
|
||||
|
||||
## 项目结构
|
||||
|
||||
```text
|
||||
@@ -104,3 +108,7 @@ Request
|
||||
| `src/server/checker/expect/` | 跨 checker 复用的断言基础设施 |
|
||||
| `src/web/` | React Dashboard |
|
||||
| `src/shared/api.ts` | 前后端共享 API 类型 |
|
||||
|
||||
## 更新触发条件
|
||||
|
||||
修改项目结构、启动流程、运行时流程、HTTP 请求流程、前后端边界或主要模块职责时，必须更新本文档。
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 后端开发
|
||||
|
||||
本文档说明 DiAL 后端的 API、配置加载、存储、拨测引擎、日志、expect 和错误模型开发约定。
|
||||
|
||||
适用场景：修改 `src/server/`、`src/shared/api.ts`、后端测试、配置契约、API 响应、store、engine、logger 或 expect 基础设施。
|
||||
|
||||
## 库使用优先级
|
||||
|
||||
| 优先级 | 来源 | 典型用途 |
|
||||
@@ -111,13 +115,28 @@ Ajv 保持严格拒绝模式：`allErrors: true`、不启用类型强制转换
|
||||
| `ContentExpectations` | 返回内容或半结构化内容 | body、stdout、stderr、banner、response、output、result |
|
||||
| `KeyedExpectations` | 动态键值断言 | headers、DB rows 列值 |
|
||||
|
||||
详细 checker 开发流程见 [Checker 开发](checker-development.md)。
|
||||
详细 checker 开发流程见 [Checker 开发](checker.md)。
|
||||
|
||||
## 错误模型
|
||||
|
||||
| 类型 | 结构 |
|
||||
| ------------ | ----------------------------------- | ------------------------------------------------------- |
|
||||
| API 错误 | `{ error: "描述", status: <code> }` |
|
||||
| CheckFailure | `{ kind: "error" | "mismatch", phase, path, expected?, actual?, message }` |
|
||||
- API 错误：`{ error: "描述", status: <code> }`
|
||||
- CheckFailure：`{ kind: "error" | "mismatch", phase, path, expected?, actual?, message }`
|
||||
|
||||
expect 校验失败记录首个失败原因；网络、超时、进程崩溃统一为 `kind: "error"`。
|
||||
|
||||
## 后端测试与验证
|
||||
|
||||
| 变更类型 | 测试重点 |
|
||||
| ---------------------- | ---------------------------------------- |
|
||||
| API 路由 | `tests/server/app.test.ts` 集成行为 |
|
||||
| 配置 schema 或语义校验 | schema 导出、合法配置、非法配置 |
|
||||
| store | SQLite 写入、查询、分页、聚合和清理 |
|
||||
| engine | 调度、并发、超时、结果写入和状态变化日志 |
|
||||
| expect 基础设施 | matcher 语义、快速失败、错误信息 |
|
||||
| checker runner | 见 [Checker 开发](checker.md#测试要求) |
|
||||
|
||||
后端运行时代码统一通过注入的 Logger 输出日志，禁止直接使用 `console.*`。新增或修改后端逻辑通常需要运行 `bun run check`；影响构建产物或前后端集成时运行 `bun run verify`。
|
||||
|
||||
## 更新触发条件
|
||||
|
||||
修改后端 API、共享类型、配置契约、store、engine、logger、expect 基础设施、错误模型或后端测试规范时，必须更新本文档。
|
||||
|
||||
@@ -1,8 +1,21 @@
|
||||
# Checker 开发
|
||||
|
||||
Checker 是 DiAL 的核心扩展单元。每个 checker 是 `src/server/checker/runner/<type>/` 下的自包含目录，包含该 checker 所需的类型、schema、校验、执行逻辑和断言。
|
||||
Checker 是 DiAL 的核心扩展单元。每个 checker 是 `src/server/checker/runner/<type>/` 下的自包含目录，包含类型、schema、语义校验、执行逻辑、序列化和断言。
|
||||
|
||||
新增或修改 checker 前请同时阅读 [`../../CONTRIBUTING.md`](../../CONTRIBUTING.md)、[配置文件](../user/configuration.md)、[校验规则](../user/expectations.md) 和 [Checker 用户文档](../user/checkers/README.md)。
|
||||
适用场景：新增 checker、修改 checker 配置或 expect、调整 checker 注册机制、改动 checker 测试或用户文档同步规则。
|
||||
|
||||
新增或修改 checker 前必须阅读 [开发入口](README.md)、[配置文件](../user/configuration.md)、[校验规则](../user/expectations.md) 和 [Checker 用户文档](../user/checkers/README.md)。还应阅读现有同类 checker 的实现和测试，例如 `src/server/checker/runner/http/` 与 `tests/server/checker/runner/http/`。
|
||||
|
||||
## 设计原则
|
||||
|
||||
- 每个 checker 必须自包含在 `src/server/checker/runner/<type>/`。
|
||||
- checker 专属类型、schema、validate、execute、expect 和协议辅助逻辑放在同一目录。
|
||||
- 注册只修改 `src/server/checker/runner/index.ts`，中间层不新增 type switch。
|
||||
- schema 层只描述契约，语义规则放入 `validate.ts`。
|
||||
- `resolve()` 只做默认值填充、路径解析和单位转换，不执行校验。
|
||||
- `execute()` 必须支持 `CheckerContext.signal` 超时取消。
|
||||
- expect 字段必须选择合适断言模型，不为了统一而滥用 ValueMatcher。
|
||||
- failure phase 命名遵循去单位后缀规则，例如 `durationMs` 对应 `duration`。
|
||||
|
||||
## 架构目标
|
||||
|
||||
@@ -136,26 +149,39 @@ const resolvedExpect: ResolvedXxxExpectConfig = expect
|
||||
- `probe-config.schema.json`，通过 `bun run schema` 生成
|
||||
- `docs/user/checkers/<type>.md`
|
||||
- `docs/user/checkers/README.md`
|
||||
- `docs/user/expectations.md`，仅当断言模型或通用规则变化
|
||||
- `docs/development/checker-development.md`，仅当开发机制变化
|
||||
- `CONTRIBUTING.md`，仅当贡献流程或 checklist 变化
|
||||
- `docs/user/expectations.md`，仅当断言模型、状态模型或通用规则变化
|
||||
- `docs/user/configuration.md`，仅当 target 通用字段或配置加载形态变化
|
||||
- `docs/development/checker.md`，仅当 checker 开发机制、测试要求或 checklist 变化
|
||||
- `docs/README.md` 和 `openspec/config.yaml`，仅当文档同步规则变化
|
||||
|
||||
## 验证命令
|
||||
|
||||
新增或修改 checker 后通常需要运行：
|
||||
|
||||
```bash
|
||||
bun run schema
|
||||
bun run schema:check
|
||||
bun run check
|
||||
```
|
||||
|
||||
影响构建、Docker 或发布包时追加运行 `bun run verify`。
|
||||
|
||||
## 完成检查清单
|
||||
|
||||
```text
|
||||
□ src/server/checker/runner/<type>/types.ts
|
||||
□ src/server/checker/runner/<type>/schema.ts
|
||||
□ src/server/checker/runner/<type>/validate.ts
|
||||
□ src/server/checker/runner/<type>/execute.ts
|
||||
□ src/server/checker/runner/<type>/expect.ts
|
||||
□ src/server/checker/runner/<type>/index.ts
|
||||
□ src/server/checker/runner/index.ts
|
||||
□ tests/server/checker/runner/<type>/
|
||||
□ probes.example.yaml
|
||||
□ probe-config.schema.json
|
||||
□ docs/user/checkers/<type>.md
|
||||
□ bun run schema
|
||||
□ bun run schema:check
|
||||
□ bun run check
|
||||
□ bun run verify
|
||||
□ checker 类型、schema、validate、resolve、execute、serialize 已实现
|
||||
□ checker 已在 runner/index.ts 注册
|
||||
□ 配置契约、语义校验和 JSON Schema 导出已同步
|
||||
□ probes.example.yaml 已添加或更新示例
|
||||
□ tests/server/checker/runner/<type>/ 已覆盖契约、校验、resolve、execute、注册和配置加载
|
||||
□ docs/user/checkers/<type>.md 已添加或更新
|
||||
□ docs/user/checkers/README.md 已添加或更新
|
||||
□ 文档影响分析已完成，必要文档已同步
|
||||
□ bun run schema 和 bun run schema:check 已通过
|
||||
□ bun run check 已通过
|
||||
□ bun run verify 已通过或记录未执行原因
|
||||
```
|
||||
|
||||
## 更新触发条件
|
||||
|
||||
修改 checker 开发机制、目录结构、schema/validate/resolve/execute/expect 约定、测试要求、验证命令或文档同步 checklist 时，必须更新本文档。
|
||||
@@ -1,5 +1,9 @@
|
||||
# 前端开发
|
||||
|
||||
本文档说明 DiAL Dashboard 的 React、TDesign、TanStack Query、组件、样式和前端测试约定。
|
||||
|
||||
适用场景：修改 `src/web/`、前端共享类型使用方式、Dashboard 数据流、组件结构、样式规则或前端测试。
|
||||
|
||||
## 技术栈
|
||||
|
||||
| 层面 | 技术 | 用途 |
|
||||
@@ -108,10 +112,19 @@ async function fetchJson<T>(url: string): Promise<T> {
|
||||
- 严禁使用 `!important`。
|
||||
- 颜色统一使用 TDesign CSS tokens，不使用硬编码色值。
|
||||
|
||||
## 前端测试
|
||||
## 前端测试与验证
|
||||
|
||||
- 测试目录为 `tests/web/`，结构对应 `src/web/`。
|
||||
- 重点测试 `constants/` 中的纯函数。
|
||||
- 单元测试重点覆盖 `constants/`、`utils/` 和 hooks 中的纯逻辑。
|
||||
- 组件测试使用 jsdom 和 `@testing-library/react`。
|
||||
- 测试用户行为而非实现细节。
|
||||
- 只 mock 系统边界，例如 `fetch`。
|
||||
- 使用真实的 QueryClientProvider 包裹依赖 TanStack Query 的组件。
|
||||
- 异步错误断言使用 helper 或显式 try/catch，避免依赖 Bun `expect(...).rejects` 与 `await-thenable` 规则的类型不匹配。
|
||||
- 组件测试环境由 `tests/setup.ts` 和 `bunfig.toml` preload 提供，包含 ResizeObserver、IntersectionObserver、matchMedia、attachEvent 和 Recharts mock。
|
||||
|
||||
前端逻辑变更通常需要运行 `bun run check`。影响生产静态资源、前后端集成或构建流程时运行 `bun run verify`。
|
||||
|
||||
## 更新触发条件
|
||||
|
||||
修改前端技术栈、组件边界、数据流、样式规则、测试环境或前端验证方式时，必须更新本文档。
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# 构建与发布
|
||||
|
||||
本文档说明开发服务、前后端集成、生产构建、Docker 镜像、跨平台 release 和相关脚本维护方式。
|
||||
|
||||
适用场景：修改 `scripts/`、构建流程、Dockerfile、静态资源集成、release 打包、运行时环境变量或部署产物。
|
||||
|
||||
## 开发期运行
|
||||
|
||||
```bash
|
||||
@@ -105,3 +109,19 @@ release 流程：
|
||||
- `scripts/build-common.ts` 中的 import specifier 输出必须使用 `/` 分隔符。
|
||||
- 跨平台路径测试不得用当前平台 `path.sep` 伪装其他平台，应使用 `node:path.win32` 或等价注入方式模拟。
|
||||
- 如本地 Docker 环境不支持 buildx 或多架构模拟，需在变更记录中说明未执行原因。
|
||||
|
||||
## 发布验证
|
||||
|
||||
| 变更类型 | 验证方式 |
|
||||
| ---------------- | --------------------------------------- |
|
||||
| 构建脚本 | `bun run verify` |
|
||||
| release 脚本 | `bun run release` 或指定受影响 target |
|
||||
| Dockerfile | 本地 `docker build`，无法执行时说明原因 |
|
||||
| 静态资源集成 | `bun run build`，必要时启动产物手动验证 |
|
||||
| 配置 schema 同步 | `bun run schema:check` |
|
||||
|
||||
影响用户部署方式、Docker 运行参数、发布包内容或运行时依赖时，必须同步更新 [用户部署文档](../user/deployment.md)。
|
||||
|
||||
## 更新触发条件
|
||||
|
||||
修改开发服务、前后端集成、构建产物、Docker 镜像、release target、脚本参数或发布验证方式时，必须更新本文档。
|
||||
@@ -1,93 +0,0 @@
|
||||
# 测试与质量
|
||||
|
||||
## 质量命令
|
||||
|
||||
| 命令 | 说明 |
|
||||
| ---------------------- | -------------------------------------------------------------- |
|
||||
| `bun run lint` | ESLint 检查，含类型感知规则、导入排序、导入验证、Prettier 格式 |
|
||||
| `bun run format` | Prettier 自动格式化 |
|
||||
| `bun run schema:check` | 检查 `probe-config.schema.json` 是否与 TypeBox fragments 同步 |
|
||||
| `bun run typecheck` | TypeScript 类型检查 |
|
||||
| `bun test` | 运行所有测试 |
|
||||
| `bun run check` | `schema:check + typecheck + lint + test` |
|
||||
| `bun run verify` | `check + build` |
|
||||
|
||||
## ESLint
|
||||
|
||||
配置文件：`eslint.config.js`。
|
||||
|
||||
| 配置来源 | 用途 |
|
||||
| -------------------------------------------- | ---------------------------------------- |
|
||||
| `@eslint/js` recommended | JavaScript 基础规则 |
|
||||
| `typescript-eslint` recommended-type-checked | TypeScript 类型感知规则 |
|
||||
| `typescript-eslint` stylistic-type-checked | TypeScript 风格规则 |
|
||||
| `eslint-plugin-perfectionist` | 导入语句和命名导出排序 |
|
||||
| `eslint-plugin-import` | 导入路径验证、循环依赖检测、重复导入合并 |
|
||||
| `eslint-plugin-prettier` | 将 Prettier 格式集成为 ESLint 规则 |
|
||||
|
||||
后端运行时代码禁止直接使用 `console.*`，请通过注入的 Logger 实例输出日志。
|
||||
|
||||
## Prettier
|
||||
|
||||
配置文件：`.prettierrc.json`。显式声明格式化参数，包括 `printWidth: 120`、`semi: true`、`singleQuote: false`、`trailingComma: "all"`、`endOfLine: "lf"`。
|
||||
|
||||
## TypeScript 严格标志
|
||||
|
||||
| 标志 | 值 | 说明 |
|
||||
| ------------------------------------ | ----- | ------------------------------- |
|
||||
| `strict` | true | 全局严格模式 |
|
||||
| `noUnusedLocals` | true | 未使用局部变量视为错误 |
|
||||
| `noUnusedParameters` | false | 保留关闭 |
|
||||
| `noPropertyAccessFromIndexSignature` | true | 索引签名必须用括号访问 |
|
||||
| `noUncheckedIndexedAccess` | true | 数组和 Map 访问必须运行时检查 |
|
||||
| `noImplicitOverride` | true | 覆盖父类方法必须显式 `override` |
|
||||
| `verbatimModuleSyntax` | true | 强制 `import type` 纯类型导入 |
|
||||
|
||||
## Git hooks
|
||||
|
||||
| Hook | 行为 |
|
||||
| ------------ | ------------------------------------------ |
|
||||
| `pre-commit` | lint-staged 对变更文件运行 eslint/prettier |
|
||||
| `commit-msg` | commitlint 校验提交信息格式 |
|
||||
|
||||
提交信息格式为 `类型: 简短描述`，类型限定为 `feat`、`fix`、`refactor`、`docs`、`style`、`test`、`chore`。
|
||||
|
||||
## 测试分层
|
||||
|
||||
| 层级 | 覆盖范围 | 位置 |
|
||||
| -------- | ---------------------- | ----------------------------------------------------------------------------- |
|
||||
| 单元测试 | 后端函数、纯函数、常量 | `tests/server/**/*.test.ts`、`tests/web/{constants,utils,hooks}/**/*.test.ts` |
|
||||
| 组件测试 | React 组件渲染和交互 | `tests/web/components/**/*.test.tsx` |
|
||||
|
||||
## 测试命令
|
||||
|
||||
```bash
|
||||
bun test
|
||||
bun test tests/server
|
||||
bun test tests/web
|
||||
bun run check
|
||||
bun run verify
|
||||
```
|
||||
|
||||
## 组件测试环境
|
||||
|
||||
组件测试使用 jsdom，配置位于 `tests/setup.ts`，通过 `bunfig.toml` preload 加载。
|
||||
|
||||
包含的 polyfill 和 mock：
|
||||
|
||||
- ResizeObserver
|
||||
- IntersectionObserver
|
||||
- matchMedia
|
||||
- attachEvent
|
||||
- recharts 图表 mock
|
||||
|
||||
## 编写规范
|
||||
|
||||
- 优先使用 `@testing-library/react` 的语义化查询。
|
||||
- 测试用户行为而非实现细节。
|
||||
- 只 mock 系统边界。
|
||||
- 使用真实的 QueryClientProvider 包裹组件。
|
||||
- 组件测试文件命名为 `tests/web/components/ComponentName.test.tsx`。
|
||||
- 异步错误断言使用 helper 或显式 try/catch，避免依赖 Bun `expect(...).rejects` 与 `await-thenable` 规则的类型不匹配。
|
||||
- polyfill 中的 intentional no-op 使用显式可解释写法。
|
||||
- 对 `process.exit` 等系统 API 使用 `spyOn` 受控 mock。
|
||||
Reference in New Issue
Block a user