zizi 7277b9c558 fix(baseline): 修复管理基线文档一致性问题并补充安全/日志规范

Critical修复：
- CI配置MySQL→PostgreSQL对齐架构决策
- 错误码格式统一为分段格式(系统-模块-分类-序号)
- 覆盖率指标统一(Domain 90%/Application 80%/新增 90%)

Major修复：
- 分支策略统一为trunk-based，去掉develop分支
- muse-studio部署描述修正为Vite SPA静态部署
- muse-studio提交类型统一为英文前缀
- API路径统一为/app-api，端口对齐48080
- DROP COLUMN措辞修正为条件性禁止
- 增加规范优先级声明

新增文档：
- 05-安全开发规范.md（认证授权/输入校验/AI安全/审计）
- 06-日志与可观测性规范.md（日志级别/结构化/链路追踪/监控）
- muse-admin测试编写指南

2026-05-24 11:36:22 +08:00

12 KiB

Raw Blame History

AI 开发管理总则

版本：v1
更新日期：2026-05-24
适用范围：muse-cloud / muse-admin / muse-studio / muse-design-docs 四仓全局
目标读者：AI agent、人类开发者、架构师、项目管理者

规范优先级

当多份文档存在冲突时，按以下优先级执行：

各仓库 CLAUDE.md（最具体的约束）
全局总则和跨仓协作规范（通用规则）
dev-guide 开发指南（参考性指导）

如果发现冲突，应修正低优先级文档使其与高优先级对齐，而非忽略。

1. 开发模式定义

1.1 职责分工

角色	职责	不负责
AI agent	编码实现、测试编写、重构执行、文档更新、CI 修复、代码评审辅助、调试定位	架构决策、需求确认、发布决策、安全审计最终判定
人类开发者	架构决策、需求确认、PR review、发布决策、安全审计、异常升级处理	重复性编码、格式化、简单 bug 修复

1.2 协作流程

人类提出任务 → agent 分析并规划方案 → 人类确认方案 → agent 执行实现 → agent 自验证 → 人类 review → 合入

对于低风险、局部、验证明确的任务（typo 修复、简单 bug fix、测试补充），agent 可直接执行后提交 review，无需预先确认方案。

1.3 决策升级规则

以下情况 agent 必须停下来等待人类确认：

涉及架构变更（新增模块、修改模块边界、新增外部依赖）
涉及数据模型变更（新增表、修改字段语义、删除字段）
涉及 API 契约变更（新增接口、修改入参出参语义、废弃接口）
涉及安全相关变更（认证、授权、加密、数据脱敏）
涉及跨仓协调（一个变更需要多个仓库同步修改）
方案有多个可行路径且各有明显取舍时

2. 代码质量基线

2.1 中文注释规范

所有代码必须有合理的中文注释，遵循以下分级：

级别	适用场景	注释要求
必须详细注释	状态转换、事务边界、安全校验、数据流转换、AI 编排逻辑、双轨写入规则	说明 WHY（为什么这样做）、边界条件、失败处理策略
必须注释	公开接口、领域服务方法、配置项、枚举值	说明用途、参数含义、返回值语义
建议注释	工具方法、数据转换、非显而易见的条件判断	说明意图或 workaround 原因
禁止注释	代码自解释的简单操作	如 `// 获取用户` 对应 `getUser()` 是无意义注释

2.2 注释原则

注释说明 WHY 而非 WHAT（代码本身说明 what）
复杂算法必须注释时间/空间复杂度和核心思路
非显而易见的设计决策必须注释决策原因
Workaround 必须注释：问题描述、临时方案、TODO 标记预期修复时间
禁止注释掉的代码长期留存（用 git 管理历史）

2.3 代码可读性

方法长度：单个方法不超过 80 行（不含注释），超过必须拆分
嵌套深度：不超过 3 层，超过用 early return 或提取方法
命名：变量和方法名必须自解释，禁止单字母变量（循环变量除外）
魔法值：禁止硬编码数字和字符串，必须提取为常量并注释含义

3. 代码风格一致性

3.1 各仓独立规范

每个仓库遵循各自 CLAUDE.md 中定义的语言和框架规范：

muse-cloud：Java / Spring Boot / MyBatis-Plus 规范
muse-admin：Vue 3 / TypeScript / Vben Admin 规范
muse-studio：React / TypeScript / Vite SPA 规范
muse-design-docs：Markdown 文档规范

