nex/openspec/specs/ci-test-gate/spec.md

# CI Test Gate

## Purpose

定义 CI 全流程测试门禁，作为 release 和未来其他 CI 流程的前序质量检查，覆盖 lint、默认测试、MySQL 测试和 E2E 测试。

## Requirements

### Requirement: 独立可复用测试 workflow

系统 SHALL 提供独立的全流程测试 workflow（`test.yml`），使用 `workflow_call` 触发器，通过 `full` 布尔参数控制测试分层执行。

#### Scenario: workflow_call 触发器

- **WHEN** 查看 `.github/workflows/test.yml` 的触发器配置
- **THEN** SHALL 使用 `on: workflow_call` 触发器
- **THEN** SHALL 声明 `inputs.full` 布尔参数，默认值为 `false`
- **THEN** SHALL NOT 使用 `push`、`pull_request` 等其他触发器

#### Scenario: 被其他 workflow 引用（快速模式）

- **WHEN** 其他 workflow 的 job 通过 `uses: ./.github/workflows/test.yml` 引用此 workflow 且未传 `full` 或传 `full: false`
- **THEN** test workflow SHALL 仅执行 `check` job（lint + 全量测试）
- **THEN** test workflow SHALL NOT 执行 MySQL 测试和 E2E 测试

#### Scenario: 被其他 workflow 引用（完整模式）

- **WHEN** 其他 workflow 的 job 引用此 workflow 且传 `full: true`
- **THEN** test workflow SHALL 执行 `check`、`mysql`、`e2e` 三个 job
- **THEN** `mysql` 和 `e2e` job SHALL 在 `check` job 成功后并行执行

### Requirement: 全流程测试步骤编排

测试 workflow SHALL 将测试步骤拆分为 `check`、`mysql`、`e2e` 三个独立 job，通过 `full` 参数和 `needs` 依赖控制执行。

#### Scenario: check job（始终执行，三平台 matrix）

- **WHEN** 测试 workflow 被调用（无论 `full` 值）
- **THEN** `check` job SHALL 始终执行
- **THEN** `check` job SHALL 使用 `strategy.matrix.os` 在 `ubuntu-latest`、`macos-latest`、`windows-latest` 三个平台并行运行
- **THEN** 每个平台 SHALL 按顺序执行：checkout（含 LFS）→ setup Go → setup Bun → `make lint` → `make test`
- **THEN** 在 Linux 平台上，lint/test 之前 SHALL 执行 `sudo apt-get install -y libayatana-appindicator3-dev` 安装系统依赖
- **THEN** macOS 和 Windows 平台 SHALL NOT 安装额外系统依赖
- **THEN** `make lint` SHALL 覆盖 backend golangci-lint、frontend typecheck + eslint + prettier、versionctl golangci-lint
- **THEN** `make test` SHALL 覆盖 backend 核心测试、frontend Vitest 单元/组件测试、desktop 测试和 versionctl 测试
- **THEN** `make test` SHALL NOT 覆盖 MySQL 专项测试或 frontend E2E 测试
- **THEN** lint 或测试失败时 SHALL 阻止后续步骤执行
- **THEN** 任一平台失败 SHALL 导致 `check` job 整体失败

#### Scenario: check job 平台特定依赖安装

- **WHEN** `check` job 在 Linux 平台运行
- **THEN** SHALL 在 lint 步骤之前执行系统依赖安装步骤
- **THEN** 该步骤 SHALL 使用 `if: runner.os == 'Linux'` 条件控制
- **THEN** 该步骤 SHALL 安装 `libayatana-appindicator3-dev`

#### Scenario: check job macOS 平台

- **WHEN** `check` job 在 macOS 平台运行
- **THEN** SHALL NOT 安装额外系统依赖
- **THEN** `make lint` 和 `make test` SHALL 正常执行

#### Scenario: check job Windows 平台

- **WHEN** `check` job 在 Windows 平台运行
- **THEN** SHALL NOT 安装额外系统依赖
- **THEN** `make lint` 和 `make test` SHALL 正常执行

#### Scenario: mysql job（仅 full=true）

- **WHEN** 测试 workflow 被调用且 `full=true`，且 `check` job 成功
- **THEN** `mysql` job SHALL 执行
- **THEN** SHALL checkout 仓库代码
- **THEN** SHALL 安装 Go 工具链（使用 `go.work` 文件指定版本，缓存覆盖 `backend/go.sum` 和 `versionctl/go.sum`）
- **THEN** SHALL 使用 GitHub Actions `services:` 声明 MySQL 8.0 容器
- **THEN** MySQL 容器 SHALL 映射端口 `13306:3306`
- **THEN** MySQL 容器 SHALL 配置 `MYSQL_DATABASE=nex_test`、`MYSQL_USER=nex_test`、`MYSQL_PASSWORD=testpass`
- **THEN** SHALL 执行 `cd backend && go test -tags=mysql ./tests/mysql/... -v -count=1`

