tyapi-server/docs/应用服务层改造TODO.md

应用服务层改造 TODO 清单

📋 总体进度

• 阶段一：基础架构搭建 (0/4)
• 阶段二：用户域改造 (0/4)
• 阶段三：认证域改造 (0/4)
• 阶段四：财务域改造 (0/4)
• 阶段五：管理员域改造 (0/3)
• 阶段六：整体优化 (0/4)

---

🏗️ 阶段一：基础架构搭建

1.1 创建新的目录结构

• 创建 internal/application/ 目录
• 创建 internal/infrastructure/ 目录
• 创建应用服务层子目录结构
  • internal/application/user/
  • internal/application/certification/
  • internal/application/finance/
  • internal/application/admin/
• 创建基础设施层子目录结构
  • internal/infrastructure/http/
  • internal/infrastructure/database/
  • internal/infrastructure/cache/
  • internal/infrastructure/external/
  • internal/infrastructure/config/

1.2 移动现有组件到基础设施层

• 移动 HTTP 处理器
  • 移动 domains/user/handlers/ → infrastructure/http/handlers/
  • 移动 domains/certification/handlers/ → infrastructure/http/handlers/
  • 移动 domains/finance/handlers/ → infrastructure/http/handlers/
  • 移动 domains/admin/handlers/ → infrastructure/http/handlers/
• 移动路由
  • 移动 domains/user/routes/ → infrastructure/http/routes/
  • 移动 domains/certification/routes/ → infrastructure/http/routes/
  • 移动 domains/finance/routes/ → infrastructure/http/routes/
  • 移动 domains/admin/routes/ → infrastructure/http/routes/
• 移动中间件
  • 移动 shared/middleware/ → infrastructure/http/middleware/
• 移动仓储实现
  • 移动 domains/user/repositories/ → infrastructure/database/repositories/user/
  • 移动 domains/certification/repositories/ → infrastructure/database/repositories/certification/
  • 移动 domains/finance/repositories/ → infrastructure/database/repositories/finance/
  • 移动 domains/admin/repositories/ → infrastructure/database/repositories/admin/
• 移动外部服务
  • 移动 shared/sms/ → infrastructure/external/sms/
  • 移动 shared/ocr/ → infrastructure/external/ocr/
  • 移动 shared/storage/ → infrastructure/external/storage/
  • 移动 shared/notification/ → infrastructure/external/notification/

1.3 更新导入路径

• 更新所有移动文件的导入路径
• 更新 container/container.go 中的导入路径
• 更新 app/app.go 中的导入路径
• 检查并修复所有编译错误

1.4 确保项目能正常启动

• 运行 go mod tidy 整理依赖
• 编译项目确保无错误
• 启动项目确保能正常运行
• 运行基础功能测试

---

👤 阶段二：用户域改造

2.1 创建用户应用服务基础结构

• 创建 internal/application/user/user_application_service.go
• 创建命令对象
  • internal/application/user/dto/commands/register_user_command.go
  • internal/application/user/dto/commands/login_user_command.go
  • internal/application/user/dto/commands/change_password_command.go
• 创建查询对象
  • internal/application/user/dto/queries/get_user_profile_query.go
• 创建响应对象
  • internal/application/user/dto/responses/register_user_response.go
  • internal/application/user/dto/responses/login_user_response.go
  • internal/application/user/dto/responses/user_profile_response.go
• 创建应用事件
  • internal/application/user/events/user_application_events.go

2.2 实现用户应用服务逻辑

• 实现 RegisterUser 方法
  • 验证短信验证码
  • 检查手机号是否已存在
  • 创建用户实体
  • 保存用户
  • 发布用户注册事件
• 实现 LoginUser 方法
  • 支持密码登录
  • 支持短信登录
  • 发布用户登录事件
• 实现 ChangePassword 方法
  • 验证短信验证码
  • 验证旧密码
  • 更新密码
  • 发布密码修改事件
