From c90a036f824c555bd864b1f295ecf70d88e39859 Mon Sep 17 00:00:00 2001 From: Stev_Wang <304865932@qq.com> Date: Wed, 4 Nov 2026 08:15:06 +0800 Subject: [PATCH] =?UTF-8?q?docs(ci):=20=E6=98=8E=E7=A1=AE=20CI=20=E4=BB=85?= =?UTF-8?q?=E6=9C=AC=E5=9C=B0=E6=89=A7=E8=A1=8C=EF=BC=8C=E8=BF=9C=E7=AB=AF?= =?UTF-8?q?=20Gitea=20=E4=B8=8D=E5=90=AF=E7=94=A8=20CI?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 背景：远端自建 Gitea 未部署 Actions runner，推送后线上 CI 无法执行；原规范仍要求「推送后确认 CI」，容易误以为需等待远端流水线。 改动： - AGENTS §6/§7：CI 只本地执行，推送前必须 pnpm ci:local 或本地门禁全绿，禁止等待/依赖远端 CI。 - 06-测试与CI规范 V1.1：新增「本地 CI 流水线（远端不跑 CI）」强制规则；集成/契约运行时机改为推送前本地。 - 01-Git规范 / 07-CodeReview：删除「推送后确认 CI」，改为本地门禁后推送。 - README：明确远端无 runner，ci.yml 仅本地参考/手动触发。 - .gitea/workflows/ci.yml：去掉 push 触发，仅保留 workflow_dispatch，避免推送停留在 queued。 影响面：仅规范与工作流配置，不影响代码/数据。 验证：pnpm format:check / lint 通过；pnpm ci:local 全部门禁通过（237.2s，4 e2e 冒烟 passed，8 个门控用例按环境变量跳过）。 --- .gitea/workflows/ci.yml | 4 ++-- AGENTS.md | 6 +++--- README.md | 2 +- docs/工程规范/01-Git规范.md | 4 ++-- docs/工程规范/06-测试与CI规范.md | 20 +++++++++++++------- docs/工程规范/07-CodeReview与PR规范.md | 4 ++-- 6 files changed, 23 insertions(+), 17 deletions(-) diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index f287843..e2ef54f 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -1,8 +1,8 @@ +# 远端 Gitea 未部署 Actions runner：本工作流不随 push 触发，仅供本地参考 / 手动触发。 +# 本地等价命令：pnpm ci:local（推送前必须全绿）。 name: ci on: - push: - branches: [main] workflow_dispatch: concurrency: diff --git a/AGENTS.md b/AGENTS.md index bbf5b50..699ac8d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -114,7 +114,7 @@ docs/ PRD / 技术架构 / 立项建议 / 工程规范 | 开发 | `pnpm dev` | | 构建 | `pnpm build` | | 质量 | `pnpm lint` · `pnpm lint:fix` · `pnpm format` · `pnpm format:check` · `pnpm typecheck` | -| 测试 | `pnpm test` · `pnpm test:int` · `pnpm test:e2e` · `pnpm ci:local` | +| 测试 | `pnpm test` · `pnpm test:int` · `pnpm test:e2e` · `pnpm ci:local`（CI 只本地执行，远端无 runner） | | 数据库 | `pnpm db:init`（迁移 + 幂等种子，不重置数据）· `pnpm db:migrate` · `pnpm db:reset`（清库重建；默认被拦截，必须 `ALLOW_DB_RESET=1` 显式确认；禁止手工删库 / 删数据卷） | | 契约 | `pnpm openapi:diff` | @@ -127,7 +127,7 @@ docs/ PRD / 技术架构 / 立项建议 / 工程规范 1. 基于最新 `main` 直接提交，小步 commit（**Conventional Commits，提交信息一律用中文**，`type` / `scope` 保留英文）。 2. 本地门禁：`pnpm format:check && pnpm lint && pnpm typecheck && pnpm test`。 3. 提交说明必含：**背景 / 改动 / 影响面 / 回滚方式 / 验证证据**；迁移、权限、AI、导出类变更须在推送前完成双人走查。 -4. 直接 `git push origin main`；禁止 force push `main`，禁止 Merge commit；推送后立即确认 CI，失败按前向修复处理。 +4. 直接 `git push origin main`；禁止 force push `main`，禁止 Merge commit。**远端 Gitea 未部署 Actions runner，线上 CI 不可用，禁止等待/依赖远端 CI**；CI 一律在推送前本地执行（`pnpm ci:local`），本地门禁全绿才能推送。 5. 发布：staging 验证 → 生产灰度；**迁移先行、代码后行**。 细则：[Git 规范](docs/工程规范/01-Git规范.md) · [Code Review](docs/工程规范/07-CodeReview与PR规范.md) · [测试与 CI](docs/工程规范/06-测试与CI规范.md) @@ -154,7 +154,7 @@ docs/ PRD / 技术架构 / 立项建议 / 工程规范 | API 与路由 | [04-API与路由规范](docs/工程规范/04-API与路由规范.md) | REST /api/v1、错误码、鉴权链、任务协议 | | 数据库 | [05-数据库规范](docs/工程规范/05-数据库规范.md) | ULID、customer_id、游标分页、expand/contract | | 测试与 CI | [06-测试与CI规范](docs/工程规范/06-测试与CI规范.md) | 分层测试、权限三态、覆盖率只升不降 | -| Code Review | [07-CodeReview与PR规范](docs/工程规范/07-CodeReview与PR规范.md) | 提交说明、双人场景、DoD、推送后观察 | +| Code Review | [07-CodeReview与PR规范](docs/工程规范/07-CodeReview与PR规范.md) | 提交说明、双人场景、DoD、本地 CI 后推送 | | 日志与可观测 | [08-日志与可观测性规范](docs/工程规范/08-日志与可观测性规范.md) | Pino 字段、trace_id、审计与日志分离、告警 | | 环境变量与密钥 | [09-环境变量与密钥规范](docs/工程规范/09-环境变量与密钥规范.md) | `.env.example` 入库、启动校验、轮换与泄露处置 | | 资产命名与图层 | [10-资产命名与PSD图层规范](docs/工程规范/10-资产命名与PSD图层规范.md) | 命名占位符、PSD 图层前缀、规格矩阵、低质量标记 | diff --git a/README.md b/README.md index e69dab2..f002c2f 100644 --- a/README.md +++ b/README.md @@ -119,7 +119,7 @@ pnpm openapi:export && pnpm openapi:diff # 契约快照与破坏性变更检 pnpm ci:local # 本地跑完整 CI 门禁（已内置 e2e 所需 env） ``` -> Gitea 暂未部署 Actions runner，推送后远程 CI 会停留在 queued；当前以 `pnpm ci:local` 为准，runner 就绪后 `.gitea/workflows/ci.yml` 会自动接管。 +> **远端 Gitea 未部署 Actions runner，线上 CI 不可用**。所有 CI 一律在本地执行：推送前跑 `pnpm ci:local`（或至少 `format:check + lint + typecheck + test`）。`.gitea/workflows/ci.yml` 仅作本地流水线参考 / 手动触发，**不随 push 自动运行**。 命令与门禁见 [AGENTS.md §6](AGENTS.md) 与 [06-测试与CI规范](docs/工程规范/06-测试与CI规范.md)。当前 UI 采用「顶部模块菜单 + 左侧功能菜单」布局，视觉方向为 **A · 云白蓝（传统企业后台 + 现代浅色质感）**。 diff --git a/docs/工程规范/01-Git规范.md b/docs/工程规范/01-Git规范.md index 01b8746..7950a07 100644 --- a/docs/工程规范/01-Git规范.md +++ b/docs/工程规范/01-Git规范.md @@ -21,7 +21,7 @@ - `GIT-01` 所有提交直接基于最新 `main`；提交前先 `git pull --ff-only`，避免落后。 - `GIT-02` 禁止创建并推送任何非 `main` 分支；确需本地验证时可临时创建，但不得推送，完成后立即删除。 -- `GIT-03` 允许直接 push `main`；推送前必须通过本地门禁（`format:check`、`lint`、`typecheck`、`test`），推送后立即确认 CI。 +- `GIT-03` 允许直接 push `main`；推送前必须通过本地门禁（`format:check`、`lint`、`typecheck`、`test`，完整链路用 `pnpm ci:local`）。**远端 Gitea 未部署 runner，线上 CI 不可用，推送后不等待远端 CI**。 - `GIT-04` 禁止 force push `main`；禁止 Merge commit；`main` 必须保持线性。 ## 2　提交信息（Conventional Commits 1.0） @@ -134,4 +134,4 @@ export default { - [ ] 提交粒度单一，无无关文件 - [ ] 无 `.env` / 密钥 / 大文件 - [ ] 提交说明含背景 / 影响面 / 回滚方式 / 验证证据 -- [ ] 本地门禁全绿，已 push `main` 并确认 CI +- [ ] 本地门禁全绿（必要时 `pnpm ci:local`），已 push `main`；远端无 CI，无需等待 diff --git a/docs/工程规范/06-测试与CI规范.md b/docs/工程规范/06-测试与CI规范.md index d73dee9..2f2ea61 100644 --- a/docs/工程规范/06-测试与CI规范.md +++ b/docs/工程规范/06-测试与CI规范.md @@ -2,10 +2,11 @@ | 项 | 内容 | | --- | --- | -| 文档版本 | V1.0（2026-11-02） | +| 文档版本 | V1.1（2026-11-04） | | 依据 | 技术架构 §10.4（测试策略）、§4.6（CI/CD）、§4.1.1（本地环境） | | 适用范围 | 全仓库 | | 强制级别 | 强制 | +| 远端 CI | **不启用**：Gitea 无 runner，CI 只本地执行 | --- @@ -14,15 +15,15 @@ | 层级 | 工具 | 范围 | 运行时机 | | --- | --- | --- | --- | | 单元 | Vitest | Service、工具函数、状态机、命名 / 表单引擎 | 每次提交（CI + 本地） | -| 集成 | Vitest + Testcontainers（PG 18 / Redis 7.4 / MinIO） | Repository、队列、迁移、事务 | 每次 push `main`（CI） | -| 契约 | OpenAPI + `oasdiff` | 接口兼容性 | 每次 push `main` | +| 集成 | Vitest + Testcontainers（PG 18 / Redis 7.4 / MinIO） | Repository、队列、迁移、事务 | 每次推送前本地 `pnpm ci:local` | +| 契约 | OpenAPI + `oasdiff` | 接口兼容性 | 每次推送前本地 `pnpm ci:local` | | E2E | Playwright | 主链路（登录 → 生成 → 预览 → 勾选 → 导出） | 主干 + 发布前 | | 性能 | k6 | 列表 / 任务提交 / SSE | 发布前（仅 staging） | | 视觉回归 | 图片像素比对 | PSD 合成产物 | 改动 `packages/render` 时 | - `TST-01` 单测与源码同目录，命名 `.spec.ts`；集成 `*.int.spec.ts`；E2E 放 `e2e/`。 - `TST-02` 关键包（`shared` / `form-engine` / `render` / `ai-sdk`）行覆盖率 **≥ 70%**；整体基线只升不降。 -- `TST-03` 禁止提交 `.skip` / `.only`；CI 检测到即失败。 +- `TST-03` 禁止提交 `.skip` / `.only`；本地 `pnpm ci:local` 检测到即失败。 - `TST-04` 禁止依赖执行顺序；每个测试自建数据、自清理（用独立 `customer_id` 前缀）。 --- @@ -46,7 +47,7 @@ ## 3　测试数据与环境 -- `TST-15` 禁止连接生产库 / 生产对象存储；CI 用 Testcontainers 起同版本依赖。 +- `TST-15` 禁止连接生产库 / 生产对象存储；本地 CI 用 Testcontainers / 本地容器起同版本依赖。 - `TST-16` 测试数据用 factory 构造，禁止依赖线上导出数据。 - `TST-17` 测试内置时钟可注入（`clock` 包），禁止 `new Date()` 直接断言时间。 - `TST-18` AI 调用在测试中一律 mock Provider，**禁止**真实外网调用（防止费用与不稳定）。 @@ -54,7 +55,7 @@ --- -## 4　CI 流水线 +## 4　本地 CI 流水线（远端不跑 CI） ``` install --frozen-lockfile @@ -64,6 +65,11 @@ install --frozen-lockfile → e2e（main）→ 镜像构建 + 漏洞扫描 ``` +> **强制规则（2026-11-04 确认）**：远端自建 Gitea **未部署 Actions runner，线上 CI 不可用**。所有 CI 一律在本地执行： +> - 推送前运行 `pnpm ci:local`（完整链路）或至少 `pnpm format:check && pnpm lint && pnpm typecheck && pnpm test`； +> - `.gitea/workflows/ci.yml` 仅供本地参考 / 手动触发，**不随 push 自动运行**； +> - 禁止在推送后等待远端 CI、禁止以「远端 CI 会在后续跑」为由跳过本地门禁。 + | 阶段 | 阻断条件 | | --- | --- | | 安装 | lock 文件与 `package.json` 不一致 | @@ -114,7 +120,7 @@ staging 部署 → 冒烟（登录 / 生成 / 预览 / 导出） - [ ] 端点有权限三态用例，客户隔离用例存在 - [ ] 状态机非法迁移、幂等、成本前置已覆盖 - [ ] 集成测试用 Testcontainers，无外网依赖 -- [ ] CI 全绿且未使用豁免 +- [ ] 本地 `pnpm ci:local` 全绿且未使用豁免（远端无 runner） - [ ] 迁移可回滚，staging 已演练 - [ ] 未完成功能藏开关，开关有清理期限 - [ ] 发布记录与回滚预案已写 diff --git a/docs/工程规范/07-CodeReview与PR规范.md b/docs/工程规范/07-CodeReview与PR规范.md index fa3fa18..90ecac7 100644 --- a/docs/工程规范/07-CodeReview与PR规范.md +++ b/docs/工程规范/07-CodeReview与PR规范.md @@ -101,7 +101,7 @@ 同时满足才可推送： -1. 本地门禁全绿；推送后 CI 全绿（含契约与集成），无豁免。 +1. 本地门禁全绿（含契约与集成，必要时 `pnpm ci:local`）；远端 Gitea 无 runner，不等待线上 CI，无豁免。 2. Review 通过，blocking 意见全部解决。 3. 文档同步：PRD 规则编号、技术架构、OpenAPI、本目录细则（如涉及）。 4. 迁移可回滚，或在描述说明为何不可回滚与前向修复方案。 @@ -113,7 +113,7 @@ ## 5　推送与推送后 - `CR-08` 推送前完成本地门禁（`format:check` / `lint` / `typecheck` / `test`）；推送即进入主干，不再有 Squash 合并环节。 -- `CR-09` 直接 `git push origin main`；禁止 force push、禁止 Merge commit；推送后 15 分钟内确认 CI 与错误率。 +- `CR-09` 直接 `git push origin main`；禁止 force push、禁止 Merge commit；推送前确认 `pnpm ci:local` 全绿，推送后不等待远端 CI（远端无 runner）。 - `CR-10` 推送后发现缺陷：优先以新提交前向修复；影响面大时按回滚预案执行（回滚也用新提交，不回写历史），并补一次复盘（写 `docs/releases/` 或 issue）。 - `CR-11` 禁止「先推后补测试 / 补文档」作为常态；紧急修复须 24 小时内以新提交补齐，并在提交说明记录。