tyapi-server/TODO_INVOICE_INTEGRATION.md

# 发票功能外部服务集成 TODO

## 1. 短信服务集成

### 位置
- `tyapi-server-gin/internal/domains/finance/services/invoice_aggregate_service_impl.go`
- `tyapi-server-gin/internal/domains/finance/events/invoice_events.go`

### 需要实现的功能
- [ ] 发票申请创建时发送短信通知管理员
- [ ] 配置管理员手机号
- [ ] 短信内容模板

### 示例代码
```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`

### 需要实现的功能
- [ ] 发票文件上传后发送邮件给用户
- [ ] 发票申请被拒绝时发送邮件通知用户
- [ ] 邮件模板设计

### 示例代码
```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
- [ ] 文件存储配置

### 示例代码
```go
// 在 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` - 聚合服务（接口+实现）

### 需要实现的功能
- [ ] 事件发布器实现
- [ ] 事件处理器实现
- [ ] 事件订阅配置

### 示例代码
```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接口实现

### 已完成的文件
- [x] `tyapi-server-gin/internal/infrastructure/http/handlers/invoice_handler.go` - 用户发票处理器
- [x] `tyapi-server-gin/internal/infrastructure/http/handlers/admin_invoice_handler.go` - 管理员发票处理器
- [x] `tyapi-server-gin/internal/infrastructure/http/routes/invoice_routes.go` - 发票路由配置
- [x] `tyapi-server-gin/docs/发票API接口文档.md` - API接口文档

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

### 管理员接口
- [x] 获取待处理申请列表 `GET /api/v1/admin/invoices/pending`
- [x] 通过发票申请 `POST /api/v1/admin/invoices/{application_id}/approve`
- [x] 拒绝发票申请 `POST /api/v1/admin/invoices/{application_id}/reject`

## 8. 依赖注入配置

### 已完成的文件
- [x] `tyapi-server-gin/internal/infrastructure/http/handlers/finance_handler.go` - 合并发票相关handler方法
- [x] `tyapi-server-gin/internal/infrastructure/http/routes/finance_routes.go` - 合并发票相关路由
- [x] 删除多余文件：`invoice_handler.go`、`admin_invoice_handler.go`、`invoice_routes.go`

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

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

## 8. 前端页面

### 需要创建的前端页面
- [ ] 发票申请页面
- [ ] 发票信息编辑页面
- [ ] 发票记录列表页面
- [ ] 管理员发票申请处理页面

## 优先级

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

## 注意事项

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