• 实现 GetUserProfile 方法
  • 获取用户信息
  • 返回脱敏信息

2.3 重构用户 HTTP 处理器

• 修改 infrastructure/http/handlers/user_handler.go
• 将 HTTP 处理器改为调用应用服务
• 简化 HTTP 处理器的职责
• 保持 API 接口不变
• 更新错误处理

2.4 更新依赖注入配置

• 在 container/container.go 中注册用户应用服务
• 更新用户 HTTP 处理器的依赖
• 确保向后兼容

2.5 测试用户相关功能

• 测试用户注册功能
• 测试用户登录功能（密码/短信）
• 测试密码修改功能
• 测试用户信息查询功能
• 验证 API 接口兼容性

---

🏢 阶段三：认证域改造

3.1 创建认证应用服务基础结构

• 创建 internal/application/certification/certification_application_service.go
• 创建命令对象
  • internal/application/certification/dto/commands/create_certification_command.go
  • internal/application/certification/dto/commands/submit_enterprise_info_command.go
  • internal/application/certification/dto/commands/upload_license_command.go
  • internal/application/certification/dto/commands/initiate_face_verify_command.go
  • internal/application/certification/dto/commands/apply_contract_command.go
• 创建查询对象
  • internal/application/certification/dto/queries/get_certification_status_query.go
  • internal/application/certification/dto/queries/get_certification_details_query.go
• 创建响应对象
  • internal/application/certification/dto/responses/certification_response.go
  • internal/application/certification/dto/responses/enterprise_info_response.go
  • internal/application/certification/dto/responses/upload_license_response.go
• 创建应用事件
  • internal/application/certification/events/certification_application_events.go

3.2 实现认证应用服务逻辑

• 实现 CreateCertification 方法
  • 检查用户是否已有认证申请
  • 创建认证申请
  • 发布认证创建事件
• 实现 SubmitEnterpriseInfo 方法
  • 验证认证状态
  • 检查统一社会信用代码
  • 创建企业信息
  • 更新认证状态
  • 发布企业信息提交事件
• 实现 UploadLicense 方法
  • 上传文件到存储服务
  • 创建上传记录
  • 进行 OCR 识别
  • 发布营业执照上传事件
• 实现 InitiateFaceVerify 方法
  • 验证认证状态
  • 调用人脸识别服务
  • 更新认证状态
  • 发布人脸识别事件
• 实现 ApplyContract 方法
  • 验证认证状态
  • 申请电子合同
  • 更新认证状态
  • 发布合同申请事件

3.3 重构认证 HTTP 处理器

• 修改 infrastructure/http/handlers/certification_handler.go
• 将 HTTP 处理器改为调用应用服务
• 简化 HTTP 处理器的职责
• 保持 API 接口不变
• 更新错误处理

3.4 处理跨域协调逻辑

• 在应用服务中协调用户域和认证域
• 确保数据一致性
• 处理跨域事件

3.5 测试认证流程

• 测试创建认证申请
• 测试提交企业信息
• 测试上传营业执照
• 测试人脸识别流程
• 测试合同申请流程
• 验证完整认证流程

---

💰 阶段四：财务域改造

4.1 创建财务应用服务基础结构

• 创建 internal/application/finance/finance_application_service.go
• 创建命令对象
  • internal/application/finance/dto/commands/create_wallet_command.go
  • internal/application/finance/dto/commands/recharge_wallet_command.go
  • internal/application/finance/dto/commands/withdraw_wallet_command.go
  • internal/application/finance/dto/commands/create_user_secrets_command.go
  • internal/application/finance/dto/commands/regenerate_access_key_command.go
• 创建查询对象
  • internal/application/finance/dto/queries/get_wallet_info_query.go
  • internal/application/finance/dto/queries/get_user_secrets_query.go
• 创建响应对象
  • internal/application/finance/dto/responses/wallet_response.go
  • internal/application/finance/dto/responses/transaction_response.go
  • internal/application/finance/dto/responses/user_secrets_response.go
