文档

openspec/changes/archive/2026-01-31-gateway-integration/specs/gateway-crypto/spec.md

@@ -0,0 +1,155 @@
+# 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 期望的编码一致