# Git Commit Analysis Report ## Commit Information | Field | Value | |-------|-------| | **Commit Hash** | `ce41fd676cd5464f34cd5c8687bbbe73ca1c562b` | | **Author** | lincube | | **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*