• 创建应用事件
  • internal/application/finance/events/finance_application_events.go

4.2 实现财务应用服务逻辑

• 实现 CreateWallet 方法
  • 检查用户是否已有钱包
  • 创建钱包
  • 发布钱包创建事件
• 实现 RechargeWallet 方法
  • 验证金额
  • 检查钱包状态
  • 增加余额
  • 发布充值事件
• 实现 WithdrawWallet 方法
  • 验证金额
  • 检查余额是否足够
  • 减少余额
  • 发布提现事件
• 实现 CreateUserSecrets 方法
  • 生成访问密钥
  • 创建用户密钥
  • 发布密钥创建事件
• 实现 RegenerateAccessKey 方法
  • 验证用户密钥
  • 重新生成访问密钥
  • 发布密钥更新事件

4.3 添加事务管理

• 在应用服务中添加事务边界
• 确保资金操作的数据一致性
• 处理事务回滚

4.4 重构财务 HTTP 处理器

• 修改 infrastructure/http/handlers/finance_handler.go
• 将 HTTP 处理器改为调用应用服务
• 简化 HTTP 处理器的职责
• 保持 API 接口不变
• 更新错误处理

4.5 测试财务功能

• 测试创建钱包
• 测试钱包充值
• 测试钱包提现
• 测试创建用户密钥
• 测试重新生成访问密钥
• 验证资金安全

---

👨‍💼 阶段五：管理员域改造

5.1 创建管理员应用服务基础结构

• 创建 internal/application/admin/admin_application_service.go
• 创建命令对象
  • internal/application/admin/dto/commands/admin_login_command.go
  • internal/application/admin/dto/commands/create_admin_command.go
  • internal/application/admin/dto/commands/update_admin_command.go
  • internal/application/admin/dto/commands/change_admin_password_command.go
• 创建查询对象
  • internal/application/admin/dto/queries/get_admin_info_query.go
  • internal/application/admin/dto/queries/list_admins_query.go
• 创建响应对象
  • internal/application/admin/dto/responses/admin_login_response.go
  • internal/application/admin/dto/responses/admin_info_response.go
  • internal/application/admin/dto/responses/admin_list_response.go
• 创建应用事件
  • internal/application/admin/events/admin_application_events.go

5.2 实现管理员应用服务逻辑

• 实现 AdminLogin 方法
  • 验证管理员凭据
  • 生成 JWT 令牌
  • 记录登录日志
  • 发布管理员登录事件
• 实现 CreateAdmin 方法
  • 检查用户名和邮箱唯一性
  • 加密密码
  • 创建管理员
  • 记录操作日志
  • 发布管理员创建事件
• 实现 UpdateAdmin 方法
  • 验证管理员存在
  • 更新管理员信息
  • 记录操作日志
  • 发布管理员更新事件
• 实现 ChangeAdminPassword 方法
  • 验证旧密码
  • 更新密码
  • 记录操作日志
  • 发布密码修改事件

5.3 重构管理员 HTTP 处理器

• 修改 infrastructure/http/handlers/admin_handler.go
• 将 HTTP 处理器改为调用应用服务
• 简化 HTTP 处理器的职责
• 保持 API 接口不变
• 更新错误处理

5.4 测试管理功能

• 测试管理员登录
• 测试创建管理员
• 测试更新管理员
• 测试修改管理员密码
• 测试管理员信息查询
• 验证权限控制

---

🔧 阶段六：整体优化

6.1 添加应用事件处理

• 实现应用事件发布机制
• 添加应用事件处理器
• 处理跨域事件协调
• 添加事件持久化

6.2 完善监控和日志

• 添加应用服务层的日志记录
• 完善错误处理和监控
• 添加性能指标收集
• 优化日志格式和级别

6.3 性能优化

• 优化数据库查询
• 添加缓存策略
• 优化并发处理
• 添加连接池配置

6.4 文档更新

• 更新 API 文档
• 更新架构文档
• 更新开发指南
• 添加部署文档

