# error-code-validation Specification

## Purpose
TBD - created by archiving change unify-error-message-source. Update Purpose after archive.
## Requirements
### Requirement: 错误码消息映射完整性校验

系统 SHALL 在启动时校验所有已注册的错误码都有对应的 `errorMessages` 映射条目。

如果发现缺失映射，系统 MUST 立即 panic 并输出清晰的错误信息，指明缺失的错误码。

#### Scenario: 所有错误码都有映射时正常启动

- **WHEN** 所有 `allErrorCodes` 中的错误码都在 `errorMessages` 映射表中存在
- **THEN** 系统正常启动，无错误日志

#### Scenario: 存在缺失映射时启动失败

- **WHEN** 某个错误码（如 `CodeNewFeature = 1099`）在 `allErrorCodes` 中注册但 `errorMessages` 中缺失
- **THEN** 系统 panic，错误信息包含 "错误码 1099 缺少映射消息"

### Requirement: 错误码注册表维护

系统 SHALL 维护一个 `allErrorCodes` 切片，包含所有已定义的错误码常量。

新增错误码时，开发者 MUST 同时：
1. 在 `codes.go` 中定义常量
2. 在 `allErrorCodes` 中注册
3. 在 `errorMessages` 中添加映射

#### Scenario: 新增错误码完整注册

- **WHEN** 开发者新增错误码 `CodeXxx = 1100`
- **THEN** 必须同时在 `allErrorCodes` 和 `errorMessages` 中添加对应条目
- **THEN** 否则启动时 panic 或测试失败

### Requirement: errors.New 默认使用映射表消息

`errors.New()` 函数 SHALL 优先使用 `errorMessages` 映射表中的消息作为默认值。

当调用者提供自定义消息时，系统 MUST 允许覆盖默认消息。

#### Scenario: 不传消息参数时使用映射表

- **WHEN** 调用 `errors.New(errors.CodeNotFound)`
- **THEN** 返回的 `AppError.Message` 为 "资源未找到"（映射表中的值）

#### Scenario: 传空字符串时使用映射表

- **WHEN** 调用 `errors.New(errors.CodeNotFound, "")`
- **THEN** 返回的 `AppError.Message` 为 "资源未找到"（映射表中的值）

#### Scenario: 传自定义消息时覆盖映射表

- **WHEN** 调用 `errors.New(errors.CodeNotFound, "提现申请不存在")`
- **THEN** 返回的 `AppError.Message` 为 "提现申请不存在"（自定义值）

### Requirement: errors.Wrap 默认使用映射表消息

`errors.Wrap()` 函数 SHALL 与 `errors.New()` 保持一致的消息处理逻辑。

#### Scenario: Wrap 不传消息时使用映射表

- **WHEN** 调用 `errors.Wrap(errors.CodeDatabaseError, originalErr)`
- **THEN** 返回的 `AppError.Message` 为 "数据库错误"（映射表中的值）
- **THEN** 返回的 `AppError.Err` 为 `originalErr`

#### Scenario: Wrap 传自定义消息时覆盖

- **WHEN** 调用 `errors.Wrap(errors.CodeDatabaseError, "查询用户失败", originalErr)`
- **THEN** 返回的 `AppError.Message` 为 "查询用户失败"
- **THEN** 返回的 `AppError.Err` 为 `originalErr`

### Requirement: CI 测试覆盖映射完整性

系统 SHALL 提供单元测试 `TestAllCodesHaveMessages`，验证所有注册的错误码都有对应的映射。

此测试 MUST 在 CI 流程中运行，防止映射表腐化。

#### Scenario: 测试检测到缺失映射

- **WHEN** 运行 `go test ./pkg/errors/...`
- **WHEN** 存在错误码在 `allErrorCodes` 但不在 `errorMessages` 中
- **THEN** 测试失败，输出缺失的错误码列表

#### Scenario: 测试检测到孤立映射

- **WHEN** 运行 `go test ./pkg/errors/...`
- **WHEN** 存在映射条目的错误码不在 `allErrorCodes` 中
- **THEN** 测试失败，输出孤立的错误码列表（可选警告）