#### Scenario: mysql job 跳过

- **WHEN** 测试 workflow 被调用且 `full=false`
- **THEN** `mysql` job SHALL NOT 执行

#### Scenario: e2e job（仅 full=true）

- **WHEN** 测试 workflow 被调用且 `full=true`，且 `check` job 成功
- **THEN** `e2e` job SHALL 执行
- **THEN** SHALL checkout 仓库代码（含 LFS）
- **THEN** SHALL 安装 Go 工具链（使用 `go.work` 文件指定版本，缓存覆盖 `backend/go.sum` 和 `versionctl/go.sum`）
- **THEN** SHALL 安装 Bun 运行时
- **THEN** SHALL 安装 Playwright Chromium 浏览器：`cd frontend && bunx playwright install --with-deps chromium`
- **THEN** SHALL 执行 `cd frontend && bun run test:e2e`
- **THEN** Playwright SHALL 使用 CI 模式（`forbidOnly: true`、`retries: 2`）

#### Scenario: e2e job 跳过

- **WHEN** 测试 workflow 被调用且 `full=false`
- **THEN** `e2e` job SHALL NOT 执行

#### Scenario: mysql 和 e2e 并行执行

- **WHEN** `full=true` 且 `check` job 成功
- **THEN** `mysql` job 和 `e2e` job SHALL 并行执行
- **THEN** 两个 job 之间 SHALL NOT 有 `needs` 依赖关系

#### Scenario: check 失败阻止后续 job

- **WHEN** `check` job 中 lint 或测试任一失败
- **THEN** `mysql` 和 `e2e` job SHALL NOT 执行

### Requirement: 开发 CI 自动触发

系统 SHALL 在 `push`（`dev` 和 `main` 分支）和所有 `pull_request` 事件时自动触发快速质量检查。

#### Scenario: push 到 dev 分支触发 CI

- **WHEN** 代码推送到 `dev` 分支
- **THEN** SHALL 触发 CI workflow
- **THEN** CI workflow SHALL 调用 `test.yml`（`full=false`）
- **THEN** SHALL 仅执行 lint 和全量单元/集成测试

#### Scenario: push 到 main 分支触发 CI

- **WHEN** 代码推送到 `main` 分支
- **THEN** SHALL 触发 CI workflow
- **THEN** CI workflow SHALL 调用 `test.yml`（`full=false`）

#### Scenario: Pull Request 触发 CI

- **WHEN** 创建或更新 Pull Request
- **THEN** SHALL 触发 CI workflow
- **THEN** CI workflow SHALL 调用 `test.yml`（`full=false`）

#### Scenario: CI workflow 极简设计

- **WHEN** 查看 `.github/workflows/ci.yml`
- **THEN** SHALL 仅包含触发器配置和一个 job 引用 `test.yml`
- **THEN** SHALL NOT 定义任何直接执行的步骤
- **THEN** SHALL NOT 传递 `full: true`

### Requirement: 发布流水线使用完整测试模式

`release.yml` 调用 `test.yml` 时 SHALL 显式传递 `full: true`，确保发布流程执行完整测试。

#### Scenario: release 调用 test.yml 传 full: true

- **WHEN** 发布流水线的 `test-gate` job 引用 `test.yml`
- **THEN** SHALL 传递 `with: full: true`
- **THEN** 发布流水线 SHALL 执行 `check`、`mysql`、`e2e` 三个 job
- **THEN** 测试行为 SHALL 与重构前一致

### Requirement: 测试 workflow 工具链依赖

测试 workflow SHALL 在各平台 runner 上准备完整的工具链环境。

#### Scenario: 工具链安装（三平台）

- **WHEN** 测试 workflow 开始执行
- **THEN** 每个平台 SHALL checkout 仓库代码并拉取 Git LFS 文件
- **THEN** 每个平台 SHALL 安装 Go 工具链（使用 `go.work` 文件指定版本）
- **THEN** 每个平台 SHALL 安装 Bun 运行时
- **THEN** Go 模块缓存 SHALL 覆盖 `backend/go.sum` 和 `versionctl/go.sum`

### Requirement: 测试 workflow 资源隔离

测试 workflow 中的各测试步骤 SHALL 使用隔离的资源，不干扰主环境。

#### Scenario: E2E 临时资源隔离

- **WHEN** E2E 测试运行
- **THEN** Go 后端 SHALL 使用临时目录的独立数据库文件（`/tmp/nex-e2e/test.db`）
- **THEN** Go 后端 SHALL 使用临时目录的日志目录（`/tmp/nex-e2e/log/`）
- **THEN** 临时资源 SHALL 在测试结束后自动清理