docs: consolidate dev baseline rules

This commit is contained in:
lili 2026-06-19 04:26:32 -07:00
parent eeb548db2c
commit 134d7646c3
7 changed files with 164 additions and 12 deletions

View File

@ -29,8 +29,8 @@
| [`rules/verification-and-anti-false-green.md`](rules/verification-and-anti-false-green.md) | ✅ | **脊柱规则**:完成=机械验证、机械门禁优先、反假绿(P0 已落地首批门禁) |
| [`rules/bc-boundaries.md`](rules/bc-boundaries.md) | ✅ | BC 边界:禁跨域 .dal 直连,ArchUnit 机械约束(已知违例 ContentMuseWorkOwnerFacade 单点登记整改) |
| [`rules/contract-first.md`](rules/contract-first.md) | ✅ | 契约先行:API=`docs/api-contracts/*`、DB=`sql/muse/V*` **原地 SSOT**;Flyway 卫生 + OpenAPI 结构 机械门禁(openapi-diff 已接 root workflow,远端首跑待确认) |
| `rules/engineering-conventions.md` | ⏳ | 命名/分层/错误码/提交/PR(收敛 `docs/dev-baseline/global/01,02`) |
| `rules/security-and-reliability.md` | ⏳ | 安全/幂等/超时重试/可观测(收敛 `docs/dev-baseline/global/05,06`) |
| [`rules/engineering-conventions.md`](rules/engineering-conventions.md) | ✅ | 工程约定:最小变更、契约协作、测试完成口径、CI/发布/回滚;已收敛 dev-baseline global 01-04 |
| [`rules/security-and-reliability.md`](rules/security-and-reliability.md) | ✅ | 安全可靠:可信边界、外部依赖 fail-closed、幂等补偿、日志审计;已收敛 dev-baseline global 05-06 |
**knowledge/**

View File

@ -0,0 +1,68 @@
# 规则:工程约定 —— 最小变更、契约协作、可验证交付
> **类型**:硬约束(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;补不了的只能标为“人工评审项”,不得包装成已机械保证。

View File

@ -0,0 +1,67 @@
# 规则:安全与可靠性 —— 可信边界、故障路径、可观测
> **类型**:硬约束(rules) · **状态**:生效 2026-06-19 · **门禁**:现有测试/契约/边界门禁 + 代码评审兜底
> **上位**:[`verification-and-anti-false-green.md`](verification-and-anti-false-green.md)、[`engineering-conventions.md`](engineering-conventions.md)
> **来源**:蒸馏 `docs/dev-baseline/global/05-安全开发规范.md``06-日志与可观测性规范.md`,并吸收项目当前“真实后端/真实 PG/外部依赖 fail-closed”经验。
---
## 一、可信边界
- 认证、授权、租户隔离、数据归属校验必须在后端可信边界执行;前端隐藏按钮或本地状态不算安全控制。
- `/admin-api/**``/app-api/**` 必须保持调用身份隔离;管理员能力不得经 app API 暴露,普通用户能力不得依赖 admin 端兜底。
- 查询和写入必须带可信的 `tenant_id` / `user_id` / owner 条件;不得信任前端传来的 owner、tenant 或权限声明。
- AI runtime 不得自授权。授权事实必须来自授权/权限端口或已验证的快照,运行时只能消费。
---
## 二、输入、文件与数据保护
- 所有外部输入必须校验:HTTP 请求、文件上传、SSE/WebSocket 消息、异步事件、外部回调都算外部输入。
- 优先使用框架校验与结构化解析;禁止用字符串拼接 SQL,禁止用正则/字符串切割代替可靠 parser。
- 文件路径、文件类型、文件大小、内容签名/格式都要校验;只看扩展名不够。写文件必须考虑部分写入、清理和路径穿越。
- 密码、token、API key、PG 密码、临时签名、授权快照不得写入代码、提交记录、日志、响应或错误信息。
- 用户隐私字段必须脱敏后展示或记录;完整手机号、邮箱、证件号、银行卡号不得进入普通日志。
---
## 三、外部依赖与异步可靠性
- 涉及外部服务、模型调用、对象存储、支付、通知、消息队列、异步任务时,必须设计超时、失败、重试、幂等、补偿和审计路径。
- 外部依赖未配置时必须 fail-closed:拒绝执行并给出可追踪错误,不得静默降级成假成功。
- 写路径必须有幂等键或命令记录;重试不得重复扣费、重复发放权益、重复创建投影或重复发送不可撤销通知。
- 异步投影必须有源事件、处理状态、重放或补偿策略;只写一侧而无法读回的设计不得声称端到端完成。
- 事务边界必须明确:跨 BC 写入优先通过端口/事件/投影,不得用跨域 DAL 拼接一个大事务。
---
## 四、日志、审计与追踪
- 关键业务状态变更、管理员操作、安全敏感操作、外部调用必须留下可追踪记录:who、what、when、where、result、commandId/traceId。
- ERROR 日志必须包含异常堆栈和足够定位的上下文;WARN 用于可恢复异常、降级、重试;INFO 记录关键业务事件;DEBUG 只用于开发诊断。
- 日志禁止输出大段正文、完整 prompt、完整 token、完整密钥、完整隐私字段。AI prompt 只记录模型、token 数、任务 ID、摘要性上下文。
- 前端请求应携带请求 ID 或等价关联信息;SSE/长连接需有 connectionId 关联事件流。
- 审计日志不得被业务普通删除路径修改或清除;敏感操作需要记录变更前后关键值或可重建来源。
---
## 五、故障处理与回滚
- 发现安全漏洞、数据错写、权限绕过、外部依赖异常时,先止血并保留证据,再修复;不得用“刷新缓存/重跑脚本”掩盖根因。
- 不可简单回滚的动作(删数据、发通知、扣费、授权发放、第三方永久写入)必须有人类确认、备份或补偿方案。
- 数据迁移必须可验证:迁移前后行数/关键约束/抽样数据有证据;大批量迁移要分批、可中断、可恢复。
- 配置变更应可独立回滚;敏感配置只通过仓库外环境或密钥系统注入。
---
## 六、机械门禁与人工评审边界
| 约束 | 机械落点 |
|---|---|
| 跨 BC 不直连他域实现 / DAL | `BcBoundaryArchTest` |
| API/DB 契约与迁移卫生 | `ContractFirstGateTest` + `openapi-diff` |
| completed 必须有测试证据 | `P1rApiCoverageReportTest` |
| 真实 PG / 外部依赖 fail-closed 证据 | `P1r*IT` 与总账证据 |
| `.agents` 规则索引 | `AgentsInfraIntegrityTest` |
目前尚无全量静态密钥扫描、SAST、依赖漏洞扫描门禁。涉及密钥、权限、支付、对象存储、模型调用、通知、生产数据迁移的变更,在补机械门禁前必须作为人工评审高风险项处理。

View File

@ -44,7 +44,7 @@ oh-my-muse/
├── agent-specs/ # 现状基线 + 对抗复盘 + P0 冻结令 + 六砖交付(过程 churn 已清理)
├── mvp/进度总账.md # 进度单一事实源(+ 历史交付时间线)
├── api-contracts/ # 各域 OpenAPI = API 契约 SSOT(原地;见 .agents/rules/contract-first.md)
├── dev-baseline/ # 既有全局/各仓规范(待收敛进 .agents/rules)
├── dev-baseline/ # 早期规范历史归档(已收敛进 .agents/rules;见 README)
└── memorys/ # 已归档清理(见 README);进度改用 mvp/进度总账.md
```
@ -94,6 +94,6 @@ oh-my-muse/
- ✅ 契约先行门([`contract-first`](.agents/rules/contract-first.md)):Flyway 迁移卫生 + OpenAPI **存在性/结构**(注:挡不住语义破坏;openapi-diff root workflow 已接线,需远端首次 PR 运行验证)。
- ✅ loop 机械牙([`AgentsInfraIntegrityTest`](muse-cloud/muse-server/src/test/java/cn/iocoder/muse/server/framework/arch/AgentsInfraIntegrityTest.java)):每业务 BC 有 `.agent`、README 索引每篇 `.agents` 文档、总账在——把写回/索引同步从自觉变机械。
- ✅ knowledge 蒸馏 / skills / workflow(AI 开发协议)/ 进度总账 + 7 BC `.agent`
- ⏳ 后续:openapi-diff 远端 CI 首跑验证、`dev-baseline` 收敛进 rules、Meta/schema 投影真实化、前端深页继续关 MSW 活体验收。`completed=测试证据`兜底(testFiles)、跨域 `.application` 边界、market-server→member-server pom 坐标收口、ai/平台预存红测试整改均已完成。
- ⏳ 后续:openapi-diff 远端 CI 首跑验证、Meta/schema 投影真实化、前端深页继续关 MSW 活体验收。`dev-baseline` 收敛进 rules、`completed=测试证据`兜底(testFiles)、跨域 `.application` 边界、market-server→member-server pom 坐标收口、ai/平台预存红测试整改均已完成。
> 进度只进 [`docs/mvp/进度总账.md`](docs/mvp/进度总账.md) + 各模块 `.agent`,不新增状态过程文档。

View File

@ -117,8 +117,8 @@ AI agent 驱动开发:
## 长任务持续性保障
- 大功能拆为可独立验证的子任务
- 每个子任务完成后更新 `design-docs/memorys/` 留痕
- Agent 可从 memorys 和 git log 恢复上下文
- 每个子任务完成后按 AGENTS.md 写回总账、模块 `.agent``.agents/` 对应层;不要新增过程状态文档
- Agent 可从总账、模块 `.agent``.agents/knowledge` 和 git log 恢复上下文
## 关键文件索引
@ -126,11 +126,11 @@ AI agent 驱动开发:
|------|------|
| `design-docs/00-文档大纲.md` | 文档集导航入口 |
| `design-docs/内容映射表.md` | 概念归属和 owner 清单 |
| `docs/dev-baseline/global/01-AI开发管理总则.md` | AI 开发全局规则 |
| `docs/dev-baseline/global/02-跨仓库协作规范.md` | 四仓协作规则 |
| `docs/dev-baseline/muse-cloud/CLAUDE.md` | 后端开发规范 |
| `docs/dev-baseline/muse-studio/CLAUDE.md` | 用户端前端规范 |
| `docs/dev-baseline/muse-admin/CLAUDE.md` | 管理端前端规范 |
| `AGENTS.md` | 项目唯一工作入口 |
| `.agents/README.md` | Agent 能力中枢索引 |
| `.agents/rules/engineering-conventions.md` | 工程约定 / 跨仓协作 / CI 发布规则 |
| `.agents/rules/security-and-reliability.md` | 安全 / 可靠性 / 可观测规则 |
| `docs/dev-baseline/README.md` | 早期 dev-baseline 历史归档说明 |
## Git 工作流

View File

@ -0,0 +1,17 @@
# dev-baseline 历史归档说明
`docs/dev-baseline/**` 是 2026-05 形成的早期全局/分仓规范来源,现已降级为**历史参考**。
当前工作入口与规则事实源:
| 主题 | 当前事实源 |
|---|---|
| 项目入口 / 工作协议 | [`../../AGENTS.md`](../../AGENTS.md) |
| Agent 能力中枢 | [`../../.agents/README.md`](../../.agents/README.md) |
| 验证与反假绿 | [`../../.agents/rules/verification-and-anti-false-green.md`](../../.agents/rules/verification-and-anti-false-green.md) |
| 工程约定 / 跨仓协作 / CI 发布 | [`../../.agents/rules/engineering-conventions.md`](../../.agents/rules/engineering-conventions.md) |
| 安全 / 可靠性 / 可观测 | [`../../.agents/rules/security-and-reliability.md`](../../.agents/rules/security-and-reliability.md) |
| 契约先行 | [`../../.agents/rules/contract-first.md`](../../.agents/rules/contract-first.md) |
| BC 边界 | [`../../.agents/rules/bc-boundaries.md`](../../.agents/rules/bc-boundaries.md) |
若本目录旧文档与上述事实源、代码或测试证据冲突,以后者为准。后续只在需要考古旧约束来源时读取本目录;新增或修正规则应回写 `.agents/rules/**` 与总账,不要继续扩写这里。

View File

@ -22,7 +22,7 @@
**market 写路径整改(2026-06-14,ultracode)**:member 暴露写端口 `MuseAccountRecordProjectionApi` + DTO(member-server 实现读写自有 DAL、tenantId 由实现侧从上下文注入防伪造、事务沿用调用方),market 5 类改消费端口、移除 member.dal 依赖 → `KNOWN_VIOLATION_EXEMPTIONS` 清空、BC 门全绿。**附带修复**:round-2 重构 `ContentKnowledgeWorkOwnerFacade` 时遗留的旧测试 `KnowledgeWorkOwnerFacadeTest`(仍断言旧 WorkMapper 行为)已删除,其装配守卫/兜底两用例并入 `ContentKnowledgeWorkOwnerFacadeTest`(5/0F)——此为 round-2 一处假绿(当时构建在平台时区用例处中止、未真正跑到 knowledge),现已补正。
**后续基建 TODO**:openapi-diff 远端 CI 首跑验证(🔧 检测逻辑+循环聚合已本地实证 2026-06-17:oasdiff v1.19.1 对 7 域真实契约 5/5 拦真破坏/放行安全演化,镜像钉版本+复现脚本已落地;2026-06-19 已把 workflow 从 `muse-cloud/.github/workflows/` 移到仓库根 `.github/workflows/`,修正自建 Gitea Actions 只扫描根 workflow 的接线问题;**仅余远端真实 PR 首跑确认**:`pull_request` paths 触发、`base.sha` worktree、docker 镜像拉取、Gitea Actions 是否已启。**`mvn -B package`[CI 确切命令]已本地实证全绿(2026-06-17,全 reactor 单测 + 打包步骤),接线后即应绿**——属远端基建首跑,留人类)`dev-baseline` 收敛进 rules。✅ 已完成项:`completed=测试证据`兜底(2026-06-19:coverage JSON 增 `testFiles`;生成器 `--check` + `P1rApiCoverageReportTest` 校验 completed 必须引用真实 `src/test/java` 证据文件且不得引用 coverage/gate 自身)、跨域 `.application` 边界门(2026-06-17:BcBoundaryArchTest 0 违例 + 反向证 238 例非空转)、market-server→member-server pom 坐标收口(2026-06-17:market-server 收窄至 member-api + tenant starter 直接声明)、ai/平台预存红测试整改(2026-06-15~17:三项全清)。
**后续基建 TODO**:openapi-diff 远端 CI 首跑验证(🔧 检测逻辑+循环聚合已本地实证 2026-06-17:oasdiff v1.19.1 对 7 域真实契约 5/5 拦真破坏/放行安全演化,镜像钉版本+复现脚本已落地;2026-06-19 已把 workflow 从 `muse-cloud/.github/workflows/` 移到仓库根 `.github/workflows/`,修正自建 Gitea Actions 只扫描根 workflow 的接线问题;**仅余远端真实 PR 首跑确认**:`pull_request` paths 触发、`base.sha` worktree、docker 镜像拉取、Gitea Actions 是否已启。**`mvn -B package`[CI 确切命令]已本地实证全绿(2026-06-17,全 reactor 单测 + 打包步骤),接线后即应绿**——属远端基建首跑,留人类)。✅ 已完成项:`dev-baseline` 收敛进 rules(2026-06-19:新增 `engineering-conventions` + `security-and-reliability`,旧 `docs/dev-baseline/**` 降级历史归档并由 `AgentsInfraIntegrityTest` 索引门兜底)、`completed=测试证据`兜底(2026-06-19:coverage JSON 增 `testFiles`;生成器 `--check` + `P1rApiCoverageReportTest` 校验 completed 必须引用真实 `src/test/java` 证据文件且不得引用 coverage/gate 自身)、跨域 `.application` 边界门(2026-06-17:BcBoundaryArchTest 0 违例 + 反向证 238 例非空转)、market-server→member-server pom 坐标收口(2026-06-17:market-server 收窄至 member-api + tenant starter 直接声明)、ai/平台预存红测试整改(2026-06-15~17:三项全清)。
**🎯 全 reactor `mvn test` 史上首次全绿(2026-06-17)**:本特性分支 30+ commit 从未 push、maven.yml 只在 push/PR-to-main 触发故 **CI 从未在本分支真跑过**,积累若干潜伏红。以 `mvn -pl muse-server -am test -fae` 全 reactor 排查,逐模块解锁(上游失败 fail-fast 会 SKIP 下游),共清 **6 处**:① market `AppMuseMarketPublishControllerTest` 9 参 `PublishRecordItem` 构造(record 自 a00c758 加 marketAssetId/appealStatus 变 10 参)② coverage 台账 33 op serviceFiles 陈旧引用(本会话 facade 移 member-api 所致)③④ knowledge/ai 的 `Content*WorkOwnerFacadeTest` 仍断言 `@ConditionalOnBean`(2026-06-14 单体修复已去除、改 @Primary)⑤ ai `MuseAiEventPublishOutboxMapperTest` 真 PG 用例无 PG 时硬 fail→改 `assumeTrue` skip(与 P1r external-acceptance env 缺失即 skip 约定一致、honest 非假绿)⑥ muse-server `P1rKnowledgeMigrationSqlTest` 元测试钉死 `TARGET_VERSION="14"`(IT 已按 4d46d7a 动态自适应)→版本无关化。**全 reactor BUILD SUCCESS、0 失败**(真 PG 类无 PG 时 skip)。教训:跨模块重构后须跑 `-fae` 全量,勿只跑改动模块。**前端 muse-studio 同步复验绿(2026-06-17:`tsc -b` 0 错误 + `vitest run` 12 文件/47 用例全过;本分支前端改动 35 文件全在 studio、admin 未动)**——故**整分支(后端 `mvn -B package` + 前端 `tsc`/`vitest`)deterministic CI 检查全绿,均本会话实证**(e2e/playwright 需活体后端+浏览器,未在本轮跑;真 PG IT 多数 2026-06-17 已人工批准且本会话变更为 import-only+单测已覆盖,未重跑)。