oneapp_docs/basic_utils/basic_logger.md

# Basic Logger - 日志系统模块文档

## 模块概述

`basic_logger` 是 OneApp 基础工具模块群中的日志系统核心模块，提供统一的日志记录、管理和分析功能。该模块支持多级别日志、文件存储、网络上传、事件打点等功能，并提供了 Android 和 iOS 的原生日志监控能力。

### 基本信息
- **模块名称**: basic_logger
- **模块路径**: oneapp_basic_utils/basic_logger
- **类型**: Flutter Plugin Module
- **主要功能**: 日志记录、事件打点、文件上传、原生日志监控

### 核心特性
- **多级别日志**: 支持debug、info、warn、error四个级别
- **业务标签**: 预定义车联网、账户、充电等业务场景标签
- **文件记录**: 支持日志文件记录和轮转机制
- **网络上传**: 支持日志文件网络上传功能
- **事件打点**: 专门的事件日志记录能力
- **原生监控**: Android/iOS原生日志监控和采集
- **性能优化**: 支持日志级别过滤和调试开关

## 目录结构

```
basic_logger/
├── lib/
│   ├── basic_logger.dart           # 模块入口文件
│   ├── logcat_monitor.dart         # 原生日志监控
│   ├── kit_logger_ios.dart         # iOS特定实现
│   └── src/                        # 源代码目录
│       ├── event_log/              # 事件日志
│       │   └── one_event_log.dart
│       ├── function/               # 核心功能
│       │   └── one_app_log.dart    # 主日志类
│       ├── model/                  # 数据模型
│       │   ├── upload_config.dart
│       │   └── upload_file_info.dart
│       ├── record/                 # 记录功能
│       │   ├── core.dart
│       │   ├── record_delegate.dart
│       │   └── impl_dart/
│       │       ├── dart_record.dart
│       │       └── dart_file_record_.dart
│       └── upload/                 # 上传功能
│           ├── core.dart
│           └── upload_handler.dart
├── android/                        # Android原生实现
├── ios/                           # iOS原生实现
└── pubspec.yaml                   # 依赖配置
```

## 核心架构组件

### 1. 日志级别枚举 (Level)

定义应用日志的级别：

```dart
/// Log Level
enum Level {
  /// none - 无日志
  none,
  /// info - 信息日志
  info,
  /// debug - 调试日志  
  debug,
  /// warn - 警告日志
  warn,
  /// error - 错误日志
  error,
}
```

### 2. 主日志类 (OneAppLog)

应用日志的核心实现类：

```dart
/// application层：日志
class OneAppLog {
  OneAppLog._();

  /// logger flag
  static const int loggerFlag = 1;
  static const String _defaultTag = 'default';
  
  static bool _debuggable = false;
  static Level _filterLevel = Level.none;

  /// 配置日志系统
  /// [debuggable] 调试开关
  /// [filterLevel] 日志过滤级别
  static void config({
    bool debuggable = false,
    Level filterLevel = Level.none,
  }) {
    _debuggable = debuggable;
    _filterLevel = filterLevel;
  }

  /// info级别日志
  /// [msg] 日志内容
  /// [tag] 日志标签
  static void i(String msg, [String tag = _defaultTag]) {
    if (Level.info.index > _filterLevel.index) {
      _log(Level.info, msg, tag);
    }
  }

  /// debug级别日志
  /// [msg] 日志内容
  /// [tag] 日志标签
  static void d(String msg, [String tag = _defaultTag]) {
    if (_debuggable && Level.debug.index > _filterLevel.index) {
      _log(Level.debug, msg, tag);
    }
  }

  /// warn级别日志
  /// [msg] 日志内容
  /// [tag] 日志标签
  static void w(String msg, [String tag = _defaultTag]) {
    if (Level.warn.index > _filterLevel.index) {
      _log(Level.warn, msg, tag);
    }
  }

  /// error级别日志
  /// [msg] 日志内容
  /// [tag] 日志标签
  static void e(String msg, [String tag = _defaultTag]) {
    _log(Level.error, msg, tag);
  }

  /// 上传日志文件
  /// [fileName] 文件名，如果为空内部自动生成
  /// [handler] 上传处理器
  /// [config] 上传配置
  static Future<UploadFileResult> upload(
    String? fileName,
    UploadHandler handler,
    UploadConfig config,
  ) => UploadManager().upload(fileName, handler, config);

  // 内部日志记录实现
  static void _log(Level level, String msg, String tag) {
    final time = DateTime.now();
    final emoji = _levelEmojis[level];
    recordIns.record(loggerFlag, '$time: $emoji[$tag] $msg');
  }
}
```

