chore: 合并 dev-ci-optimize 至 master

2026-05-07 14:17:43 +08:00
parent 4eeb14e844 0d30ed9a0f
commit 1195e119c6
6 changed files with 306 additions and 11 deletions
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,14 @@
+name: CI
+
+on:
+  push:
+    branches: [dev, main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Check
+    uses: ./.github/workflows/test.yml
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -37,9 +37,16 @@ jobs:
          go run ./versionctl verify-tag "${GITHUB_REF_NAME}"
          printf 'version=%s\n' "$version" >> "$GITHUB_OUTPUT"

+  test-gate:
+    name: Test Gate
+    needs: prepare
+    uses: ./.github/workflows/test.yml
+    with:
+      full: true
+
  build-web:
    name: Build Web Asset
-    needs: prepare
+    needs: [prepare, test-gate]
    runs-on: ubuntu-latest
    permissions:
      contents: read
@@ -81,7 +88,7 @@ jobs:

  build-linux:
    name: Build Linux ${{ matrix.arch }} Assets
-    needs: prepare
+    needs: [prepare, test-gate]
    strategy:
      fail-fast: false
      matrix:
@@ -147,7 +154,7 @@ jobs:

  build-windows:
    name: Build Windows ${{ matrix.arch }} Assets
-    needs: prepare
+    needs: [prepare, test-gate]
    runs-on: ${{ matrix.runner }}
    strategy:
      fail-fast: false
@@ -231,7 +238,7 @@ jobs:

  build-macos:
    name: Build macOS Assets
-    needs: prepare
+    needs: [prepare, test-gate]
    runs-on: macos-15
    permissions:
      contents: read
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -0,0 +1,109 @@
+name: Test (Full)
+
+on:
+  workflow_call:
+    inputs:
+      full:
+        description: "Run full test suite including MySQL and E2E"
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          lfs: true
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.work
+          cache-dependency-path: |
+            backend/go.sum
+            versionctl/go.sum
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Lint
+        run: make lint
+
+      - name: Test
+        run: make test
+
+  mysql:
+    name: MySQL Tests
+    if: inputs.full
+    needs: check
+    runs-on: ubuntu-latest
+
+    services:
+      mysql:
+        image: mysql:8.0
+        env:
+          MYSQL_ROOT_PASSWORD: testpass
+          MYSQL_DATABASE: nex_test
+          MYSQL_USER: nex_test
+          MYSQL_PASSWORD: testpass
+        ports:
+          - 13306:3306
+        options: >-
+          --health-cmd="mysqladmin ping -h localhost -u root -ptestpass"
+          --health-interval=3s
+          --health-timeout=5s
+          --health-retries=10
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          lfs: true
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.work
+          cache-dependency-path: |
+            backend/go.sum
+            versionctl/go.sum
+
+      - name: MySQL tests
+        run: cd backend && go test -tags=mysql ./tests/mysql/... -v -count=1
+
+  e2e:
+    name: E2E Tests
+    if: inputs.full
+    needs: check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          lfs: true
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.work
+          cache-dependency-path: |
+            backend/go.sum
+            versionctl/go.sum
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install Playwright browsers
+        run: cd frontend && bunx playwright install --with-deps chromium
+
+      - name: E2E tests
+        run: cd frontend && bun run test:e2e
--- a/README.md
+++ b/README.md
@@ -160,7 +160,7 @@ make server-build

 ### Release 产物

-发布流程由 Git tag `vX.Y.Z` 触发，GitHub Actions 会创建 Draft Release 并上传 server、web 和 desktop 三类产物，同时生成 `SHA256SUMS`。
+发布流程由 Git tag `vX.Y.Z` 触发，GitHub Actions 会先通过全流程测试门禁，再构建并创建 Draft Release，上传 server、web 和 desktop 三类产物，同时生成 `SHA256SUMS`。

 **server 产物**（不内置 Web 管理界面）：

@@ -429,9 +429,10 @@ make release-assets-macos
 ### GitHub Draft Release

 - 推送 `vX.Y.Z` tag 后，`.github/workflows/release.yml` 会自动执行发布流水线
- 三个平台 job 会在正式构建前先检查 `go`、`bun` 和各自的平台打包工具链，缺失时快速失败并在日志中输出诊断信息
+- 流水线会先校验 tag 与 `VERSION` 一致，再执行全流程测试门禁（lint、默认测试、MySQL 测试、E2E 测试），测试不通过则阻止构建
+- 测试通过后，三个平台 job 并行构建，各 job 会在正式构建前先检查 `go`、`bun` 和各自的平台打包工具链，缺失时快速失败并在日志中输出诊断信息
 - Windows 发布 job 在 `MSYS2 / MINGW64` shell 中执行，并继承 `setup-go` / `setup-bun` 准备好的工具链路径
- 流水线会先校验 tag 与 `VERSION` 一致，再构建以下资产并上传到 GitHub Draft Release：
+- 构建以下资产并上传到 GitHub Draft Release：
  - Linux server
  - Windows server
  - darwin-amd64 server
--- a/openspec/specs/ci-test-gate/spec.md
+++ b/openspec/specs/ci-test-gate/spec.md
@@ -0,0 +1,151 @@
+# 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（始终执行）
+
+- **WHEN** 测试 workflow 被调用（无论 `full` 值）
+- **THEN** `check` job SHALL 始终执行
+- **THEN** SHALL 在 `check` job 内按顺序执行：checkout（含 LFS）→ setup Go → setup Bun → `make lint` → `make test`
+- **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 阻止后续步骤执行
+
+#### 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 在单个 ubuntu 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 在测试结束后自动清理
--- a/openspec/specs/release-pipeline/spec.md
+++ b/openspec/specs/release-pipeline/spec.md
@@ -8,12 +8,12 @@

 ### Requirement: Tag 驱动发布流水线

-系统 SHALL 仅在符合 `vX.Y.Z` 格式的 Git tag 上触发发布流水线，普通分支 push SHALL NOT 创建发布。发布流水线 SHALL 使用 `./versionctl` 而非 `./backend/cmd/versionctl` 调用版本管理工具。
+系统 SHALL 仅在符合 `vX.Y.Z` 格式的 Git tag 上触发发布流水线，普通分支 push SHALL NOT 创建发布。发布流水线 SHALL 使用 `./versionctl` 而非 `./backend/cmd/versionctl` 调用版本管理工具。发布流水线 SHALL 在进入构建阶段前完成全流程测试验证，测试未通过 SHALL NOT 执行任何构建。

 #### Scenario: 有效发布 tag

 - **WHEN** 仓库收到 `v1.2.3` tag push
- **THEN** 发布流水线 SHALL 启动版本校验、构建和 Release 组装步骤
+- **THEN** 发布流水线 SHALL 启动版本校验、全流程测试、构建和 Release 组装步骤
 - **AND** 版本校验步骤 SHALL 使用 `go run ./versionctl print` 和 `go run ./versionctl verify-tag` 获取并验证版本

 #### Scenario: 普通分支推送
@@ -21,6 +21,19 @@
 - **WHEN** 仓库收到非 tag 的分支 push
 - **THEN** 系统 SHALL NOT 创建 GitHub Release

+#### Scenario: 测试门禁阻止构建
+
+- **WHEN** 发布流水线中全流程测试步骤（lint、默认测试、MySQL 测试、E2E 测试）任一失败
+- **THEN** 发布流水线 SHALL NOT 执行任何平台构建
+- **THEN** 发布流水线 SHALL NOT 创建 Draft Release
+- **AND** 系统 SHALL NOT 产生可直接公开的成功发布结果
+
+#### Scenario: 测试通过后并行构建
+
+- **WHEN** 全流程测试全部通过
+- **THEN** web、Linux、Windows、macOS 构建 SHALL 并行执行
+- **AND** 所有构建 job SHALL 依赖 `prepare` 和 `test-gate`
+
 ### Requirement: 发布流水线 Go 模块缓存覆盖

 发布流水线 SHALL 在所有 Go module 的 go.sum 文件存在时正确设置 Go 模块缓存路径，确保新增的 `versionctl` module 依赖也被缓存。
@@ -198,7 +211,7 @@

 #### Scenario: 发布成功时创建 Draft Release

- **WHEN** 版本校验通过且 server、web、desktop 的全部目标发布资产构建完成
+- **WHEN** 版本校验通过、全流程测试通过且 server、web、desktop 的全部目标发布资产构建完成
 - **THEN** 系统 SHALL 创建或更新与该 tag 对应的 GitHub Draft Release
 - **AND** 系统 SHALL 上传 server、web 与 desktop 的全部发布资产
 - **AND** 系统 SHALL 上传 `SHA256SUMS`
@@ -211,7 +224,7 @@

 #### Scenario: 构建失败时阻止完成发布

- **WHEN** 任一目标发布资产构建失败、打包失败、校验失败、artifact 上传为空或版本校验失败
+- **WHEN** 任一目标发布资产构建失败、打包失败、校验失败、artifact 上传为空、版本校验失败或全流程测试失败
 - **THEN** 发布流水线 SHALL 失败
 - **AND** 系统 SHALL NOT 产生可直接公开的成功发布结果