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 领域驱动设计原则