564 lines
14 KiB
Markdown
564 lines
14 KiB
Markdown
# 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 提供了灵活、可靠、高效的配置管理能力，确保应用能够快速响应业务需求变化，同时保证用户体验的一致性和稳定性。
|