### 3. 业务标签定义

为不同业务场景预定义的日志标签：

```dart
/// App通用标签
const tagApp = 'App';           // App全局日志
const tagRoute = 'Route';       // 路由跳转
const tagNetwork = 'Network';   // 网络请求
const tagWebView = 'WebView';   // WebView相关

/// 业务标签
const tagCommunity = 'Community';       // 社区功能
const tagCarSale = 'CarSale';          // 汽车销售
const tagAfterSale = 'AfterSale';      // 售后服务
const tagMall = 'Mall';                // 商城
const tagOrder = 'Order';              // 订单
const tagMaintenance = 'Maintenance';   // 保养维护

/// 车联网标签
const tagVehicleSDK = 'VehicleSDK';     // CEA/MM SDK
const tagAccount = 'Account';           // 账户系统
const tagCarHome = 'CarHome';           // 爱车首页
const tagMDK = 'MDK';                   // MDK相关
const tagRemoteControl = 'RemoteControl'; // 远程控制
const tagHVAC = 'HVAC';                 // 空调系统
const tagCarFind = 'CarFind';           // 寻车功能
const tag3DModel = '3DModel';           // 3D模型
const tagRPA = 'RPA';                   // RPA功能
const tagCamera = 'Camera';             // 摄像头
const tagIntelligentScene = 'IntelligentScene'; // 智能场景
const tagRVS = 'RVS';                   // 远程车辆状态
const tagVUR = 'VUR';                   // 用车报告
const tagAvatar = 'Avatar';             // 虚拟形象
const tagTouchGo = 'TouchGo';           // 小组件
const tagFridge = 'Fridge';             // 冰箱
const tagWallbox = 'Wallbox';           // 壁挂充电盒
const tagOTA = 'OTA';                   // 空中升级
const tagCharging = 'Charging';         // 充电功能
const tagMessage = 'Message';           // 通知消息
```

### 4. 日志级别表情符号映射

```dart
final Map<Level, String> _levelEmojis = {
  Level.debug: '🐛',
  Level.info: '💡💡',
  Level.warn: '⚠️⚠️⚠️',
  Level.error: '❌❌❌',
};
```

### 5. Logger类型别名

```dart
typedef Logger = OneAppLog;
```

## 使用指南

### 1. 日志系统初始化

```dart
import 'package:basic_logger/basic_logger.dart';

// 配置日志系统
OneAppLog.config(
  debuggable: true,           // 开启调试模式
  filterLevel: Level.debug,   // 设置过滤级别
);
```

### 2. 基础日志记录

```dart
// 使用预定义标签
OneAppLog.i('用户登录成功', tagAccount);
OneAppLog.d('调试信息：用户ID = 12345', tagAccount);
OneAppLog.w('网络请求超时，正在重试', tagNetwork);
OneAppLog.e('登录失败：用户名或密码错误', tagAccount);

// 使用默认标签
OneAppLog.i('应用启动完成');
OneAppLog.e('未知错误发生');
```

### 3. 车联网业务日志

```dart
// 车辆控制相关
OneAppLog.i('开始远程启动车辆', tagRemoteControl);
OneAppLog.w('车辆锁定状态异常', tagVehicleSDK);
OneAppLog.e('空调控制指令失败', tagHVAC);

// 充电相关
OneAppLog.i('开始充电', tagCharging);
OneAppLog.w('充电桩连接不稳定', tagCharging);
OneAppLog.e('充电异常停止', tagCharging);

// 3D模型相关
OneAppLog.d('3D模型加载中', tag3DModel);
OneAppLog.i('3D模型渲染完成', tag3DModel);

// 虚拟形象相关
OneAppLog.i('虚拟形象初始化', tagAvatar);
OneAppLog.w('虚拟形象动画加载超时', tagAvatar);
```

### 4. 日志文件上传

