4. 错误码规范：模块前缀、错误级别、自增编号、文档映射

错误码是跨模块 Result 封装中最核心的结构化字段。随意的错误编号会导致排查成本飙升、跨团队协作混乱。本章定义一套可落地的错误码规范，确保每个错误码在系统中具备唯一性、可读性与可追溯性。

4.1 错误码结构定义

规范采用四段式数字编码，每位字段之间使用短横线 - 连接：

示例：012-3-0024-01

• 012 → 用户中心模块
• 3 → ERROR 级别
• 0024 → 该模块第 24 个错误码
• 01 → 文档 ID 为 user-center-01

4.2 编码示例与边界说明

# 模块前缀注册表示例（截取）
Prefix | Module Name
-------|-------------------
000    | core-framework
001    | api-gateway
002    | auth-service
010    | payment-service
012    | user-center
013    | order-service
020    | notification-service

4.3 错误码生命周期与解析流程

下图展示一个错误从发生到被 Result 封装、再到文档映射的完整链路：

4.4 选型权衡与风险点

4.5 落地步骤

1. 确定模块前缀表：架构评审会上一次性分配所有业务模块前缀，写入 module_prefix.json。
2. 建立自增编号池：每个模块在 Git 仓库中维护 errors/code_pool_XXX.yaml，记录已使用编号。
3. 实现错误码生成器：封装一个工厂函数，传入模块前缀、级别、文档 ID，自动分配下一个可用编号。

# 伪代码示例：错误码生成器
function genErrorCode(moduleId, level, docId) {
    pool = loadPool(moduleId)
    nextSeq = pool.nextAvailableSeq()   // 0401 格式
    pool.markUsed(nextSeq)
    savePool(pool)
    return moduleId + '-' + level + '-' + nextSeq + '-' + docId
}

4.6 验收标准