team/tyapi-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
34ff6ce916b76795f9442eb014c85747f3371f9e
tyapi-server/TODO_INVOICE_INTEGRATION.md
liangzai 66845d3fe0 v1.0.0
2025-08-02 02:54:21 +08:00

7.5 KiB
Raw Blame History

发票功能外部服务集成 TODO

1. 短信服务集成

位置

  • tyapi-server-gin/internal/domains/finance/services/invoice_aggregate_service_impl.go
  • tyapi-server-gin/internal/domains/finance/events/invoice_events.go

需要实现的功能

  • 发票申请创建时发送短信通知管理员
  • 配置管理员手机号
  • 短信内容模板

示例代码

// 在 InvoiceAggregateServiceImpl 中注入短信服务
type InvoiceAggregateServiceImpl struct {
    // ... 其他依赖
    smsService SMSService
}

// 在事件处理器中发送短信
func (s *InvoiceEventHandler) HandleInvoiceApplicationCreated(ctx context.Context, event *events.InvoiceApplicationCreatedEvent) error {
    // TODO: 发送短信通知管理员
    // message := fmt.Sprintf("新的发票申请：用户%s申请开票%.2f元", event.UserID, event.Amount)
    // return s.smsService.SendSMS(ctx, adminPhone, message)
    return nil
}

2. 邮件服务集成

位置

  • tyapi-server-gin/internal/domains/finance/services/invoice_aggregate_service_impl.go
  • tyapi-server-gin/internal/domains/finance/events/invoice_events.go

需要实现的功能

  • 发票文件上传后发送邮件给用户
  • 发票申请被拒绝时发送邮件通知用户
  • 邮件模板设计

示例代码

// 在 SendInvoiceToEmail 方法中
func (s *InvoiceAggregateServiceImpl) SendInvoiceToEmail(ctx context.Context, invoiceID string) error {
    // ... 获取发票信息
    
    // TODO: 调用邮件服务发送发票
    // emailData := &EmailData{
    //     To:      invoice.ReceivingEmail,
    //     Subject: "您的发票已开具",
    //     Template: "invoice_issued",
    //     Data: map[string]interface{}{
    //         "CompanyName": invoice.CompanyName,
    //         "Amount":      invoice.Amount,
    //         "FileURL":     invoice.FileURL,
    //     },
    // }
    // return s.emailService.SendEmail(ctx, emailData)
    
    return nil
}

3. 文件存储服务集成

位置

  • tyapi-server-gin/internal/domains/finance/services/invoice_aggregate_service_impl.go

需要实现的功能

  • 上传发票PDF文件
  • 生成文件访问URL
  • 文件存储配置

示例代码

// 在 UploadInvoiceFile 方法中
func (s *InvoiceAggregateServiceImpl) UploadInvoiceFile(ctx context.Context, invoiceID string, file multipart.File) error {
    // ... 获取发票信息
    
    // TODO: 调用文件存储服务上传文件
    // uploadResult, err := s.fileStorageService.UploadFile(ctx, &UploadRequest{
    //     File:     file,
    //     Path:     fmt.Sprintf("invoices/%s", invoiceID),
    //     Filename: fmt.Sprintf("invoice_%s.pdf", invoiceID),
    // })
    // if err != nil {
    //     return fmt.Errorf("上传文件失败: %w", err)
    // }
    
    // invoice.SetFileInfo(uploadResult.FileID, uploadResult.FileName, uploadResult.FileURL, uploadResult.FileSize)
    
    return nil
}

4. 事件处理器实现

需要创建的文件

  • tyapi-server-gin/internal/domains/finance/events/invoice_event_handler.go
  • tyapi-server-gin/internal/domains/finance/events/invoice_event_publisher.go

服务文件结构

  • tyapi-server-gin/internal/domains/finance/services/invoice_domain_service.go - 领域服务（接口+实现）
  • tyapi-server-gin/internal/domains/finance/services/invoice_aggregate_service.go - 聚合服务（接口+实现）

需要实现的功能

  • 事件发布器实现
  • 事件处理器实现
  • 事件订阅配置

示例代码

