development.md

开发者指引 / 架构总览

运行时流程

• 入口：lib/main.dart 启动时先检测 CLI 参数（无则继续 UI），创建全局 AppState（Provider）并渲染 EchoTraceApp。
• AppState 负责初始化日志、配置、数据库连接（实时/备份）、错误与加载状态、解密进度、头像缓存等。UI 通过 Consumer<AppState> 订阅状态。
• HomePage 搭配 Sidebar 实现主布局，根据 AppState.currentPage 切换各业务页面（欢迎、聊天、数据分析、群聊分析、导出、数据管理、设置）。

数据与解密

• 数据库读取由 DatabaseService 承载，支持两种模式：
  • 备份模式：使用 sqflite 只读连接解密后的 SQLite（session/message/contact）。
  • 实时模式：通过 wechat_wcdb_native.dart 调用 Windows DLL 直接读取加密 WCDB。
• 解密：默认使用 Go FFI（DecryptServiceGo -> GoDecryptFFI），另有 Dart 备份实现；图片解密在 ImageDecryptService。
• 配置：ConfigService 持久化解密密钥、数据库路径、实时/备份模式、图片密钥、调试开关等。

业务服务

• AnalyticsService 与高级分析/缓存后台服务负责私聊/全局统计、时间分布、词频、年度/双人报告等。
• ChatExportService 负责 JSON/HTML/Excel 导出，页面 ChatExportPage 与 CLI 共用。
• 群聊相关能力在 GroupChatService 及群聊页面系列（活跃度、成员、媒体统计等）。
• 日志：LoggerService 统一 info/debug/warning/error，CLI 也输出到临时文件。

CLI 导出

• lib/cli/cli_export_runner.dart 拦截命令行参数（仅 Windows），初始化 AppState 与数据库后批量导出，会话筛选与时间范围与 UI 保持一致。

模型与工具

• 核心模型：ChatSession、Message、Contact、AnalyticsData 等，位于 lib/models/。
• 工具：path_utils.dart（路径/特殊字符兼容）、string_utils.dart（文本）、xml_message_parser.dart（消息 XML 解析）、batch_processor.dart（批处理节流）。

主要文件和目录

• lib/main.dart：应用与 CLI 启动入口，构建主题与全局 Provider。
• lib/providers/app_state.dart：全局状态、数据库重连、解密进度、头像缓存。
• lib/services/database_service.dart：数据库连接、实时 DLL 访问、跨库消息查询与统计。
• lib/services/analytics_service.dart 及 advanced_analytics_service.dart：统计分析。
• lib/services/chat_export_service.dart：导出实现，供 UI/CLI 复用。
• lib/services/decrypt_service_go.dart / go_decrypt_ffi.dart：数据库解密。
• lib/services/config_service.dart：配置持久化。
• lib/services/wechat_wcdb_native.dart：WCDB DLL FFI 封装。
• lib/pages/：各个业务页面与布局；widgets/：可复用组件（侧边栏、气泡、进度遮罩等）。
• lib/utils/：通用工具。

构建与调试提示

• 依赖：flutter pub get。
• 运行：flutter run（桌面需已启用目标平台），或 flutter build windows/macos/linux。
• CLI：Windows 上直接运行可执行文件，使用 -e/--format/--start/--end/--all 参数导出。
• 日志：App 内部使用 LoggerService，CLI 模式附加输出到系统临时目录的 echotrace_cli.log。