面向用户的错误封装规范

核心原则

技术细节封闭在程序内部，绝不暴露给最终用户。

组件名（ffmpeg、grpc、ONVIF…）、文件路径、依赖库的原始报错、内部错误串，这些只属于开发/运维。最终用户看到的错误必须满足：

1. 有稳定错误码：如 CTRL-4101，用户报障时引用，客服/研发据此定位
2. 普通人能读懂：说清"发生了什么、用户能做什么"，如"视频功能暂不可用，请联系维护人员处理"
3. 零技术细节：不含组件名、命令、路径、英文堆栈

反例：{"error":"ffmpeg not installed on controller"} 正例：{"error":"[CTRL-4101] 视频功能暂不可用，请联系维护人员处理","code":"CTRL-4101"}

实现模式（三段式错误类型）

type Error struct {
    Code    string // 稳定错误码，一旦对外发布不可变更含义
    Message string // 面向最终用户的非技术提示（用户语言）
    Cause   error  // 技术根因：只进日志，绝不序列化给用户
}

func (e *Error) Error() string { return fmt.Sprintf("[%s] %s", e.Code, e.Message) } // 兼容字符串渲染
func (e *Error) Unwrap() error { return e.Cause }                                    // 保留 errors.Is/As 链

• 响应出口统一转换：HTTP/RPC 的错误出口处判断该类型 → 输出 {error:"[CODE] 提示", code:"CODE"}；其余错误保持原文（参数校验类）。这样任何新错误只需构造该类型，出口自动脱敏
• 文本格式 [CODE] 提示 兼容把 error 当字符串渲染的旧消费方，平台零改动即可显示友好文案
• 技术根因必须有日志：出口处记 [模块][操作] user error: CODE: cause，可搜索前缀，现场可追溯。没有日志的脱敏等于丢失排查能力

错误码段位表

按功能分配段位、集中登记在一处（包级常量/文档），示例：

41xx 视频功能    42xx 相机    43xx 导航    44xx 平台通信    45xx 设备连接

新增错误 = 登记码 + 构造函数（函数而非变量，避免复用共享 Cause）。

检查清单（新增/改造错误时）

1. 这个错误用户会看到吗？会 → 必须走错误码+提示；只给运维/调试接口 → 原文可以
2. 提示是否说清了"用户下一步能做什么"（重试/联系维护）？
3. 文本里有没有组件名/路径/英文报错？有 → 移入 Cause
4. Cause 是否已写入日志（含可搜索前缀）？
5. 错误码是否已登记段位表、且不会与已有码冲突？
6. 有没有测试锁定"用户文本不含技术词"？（防回归）

判定标准

给非技术同事看错误文案：能明白发生了什么、知道该找谁，就算合格；若对方追问"ffmpeg 是什么"，就是失败。