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

应用服务层改造计划

📋 项目概述

当前项目状态

• 项目名称: TYAPI Server (Gin 框架)
• 当前架构: DDD 领域驱动设计（不完整）
• 现有域: 用户域、认证域、财务域、管理员域
• 主要问题: HTTP 处理器直接调用域服务，缺乏应用服务层

改造目标

• 完善 DDD 分层架构
• 添加应用服务层
• 重构基础设施层
• 提高代码可维护性和可测试性

🏗️ 目标架构设计

改造后的目录结构

internal/
├── application/                    # 应用服务层 (Application Services Layer)
│   ├── user/
│   │   ├── user_application_service.go
│   │   ├── dto/
│   │   │   ├── commands/
│   │   │   │   ├── register_user_command.go
│   │   │   │   ├── login_user_command.go
│   │   │   │   └── change_password_command.go
│   │   │   ├── queries/
│   │   │   │   └── get_user_profile_query.go
│   │   │   └── responses/
│   │   │       ├── register_user_response.go
│   │   │       ├── login_user_response.go
│   │   │       └── user_profile_response.go
│   │   └── events/
│   │       └── user_application_events.go
│   ├── certification/
│   │   ├── certification_application_service.go
│   │   ├── dto/
│   │   │   ├── commands/
│   │   │   │   ├── create_certification_command.go
│   │   │   │   ├── submit_enterprise_info_command.go
│   │   │   │   ├── upload_license_command.go
│   │   │   │   ├── initiate_face_verify_command.go
│   │   │   │   └── apply_contract_command.go
│   │   │   ├── queries/
│   │   │   │   ├── get_certification_status_query.go
│   │   │   │   └── get_certification_details_query.go
│   │   │   └── responses/
│   │   │       ├── certification_response.go
│   │   │       ├── enterprise_info_response.go
│   │   │       └── upload_license_response.go
│   │   └── events/
│   │       └── certification_application_events.go
│   ├── finance/
│   │   ├── finance_application_service.go
│   │   ├── dto/
│   │   │   ├── commands/
│   │   │   │   ├── create_wallet_command.go
│   │   │   │   ├── recharge_wallet_command.go
│   │   │   │   ├── withdraw_wallet_command.go
│   │   │   │   ├── create_user_secrets_command.go
│   │   │   │   └── regenerate_access_key_command.go
│   │   │   ├── queries/
│   │   │   │   ├── get_wallet_info_query.go
│   │   │   │   └── get_user_secrets_query.go
│   │   │   └── responses/
│   │   │       ├── wallet_response.go
│   │   │       ├── transaction_response.go
│   │   │       └── user_secrets_response.go
│   │   └── events/
│   │       └── finance_application_events.go
│   └── admin/
│       ├── admin_application_service.go
│       ├── dto/
│       │   ├── commands/
│       │   │   ├── admin_login_command.go
│       │   │   ├── create_admin_command.go
│       │   │   ├── update_admin_command.go
│       │   │   └── change_admin_password_command.go
│       │   ├── queries/
│       │   │   ├── get_admin_info_query.go
│       │   │   └── list_admins_query.go
│       │   └── responses/
│       │       ├── admin_login_response.go
│       │       ├── admin_info_response.go
│       │       └── admin_list_response.go
│       └── events/
│           └── admin_application_events.go
├── domains/                        # 领域层 (Domain Layer) - 保持不变
│   ├── user/
│   │   ├── entities/
│   │   ├── services/
│   │   ├── repositories/
│   │   ├── dto/
│   │   └── events/
│   ├── certification/
│   │   ├── entities/
│   │   ├── services/
│   │   ├── repositories/
│   │   ├── dto/
│   │   ├── events/
│   │   └── enums/
│   ├── finance/
│   │   ├── entities/
│   │   ├── services/
│   │   ├── repositories/
│   │   ├── dto/
│   │   └── value_objects/
│   └── admin/
│       ├── entities/
│       ├── services/
│       ├── repositories/
│       └── dto/
├── infrastructure/                 # 基础设施层 (Infrastructure Layer) - 新增
│   ├── http/
│   │   ├── handlers/
│   │   │   ├── user_handler.go           # 从 domains/user/handlers/ 移动
│   │   │   ├── certification_handler.go  # 从 domains/certification/handlers/ 移动
│   │   │   ├── finance_handler.go        # 从 domains/finance/handlers/ 移动
│   │   │   └── admin_handler.go          # 从 domains/admin/handlers/ 移动
│   │   ├── middleware/                    # 从 shared/middleware/ 移动
│   │   │   ├── auth.go
│   │   │   ├── cors.go
│   │   │   ├── ratelimit.go
│   │   │   ├── request_logger.go
│   │   │   └── tracing.go
│   │   └── routes/
│   │       ├── user_routes.go            # 从 domains/user/routes/ 移动
│   │       ├── certification_routes.go   # 从 domains/certification/routes/ 移动
│   │       ├── finance_routes.go         # 从 domains/finance/routes/ 移动
│   │       └── admin_routes.go           # 从 domains/admin/routes/ 移动
│   ├── database/
│   │   ├── repositories/
│   │   │   ├── user/
│   │   │   │   ├── user_repository.go
│   │   │   │   └── sms_code_repository.go
│   │   │   ├── certification/
│   │   │   │   ├── certification_repository.go
│   │   │   │   ├── enterprise_repository.go
│   │   │   │   └── license_upload_repository.go
│   │   │   ├── finance/
│   │   │   │   ├── wallet_repository.go
│   │   │   │   └── user_secrets_repository.go
│   │   │   └── admin/
│   │   │       ├── admin_repository.go
│   │   │       └── admin_login_log_repository.go
│   │   └── migrations/
│   │       ├── user_migrations/
│   │       ├── certification_migrations/
│   │       ├── finance_migrations/
│   │       └── admin_migrations/
│   ├── cache/
│   │   ├── redis_cache.go
│   │   └── memory_cache.go
│   ├── external/
│   │   ├── sms/
│   │   │   └── sms_service.go
│   │   ├── ocr/
│   │   │   └── baidu_ocr_service.go
│   │   ├── storage/
│   │   │   └── qiniu_storage_service.go
│   │   └── notification/
│   │       └── wechat_work_service.go
│   └── config/
│       ├── database_config.go
│       ├── redis_config.go
│       └── external_services_config.go
├── shared/                         # 共享层 (Shared Layer) - 保留核心组件
│   ├── interfaces/
│   │   ├── service.go
│   │   ├── repository.go
│   │   ├── event.go
│   │   └── http.go
│   ├── domain/
│   │   └── entity.go
│   ├── events/
│   │   └── event_bus.go
│   ├── logger/
│   │   └── logger.go
│   ├── metrics/
│   │   ├── business_metrics.go
│   │   └── prometheus_metrics.go
│   ├── resilience/
│   │   ├── circuit_breaker.go
│   │   └── retry.go
│   ├── saga/
│   │   └── saga.go
│   ├── hooks/
│   │   └── hook_system.go
│   └── tracing/
│       ├── tracer.go
│       └── decorators.go
├── config/                         # 配置层 - 保持不变
│   ├── config.go
│   └── loader.go
├── container/                      # 容器层 - 保持不变
│   └── container.go
└── app/                           # 应用层 - 保持不变
    └── app.go

