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. 应用服务结构

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

#### 2. 命令对象模式

```go
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. 查询对象模式

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

#### 4. 响应对象模式

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

#### 5. 应用事件模式

```go
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. 应用服务方法结构

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

#### 2. 错误处理模式

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

#### 3. 事件发布模式

```go
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. 事务管理模式

```go
// 在应用服务中使用事务
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. 单元测试

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

#### 2. 集成测试

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

---

## 🚀 快速开始

### 第一步：备份当前代码

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

### 第二步：开始阶段一

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

### 第三步：验证改造

每个阶段完成后，确保：

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

### 第四步：提交代码

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

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

---

## 📞 支持

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

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