7277b9c558
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测试编写指南
2.8 KiB
2.8 KiB
日志与可观测性规范
1. 日志级别标准
| 级别 | 使用场景 | 示例 |
|---|---|---|
| ERROR | 需要人工介入的故障 | 数据库连接失败、外部服务不可达、数据不一致 |
| WARN | 异常但可自动恢复 | 重试成功、降级触发、接近阈值 |
| INFO | 关键业务事件 | 用户登录、作品创建、AI 生成完成、支付成功 |
| DEBUG | 开发调试信息 | 方法入参、中间状态、SQL 语句 |
规则：
- 生产环境默认 INFO 级别
- ERROR 必须包含异常堆栈和上下文
- 禁止在循环中打 INFO/WARN 日志
- DEBUG 日志使用条件判断或 SLF4J 占位符，避免字符串拼接开销
2. 结构化日志格式
后端使用 JSON 格式输出：
{
"timestamp": "2024-01-01T12:00:00.000Z",
"level": "INFO",
"traceId": "abc123",
"spanId": "def456",
"service": "muse-cloud",
"module": "content",
"message": "作品创建成功",
"userId": 12345,
"workId": 67890,
"duration": 150
}
前端错误上报格式：
{
"timestamp": "...",
"level": "ERROR",
"source": "muse-studio",
"page": "/works/123/editor",
"message": "Block 保存失败",
"error": "NetworkError: timeout",
"userId": 12345,
"context": { "blockId": "...", "revision": 5 }
}
3. 敏感信息脱敏
日志中禁止出现：
- 密码、token、密钥的明文
- 完整的身份证号、银行卡号
- 用户的完整手机号、邮箱
脱敏规则：
- 手机号：138****1234
- 邮箱：u***@example.com
- token：前 4 位 + ****
4. 链路追踪
- 使用 traceId 贯穿请求全链路（网关 → 服务 → 数据库 → 外部调用）
- 前端请求携带 X-Request-Id header
- 异步任务继承父任务的 traceId
- SSE 连接使用 connectionId 关联同一会话的所有事件
5. 前端错误监控
- 全局错误边界捕获未处理异常
- API 请求失败自动上报（排除 4xx 客户端错误中的 401/403）
- 编辑器崩溃单独上报（含 Block 状态快照）
- 性能指标上报：FCP、LCP、CLS
6. 后端监控指标
关键指标：
- API 响应时间（P50/P95/P99）
- 错误率（5xx / 总请求）
- AI 生成延迟（首 token 时间、总生成时间）
- 数据库连接池使用率
- 消息队列积压量
告警阈值建议：
- API P99 > 3s：WARN
- API P99 > 10s：ERROR
- 错误率 > 1%：WARN
- 错误率 > 5%：ERROR
- DB 连接池 > 80%：WARN
7. Agent 日志行为规则
- 关键业务操作必须打 INFO 日志（创建、修改、删除、状态变更）
- 外部调用（AI API、文件存储、消息队列）必须打日志（入参摘要 + 耗时 + 结果）
- 异常处理必须打 ERROR 日志（含堆栈和上下文）
- 不在日志中输出大段正文内容（截取前 100 字符）
- 不在日志中输出完整的 AI prompt（只记录 token 数和模型名）