v1.0.0

事件系统调试指南.md

@@ -0,0 +1,154 @@
+# 发票事件系统调试指南
+
+## 🔍 调试概述
+
+本指南帮助您调试发票邮箱发送的领域事件系统。
+
+## 📋 事件流程
+
+### 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. **性能调优**: 根据负载调整工作协程数量和队列大小