telegram-management-system/frontend/SENTRY_INTEGRATION.md

# Sentry 错误监控集成指南

## 概述

本项目已集成 Sentry 错误监控系统，用于实时监控和追踪 Telegram 管理系统的错误、性能和用户行为。

## 功能特性

### 1. 自动错误捕获
- Vue 应用全局错误处理
- API 请求错误监控
- WebSocket 连接错误追踪
- UI 组件错误记录

### 2. 性能监控
- API 请求响应时间
- 页面加载性能
- 用户交互延迟
- 会话重播（Session Replay）

### 3. 用户行为追踪
- 页面访问记录
- 用户操作行为
- 任务操作监控
- 搜索和筛选行为

### 4. Telegram 专用监控
- 任务创建和执行状态
- 消息发送成功率
- 目标用户添加监控
- 引擎状态变化追踪

## 配置说明

### 环境变量配置

#### 开发环境 (`.env.development`)
```bash
VUE_APP_SENTRY_DSN=your_development_dsn
VUE_APP_SENTRY_ENVIRONMENT=development
VUE_APP_SENTRY_DEBUG=true
```

#### 生产环境 (`.env.production`)
```bash
VUE_APP_SENTRY_DSN=your_production_dsn
VUE_APP_SENTRY_ENVIRONMENT=production
VUE_APP_SENTRY_DEBUG=false
```

### 采样率配置

- **开发环境**: 100% 错误采样，100% 性能监控
- **生产环境**: 80% 错误采样，10% 性能监控，10% 会话重播

## 使用方法

### 1. 在组件中手动发送错误

```javascript
// 导入工具函数
import { sentryUtils, ERROR_TYPES } from '@/config/sentry'

// 发送自定义错误
this.$sentryUtils.captureError(
  new Error('自定义错误消息'),
  ERROR_TYPES.VALIDATION_ERROR,
  { 
    component: 'MyComponent',
    userInput: formData 
  }
)

// 记录用户行为
this.$sentryUtils.captureUserAction('button_clicked', {
  buttonName: 'submit',
  formType: 'task_creation'
})
```

### 2. Telegram 专用监控

```javascript
import telegramSentry, { TASK_STATUSES } from '@/libs/sentryTelegram'

// 监控任务创建
telegramSentry.trackTaskCreation(taskData, result)

// 监控任务执行状态
telegramSentry.trackTaskExecution(taskId, TASK_STATUSES.RUNNING, metrics)

// 监控消息发送
telegramSentry.trackMessageSend(taskId, targetId, success, error)

// 监控 Telegram API 错误
telegramSentry.trackTelegramApiError('sendMessage', error, context)
```

### 3. 设置用户上下文

```javascript
// 在组件 mounted 中设置用户信息
mounted() {
  this.$sentryUtils.setUser({
    id: this.$store.state.user.id,
    username: this.$store.state.user.name,
    email: this.$store.state.user.email
  })
}
```

## 错误类型

### 通用错误类型
- `api_error`: API 请求错误
- `validation_error`: 数据验证错误
- `network_error`: 网络连接错误
- `ui_error`: 用户界面错误
- `websocket_error`: WebSocket 连接错误

### Telegram 专用错误类型
- `task_creation_failed`: 任务创建失败
- `target_addition_failed`: 目标用户添加失败
- `message_send_failed`: 消息发送失败
- `telegram_auth_failed`: Telegram 认证失败
- `rate_limit_exceeded`: 频率限制超出
- `invalid_username`: 无效用户名
- `chat_not_found`: 聊天不存在

## 数据隐私

### 自动过滤的敏感信息
- 密码和认证令牌
- 个人身份信息 (PII)
- API 密钥和密钥

### 发送的上下文信息
- 用户 ID 和用户名（非敏感）
- 错误发生的页面和组件
- API 请求的 URL 和方法
- 任务和操作的元数据

## 监控仪表板

### Sentry 仪表板功能
1. **错误追踪**: 实时错误监控和告警
2. **性能分析**: API 和页面性能指标
3. **用户会话**: 用户行为和操作回放
4. **发布追踪**: 代码发布和错误关联

### 关键指标
- 错误率和错误趋势
- API 响应时间分布
- 用户活跃度和操作频率
- 任务成功率和失败原因

## 最佳实践

### 1. 错误处理
```javascript
try {
  await riskyOperation()
} catch (error) {
  // 记录错误并提供上下文
  this.$sentryUtils.captureError(error, ERROR_TYPES.API_ERROR, {
    operation: 'riskyOperation',
    userId: this.currentUserId,
    timestamp: new Date().toISOString()
  })
  
  // 用户友好的错误提示
  this.$Message.error('操作失败，请稍后重试')
}
```

### 2. 性能监控
```javascript
// 监控长时间运行的操作
const startTime = Date.now()
await heavyOperation()
const duration = Date.now() - startTime

if (duration > 3000) {
  this.$sentryUtils.captureMessage('slow_operation', {
    operation: 'heavyOperation',
    duration: duration
  })
}
```

### 3. 用户体验追踪
```javascript
// 记录用户关键操作
onTaskCreate() {
  this.$sentryUtils.captureUserAction('task_create_started')
  // ... 任务创建逻辑
}
```

## 故障排除

### 常见问题

1. **Sentry 事件未发送**
   - 检查 DSN 配置是否正确
   - 确认网络连接正常
   - 查看浏览器控制台错误

2. **采样率过低**
   - 调整环境变量中的采样率设置
   - 开发环境建议设置为 100%

3. **敏感信息泄露**
   - 检查 beforeSend 过滤规则
   - 避免在错误上下文中包含敏感数据

### 调试模式

开发环境启用调试模式：
```javascript
// 在 .env.development 中设置
VUE_APP_SENTRY_DEBUG=true
```

## 更新和维护

### 定期检查
- 每月检查错误趋势和新增错误类型
- 定期清理过期的任务指标数据
- 更新错误过滤规则

### 配置优化
- 根据实际使用情况调整采样率
- 优化错误分组和标签系统
- 完善用户上下文信息

## 技术支持

如有技术问题或需要配置支持，请联系开发团队或查看 Sentry 官方文档。