69 lines
4.6 KiB
Markdown
69 lines
4.6 KiB
Markdown
# 规则:工程约定 —— 最小变更、契约协作、可验证交付
|
|
|
|
> **类型**:硬约束(rules) · **状态**:生效 2026-06-19 · **门禁**:现有 CI/JUnit/ArchUnit/契约门禁组合兜底
|
|
> **上位**:[`verification-and-anti-false-green.md`](verification-and-anti-false-green.md)
|
|
> **来源**:蒸馏 `docs/dev-baseline/global/01-AI开发管理总则.md`、`02-跨仓库协作规范.md`、`03-CI-CD基线配置.md`、`04-发布与部署规范.md`;旧 dev-baseline 降级为历史来源,不再作为工作入口。
|
|
|
|
---
|
|
|
|
## 一、工作入口与优先级
|
|
|
|
1. 项目入口只认根 [`../../AGENTS.md`](../../AGENTS.md);能力中枢只认 [`.agents/README.md`](../README.md)。
|
|
2. 旧 `docs/dev-baseline/**` 只作为历史来源。若与 `AGENTS.md`、`.agents/rules/**`、代码或测试证据冲突,以已验证事实和 `.agents/rules/**` 为准。
|
|
3. 复杂任务先读相关 knowledge/rules/总账/模块 `.agent`,再动手;简单、低风险、局部、验证明确的任务可直接最小改动并验证。
|
|
|
|
---
|
|
|
|
## 二、编码约定
|
|
|
|
- **最小变更**:只改当前任务直接相关代码;不顺手重构、改名、调格式或扩大模块边界。
|
|
- **复用既有模式**:优先使用本仓已有框架、helper、测试基类和领域端口;新增抽象必须有真实复用收益或明确演进点。
|
|
- **中文注释**:公开接口、状态转换、事务边界、安全校验、外部调用、AI 编排、补偿逻辑必须有中文注释说明 WHY、边界和失败处理;禁止“获取用户”这类复述代码的空注释。
|
|
- **命名与数据形态**:API 路径用 kebab-case;分页使用 `pageNo/pageSize`;响应分页为 `{ list, total }`;Long ID 传到前端按 string 处理以避开 JS 精度问题;枚举传输遵循现有契约,不得擅自改语义。
|
|
- **不造孤儿设计**:任何新增接口、表、端口、事件、投影、枚举都必须同时说明入口、使用方、失败路径、验收标准和回滚/兼容策略。
|
|
|
|
---
|
|
|
|
## 三、跨仓与契约协作
|
|
|
|
- 后端/API/DB 变更必须先对齐契约 SSOT:API=`docs/api-contracts/**`,DB=`muse-cloud/sql/muse/V*.sql`,详见 [`contract-first.md`](contract-first.md)。
|
|
- 前端不得直接要求“加字段”并绕过契约;后端不得新增对外行为却不更新契约。
|
|
- `muse-admin` 只消费 `/admin-api/**`;`muse-studio` 只消费 `/app-api/**`;前端不访问数据库,不承载授权事实。
|
|
- 跨 BC 只经 `-api`/对外端口,禁止跨域 `.dal` 或 `.application` 直连,详见 [`bc-boundaries.md`](bc-boundaries.md)。
|
|
- 破坏性 API/DB 变更必须分阶段:先兼容新旧、迁移调用方、确认无旧引用,再删除旧契约或旧列。
|
|
|
|
---
|
|
|
|
## 四、测试与完成口径
|
|
|
|
- 完成只能基于自动化绿证据,不得基于台账数字、截图、手工拨状态或 mock 通过;详见 [`verification-and-anti-false-green.md`](verification-and-anti-false-green.md)。
|
|
- 业务变更必须评估测试增删改;Bug 修复优先补能复现问题的测试,再修复。
|
|
- 前端 mock/MSW 下通过只证明组件局部逻辑,不证明旅程可用。用户可见旅程必须关 mock、对真后端、跑 Playwright/e2e 或等价自动化。
|
|
- 无法运行最相关验证时,必须说明缺口、已做替代验证、下一步真实验证方式。
|
|
|
|
---
|
|
|
|
## 五、CI、发布与回滚
|
|
|
|
- CI 不得跳测试;JDK/Node/包管理器版本必须与项目实际一致。当前后端机械门禁以 Maven/JUnit/ArchUnit 为主,前端以 TypeScript/Vitest/Playwright 为主。
|
|
- 新增 CI 规则必须能在本地复现核心逻辑,并在文档中记录不可本地覆盖的远端残留。
|
|
- 发布前至少具备:相关测试绿、契约兼容性判断、迁移策略、配置变更说明、回滚策略。
|
|
- 数据库变更只新增迁移,不得改已合入历史迁移;删除列/表、改类型、数据迁移必须有兼容窗口和回滚/补偿方案。
|
|
- 配置与密钥不得入库;环境差异应通过环境变量或配置中心表达,并提供本地/测试环境验证路径。
|
|
|
|
---
|
|
|
|
## 六、机械门禁
|
|
|
|
本规则的约束由现有门禁组合兜底,不是靠自觉:
|
|
|
|
| 约束 | 机械落点 |
|
|
|---|---|
|
|
| 完成=绿证据 / coverage completed 必须有测试文件 | `P1rApiCoverageReportTest` |
|
|
| 契约与迁移卫生 / openapi-diff workflow 位置 | `ContractFirstGateTest` + `.github/workflows/openapi-diff.yml` |
|
|
| BC 边界 | `BcBoundaryArchTest` |
|
|
| `.agents` 新规则索引与总账存在 | `AgentsInfraIntegrityTest` |
|
|
| 前端真实旅程 | `muse-studio` Playwright/Vitest/tsc,按总账中已验证切片执行 |
|
|
|
|
新增工程约定若不能被上述门禁覆盖,必须优先补测试/脚本/CI;补不了的只能标为“人工评审项”,不得包装成已机械保证。
|