# 错误码注册治理

Go 定义是唯一权威来源，位于 `domains/`。JSON 文件是导出物，供服务查询、CLI 导出和跨语言消费。

## 新增一条码

1. 在 `errcode/codes.go` 增加 `Code` 常量。
2. 在对应域的 `register*` 中登记 HTTP、严重级别、重试、副作用、中文摘要与处置建议。
3. 若承接旧字符串，把它写成 `Aliases`，不要新造一套平行码。
4. 运行 `go test ./...`。目录一致性测试会失败，按测试输出重新导出 JSON：

```bash
WRITE_CATALOG=1 go test ./domains -run TestWriteCatalog -count=1
```

5. 更新 `docs/` 中对应系统的映射表。

## 不变量

- 规范码全局唯一；别名不得指向两个码，也不得与规范码同形冲突。
- 已发布的规范码只追加别名或澄清文案，不改变码字符串的含义。含义变化时新增码，旧码保留为别名或标记在映射表中。
- 副作用为 `possible` 或 `unknown` 的码，默认重试不得是 `always`。
- 种子数据在进程启动时登记。登记失败直接 panic，避免带着残缺目录对外服务。

## 自定义域

产品可以不改本仓库，在运行期加载 JSON：

```go
reg := errcode.NewRegistry()
domains.RegisterAll(reg)
data, _ := os.ReadFile("product.json")
if err := reg.LoadJSON(data); err != nil { /* 本批回滚 */ }
```

JSON 可以是数组，或 `{"codes":[...]}`。本批任一记录不合法时，整批回滚。