first commit

2025-09-24 14:08:54 +08:00
commit 40784642cf
83 changed files with 37832 additions and 0 deletions
--- a/service_component/app_configuration.md
+++ b/service_component/app_configuration.md
@@ -0,0 +1,563 @@
+# App Configuration - 应用配置管理模块
+
+## 模块概述
+
+`app_configuration` 是 OneApp 的车辆配置管理模块，专注于车辆配置选择和管理功能。该模块提供了完整的车辆配置解决方案，包括车型选择、外观配置、内饰配置、选装配置等功能。
+
+## 核心功能
+
+### 1. 车辆配置管理
+- **车型配置页面**：提供完整的车辆配置选择界面
+- **配置选项管理**：支持各种车辆配置选项
+- **3D模型展示**：集成3D车辆模型展示功能
+- **配置验证**：配置有效性验证机制
+
+### 2. 模块导出组件
+
+基于真实项目代码的主要导出：
+
+```dart
+library app_configuration;
+
+// 车辆配置页面
+export 'src/app_modules/car_configuration/pages/car_configuration_page.dart';
+
+// 车辆配置状态管理
+export 'src/app_modules/car_configuration/blocs/car_configuration_bloc.dart';
+
+// 配置相关组件
+export 'src/app_modules/car_configuration/widgets/car_rights_dialog_widget.dart';
+export 'src/app_modules/car_configuration/widgets/car_order_count_exception_dialog.dart';
+
+// 路由导出
+export 'src/route_export.dart';
+
+// 配置常量
+export 'src/app_modules/car_configuration/configuration_constant.dart';
+```
+
+### 3. 车辆配置页面 (CarConfigurationPage)
+
+核心配置页面实现：
+
+```dart
+/// 车辆配置页面
+class CarConfigurationPage extends StatefulWidget with RouteObjProvider {
+  CarConfigurationPage({
+    Key? key,
+    this.carModelCode,
+    this.smallPreOrderNum,
+    this.carOrderNum,
+    this.needDepositAmount,
+    this.pageFrom = PageFrom.pageNone,
+  }) : super(key: key);
+
+  /// 已选车型配置代码
+  final String? carModelCode;
+
+  /// 小订订单号，创建大定时可以关联小订
+  final String? smallPreOrderNum;
+
+  /// 大定修改订单原始订单号
+  final String? carOrderNum;
+
+  /// 大定修改，大定定金金额
+  final double? needDepositAmount;
+
+  /// 页面来源类型
+  PageFrom? pageFrom = PageFrom.pageNone;
+
+  @override
+  State<CarConfigurationPage> createState() => _CarConfigurationPageState();
+}
+```
+
+### 4. 模块架构组件
+
+实际项目包含的配置组件：
+
+- **car_3D_model_webview.dart**: 3D车辆模型WebView组件
+- **car_exterior_config.dart**: 车辆外观配置组件  
+- **car_interior_config.dart**: 车辆内饰配置组件
+- **car_model_config_new.dart**: 新版车型配置组件
+- **car_option_config.dart**: 车辆选装配置组件
+- **config_bottom_bar_widget.dart**: 配置底部栏组件
+- **configuration_tab.dart**: 配置选项卡组件
+
+## 技术架构
+
+### 模块注册
+
+```dart
+/// App配置模块
+class AppConfigurationModule extends Module with RouteObjProvider {
+  @override
+  List<Module> get imports => [];
+
+  @override
+  List<Bind> get binds => [];
+
+  @override
+  List<ModularRoute> get routes {
+    final r1 = RouteCenterAPI.routeMetaBy(
+      AppConfigurationRouteExport.keyAppConfiguration
+    );
+
+    return [
+      ChildRoute(
+        r1.path, 
+        child: (_, args) => r1.provider(args).as(),
+        guards: loginGuardList,
+      ),
+    ];
+  }
+}
+```
+
+### 目录结构
+
+基于实际项目结构：
+
+```
+lib/
+├── app_configuration.dart      # 主导出文件
+├── generated/                  # 生成的国际化文件
+├── l10n/                      # 国际化资源文件
+└── src/                       # 源代码目录
+    ├── app_modules/           # 应用模块
+    │   └── car_configuration/ # 车辆配置模块
+    │       ├── blocs/         # BLoC状态管理
+    │       ├── model/         # 数据模型
+    │       ├── pages/         # 页面组件
+    │       ├── widgets/       # 配置组件
+    │       └── configuration_constant.dart # 配置常量
+    ├── app_defines/           # 应用定义
+    └── route_export.dart      # 路由导出
+```
+
+### 核心组件
+
+#### 1. 配置管理器 (ConfigurationManager)
+```dart
+class ConfigurationManager {
+  // 初始化配置管理器
+  Future<bool> initialize(ConfigurationConfig config);
+  
+  // 获取配置值
+  T? getValue<T>(String key, {T? defaultValue});
+  
+  // 设置配置值
+  Future<bool> setValue<T>(String key, T value);
+  
+  // 删除配置
+  Future<bool> removeValue(String key);
+  
+  // 获取所有配置
+  Map<String, dynamic> getAllConfigurations();
+}
+```
+
+#### 2. 远程配置服务 (RemoteConfigService)
+```dart
+class RemoteConfigService {
+  // 从服务端获取配置
+  Future<ConfigurationResult> fetchRemoteConfig();
+  
+  // 检查配置更新
+  Future<bool> checkForUpdates();
+  
+  // 应用远程配置
+  Future<bool> applyRemoteConfig(Map<String, dynamic> config);
+  
+  // 获取配置版本信息
+  Future<ConfigVersion> getConfigVersion();
+}
+```
+
+#### 3. 本地缓存管理器 (LocalCacheManager)
+```dart
+class LocalCacheManager {
+  // 缓存配置到本地
+  Future<bool> cacheConfiguration(String key, dynamic value);
+  
+  // 从缓存获取配置
+  T? getCachedConfiguration<T>(String key);
+  
+  // 清除缓存
+  Future<bool> clearCache([String? key]);
+  
+  // 获取缓存大小
+  Future<int> getCacheSize();
+  
+  // 压缩缓存数据
+  Future<bool> compressCache();
+}
+```
+
+#### 4. 环境管理器 (EnvironmentManager)
+```dart
+class EnvironmentManager {
+  // 设置当前环境
+  Future<bool> setCurrentEnvironment(Environment environment);
+  
+  // 获取当前环境
+  Environment getCurrentEnvironment();
+  
+  // 获取环境配置
+  Map<String, dynamic> getEnvironmentConfig(Environment environment);
+  
+  // 验证环境配置
+  Future<bool> validateEnvironmentConfig(Environment environment);
+}
+```
+
+## 数据模型
+
+### 配置模型
+```dart
+class Configuration {
+  final String key;
+  final dynamic value;
+  final ConfigurationType type;
+  final DateTime createdAt;
+  final DateTime updatedAt;
+  final String version;
+  final Map<String, dynamic> metadata;
+  final bool isRemote;
+  final bool isEncrypted;
+}
+
+enum ConfigurationType {
+  string,
+  integer,
+  double,
+  boolean,
+  json,
+  list
+}
+```
+
+### 环境模型
+```dart
+enum Environment {
+  development,
+  testing,
+  staging,
+  production
+}
+
+class EnvironmentConfig {
+  final Environment environment;
+  final String baseUrl;
+  final String apiKey;
+  final Map<String, String> headers;
+  final int timeout;
+  final bool enableLogging;
+  final Map<String, dynamic> features;
+}
+```
+
+### 配置版本模型
+```dart
+class ConfigVersion {
+  final String version;
+  final DateTime publishTime;
+  final String description;
+  final List<String> changedKeys;
+  final Map<String, dynamic> changeset;
+  final bool isForced;
+  final DateTime expireTime;
+}
+```
+
+## API 接口
+
+### 配置管理接口
+```dart
+abstract class ConfigurationService {
+  // 初始化配置服务
+  Future<ApiResponse<bool>> initialize(InitConfigRequest request);
+  
+  // 获取配置
+  Future<ApiResponse<ConfigurationResult>> getConfiguration(GetConfigRequest request);
+  
+  // 批量获取配置
+  Future<ApiResponse<Map<String, dynamic>>> getBatchConfiguration(BatchConfigRequest request);
+  
+  // 更新配置
+  Future<ApiResponse<bool>> updateConfiguration(UpdateConfigRequest request);
+}
+```
+
+### 远程配置接口
+```dart
+abstract class RemoteConfigurationService {
+  // 获取远程配置
+  Future<ApiResponse<Map<String, dynamic>>> fetchRemoteConfiguration(FetchConfigRequest request);
+  
+  // 检查配置更新
+  Future<ApiResponse<UpdateCheckResult>> checkConfigurationUpdate(CheckUpdateRequest request);
+  
+  // 上报配置使用情况
+  Future<ApiResponse<bool>> reportConfigurationUsage(UsageReportRequest request);
+}
+```
+
+## 配置管理
+
+### 默认配置
+```dart
+class DefaultConfiguration {
+  static const Map<String, dynamic> defaultConfig = {
+    'app': {
+      'name': 'OneApp',
+      'version': '1.0.0',
+      'debug': false,
+    },
+    'network': {
+      'timeout': 30000,
+      'retryCount': 3,
+      'enableCache': true,
+    },
+    'ui': {
+      'theme': 'auto',
+      'language': 'auto',
+      'animations': true,
+    },
+    'features': {
+      'enableAnalytics': true,
+      'enablePush': true,
+      'enableLocation': false,
+    },
+  };
+}
+```
+
+### 环境配置
+```dart
+class EnvironmentConfiguration {
+  static const Map<Environment, EnvironmentConfig> environments = {
+    Environment.development: EnvironmentConfig(
+      environment: Environment.development,
+      baseUrl: 'https://dev-api.oneapp.com',
+      apiKey: 'dev_api_key',
+      enableLogging: true,
+    ),
+    Environment.production: EnvironmentConfig(
+      environment: Environment.production,
+      baseUrl: 'https://api.oneapp.com',
+      apiKey: 'prod_api_key',
+      enableLogging: false,
+    ),
+  };
+}
+```
+
+## 使用示例
+
+### 基本配置管理
+```dart
+// 初始化配置管理器
+final configManager = ConfigurationManager.instance;
+await configManager.initialize(ConfigurationConfig.defaultConfig);
+
+// 获取配置值
+final appName = configManager.getValue<String>('app.name', defaultValue: 'OneApp');
+final timeout = configManager.getValue<int>('network.timeout', defaultValue: 30000);
+final enableAnalytics = configManager.getValue<bool>('features.enableAnalytics', defaultValue: true);
+
+// 设置配置值
+await configManager.setValue('ui.theme', 'dark');
+await configManager.setValue('features.enablePush', false);
+
+// 监听配置变化
+configManager.onConfigurationChanged.listen((change) {
+  print('配置变更: ${change.key} = ${change.newValue}');
+});
+```
+
+### 远程配置更新
+```dart
+// 检查远程配置更新
+final remoteConfigService = RemoteConfigService.instance;
+final hasUpdate = await remoteConfigService.checkForUpdates();
+
+if (hasUpdate) {
+  // 获取远程配置
+  final remoteConfig = await remoteConfigService.fetchRemoteConfig();
+  
+  if (remoteConfig.isSuccess) {
+    // 应用远程配置
+    await remoteConfigService.applyRemoteConfig(remoteConfig.data);
+    print('远程配置已更新');
+  }
+}
+
+// 监听远程配置更新
+remoteConfigService.onRemoteConfigUpdated.listen((config) {
+  print('收到远程配置更新');
+  // 处理配置更新逻辑
+});
+```
+
+### 环境配置切换
+```dart
+// 获取当前环境
+final currentEnv = EnvironmentManager.instance.getCurrentEnvironment();
+print('当前环境: $currentEnv');
+
+// 切换到测试环境
+await EnvironmentManager.instance.setCurrentEnvironment(Environment.testing);
+
+// 获取环境配置
+final envConfig = EnvironmentManager.instance.getEnvironmentConfig(Environment.testing);
+print('测试环境配置: $envConfig');
+
+// 验证环境配置
+final isValid = await EnvironmentManager.instance.validateEnvironmentConfig(Environment.testing);
+if (!isValid) {
+  print('环境配置验证失败');
+}
+```
+
+### 配置缓存管理
+```dart
+// 缓存配置
+final cacheManager = LocalCacheManager.instance;
+await cacheManager.cacheConfiguration('user_preferences', userPreferences);
+
+// 获取缓存配置
+final cachedPreferences = cacheManager.getCachedConfiguration<Map<String, dynamic>>('user_preferences');
+
+// 获取缓存大小
+final cacheSize = await cacheManager.getCacheSize();
+print('缓存大小: ${cacheSize}KB');
+
+// 清理缓存
+if (cacheSize > 1024 * 1024) { // 超过1MB
+  await cacheManager.compressCache();
+}
+```
+
+## 测试策略
+
+### 单元测试
+```dart
+group('ConfigurationManager Tests', () {
+  test('should get and set configuration values', () async {
+    // Given
+    final configManager = ConfigurationManager();
+    await configManager.initialize(ConfigurationConfig.defaultConfig);
+    
+    // When
+    await configManager.setValue('test.key', 'test_value');
+    final value = configManager.getValue<String>('test.key');
+    
+    // Then
+    expect(value, 'test_value');
+  });
+  
+  test('should return default value when key not found', () {
+    // Given
+    final configManager = ConfigurationManager();
+    
+    // When
+    final value = configManager.getValue<String>('nonexistent.key', defaultValue: 'default');
+    
+    // Then
+    expect(value, 'default');
+  });
+});
+```
+
+### 集成测试
+```dart
+group('Configuration Integration Tests', () {
+  testWidgets('configuration update flow', (tester) async {
+    // 1. 初始化配置
+    await ConfigurationManager.instance.initialize(ConfigurationConfig.defaultConfig);
+    
+    // 2. 模拟远程配置更新
+    final mockRemoteConfig = {'feature.newFeature': true};
+    await RemoteConfigService.instance.applyRemoteConfig(mockRemoteConfig);
+    
+    // 3. 验证配置已更新
+    final newFeatureEnabled = ConfigurationManager.instance.getValue<bool>('feature.newFeature');
+    expect(newFeatureEnabled, true);
+  });
+});
+```
+
+## 性能优化
+
+### 缓存策略
+- **内存缓存**：热点配置内存缓存
+- **磁盘缓存**：所有配置磁盘持久化
+- **缓存过期**：配置缓存过期机制
+- **预加载**：应用启动时预加载关键配置
+
+### 网络优化
+- **增量同步**：只同步变化的配置项
+- **压缩传输**：配置数据压缩传输
+- **批量操作**：批量获取和更新配置
+- **连接池**：网络连接池优化
+
+## 安全考虑
+
+### 数据安全
+- **配置加密**：敏感配置加密存储
+- **传输加密**：配置传输使用HTTPS
+- **签名验证**：配置数据签名验证
+- **访问控制**：配置访问权限控制
+
+### 隐私保护
+- **数据最小化**：只收集必要的配置数据
+- **匿名化**：用户相关配置匿名化
+- **数据清理**：定期清理过期配置
+- **透明度**：配置使用透明化
+
+## 监控和诊断
+
+### 性能监控
+- **配置使用统计**：统计配置项使用频率
+- **更新性能**：监控配置更新性能
+- **缓存命中率**：监控缓存命中率
+- **网络性能**：监控配置网络请求性能
+
+### 故障诊断
+- **配置验证**：配置数据有效性验证
+- **更新失败恢复**：配置更新失败自动恢复
+- **异常监控**：配置相关异常监控
+- **健康检查**：配置服务健康检查
+
+## 版本历史
+
+### v0.2.6+8 (当前版本)
+- 新增配置热更新功能
+- 优化缓存性能
+- 支持配置分组管理
+- 修复环境切换问题
+
+### v0.2.5
+- 支持远程配置灰度发布
+- 新增配置使用统计
+- 优化配置同步机制
+- 改进错误处理
+
+## 依赖关系
+
+### 内部依赖
+- `clr_configuration`: 配置服务SDK
+- `basic_storage`: 本地存储服务
+- `basic_network`: 网络请求服务
+- `basic_error`: 错误处理框架
+
+### 外部依赖
+- `shared_preferences`: 本地配置存储
+- `dio`: HTTP客户端
+- `encrypt`: 数据加密
+- `rxdart`: 响应式编程
+
+## 总结
+
+`app_configuration` 作为应用配置管理的核心模块，提供了完整的配置管理解决方案。通过远程配置、本地缓存、热更新和环境切换等功能，为 OneApp 提供了灵活、可靠、高效的配置管理能力，确保应用能够快速响应业务需求变化，同时保证用户体验的一致性和稳定性。