# Gateway Crypto Specification

Gateway API 的加密和签名工具函数，实现 AES-128-ECB 加密和 MD5 签名机制。

## ADDED Requirements

### Requirement: AES-128-ECB 加密

系统 SHALL 提供 `aesEncrypt` 函数，使用 AES-128-ECB 模式加密业务数据。

加密流程：
1. 密钥生成：`MD5(appSecret)` 的原始字节数组（16字节）
2. 加密算法：AES-128-ECB
3. 填充方式：PKCS5Padding
4. 编码输出：Base64

#### Scenario: 加密业务数据

- **WHEN** 调用 `aesEncrypt(data, appSecret)`
- **AND** `data` 为业务数据的 JSON 字节数组
- **THEN** 返回 Base64 编码的加密字符串
- **AND** 密钥为 `MD5(appSecret)` 的 16 字节数组

#### Scenario: PKCS5 填充正确性

- **WHEN** 业务数据长度不是 AES 块大小（16 字节）的整数倍
- **THEN** 使用 PKCS5Padding 进行填充
- **AND** 填充字节值等于填充长度

#### Scenario: 加密输出格式

- **WHEN** 加密成功
- **THEN** 输出为 Base64 字符串
- **AND** 字符串不包含换行符

#### Scenario: 加密失败

- **WHEN** AES 加密过程失败
- **THEN** 返回 `CodeGatewayEncryptError` 错误
- **AND** 错误信息包含原始错误

### Requirement: MD5 签名生成

系统 SHALL 提供 `generateSign` 函数，生成 MD5 签名。

签名流程：
1. 参数排序：`appId`、`data`、`timestamp` 按字母升序
2. 拼接字符串：`appId=xxx&data=xxx&timestamp=xxx&key=appSecret`
3. MD5 加密
4. 转大写十六进制

#### Scenario: 生成正确的签名

- **WHEN** 调用 `generateSign(appID, encryptedData, timestamp, appSecret)`
- **THEN** 参数按字母序拼接：`appId` → `data` → `timestamp`
- **AND** 追加 `&key=appSecret`
- **AND** MD5 加密后转大写十六进制

#### Scenario: 签名输出格式

- **WHEN** 签名生成成功
- **THEN** 输出为 32 位大写十六进制字符串
- **AND** 例如："ABCDEF1234567890ABCDEF1234567890"

#### Scenario: 签名可重现

- **WHEN** 使用相同的 `appID`、`encryptedData`、`timestamp`、`appSecret`
- **THEN** 多次调用 `generateSign` 生成相同的签名

#### Scenario: 时间戳格式

- **WHEN** 签名中使用时间戳
- **THEN** 时间戳为 Unix 秒级时间戳（10 位数字）
- **AND** 例如：1704067200

### Requirement: 参数序列化

系统 SHALL 正确序列化请求参数，确保与 Gateway 期望格式一致。

#### Scenario: 业务数据序列化

- **WHEN** 业务数据为 Go 结构体
- **THEN** 使用 `sonic.Marshal` 序列化为 JSON 字符串
- **AND** JSON 格式与 Gateway 文档一致

#### Scenario: 空字段处理

- **WHEN** 请求结构体中某些字段为空（omitempty）
- **THEN** 序列化时忽略空字段
- **AND** 减少请求体大小

### Requirement: 加密/签名测试验证

系统 SHALL 提供加密和签名的单元测试，验证与 Gateway 文档一致性。

#### Scenario: 加密测试用例

- **WHEN** 使用已知的业务数据和 appSecret
- **THEN** 加密输出与 Gateway 文档示例一致
- **AND** 可以被 Gateway 正确解密

#### Scenario: 签名测试用例

- **WHEN** 使用已知的参数和 appSecret
- **THEN** 签名输出与 Gateway 文档示例一致
- **AND** Gateway 验证签名成功

#### Scenario: 端到端验证

- **WHEN** 运行集成测试，实际调用 Gateway API
- **THEN** 加密和签名被 Gateway 接受
- **AND** 响应状态码为 200

### Requirement: 性能要求

系统 SHALL 确保加密和签名操作的性能满足要求。

#### Scenario: 加密性能

- **WHEN** 加密 1KB 的业务数据
- **THEN** 加密时间 < 1ms
- **AND** 内存分配最小化

#### Scenario: 签名性能

- **WHEN** 生成签名
- **THEN** 签名时间 < 0.5ms
- **AND** 无不必要的内存分配

### Requirement: 安全性说明

系统 SHALL 在文档中说明 AES-ECB 模式的安全性限制。

#### Scenario: 安全性文档

- **WHEN** 查看加密函数的文档注释
- **THEN** 注释中说明 ECB 模式不推荐用于生产环境
- **AND** 说明这是 Gateway 强制要求，无法改变
- **AND** 建议使用 HTTPS 加密传输层

### Requirement: 字符编码一致性

系统 SHALL 确保所有字符串操作使用 UTF-8 编码。

#### Scenario: 字符串编码

- **WHEN** 序列化业务数据
- **THEN** 使用 UTF-8 编码
- **AND** 中文字符正确处理

#### Scenario: 签名字符串编码

- **WHEN** 生成签名的拼接字符串
- **THEN** 使用 UTF-8 编码
- **AND** 与 Gateway 期望的编码一致