// 事件发布器实现
type InvoiceEventPublisherImpl struct {
    // 可以使用消息队列、Redis发布订阅等
}

// 事件处理器实现
type InvoiceEventHandlerImpl struct {
    smsService  SMSService
    emailService EmailService
}

func (h *InvoiceEventHandlerImpl) HandleInvoiceApplicationCreated(ctx context.Context, event *events.InvoiceApplicationCreatedEvent) error {
    // 发送短信通知管理员
    return h.smsService.SendSMS(ctx, adminPhone, "新的发票申请")
}

func (h *InvoiceEventHandlerImpl) HandleInvoiceFileUploaded(ctx context.Context, event *events.InvoiceFileUploadedEvent) error {
    // 发送邮件给用户
    return h.emailService.SendInvoiceEmail(ctx, event.ReceivingEmail, event.FileURL, event.FileName)
}

5. 数据库迁移

需要创建的表

  • invoice_applications - 发票申请表（包含文件信息）

迁移文件位置

  • tyapi-server-gin/migrations/

6. 仓储实现

需要实现的文件

  • tyapi-server-gin/internal/infrastructure/database/repositories/invoice_application_repository_impl.go

7. HTTP接口实现

已完成的文件

  • tyapi-server-gin/internal/infrastructure/http/handlers/invoice_handler.go - 用户发票处理器
  • tyapi-server-gin/internal/infrastructure/http/handlers/admin_invoice_handler.go - 管理员发票处理器
  • tyapi-server-gin/internal/infrastructure/http/routes/invoice_routes.go - 发票路由配置
  • tyapi-server-gin/docs/发票API接口文档.md - API接口文档

用户接口

  • 申请开票 POST /api/v1/invoices/apply
  • 获取用户发票信息 GET /api/v1/invoices/info
  • 更新用户发票信息 PUT /api/v1/invoices/info
  • 获取用户开票记录 GET /api/v1/invoices/records
  • 获取可开票金额 GET /api/v1/invoices/available-amount
  • 下载发票文件 GET /api/v1/invoices/{application_id}/download

管理员接口

  • 获取待处理申请列表 GET /api/v1/admin/invoices/pending
  • 通过发票申请 POST /api/v1/admin/invoices/{application_id}/approve
  • 拒绝发票申请 POST /api/v1/admin/invoices/{application_id}/reject

8. 依赖注入配置

已完成的文件

  • tyapi-server-gin/internal/infrastructure/http/handlers/finance_handler.go - 合并发票相关handler方法
  • tyapi-server-gin/internal/infrastructure/http/routes/finance_routes.go - 合并发票相关路由
  • 删除多余文件：invoice_handler.go、admin_invoice_handler.go、invoice_routes.go

已完成的文件

  • tyapi-server-gin/internal/infrastructure/database/repositories/finance/invoice_application_repository_impl.go - 实现发票申请仓储
  • tyapi-server-gin/internal/application/finance/invoice_application_service.go - 实现发票应用服务（合并用户端和管理员端）
  • tyapi-server-gin/internal/container/container.go - 添加发票相关服务的依赖注入

已完成的工作

  • 删除 tyapi-server-gin/internal/application/finance/admin_invoice_application_service.go - 已合并到主服务文件
  • 修复 tyapi-server-gin/internal/application/finance/invoice_application_service.go - 所有编译错误已修复
  • 使用 *storage.QiNiuStorageService 替换 interfaces.StorageService
  • 更新仓储接口以包含所有必要的方法
  • 修复DTO字段映射和类型转换
  • 修复聚合服务调用参数

8. 前端页面

需要创建的前端页面

  • 发票申请页面
  • 发票信息编辑页面
  • 发票记录列表页面
  • 管理员发票申请处理页面

优先级

  1. 高优先级: 数据库迁移、仓储实现、依赖注入配置
  2. 中优先级: 事件处理器实现、基础API接口
  3. 低优先级: 外部服务集成（短信、邮件、文件存储）

注意事项

  • 所有外部服务调用都应该有适当的错误处理和重试机制
  • 事件发布失败不应该影响主业务流程
  • 文件上传需要验证文件类型和大小
  • 邮件发送需要支持模板和国际化