---

📝 开发指南

应用服务层开发模式

1. 应用服务结构

type UserApplicationService struct {
    userService    *services.UserService
    smsCodeService *services.SMSCodeService
    eventBus       interfaces.EventBus
    logger         *zap.Logger
}

2. 命令对象模式

type RegisterUserCommand struct {
    Phone          string `json:"phone" binding:"required,len=11"`
    Password       string `json:"password" binding:"required,min=6,max=128"`
    ConfirmPassword string `json:"confirm_password" binding:"required,eqfield=Password"`
    Code           string `json:"code" binding:"required,len=6"`

    // 应用层上下文信息
    CorrelationID string `json:"-"`
    ClientIP      string `json:"-"`
    UserAgent     string `json:"-"`
}

3. 查询对象模式

type GetUserProfileQuery struct {
    UserID string `json:"-"`
}

4. 响应对象模式

type RegisterUserResponse struct {
    UserID       string    `json:"user_id"`
    Phone        string    `json:"phone"`
    RegisteredAt time.Time `json:"registered_at"`
}

5. 应用事件模式

type UserRegisteredApplicationEvent struct {
    ID            string    `json:"id"`
    UserID        string    `json:"user_id"`
    Phone         string    `json:"phone"`
    RegisteredAt  time.Time `json:"registered_at"`
    CorrelationID string    `json:"correlation_id"`
    ClientIP      string    `json:"client_ip"`
    UserAgent     string    `json:"user_agent"`
}

业务逻辑编写指南

1. 应用服务方法结构

func (s *UserApplicationService) RegisterUser(ctx context.Context, cmd *dto.RegisterUserCommand) (*dto.RegisterUserResponse, error) {
    // 1. 参数验证
    // 2. 业务规则检查
    // 3. 调用域服务
    // 4. 事务处理
    // 5. 发布事件
    // 6. 返回结果
}

2. 错误处理模式

if err != nil {
    s.logger.Error("操作失败", zap.Error(err))
    return nil, fmt.Errorf("操作失败: %w", err)
}

3. 事件发布模式

event := &dto.UserRegisteredApplicationEvent{
    ID:            uuid.New().String(),
    UserID:        user.ID,
    Phone:         user.Phone,
    RegisteredAt:  time.Now(),
    CorrelationID: cmd.CorrelationID,
    ClientIP:      cmd.ClientIP,
    UserAgent:     cmd.UserAgent,
}

if err := s.eventBus.Publish(ctx, event); err != nil {
    s.logger.Warn("发布事件失败", zap.Error(err))
}

4. 事务管理模式

// 在应用服务中使用事务
tx := s.db.Begin()
defer func() {
    if r := recover(); r != nil {
        tx.Rollback()
    }
}()

// 执行业务操作
if err := s.userService.CreateUser(ctx, user); err != nil {
    tx.Rollback()
    return nil, err
}

if err := tx.Commit().Error; err != nil {
    return nil, err
}

测试指南

1. 单元测试

func TestUserApplicationService_RegisterUser(t *testing.T) {
    // 准备测试数据
    // 执行测试
    // 验证结果
}

2. 集成测试

func TestUserRegistrationFlow(t *testing.T) {
    // 测试完整流程
    // 验证数据库状态
    // 验证事件发布
}

---

🚀 快速开始

第一步：备份当前代码

git checkout -b feature/application-service-layer
git add .
git commit -m "备份当前代码状态"

第二步：开始阶段一

按照 TODO 清单逐步执行阶段一的任务。

第三步：验证改造

每个阶段完成后，确保：

• 项目能正常编译
• 项目能正常启动
• 基础功能正常工作
• 测试通过

第四步：提交代码

每个阶段完成后提交代码：

git add .
git commit -m "完成阶段X：XXX改造"

---

📞 支持

如果在改造过程中遇到问题：

1. 检查 TODO 清单是否遗漏
2. 查看相关文档
3. 运行测试验证
4. 回滚到上一个稳定版本