diff --git a/AGENTS.md b/AGENTS.md index 699ac8d..8971bc6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 图层前缀、规格矩阵、低质量标记 | diff --git a/README.md b/README.md index 8af8083..b739985 100644 --- a/README.md +++ b/README.md @@ -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 · 云白蓝(传统企业后台 + 现代浅色质感)**。 diff --git a/docs/工程规范/01-Git规范.md b/docs/工程规范/01-Git规范.md index 7950a07..603331a 100644 --- a/docs/工程规范/01-Git规范.md +++ b/docs/工程规范/01-Git规范.md @@ -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 结果(失败即修复) diff --git a/docs/工程规范/06-测试与CI规范.md b/docs/工程规范/06-测试与CI规范.md index 2f2ea61..86aa0e6 100644 --- a/docs/工程规范/06-测试与CI规范.md +++ b/docs/工程规范/06-测试与CI规范.md @@ -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 已演练 - [ ] 未完成功能藏开关,开关有清理期限 - [ ] 发布记录与回滚预案已写 diff --git a/docs/工程规范/07-CodeReview与PR规范.md b/docs/工程规范/07-CodeReview与PR规范.md index 90ecac7..bedad5e 100644 --- a/docs/工程规范/07-CodeReview与PR规范.md +++ b/docs/工程规范/07-CodeReview与PR规范.md @@ -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 小时内以新提交补齐,并在提交说明记录。