# error-handling Specification

## Purpose
TBD - created by archiving change refactor-framework-cleanup. Update Purpose after archive.
## Requirements
### Requirement: Simplified AppError Structure

系统 SHALL 简化 AppError 结构，删除冗余的 HTTPStatus 字段。

#### Scenario: AppError 字段
- **WHEN** 创建 AppError
- **THEN** 结构体只包含 3 个字段：
  - Code: 业务错误码
  - Message: 错误消息
  - Err: 底层错误（可选）

#### Scenario: HTTP 状态码获取
- **WHEN** ErrorHandler 处理 AppError
- **THEN** 通过 GetHTTPStatus(code) 实时获取 HTTP 状态码
- **AND** 不从 AppError 字段中读取

#### Scenario: 禁止手动设置状态码
- **WHEN** 创建 AppError
- **THEN** 不提供 WithHTTPStatus() 方法
- **AND** Code 和 HTTPStatus 始终保持一致

### Requirement: Unified Error Response Format

系统 SHALL 使用统一的 JSON 响应格式（错误和成功均使用相同字段）。

#### Scenario: 响应结构
- **WHEN** 返回任何响应时
- **THEN** JSON 结构仅包含 4 个字段：
  - code: 业务错误码（0 表示成功）
  - msg: 消息（错误消息或 "success"）
  - data: 响应数据（成功时有数据，错误时为 null）
  - timestamp: ISO 8601 时间戳

#### Scenario: 不返回 HTTP 状态码字段
- **WHEN** 返回响应时
- **THEN** JSON 不包含 httpstatus 或 http_status 字段
- **AND** HTTP 状态码仅在响应头中体现

#### Scenario: Handler 返回错误
- **WHEN** Handler 函数返回 error
- **THEN** 全局 ErrorHandler 拦截错误
- **AND** 根据错误类型构造统一格式响应

### Requirement: Handler Error Return Convention

所有 Handler 函数 SHALL 通过返回 error 传递错误，由全局 ErrorHandler 统一处理。

#### Scenario: 业务错误
- **WHEN** Handler 遇到业务错误
- **THEN** 返回 errors.New(code, message) 创建的 AppError
- **AND** 不直接调用 response.Error()

#### Scenario: 参数验证错误
- **WHEN** 请求参数验证失败
- **THEN** 返回 errors.New(CodeInvalidParam, "具体错误描述")

#### Scenario: 成功响应
- **WHEN** Handler 执行成功
- **THEN** 调用 response.Success(c, data)
- **AND** 返回 nil

### Requirement: Standardized Error Codes

系统 SHALL 使用标准化的错误码，删除向后兼容的别名。

#### Scenario: 参数验证错误码
- **WHEN** 参数验证失败
- **THEN** 使用 CodeInvalidParam
- **AND** 不使用 CodeBadRequest（别名已删除）

#### Scenario: 服务不可用错误码
- **WHEN** 服务不可用
- **THEN** 使用 CodeServiceUnavailable
- **AND** 不使用 CodeAuthServiceUnavailable（别名已删除）