3.2 跨仓一致性约定

以下约定跨四仓统一执行：

约定项	统一标准	说明
错误码格式	`{系统}-{模块}-{分类}-{序号}`	系统：1=muse；模块：001=content, 002=ai, 003=knowledge, 004=market, 005=account, 006=meta；分类：000=通用, 001=参数校验, 002=业务规则, 003=权限, 004=外部依赖；序号：000-999。示例：1-001-002-001 表示 content 模块的业务规则错误第 1 号
API 路径命名	小写 kebab-case	`/app-api/work/text-block`
日期时间格式	ISO 8601（`2026-05-24T10:30:00+08:00`）	前后端传输统一
分页参数	`pageNo`（从 1 开始）/ `pageSize`（默认 20，最大 100）	请求参数
分页响应	`{ list, total }`	响应体
布尔参数命名	`is` / `has` / `can` / `enable` 前缀	语义明确
枚举传输	整数值传输，前端维护显示映射	不传字符串枚举
空值语义	`null` 表示未设置，空字符串/空数组表示显式清空	前后端统一理解
时区	服务端存储 UTC，展示层转本地时区	数据库存 UTC
ID 类型	Long（雪花算法），JSON 传输为 string 避免精度丢失	前端用 string 接收

4. 测试自动化策略

4.1 测试金字塔

        /  E2E 测试  \          ← 关键用户旅程，数量少
       / 集成测试      \        ← Application 层，验证模块协作
      / 契约测试        \       ← API 入参出参校验
     / 单元测试          \      ← Domain 层，覆盖业务规则
    /____________________\

4.2 各层测试要求

测试层	覆盖目标	运行时机	失败影响
单元测试	Domain 实体、值对象、领域服务的业务规则	每次提交	阻断合入
集成测试	Application Service 的编排逻辑、事务边界	每次提交	阻断合入
契约测试	API 入参校验、出参结构、错误码	每次提交	阻断合入
组件测试（前端）	组件渲染、交互、状态管理	每次提交	阻断合入
E2E 测试	关键用户旅程端到端验证	合入主分支前	阻断发布
AI 质量评测	生成文本的 canon_compliance、character_voice	模型/Prompt 变更时	阻断相关发布

4.3 测试编写规则

每次业务代码变更必须评估测试用例的增删改
新增功能必须同步提交对应测试
Bug 修复必须先写失败测试，再修复使其通过
测试命名：should_{预期行为}_when_{前置条件}
测试数据：使用 Builder 或 Factory 模式构造，不依赖外部数据源
Mock 边界：只 mock 外部依赖（数据库、第三方 API、消息队列），不 mock 被测模块内部

4.4 覆盖率目标

Domain 层：行覆盖率 > 90%
Application 层：行覆盖率 > 80%
Controller 层：契约测试覆盖所有公开接口
前端组件：关键交互路径覆盖率 > 80%
整体自动化率目标：> 90%，人工只复核非标准场景

5. 长任务持续性保障

5.1 任务拆分原则

大功能必须拆为可独立验证的子任务，每个子任务满足：

有明确的完成条件（可验证）
可独立提交和 review
不依赖未完成的其他子任务才能运行
单个子任务工作量不超过一个 agent 会话能完成的范围

5.2 上下文传递机制

任务开始 → 读取 docs/memorys/ 和 git log 恢复上下文
    ↓
执行子任务 → 完成后更新 docs/memorys/YYYY-MM-DD-任务描述.md
    ↓
下一个子任务 → 从 memorys 和 git log 恢复上下文继续

5.3 留痕规范

每个有复杂度的任务完成后，在 docs/memorys/ 留痕：

文件名：YYYY-MM-DD-任务描述.md（任务描述 10-20 字）
内容：目标、关键决策、变更范围、验证结果、遗留问题
目的：下次类似任务或断点恢复时可快速获取上下文

5.4 断点恢复

agent 恢复中断任务时：

读取最近相关的 docs/memorys/ 文件
查看 git log 了解最近提交
检查当前分支状态和未完成的变更
确认当前进度后继续执行，不重复已完成的工作

6. 稳定性保障

6.1 CI 门禁

每个 PR 必须通过以下检查才能合入：

编译成功（零错误）
Lint 通过（零错误，warning 不阻断但需逐步清理）
单元测试全部通过
集成测试全部通过
类型检查通过（前端 TypeScript strict mode）

