4.6 KiB
4.6 KiB
规则:工程约定 —— 最小变更、契约协作、可验证交付
类型:硬约束(rules) · 状态:生效 2026-06-19 · 门禁:现有 CI/JUnit/ArchUnit/契约门禁组合兜底 上位:
verification-and-anti-false-green.md来源:蒸馏docs/dev-baseline/global/01-AI开发管理总则.md、02-跨仓库协作规范.md、03-CI-CD基线配置.md、04-发布与部署规范.md;旧 dev-baseline 降级为历史来源,不再作为工作入口。
一、工作入口与优先级
- 项目入口只认根
../../AGENTS.md;能力中枢只认.agents/README.md。 - 旧
docs/dev-baseline/**只作为历史来源。若与AGENTS.md、.agents/rules/**、代码或测试证据冲突,以已验证事实和.agents/rules/**为准。 - 复杂任务先读相关 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。 - 前端不得直接要求“加字段”并绕过契约;后端不得新增对外行为却不更新契约。
muse-admin只消费/admin-api/**;muse-studio只消费/app-api/**;前端不访问数据库,不承载授权事实。- 跨 BC 只经
-api/对外端口,禁止跨域.dal或.application直连,详见bc-boundaries.md。 - 破坏性 API/DB 变更必须分阶段:先兼容新旧、迁移调用方、确认无旧引用,再删除旧契约或旧列。
四、测试与完成口径
- 完成只能基于自动化绿证据,不得基于台账数字、截图、手工拨状态或 mock 通过;详见
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;补不了的只能标为“人工评审项”,不得包装成已机械保证。