mirror of
https://github.com/wwiinnddyy/LanMountainDesktop.git
synced 2026-06-20 23:54:26 +08:00
326 lines
11 KiB
Markdown
326 lines
11 KiB
Markdown
# Git Commit Analysis Report
|
||
|
||
## Commit Information
|
||
|
||
| Field | Value |
|
||
|-------|-------|
|
||
| **Commit Hash** | `ce41fd676cd5464f34cd5c8687bbbe73ca1c562b` |
|
||
| **Author** | lincube <lincube3@hotmail.com> |
|
||
| **Author Date** | 2026-05-27 09:41:18 +0800 |
|
||
| **Commit Date** | 2026-05-27 09:41:18 +0800 |
|
||
| **Commit Message** | changed.调整了遥测系统。 |
|
||
|
||
## Change Statistics
|
||
|
||
| Metric | Value |
|
||
|--------|-------|
|
||
| **Files Modified** | 8 |
|
||
| **Files Added** | 1 |
|
||
| **Files Deleted** | 0 |
|
||
| **Total Insertions** | +962 |
|
||
| **Total Deletions** | -61 |
|
||
| **Net Change** | +901 |
|
||
|
||
## Commit Message Summary
|
||
|
||
本次提交是对遥测系统的重大调整和重构，主要包括：
|
||
- 新增统一的遥测事件命名规范（`TelemetryEventNames.cs`）
|
||
- 重构 Sentry 崩溃报告服务（优化 Tags/Extras 分离、改进中文标签）
|
||
- 重构 PostHog 使用追踪服务（修复 distinct_id 一致性、增强 Session 生命周期管理）
|
||
- 新增遥测环境信息增强类
|
||
- 添加详细的遥测系统规范化设计文档
|
||
|
||
## Detailed Change Analysis
|
||
|
||
### 1. LanMountainDesktop/App.axaml.cs
|
||
|
||
**Change Type:** Modified
|
||
**Lines Changed:** +1, -0
|
||
|
||
**变更说明:** 在应用启动入口添加遥测追踪初始化调用，确保应用级别的 Session 生命周期正确管理。
|
||
|
||
### 2. LanMountainDesktop/Models/DesktopComponentPlacementSnapshot.cs
|
||
|
||
**Change Type:** Modified
|
||
**Lines Changed:** +2, -2
|
||
|
||
**变更说明:** 为桌面组件快照模型添加 `ComponentName` 属性，便于遥测事件中记录组件的可读名称，便于后续分析和调试。
|
||
|
||
### 3. LanMountainDesktop/Services/PostHogUsageTelemetryService.cs ⭐
|
||
|
||
**Change Type:** Modified
|
||
**Lines Changed:** +37, -42
|
||
|
||
**变更说明:** 这是本次提交的核心改动之一，主要优化包括：
|
||
|
||
#### 3.1 distinct_id 统一
|
||
- **修复前:** 使用 `InstallId` 作为 `distinct_id`
|
||
- **修复后:** 统一使用 `TelemetryId` 作为 `distinct_id`
|
||
- **影响:** 确保 PostHog 中的用户身份追踪一致性
|
||
|
||
#### 3.2 Session 生命周期增强
|
||
- 优化了 `StartSession` 和 `EndSession` 方法
|
||
- 添加了 `TrackSessionStarted` 和 `TrackSessionEnded` 追踪
|
||
- 与 MainWindow 和 App 层生命周期正确关联
|
||
|
||
#### 3.3 事件属性优化
|
||
- 移除了每个事件中重复的环境信息字段
|
||
- 添加了 `event_display_name` 属性（中文显示名）
|
||
- 移除了 `payload_` 前缀，使事件属性更简洁
|
||
- 使用统一的 `TelemetryEventNames` 常量
|
||
|
||
#### 3.4 Flush 策略优化
|
||
- **修复前:** 每个事件都执行 `forceFlush`
|
||
- **修复后:** 仅在关键事件（session、first_launch）执行 `forceFlush`
|
||
- **影响:** 降低性能开销，提升事件批处理效率
|
||
|
||
#### 3.5 DescribePlacement 增强
|
||
- 添加了 `component_name` 字段到组件位置快照描述
|
||
- 便于在遥测数据中识别具体组件
|
||
|
||
### 4. LanMountainDesktop/Services/SentryCrashTelemetryService.cs ⭐
|
||
|
||
**Change Type:** Modified
|
||
**Lines Changed:** +10, -16
|
||
|
||
**变更说明:** 重构崩溃报告服务，优化遥测上下文管理：
|
||
|
||
#### 4.1 SendDefaultPii 安全设置
|
||
- **修复前:** `options.SendDefaultPii = true`
|
||
- **修复后:** `options.SendDefaultPii = false`
|
||
- **影响:** 提升用户隐私保护，避免发送敏感个人信息
|
||
|
||
#### 4.2 Tags/Extras 职责分离
|
||
- **Tags:** 仅保留用于过滤和索引的核心字段（6 个）
|
||
- telemetry_channel, event_type, event_display_name, source, app_version, environment, os_name, os_version, language
|
||
- **Extras:** 保留所有详细上下文信息用于调试分析
|
||
- install_id, telemetry_id, 设备信息, 运行时信息, 日志文件路径等
|
||
|
||
#### 4.3 中文标签支持
|
||
- 新增 `event_display_name` Tag，提供事件的中文显示名
|
||
- 改善 Sentry Dashboard 的可读性
|
||
|
||
#### 4.4 事件命名规范化
|
||
- 使用 `TelemetryEventNames` 常量替代硬编码字符串
|
||
- 确保 Sentry 和 PostHog 使用统一的事件命名
|
||
|
||
### 5. LanMountainDesktop/Services/TelemetryEnvironmentInfo.cs ⭐
|
||
|
||
**Change Type:** Modified
|
||
**Lines Changed:** +31, -1
|
||
|
||
**变更说明:** 新增和增强了遥测环境信息收集功能：
|
||
|
||
#### 5.1 新增方法
|
||
- `GetDeviceModel()`: 获取设备型号
|
||
- `GetDeviceArchitecture()`: 获取设备架构
|
||
- `GetTotalMemoryMB()`: 获取总内存（MB）
|
||
- `GetLocalDayPart(DateTimeOffset)`: 根据时间段返回日夜标识
|
||
- `GetRenderMode()`: 获取渲染模式（DirectX/OpenGL/Software）
|
||
|
||
#### 5.2 现有方法增强
|
||
- 优化了 `GetOsVersion()` 返回格式
|
||
- 改进了语言信息的收集
|
||
|
||
### 6. LanMountainDesktop/Services/TelemetryEventNames.cs ✨
|
||
|
||
**Change Type:** Added
|
||
**Lines Changed:** +69, -0
|
||
|
||
**变更说明:** 全新的统一遥测事件命名规范类，包含：
|
||
|
||
#### 6.1 Sentry 事件命名
|
||
- `SentryUnhandledException`: 未处理的异常
|
||
- `SentryTaskException`: 任务异常
|
||
- `SentryShutdown`: 应用关闭
|
||
|
||
#### 6.2 PostHog 事件命名
|
||
- `AppFirstLaunch`: 应用首次启动
|
||
- `AppSessionStart`: 应用会话开始
|
||
- `AppSessionEnd`: 应用会话结束
|
||
- `MainWindowOpened`: 主窗口打开
|
||
- `MainWindowClosed`: 主窗口关闭
|
||
- `SettingsWindowOpened`: 设置窗口打开
|
||
- `SettingsWindowClosed`: 设置窗口关闭
|
||
- `SettingsNavigation`: 设置导航
|
||
- `SettingsDrawerOpened`: 设置抽屉打开
|
||
- `SettingsDrawerClosed`: 设置抽屉关闭
|
||
- `DesktopComponentPlaced`: 组件放置
|
||
- `DesktopComponentMoved`: 组件移动
|
||
- `DesktopComponentResized`: 组件调整大小
|
||
- `DesktopComponentDeleted`: 组件删除
|
||
- `DesktopComponentEditorOpened`: 组件编辑器打开
|
||
|
||
#### 6.3 辅助方法
|
||
- `DisplayName(string eventName)`: 返回事件的中文显示名
|
||
|
||
### 7. LanMountainDesktop/Views/MainWindow.ComponentSystem.cs
|
||
|
||
**Change Type:** Modified
|
||
**Lines Changed:** +1, -0
|
||
|
||
**变更说明:** 在组件系统初始化中添加 `TrackSessionStarted` 调用，确保组件级别的遥测追踪。
|
||
|
||
### 8. LanMountainDesktop/Views/MainWindow.axaml.cs
|
||
|
||
**Change Type:** Modified
|
||
**Lines Changed:** +1, -0
|
||
|
||
**变更说明:** 在主窗口打开事件中添加 `TrackSessionStarted` 调用，完善 Session 生命周期追踪。
|
||
|
||
### 9. docs/superpowers/plans/2026-05-26-telemetry-normalization.md ✨
|
||
|
||
**Change Type:** Added
|
||
**Lines Changed:** +810, -0
|
||
|
||
**变更说明:** 新增详尽的遥测系统规范化设计文档，包含：
|
||
- 遥测系统架构设计
|
||
- PostHog 和 Sentry 的职责划分
|
||
- 统一的事件命名规范
|
||
- 具体的代码修改指南
|
||
- 实施任务清单
|
||
|
||
## Code Review Points
|
||
|
||
### 1. 遥测系统架构重构 ✅
|
||
|
||
**状态:** 通过
|
||
**说明:** 本次重构遵循了良好的软件设计原则，实现了关注点分离：
|
||
- **PostHog**: 负责使用追踪和行为分析
|
||
- **Sentry**: 负责崩溃报告和错误追踪
|
||
- **统一的事件命名**: 通过 `TelemetryEventNames` 避免硬编码
|
||
|
||
### 2. 用户隐私保护 ✅
|
||
|
||
**状态:** 优秀
|
||
**改进:**
|
||
- 禁用 `SendDefaultPii` 避免发送敏感个人信息
|
||
- 统一使用匿名的 `TelemetryId` 而非可识别的 `InstallId` 作为用户标识
|
||
- 在 Sentry 中移除 `IpAddress` 收集
|
||
|
||
### 3. 性能优化 ✅
|
||
|
||
**状态:** 通过
|
||
**改进:**
|
||
- PostHog 事件移除重复的环境信息，减少网络开销
|
||
- Flush 策略优化，仅关键事件立即刷新
|
||
- 合理使用 `forceFlush` 平衡实时性和性能
|
||
|
||
### 4. 可维护性 ✅
|
||
|
||
**状态:** 优秀
|
||
**改进:**
|
||
- 使用常量替代硬编码字符串，便于后续维护和扩展
|
||
- 完善的文档和设计规范
|
||
- 清晰的事件命名规范
|
||
|
||
### 5. Session 生命周期管理 ⚠️
|
||
|
||
**状态:** 需验证
|
||
**关注点:**
|
||
- Session 开始和结束的时机需要与实际应用生命周期完全匹配
|
||
- 需要在多种退出场景（正常关闭、崩溃、异常）下验证 Session 追踪的完整性
|
||
- 建议进行压力测试和长时间运行测试
|
||
|
||
**建议验证清单:**
|
||
- [ ] 正常关闭应用时 Session 是否正确结束
|
||
- [ ] 崩溃时 Session 是否能正确记录
|
||
- [ ] 异常退出后重启时 Session 标识是否正确
|
||
- [ ] 快速重启场景下 Session 追踪是否正确
|
||
|
||
### 6. 事件命名一致性 ⚠️
|
||
|
||
**状态:** 需验证
|
||
**关注点:**
|
||
- 确保 Sentry 和 PostHog 中的事件命名完全一致
|
||
- 验证 `DisplayName` 方法覆盖所有事件类型
|
||
- 建议在文档中维护事件清单
|
||
|
||
### 7. 向后兼容性 ✅
|
||
|
||
**状态:** 通过
|
||
**说明:** 本次改动主要是对内部实现的优化，未改变外部 API 接口，对插件开发者透明。
|
||
|
||
## Impact Assessment
|
||
|
||
### 风险等级: 🟢 低
|
||
|
||
**原因:**
|
||
- 重构主要在内部实现层面，不影响外部 API
|
||
- 遵循最佳实践，提升了系统可维护性
|
||
- 增强了用户隐私保护
|
||
- 包含详尽的测试指南
|
||
|
||
**建议操作:**
|
||
1. ✅ 执行完整的构建测试
|
||
2. ✅ 运行测试套件验证无回归
|
||
3. ⚠️ 进行 Session 生命周期的集成测试
|
||
4. ⚠️ 验证遥测数据上报的完整性
|
||
5. ⚠️ 检查 Sentry Dashboard 中的事件命名
|
||
6. ⚠️ 检查 PostHog 中的用户追踪一致性
|
||
|
||
## Related Documentation
|
||
|
||
- [2026-05-26-telemetry-normalization.md](file:///d:/github/LanMountainDesktop/docs/superpowers/plans/2026-05-26-telemetry-normalization.md) - 遥测系统规范化设计文档
|
||
- [ARCHITECTURE.md](file:///d:/github/LanMountainDesktop/docs/ARCHITECTURE.md) - 架构文档
|
||
- [DEVELOPMENT.md](file:///d:/github/LanMountainDesktop/docs/DEVELOPMENT.md) - 开发环境指南
|
||
- [PRIVACY.md](file:///d:/github/LanMountainDesktop/docs/PRIVACY.md) - 隐私政策（建议更新）
|
||
|
||
## Testing Recommendations
|
||
|
||
### 1. 基础功能测试
|
||
|
||
```bash
|
||
# 构建验证
|
||
dotnet build LanMountainDesktop.slnx -c Debug
|
||
|
||
# 运行测试
|
||
dotnet test LanMountainDesktop.slnx -c Debug
|
||
```
|
||
|
||
### 2. 遥测功能测试
|
||
|
||
#### 2.1 PostHog 测试场景
|
||
- [ ] 应用首次启动事件是否正确上报
|
||
- [ ] Session 开始/结束事件是否正确
|
||
- [ ] 组件操作事件是否携带完整信息
|
||
- [ ] distinct_id 是否一致
|
||
|
||
#### 2.2 Sentry 测试场景
|
||
- [ ] 触发未处理异常，检查 Sentry 是否收到
|
||
- [ ] 验证 Tags 中的 event_display_name 是否为中文
|
||
- [ ] 检查是否正确禁用 PII 收集
|
||
- [ ] 验证 log tail 是否正确附加
|
||
|
||
#### 2.3 Session 生命周期测试
|
||
- [ ] 正常关闭应用
|
||
- [ ] 通过任务管理器强制结束
|
||
- [ ] 触发崩溃（可使用测试异常）
|
||
- [ ] 快速重启测试
|
||
|
||
### 3. 数据质量验证
|
||
|
||
- [ ] 遥测数据中的事件名称是否一致
|
||
- [ ] 环境信息是否完整
|
||
- [ ] 时间戳是否准确
|
||
- [ ] component_name 是否正确填充
|
||
|
||
## Summary
|
||
|
||
本次提交是一个**重大的遥测系统重构**，包含以下核心改进：
|
||
|
||
1. **统一的事件命名规范**: 避免了硬编码字符串，提升代码可维护性
|
||
2. **增强的隐私保护**: 禁用 PII 收集，使用匿名标识符
|
||
3. **优化的性能**: 减少重复数据，优化 Flush 策略
|
||
4. **完善的生命周期管理**: Session 追踪覆盖更全面
|
||
5. **详尽的文档**: 包含完整的重构指南和实施计划
|
||
|
||
**整体评估:** 这是一次高质量的系统重构，建议合并后进行全面测试验证。
|
||
|
||
**预计测试时间:** 2-3 小时（包括基础测试和集成测试）
|
||
|
||
---
|
||
|
||
*Report generated: 2026-05-27*
|
||
*Analyzer: Git Commit Analysis Tool*
|