📝 各层职责说明

应用服务层 (Application Layer)

• 职责: 编排业务用例，管理事务边界，协调跨域操作
• 包含: 应用服务、命令对象、查询对象、响应对象、应用事件
• 特点: 无状态，专注于用例编排

领域层 (Domain Layer)

• 职责: 核心业务逻辑，业务规则，领域实体
• 包含: 实体、值对象、域服务、仓储接口、域事件
• 特点: 业务逻辑的核心，与技术实现无关

基础设施层 (Infrastructure Layer)

• 职责: 技术实现细节，外部系统集成
• 包含: HTTP 处理器、数据库仓储、缓存、外部服务
• 特点: 实现领域层定义的接口

共享层 (Shared Layer)

• 职责: 通用工具、接口定义、跨层共享组件
• 包含: 接口定义、事件总线、日志、监控、追踪
• 特点: 被其他层依赖，但不依赖其他层

🎯 改造优先级

第一优先级：用户域

• 原因: 最基础的认证功能，其他域都依赖
• 复杂度: 中等
• 影响范围: 全局

第二优先级：认证域

• 原因: 核心业务流程，涉及多个实体协调
• 复杂度: 高
• 影响范围: 用户域、管理员域

第三优先级：财务域

• 原因: 涉及资金安全，需要事务管理
• 复杂度: 高
• 影响范围: 用户域

第四优先级：管理员域

• 原因: 后台管理功能，相对独立
• 复杂度: 低
• 影响范围: 其他域

📋 实施计划

阶段一：基础架构搭建 (1-2 天)

1. 创建新的目录结构
2. 移动现有组件到基础设施层
3. 更新依赖注入配置
4. 确保项目能正常启动

阶段二：用户域改造 (2-3 天)

1. 实现用户应用服务
2. 重构用户 HTTP 处理器
3. 测试用户相关功能
4. 完善错误处理

阶段三：认证域改造 (3-4 天)

1. 实现认证应用服务
2. 重构认证 HTTP 处理器
3. 处理跨域协调逻辑
4. 测试认证流程

阶段四：财务域改造 (2-3 天)

1. 实现财务应用服务
2. 重构财务 HTTP 处理器
3. 添加事务管理
4. 测试财务功能

阶段五：管理员域改造 (1-2 天)

1. 实现管理员应用服务
2. 重构管理员 HTTP 处理器
3. 测试管理功能

阶段六：整体优化 (2-3 天)

1. 添加应用事件处理
2. 完善监控和日志
3. 性能优化
4. 文档更新

⚠️ 注意事项

备份策略

• 每个阶段开始前备份当前代码
• 使用 Git 分支进行改造
• 保留原始代码作为参考

测试策略

• 每个域改造完成后进行单元测试
• 保持 API 接口兼容性
• 进行集成测试验证

回滚策略

• 如果改造出现问题，可以快速回滚到上一个稳定版本
• 保持数据库结构不变
• 确保配置文件的兼容性

📊 预期收益

架构改进

• ✅ 职责分离更清晰
• ✅ 代码组织更规范
• ✅ 可维护性更强

开发效率

• ✅ 可测试性更好
• ✅ 扩展性更强
• ✅ 复用性更高

业务价值

• ✅ 业务逻辑更清晰
• ✅ 跨域协调更简单
• ✅ 事务管理更可靠