wang259797/lingxi
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(ci): 同步远端 CI 已启用与推送前本地门禁要求
ci / 质量门禁 (push) Failing after 2m11s
Details

Browse Source 
背景：自建 Gitea 已部署 Actions runner（gitea-runner-01），旧文档
「远端无 runner、CI 只本地执行」已与事实不符。

改动：AGENTS.md、README、01/06/07 三份细则统一改为「推送前本地门禁强制 +
push main 自动远端 CI，失败即以新提交修复」，并注明 ci-smoke.yml 可手动冒烟；
AGENTS 版本升 V1.2，01/06/07 版本升 V1.2。

影响面：仅文档与索引版本号，不改代码与流水线行为。
回滚方式：revert 本提交。
验证证据：prettier 检查通过；文档相对链接未变。
This commit is contained in:
Stev_Wang committed 2026-11-04 17:52:24 +08:00
1 parent 88d9c77522
commit a06043ce92
5 files changed
+24 -23
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

AGENTS.md
+4 -4
View File
@@ -7,7 +7,7 @@
| --- | --- |
| 适用对象 | 前端 / 后端 / 测试 / 运维 / AI 工程 / 产品（技术边界） |
| 适用产物 | 代码、配置、脚本、迁移、文档、Prompts |
| 文档版本 | V1.1（2026-11-02） |
| 文档版本 | V1.2（2026-11-04） |
| 事实基线 | PRD `V1.6`、技术架构 `V0.4` |
---
@@ -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`（CI 只本地执行，远端无 runner） |
| 测试 | `pnpm test` · `pnpm test:int` · `pnpm test:e2e` · `pnpm ci:local`（推送前本地强制；远端 Gitea runner 已就绪，push `main` 自动跑 `.gitea/workflows/ci.yml`） |
| 数据库 | `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。**远端 Gitea 未部署 Actions runner，线上 CI 不可用，禁止等待/依赖远端 CI**；CI 一律在推送前本地执行（`pnpm ci:local`），本地门禁全绿才能推送。
4. 直接 `git push origin main`；禁止 force push `main`，禁止 Merge commit。**本地门禁全绿才能推送**（`pnpm ci:local` 或至少 §7.2 四件套）；远端自建 Gitea 已部署 Actions runner（`gitea-runner-01`），push `main` 自动执行 `.gitea/workflows/ci.yml`，推送后必须关注远端结果、失败立即修复，**不得以「远端 CI 会跑」替代本地门禁**。
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、本地 CI 后推送 |
| 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 图层前缀、规格矩阵、低质量标记 |
README.md
+2 -2
View File
@@ -12,7 +12,7 @@
| 文档 | 路径 | 版本 | 作用 |
| ------------ | ------------------------------------------------------------------------------------------------------ | -------------------- | ---------------------------------------------------------------------- |
| **项目总纲** | [AGENTS.md](AGENTS.md) | V1.0 | 硬约束、技术栈、仓库结构、命令契约、流程 |
| **项目总纲** | [AGENTS.md](AGENTS.md) | V1.2 | 硬约束、技术栈、仓库结构、命令契约、流程 |
| **PRD** | [灵犀-信息流广告素材一站式生产平台PRD.md](docs/PRD/灵犀-信息流广告素材一站式生产平台PRD.md) | **V1.6（最新）** | 需求、业务规则（R-01~R-30）、验收标准 |
| **技术架构** | [灵犀_信息流素材生产平台_技术架构_V0.1.md](docs/技术架构/灵犀_信息流素材生产平台_技术架构_V0.1.md) | **V0.4（内部版本）** | 技术选型、分层模块、数据模型、接口、ADR |
| **开发计划** | [灵犀_信息流素材生产平台_开发计划_V0.1.md](docs/开发计划/灵犀_信息流素材生产平台_开发计划_V0.1.md) | **V0.1（初稿）** | 全项目 M0–M4：里程碑、批次、WBS、七管理模块专项、门禁、风险、验收 |
@@ -121,7 +121,7 @@ pnpm openapi:export && pnpm openapi:diff # 契约快照与破坏性变更检
pnpm ci:local # 本地跑完整 CI 门禁（已内置 e2e 所需 env）
```
> **远端 Gitea 未部署 Actions runner，线上 CI 不可用**。所有 CI 一律在本地执行：推送前跑 `pnpm ci:local`（或至少 `format:check + lint + typecheck + test`）。`.gitea/workflows/ci.yml` 仅作本地流水线参考 / 手动触发，**不随 push 自动运行**。
> **推送前本地门禁仍为强制项**：跑 `pnpm ci:local`（或至少 `format:check + lint + typecheck + test`）。远端自建 Gitea 已部署 Actions runner（`gitea-runner-01`），push `main` 自动执行 `.gitea/workflows/ci.yml`；需要快速确认 runner 可用时手动触发 `.gitea/workflows/ci-smoke.yml`（约 1 分钟）。远端 CI 失败必须立即修复，**不得以「远端 CI 会跑」替代本地门禁**。
命令与门禁见 [AGENTS.md §6](AGENTS.md) 与 [06-测试与CI规范](docs/工程规范/06-测试与CI规范.md)。当前 UI 采用「顶部模块菜单 + 左侧功能菜单」布局，视觉方向为 **A · 云白蓝（传统企业后台 + 现代浅色质感）**。
docs/工程规范/01-Git规范.md
+3 -3
View File
@@ -2,7 +2,7 @@
| 项 | 内容 |
| --- | --- |
| 文档版本 | V1.1（2026-11-02） |
| 文档版本 | V1.2（2026-11-04） |
| 依据 | 技术架构 §4.6（CI/CD）、§10.1（仓库结构） |
| 适用范围 | 全仓库（代码、文档、配置、迁移） |
| 强制级别 | 强制 |
@@ -21,7 +21,7 @@
- `GIT-01` 所有提交直接基于最新 `main`；提交前先 `git pull --ff-only`，避免落后。
- `GIT-02` 禁止创建并推送任何非 `main` 分支；确需本地验证时可临时创建，但不得推送，完成后立即删除。
- `GIT-03` 允许直接 push `main`；推送前必须通过本地门禁（`format:check`、`lint`、`typecheck`、`test`，完整链路用 `pnpm ci:local`）。**远端 Gitea 未部署 runner，线上 CI 不可用，推送后不等待远端 CI**。
- `GIT-03` 允许直接 push `main`；推送前必须通过本地门禁（`format:check`、`lint`、`typecheck`、`test`，完整链路用 `pnpm ci:local`）。远端自建 Gitea 已部署 Actions runner，push `main` 自动执行 CI；推送后关注远端结果，失败立即以新提交修复。
- `GIT-04` 禁止 force push `main`；禁止 Merge commit；`main` 必须保持线性。
## 2　提交信息（Conventional Commits 1.0）
@@ -134,4 +134,4 @@ export default {
- [ ] 提交粒度单一，无无关文件
- [ ] 无 `.env` / 密钥 / 大文件
- [ ] 提交说明含背景 / 影响面 / 回滚方式 / 验证证据
- [ ] 本地门禁全绿（必要时 `pnpm ci:local`），已 push `main`；远端无 CI，无需等待
- [ ] 本地门禁全绿（必要时 `pnpm ci:local`），已 push `main`；已确认远端 CI 结果（失败即修复）
docs/工程规范/06-测试与CI规范.md
+12 -11
View File
@@ -2,11 +2,11 @@
| 项 | 内容 |
| --- | --- |
| 文档版本 | V1.1（2026-11-04） |
| 文档版本 | V1.2（2026-11-04） |
| 依据 | 技术架构 §10.4（测试策略）、§4.6（CI/CD）、§4.1.1（本地环境） |
| 适用范围 | 全仓库 |
| 强制级别 | 强制 |
| 远端 CI | **不启用**：Gitea 无 runner，CI 只本地执行 |
| 远端 CI | **已启用**：自建 Gitea Actions runner（`gitea-runner-01`，label `ubuntu-latest`）；push `main` 自动执行，本地门禁仍为推送前强制项 |
---
@@ -15,8 +15,8 @@
| 层级 | 工具 | 范围 | 运行时机 |
| --- | --- | --- | --- |
| 单元 | Vitest | Service、工具函数、状态机、命名 / 表单引擎 | 每次提交（CI + 本地） |
| 集成 | Vitest + Testcontainers（PG 18 / Redis 7.4 / MinIO） | Repository、队列、迁移、事务 | 每次推送前本地 `pnpm ci:local` |
| 契约 | OpenAPI + `oasdiff` | 接口兼容性 | 每次推送前本地 `pnpm ci:local` |
| 集成 | Vitest + Testcontainers（PG 18 / Redis 7.4 / MinIO） | Repository、队列、迁移、事务 | 推送前本地 `pnpm ci:local` + push 后远端 CI |
| 契约 | OpenAPI + `oasdiff` | 接口兼容性 | 推送前本地 `pnpm ci:local` + push 后远端 CI |
| E2E | Playwright | 主链路（登录 → 生成 → 预览 → 勾选 → 导出） | 主干 + 发布前 |
| 性能 | k6 | 列表 / 任务提交 / SSE | 发布前（仅 staging） |
| 视觉回归 | 图片像素比对 | PSD 合成产物 | 改动 `packages/render` 时 |
@@ -55,20 +55,21 @@
---
## 4　本地 CI 流水线（远端不跑 CI）
## 4　CI 流水线（本地门禁 + 远端 Gitea Actions）
```
install --frozen-lockfile
→ turbo build --filter='./packages/*'（Lint / 类型解析依赖 packages dist）
→ format:check → lint --max-warnings=0 → typecheck
→ unit test（coverage）→ build
→ integration（Testcontainers）→ openapi:diff
→ integration（Testcontainers）→ openapi:export / diff
→ 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 会在后续跑」为由跳过本地门禁。
> **强制规则（2026-11-04 更新）**：远端自建 Gitea 已部署 Actions runner（`gitea-runner-01`，label `ubuntu-latest`），push `main` 自动执行 `.gitea/workflows/ci.yml`：
> - 推送前仍必须跑通 `pnpm ci:local`（完整链路）或至少 `pnpm format:check && pnpm lint && pnpm typecheck && pnpm test`；
> - 远端 CI 是第二道防线，**不得以「远端 CI 会跑」为由跳过本地门禁**；推送后关注远端结果，失败立即以新提交修复；
> - 需要快速确认 runner 可用时，手动触发 `.gitea/workflows/ci-smoke.yml`（约 1 分钟）。
| 阶段 | 阻断条件 |
| --- | --- |
@@ -120,7 +121,7 @@ staging 部署 → 冒烟（登录 / 生成 / 预览 / 导出）
- [ ] 端点有权限三态用例，客户隔离用例存在
- [ ] 状态机非法迁移、幂等、成本前置已覆盖
- [ ] 集成测试用 Testcontainers，无外网依赖
- [ ] 本地 `pnpm ci:local` 全绿且未使用豁免（远端无 runner）
- [ ] 本地 `pnpm ci:local` 全绿且未使用豁免，远端 CI 结果已确认（失败即修复）
- [ ] 迁移可回滚，staging 已演练
- [ ] 未完成功能藏开关，开关有清理期限
- [ ] 发布记录与回滚预案已写
docs/工程规范/07-CodeReview与PR规范.md
+3 -3
View File
@@ -2,7 +2,7 @@
| 项 | 内容 |
| --- | --- |
| 文档版本 | V1.1（2026-11-02） |
| 文档版本 | V1.2（2026-11-04） |
| 依据 | 技术架构 §10.1（工程约定）、§4.6（CI/CD） |
| 适用范围 | 所有直接推送到 `main` 的提交 |
| 强制级别 | 强制 |
@@ -101,7 +101,7 @@
同时满足才可推送：
1. 本地门禁全绿（含契约与集成，必要时 `pnpm ci:local`）；远端 Gitea 无 runner，不等待线上 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；推送前确认 `pnpm ci:local` 全绿，推送后不等待远端 CI（远端无 runner）。
- `CR-09` 直接 `git push origin main`；禁止 force push、禁止 Merge commit；推送前确认 `pnpm ci:local` 全绿，推送后关注远端 CI 结果，失败以新提交修复。
- `CR-10` 推送后发现缺陷：优先以新提交前向修复；影响面大时按回滚预案执行（回滚也用新提交，不回写历史），并补一次复盘（写 `docs/releases/` 或 issue）。
- `CR-11` 禁止「先推后补测试 / 补文档」作为常态；紧急修复须 24 小时内以新提交补齐，并在提交说明记录。