```dart
// 创建上传配置
final uploadConfig = UploadConfig(
  serverUrl: 'https://api.example.com/logs',
  apiKey: 'your_api_key',
  timeout: Duration(seconds: 30),
);

// 创建上传处理器
final uploadHandler = CustomUploadHandler();

// 上传日志文件
try {
  final result = await OneAppLog.upload(
    'app_logs_20231201.log',
    uploadHandler,
    uploadConfig,
  );
  
  if (result.success) {
    OneAppLog.i('日志上传成功', tagApp);
  } else {
    OneAppLog.e('日志上传失败: ${result.error}', tagApp);
  }
} catch (e) {
  OneAppLog.e('日志上传异常: $e', tagApp);
}
```

### 5. 条件日志记录

```dart
// 仅在调试模式下记录
if (kDebugMode) {
  OneAppLog.d('这是调试信息，仅开发时可见', tagApp);
}

// 根据业务条件记录
void onUserAction(String action) {
  OneAppLog.i('用户执行操作: $action', tagApp);
  
  if (action == 'high_risk_operation') {
    OneAppLog.w('用户执行高风险操作', tagApp);
  }
}
```

## 依赖配置

### pubspec.yaml 配置

```yaml
dependencies:
  flutter:
    sdk: flutter
    
  # 基础日志模块
  basic_logger:
    path: ../oneapp_basic_utils/basic_logger

dev_dependencies:
  flutter_test:
    sdk: flutter
```

## 高级功能

### 1. 自定义上传处理器

```dart
class CustomUploadHandler extends UploadHandler {
  @override
  Future<UploadFileResult> upload(
    String filePath, 
    UploadConfig config
  ) async {
    // 实现自定义上传逻辑
    try {
      // 发送HTTP请求上传文件
      final response = await http.post(
        Uri.parse(config.serverUrl),
        headers: {'Authorization': 'Bearer ${config.apiKey}'},
        body: await File(filePath).readAsBytes(),
      );
      
      if (response.statusCode == 200) {
        return UploadFileResult.success();
      } else {
        return UploadFileResult.failure('上传失败: ${response.statusCode}');
      }
    } catch (e) {
      return UploadFileResult.failure('上传异常: $e');
    }
  }
}
```

### 2. 事件日志记录

```dart
import 'package:basic_logger/basic_logger.dart';

// 记录事件日志
OneEventLog.record({
  'event_type': 'user_click',
  'element_id': 'login_button',
  'timestamp': DateTime.now().millisecondsSinceEpoch,
  'user_id': '12345',
});
```

### 3. 原生日志监控

```dart
import 'package:basic_logger/logcat_monitor.dart';

// 开启原生日志监控
final monitor = LogcatMonitor();
await monitor.startMonitoring();

// 停止监控
await monitor.stopMonitoring();
```

## 性能优化建议

### 1. 日志级别管理
- 生产环境关闭debug日志：`debuggable: false`
- 设置合适的过滤级别：`filterLevel: Level.warn`
- 避免在循环中大量打印日志

### 2. 文件管理
- 定期清理过期日志文件
- 控制日志文件大小，避免占用过多存储空间
- 使用日志轮转机制

### 3. 网络上传优化
- 在WiFi环境下上传日志
- 压缩日志文件减少网络开销
- 实现上传失败重试机制

## 最佳实践

### 1. 标签使用规范
```dart
// 推荐：使用预定义业务标签
OneAppLog.i('充电状态更新', tagCharging);

// 避免：使用无意义的标签
OneAppLog.i('充电状态更新', 'test');
```

### 2. 敏感信息保护
```dart
// 推荐：脱敏处理
OneAppLog.i('用户登录: ${userId.substring(0, 3)}***', tagAccount);

// 避免：直接记录敏感信息
OneAppLog.i('用户登录: $userPassword', tagAccount);
```

### 3. 错误日志详细性
```dart
// 推荐：提供详细上下文
OneAppLog.e('网络请求失败: $url, 状态码: $statusCode, 错误: $error', tagNetwork);

// 避免：信息不足的错误日志
OneAppLog.e('请求失败', tagNetwork);
```

## 问题排查

### 常见问题
1. **日志不显示**: 检查debuggable配置和filterLevel设置
2. **文件上传失败**: 确认网络权限和上传配置
3. **性能影响**: 避免高频日志输出，合理设置日志级别

### 调试技巧
- 使用Android Studio/Xcode查看原生日志
- 通过文件系统检查日志文件生成
- 监控应用内存使用避免日志系统影响性能