# 发票事件系统调试指南

## 🔍 调试概述

本指南帮助您调试发票邮箱发送的领域事件系统。

## 📋 事件流程

### 1. 事件发布流程
```
发票申请通过 → 聚合服务 → 事件发布器 → 事件总线 → 事件处理器 → 邮件服务
```

### 2. 关键组件
- **InvoiceAggregateService**: 发票聚合服务，负责发布事件
- **InvoiceEventPublisher**: 事件发布器，将事件发送到事件总线
- **MemoryEventBus**: 内存事件总线，管理事件队列和工作协程
- **InvoiceEventHandler**: 事件处理器，处理发票相关事件并发送邮件
- **QQEmailService**: QQ邮件服务，发送发票邮件

## 🚀 调试步骤

### 步骤1: 启动服务器
```bash
cd tyapi-server-gin
go run cmd/api/main.go
```

### 步骤2: 观察启动日志
启动时应该看到以下日志：
```
👷 事件工作协程启动 worker_id=0
👷 事件工作协程启动 worker_id=1
...
发票事件处理器注册成功 event_type=InvoiceFileUploaded handler=invoice-event-handler
所有事件处理器已注册
```

### 步骤3: 测试事件系统
使用调试脚本测试：
```bash
go run debug_event_test.go
```

### 步骤4: 观察事件处理日志
应该看到以下日志序列：
```
📤 开始发布发票文件上传事件
🚀 准备发布事件到事件总线
📤 开始发布事件
📋 找到事件处理器
🔄 处理事件
✅ 事件已加入异步队列
📥 工作协程接收到事件任务
🔧 开始处理事件任务
🔄 开始处理发票事件
📎 处理发票文件上传事件
📎 发票文件已上传事件开始处理
📋 事件数据解析开始
📄 事件数据序列化成功
✅ 事件数据解析成功
📧 开始发送发票邮件
📋 邮件数据构建完成
🚀 开始调用邮件服务发送邮件
✅ 发票邮件发送成功
```

## 🔧 常见问题排查

### 问题1: 事件处理器未注册
**症状**: 日志显示"没有找到事件处理器"
**排查**:
1. 检查容器配置中的事件处理器注册
2. 确认事件总线已启动
3. 检查事件类型名称是否匹配

### 问题2: 事件数据解析失败
**症状**: 日志显示"解析发票文件上传事件失败"
**排查**:
1. 检查事件结构体定义
2. 确认事件数据序列化正确
3. 验证事件字段类型匹配

### 问题3: 邮件发送失败
**症状**: 日志显示"发送发票邮件失败"
**排查**:
1. 检查QQ邮箱配置
2. 确认网络连接正常
3. 验证邮箱授权码正确

### 问题4: 事件队列已满
**症状**: 日志显示"事件队列已满，丢弃事件"
**排查**:
1. 增加事件队列容量
2. 增加工作协程数量
3. 检查是否有长时间阻塞的事件处理

## 📊 监控指标

### 事件总线统计
可以通过以下方式获取事件总线状态：
```go
stats := eventBus.GetStats()
// 包含: running, worker_count, queue_length, queue_capacity, event_types, subscribers
```

### 关键日志标识
- 🔄 事件处理开始
- 📤 事件发布
- 📥 事件接收
- ✅ 成功处理
- ❌ 处理失败
- ⚠️ 警告信息

## 🛠️ 调试工具

### 1. 调试端点
访问 `GET /api/v1/debug/events` 获取事件系统状态

### 2. 日志级别
确保日志级别设置为 INFO 或 DEBUG 以查看详细日志

### 3. 测试脚本
使用 `debug_event_test.go` 模拟完整的发票申请流程

## 📝 日志分析

### 成功流程日志示例
```
2024/01/15 10:30:00 INFO 📤 开始发布发票文件上传事件 invoice_id=xxx
2024/01/15 10:30:00 INFO 🚀 准备发布事件到事件总线 event_type=InvoiceFileUploaded
2024/01/15 10:30:00 INFO 📤 开始发布事件 event_type=InvoiceFileUploaded
2024/01/15 10:30:00 INFO 📋 找到事件处理器 handler_count=1
2024/01/15 10:30:00 INFO ✅ 事件已加入异步队列
2024/01/15 10:30:01 INFO 📥 工作协程接收到事件任务
2024/01/15 10:30:01 INFO 🔄 开始处理发票事件
2024/01/15 10:30:01 INFO 📧 开始发送发票邮件
2024/01/15 10:30:02 INFO ✅ 发票邮件发送成功
```

### 失败流程日志示例
```
2024/01/15 10:30:00 INFO 📤 开始发布发票文件上传事件
2024/01/15 10:30:00 ERROR ❌ 发布发票文件上传事件到事件总线失败
2024/01/15 10:30:00 ERROR ❌ 事件数据为空
2024/01/15 10:30:00 ERROR ❌ 发送发票邮件失败
```

## 🎯 优化建议

1. **增加监控**: 添加事件处理时间、成功率等指标
2. **错误重试**: 配置合理的重试策略
3. **日志聚合**: 使用ELK等工具聚合和分析日志
4. **性能调优**: 根据负载调整工作协程数量和队列大小