6.2 数据库变更规则

所有 Schema 变更必须通过 migration 脚本，禁止手动执行 DDL
每个 migration 必须有对应的 rollback 脚本
破坏性变更（删列、改类型、删表）必须分阶段执行：
1. 先部署代码兼容新旧 Schema
2. 执行 migration
3. 清理兼容代码
大表变更必须评估锁表时间，超过 5 秒的变更需要使用 online DDL 工具

6.3 API 兼容性

API 变更必须向后兼容，通过 X-API-Version header 区分版本
废弃接口标记 @Deprecated，保留至少一个版本周期后才能删除
新增字段默认可选（nullable 或有默认值），不破坏现有调用方
删除字段先标记废弃，下个版本才实际移除

6.4 依赖管理

依赖升级必须在独立 PR 中进行，不混合业务变更
使用精确版本号（不用 ^ 或 ~），通过 lockfile 锁定
新增依赖必须评估：维护活跃度、安全记录、包大小、许可证兼容性
禁止引入与现有依赖功能重叠的新包

7. 可扩展性保障

7.1 模块边界

遵循设计文档中定义的 BC 边界和依赖方向（见 架构-01）
模块间通信只通过定义好的接口，禁止跨模块直接访问内部实现
依赖方向：Domain 不依赖 Infrastructure，Application 编排 Domain
新增模块前必须在 架构-01 中确认其 BC 归属

7.2 扩展点设计

预留扩展点通过接口/SPI 机制，不通过配置爆炸
不为单次使用做过度抽象（YAGNI）
扩展点必须有至少一个真实使用场景才能引入
策略模式、模板方法等设计模式的使用必须注释其扩展意图

7.3 复用优先

新增功能前先检查是否有现有抽象可复用
跨模块的通用能力提取到 framework 层
业务特有逻辑留在业务模块内，不过早泛化

8. 可维护性保障

8.1 代码自解释 + 注释双保险

代码结构和命名做到自解释（what）
中文注释补充意图和决策（why）
两者互补，不互相替代

8.2 设计文档对应

复杂流程（涉及 3 个以上模块协作）必须有对应的设计文档
设计文档在 muse-design-docs 仓维护，实现代码中注释引用文档路径
格式：// 设计文档：muse-design-docs/后端-03-关键流程实现与接口契约.md#章节名

8.3 模块 README

每个顶层模块目录下必须有 README.md，说明：

模块职责（一句话）
边界（负责什么、不负责什么）
依赖关系（依赖谁、被谁依赖）
关键入口（主要的 Service / Controller / Component）

8.4 代码卫生

废弃代码及时清理，不留 dead code
TODO 必须标注负责人和预期处理时间：// TODO(zizi): 2026-06 迁移到新接口后删除
注释掉的代码禁止提交（用 git 管理历史）
临时调试代码（console.log、System.out.println）禁止提交

9. Agent 通用行为规则

9.1 先读后写

修改前必须读取相关代码理解上下文
理解现有模式后再动手，不凭假设编码
检查是否有现有的工具方法、常量、类型可复用

9.2 最小变更

只改当前任务直接相关的代码
不顺手重构无关的命名、格式、注释
不为改善代码风格而扩大变更范围
一个 PR 只做一件事

9.3 验证闭环

改完必须运行测试验证
无法运行测试时说明原因和替代验证方式
验证通过后才能声称"已完成"
验证失败时修复后重新验证，不跳过

9.4 失败处理

同一方法失败两次，停下来分析根因
分析后换方向，不做第三次相同尝试
记录失败原因和新方向的选择理由

9.5 安全意识

不硬编码密钥、token、密码
不跳过权限检查
不信任前端输入（所有输入必须后端校验）
不在日志中输出敏感信息
SQL 必须使用参数化查询，禁止字符串拼接
文件操作必须校验路径，防止路径穿越

9.6 幂等与容错

涉及外部服务调用时，必须考虑超时和重试
涉及异步任务时，必须考虑失败补偿
涉及支付/通知时，必须保证幂等性
涉及文件操作时，必须考虑部分写入和清理

9.7 上下文管理

大任务主动拆分为可独立验证的子任务
每个子任务完成后评估是否需要留痕
恢复任务时先读 memorys 和 git log，不从零开始
不在单次会话中尝试完成超出上下文窗口的工作量

12 KiB Raw Blame History Unescape Escape