0 Fork 0

Files

T

Stev_Wang 00ae12435e docs(specs): add AGENTS.md and engineering guidelines

项目尚无统一工程规范，AI 助手与研发各自发挥导致返工风险。建立
总纲 + 细则两层结构：AGENTS.md 只写硬约束与索引（14 条红线、技术栈
基线、仓库结构、命令契约），细则拆为 10 份文档覆盖 Git、代码风格、
格式化、API 与路由、数据库、测试与 CI、Review、日志、密钥、资产命名。

影响面：仅文档。约束力从本轮起对新建代码生效；与现状冲突处以文档为准。
回滚方式：git revert 本提交。

2026-11-02 15:09:51 +08:00

5.7 KiB

Raw Blame History

08 · 日志与可观测性规范

项	内容
文档版本	V1.0（2026-11-02）
依据	技术架构 §2.7（可观测性）、§9.7、§5.4.5（审计表）
适用范围	`apps/api`、`apps/worker`、`apps/web`（错误上报）
强制级别	强制

1　日志（Pino，结构化 JSON）

必带字段（每条日志）

字段	说明
`ts`	ISO 8601 UTC
`level`	`error` / `warn` / `info` / `debug`
`msg`	稳定短句（可被聚合），变量放字段里
`trace_id`	贯穿请求链路；HTTP 入口生成，响应头 `x-trace-id` 回传
`module`	模块名（`media` / `script` / `identity`…）
`action`	动作（`media.task.submit`、`script.generate`）

按需字段：user_id、customer_id、task_id、item_id、duration_ms、error.code、error.stack（仅后端内部日志）、retry_count、provider、model。

LOG-01 禁止 console.log；后端用注入的 logger，前端用统一 logger + 错误上报。
LOG-02 msg 用英文短句 + 常量，禁止拼业务变量（"task 123 failed"），便于聚合统计。
LOG-03 禁止记录：密码、Token、密钥、Cookie、签名 URL、Authorization 头、完整手机号 / 身份证、客户素材原始内容。
LOG-04 大对象（请求体 / 模型响应）必须先裁剪：≤ 2 KB，且标注 truncated: true。
LOG-05 AI 调用日志记录：供应商、模型、任务类型、耗时、token 数、费用、是否降级；不记录 prompt 全文（敏感客户信息），需要复现时用引用 ID。
LOG-06 日志级别语义：error = 需人处理；warn = 已降级 / 重试；info = 业务里程碑与状态变更；debug = 仅开发环境默认关闭。
LOG-07 生产默认 info，可按模块动态调级（不重启）；禁止长期开 debug。

2　链路追踪（OpenTelemetry）

LOG-08 HTTP 入口创建 span，trace_id 写入响应头、错误体、日志三处，便于用户报错时定位。
LOG-09 跨队列传递 traceparent（BullMQ job data 中携带），worker 侧继续同一 trace。
LOG-10 外部调用（AI / 存储 / ffmpeg）必须建子 span，记录目标、耗时、结果状态。
LOG-11 采样率：生产默认 10%，错误与慢请求 100%；采样配置走环境变量。

3　审计（与日志严格分离）

维度	日志	审计
存储	日志系统（可轮转、可丢弃）	`audit_logs` 表（append-only）
用途	排障	追责、合规、回溯「为什么这样」
内容	技术细节	actor / action / target / before / after / ip / ua / trace_id
修改	可删可改	仅 INSERT，任何角色不可改（PRD 9.2）

LOG-12 必须审计的操作：登录 / 登出、权限点与角色变更、客户创建与状态变更、导出、分享链接创建与作废、AI 配置变更、行业包发布、字段变更与审批、资产删除 / 停用、跨客户复用授权。
LOG-13 审计写入与业务写在同一事务内（或 outbox 保证最终一致），禁止业务成功但审计丢失。
LOG-14 审计查询本身也要留痕（谁查了审计）。

4　指标（Prometheus 命名）

命名：<domain>_<metric>_<unit>，如 media_task_finished_total、queue_depth、ai_cost_cny_total。

类别	必含指标
HTTP	请求量、错误率、P50/P95 延迟（按路由模板，不按原始 URL）
队列	各队列深度、等待时长、失败率、重试次数
业务	任务成功率、单条成本、图片有效率、抠图降级率、低质量产出率
AI	调用次数、失败 / 降级率、token 用量、费用（预算占比）
存储	桶容量、上传失败率、签名 URL 下发量
依赖	PG 连接数 / 慢查询、Redis 内存 / 命中率

LOG-15 标签基数受控：禁止把 user_id、customer_id、task_id 作为指标标签（用日志 / trace 查）。
LOG-16 派生指标（汇总 / 均值 / 占比）运行时计算，不落库（技术架构 §5.7）。

5　告警

告警	阈值（起步，可调）	处置
接口错误率	5 分钟内 > 5%	查 trace → 定位依赖 → 必要时回滚
队列积压	单队列深度 > 1000 或等待 > 10 分钟	扩 worker / 查卡死任务
AI 预算	达软限 80% 告警、硬限 100% 阻断	降级路由 / 通知负责人
任务失败率	10 分钟内 > 10%	查供应商 / 依赖 → 切路由
磁盘 / 存储	使用率 > 80%	清理 temp / 扩容
证书到期	< 14 天	续签
抠图降级率	单批次 > 30%	排查模型 / 输入质量

LOG-17 每条告警必须可执行：附 runbook 链接（docs/runbook/）与负责人。
LOG-18 禁止「告警风暴」：同一根因聚合，5 分钟内同一告警只发一次。

6　前端可观测

LOG-19 前端错误上报必须带：release 版本、trace_id（若有）、路由、浏览器、是否客户数据脱敏。
LOG-20 禁止上报用户隐私与客户素材内容；上报前统一脱敏。
LOG-21 关键交互（生成、预览、勾选、导出）埋点事件名稳定，带 customer_id / batch_id / user_id 三维（PRD 8.1）。

7　检查清单

日志结构化，必带 trace_id / module / action
msg 稳定可聚合，变量进字段
无敏感信息、无签名 URL、无 prompt 全文
跨队列传递 traceparent
审计与日志分离，关键操作全部入 audit_logs
新增关键路径有指标与告警
指标标签基数受控，派生指标不落库

5.7 KiB Raw Blame History Unescape Escape

08 · 日志与可观测性规范

1 日志（Pino，结构化 JSON）

2 链路追踪（OpenTelemetry）

3 审计（与日志严格分离）

4 指标（Prometheus 命名）

5 告警

6 前端可观测

7 检查清单