hdk-pay/.trae/documents/plan_20251128_101341.md

# 邮箱管理 SDK 生成计划（最终版本）

## 任务目标
根据 OpenAPI 规范，生成“获取用户常用邮箱”和“更新用户常用邮箱”接口的 SDK，严格遵循 DDD 架构，不创建新的 Rpc 文件，创建独立的邮箱管理仓库或合理命名现有仓库。

## 分析与设计

### 1. 接口分析
从 OpenAPI 规范中，我找到了两个邮箱管理相关接口：
- **GET /rpc/v2/account/{uid}/inv-email**：获取用户常用邮箱
- **PUT /rpc/v2/account/{uid}/inv-email**：更新用户常用邮箱

### 2. 现有代码结构（DDD 架构）
- **Domain 层**：
  - `AccountRepoInterface`：账户仓库接口
  - `AccountBalance`、`PointsBalance`：账户相关聚合根和值对象
  - `PointType`、`PointAction`：枚举类

- **Infrastructure 层**：
  - `AccountBalanceRepo`：实现了 `AccountRepoInterface`，但名称仅反映余额管理
  - `AbstractRepo`：基础仓库类，封装了 HTTP 请求

### 3. 实现方案

#### 3.1 方案选择
考虑到用户反馈，我选择以下方案：
- **扩展 AccountRepoInterface**：添加邮箱管理方法
- **创建新的 AccountRepo 实现**：将 AccountBalanceRepo 重命名为 AccountRepo，使其更通用
- **创建 Email 领域对象**：创建 Email 值对象封装邮箱信息

#### 3.2 具体设计

1. **创建 Email 领域对象**：
   - `Email`：值对象，封装邮箱信息

2. **扩展 AccountRepoInterface**：
   - `getEmail`：获取用户常用邮箱，返回 `Email` 对象
   - `updateEmail`：更新用户常用邮箱，接收 `Email` 对象

3. **重命名并扩展 AccountBalanceRepo**：
   - 将 `AccountBalanceRepo` 重命名为 `AccountRepo`
   - 实现新添加的邮箱管理方法
   - 保持原有余额管理功能不变

## 执行步骤

1. **创建 Email 领域对象**：
   - 在 `Domain/Account/ValueObject` 目录下创建 `Email.php`

2. **扩展 AccountRepoInterface**：
   - 添加 `getEmail` 和 `updateEmail` 方法

3. **重命名并扩展 AccountBalanceRepo**：
   - 将 `AccountBalanceRepo` 重命名为 `AccountRepo`
   - 实现邮箱管理方法

4. **更新 ConfigProvider**：
   - 更新依赖注入配置，将 `AccountRepoInterface` 指向新的 `AccountRepo`

5. **编写测试用例**：
   - 验证邮箱管理功能

## 预期结果

- 完成邮箱管理相关接口的 SDK 实现
- 严格遵循 DDD 架构，不创建新的 Rpc 文件
- 仓库名称更合理，支持账户的多种操作（余额和邮箱）
- 创建了 Email 领域对象，封装邮箱信息
- 代码结构符合项目现有规范
- 包含必要的测试用例

## 技术细节

- 使用现有的 `AbstractRepo` 作为基础类
- 使用 `RequestService` 进行 HTTP 请求
- 遵循项目现有的代码风格和命名规范
- 使用 PHP 8.2 的特性（如 readonly 属性、命名参数）
- 保持与现有代码的一致性

## 命名调整说明

- 将 `AccountBalanceRepo` 重命名为 `AccountRepo`，使其更通用，能够处理账户相关的多种操作，包括余额和邮箱管理
- 创建 `Email` 值对象，封装邮箱信息，符合 DDD 领域驱动设计原则