first commit

2025-09-24 14:08:54 +08:00
commit 40784642cf
83 changed files with 37832 additions and 0 deletions
--- a/after_sales/clr_after_sales.md
+++ b/after_sales/clr_after_sales.md
@@ -0,0 +1,726 @@
+# CLR After Sales 售后服务SDK
+
+## 模块概述
+
+`clr_after_sales` 是 OneApp 售后服务模块群中的核心服务SDK，负责封装售后服务的业务逻辑、API接口调用和数据模型定义。该模块为售后服务应用层提供统一的服务接口和数据处理能力。
+
+### 基本信息
+- **模块名称**: clr_after_sales
+- **版本**: 0.0.1
+- **描述**: 售后服务核心SDK
+- **Flutter 版本**: >=1.17.0
+- **Dart 版本**: >=3.0.0 <4.0.0
+
+## 功能特性
+
+### 核心功能
+1. **API接口封装**
+   - 售后服务API统一封装
+   - 网络请求统一处理
+   - 错误处理和重试机制
+   - 数据缓存和同步
+
+2. **业务逻辑封装**
+   - 预约业务逻辑
+   - 服务流程管理
+   - 支付结算逻辑
+   - 数据验证规则
+
+3. **数据模型管理**
+   - 统一数据模型定义
+   - JSON序列化支持
+   - 数据转换和映射
+   - 模型验证机制
+
+4. **状态管理**
+   - 业务状态统一管理
+   - 事件驱动更新
+   - 状态持久化
+   - 状态同步机制
+
+## 技术架构
+
+### 目录结构
+```
+lib/
+├── clr_after_sales.dart       # 模块入口文件
+├── src/                       # 源代码目录
+│   ├── services/              # 业务服务
+│   ├── repositories/          # 数据仓库
+│   ├── models/                # 数据模型
+│   ├── enums/                 # 枚举定义
+│   ├── exceptions/            # 异常定义
+│   ├── utils/                 # 工具类
+│   └── constants/             # 常量定义
+├── test/                      # 测试文件
+└── generated/                 # 代码生成文件
+```
+
+### 依赖关系
+
+#### 基础框架依赖
+- `basic_network: ^0.2.3+4` - 网络通信框架
+- `common_utils: ^2.1.0` - 通用工具库
+
+#### 内部依赖 (dependency_overrides)
+- `ui_basic` - 基础UI组件（本地路径）
+- `basic_platform` - 平台适配（本地路径）
+- `basic_utils` - 基础工具（本地路径）
+- `basic_uis` - 基础UI集合（本地路径）
+- `base_mvvm` - MVVM架构（本地路径）
+
+## 核心模块分析
+
+### 1. 业务服务 (`src/services/`)
+
+#### 预约服务
+```dart
+class AppointmentService {
+  final AppointmentRepository _repository;
+  final NetworkService _networkService;
+  
+  AppointmentService(this._repository, this._networkService);
+  
+  /// 创建预约
+  Future<Result<Appointment>> createAppointment(
+    AppointmentCreateRequest request,
+  ) async {
+    try {
+      // 1. 验证请求数据
+      final validationResult = _validateCreateRequest(request);
+      if (validationResult.isFailure) {
+        return Result.failure(validationResult.error);
+      }
+      
+      // 2. 检查时间可用性
+      final availability = await checkTimeAvailability(
+        request.storeId,
+        request.appointmentTime,
+      );
+      
+      if (!availability.isAvailable) {
+        return Result.failure(
+          AppointmentException('预约时间不可用'),
+        );
+      }
+      
+      // 3. 调用API创建预约
+      final apiResponse = await _networkService.post(
+        '/appointments',
+        data: request.toJson(),
+      );
+      
+      // 4. 解析响应数据
+      final appointment = Appointment.fromJson(apiResponse.data);
+      
+      // 5. 缓存到本地
+      await _repository.saveAppointment(appointment);
+      
+      return Result.success(appointment);
+    } catch (e) {
+      return Result.failure(AppointmentException(e.toString()));
+    }
+  }
+  
+  /// 获取用户预约列表
+  Future<Result<List<Appointment>>> getUserAppointments({
+    String? status,
+    int page = 1,
+    int pageSize = 20,
+  }) async {
+    try {
+      // 1. 先从缓存获取
+      final cachedAppointments = await _repository.getCachedAppointments(
+        status: status,
+        page: page,
+        pageSize: pageSize,
+      );
+      
+      // 2. 如果缓存存在且未过期，直接返回
+      if (cachedAppointments.isNotEmpty && !_isCacheExpired()) {
+        return Result.success(cachedAppointments);
+      }
+      
+      // 3. 从网络获取最新数据
+      final apiResponse = await _networkService.get(
+        '/appointments',
+        queryParameters: {
+          'status': status,
+          'page': page,
+          'pageSize': pageSize,
+        },
+      );
+      
+      // 4. 解析并缓存数据
+      final appointments = (apiResponse.data['items'] as List)
+          .map((json) => Appointment.fromJson(json))
+          .toList();
+      
+      await _repository.cacheAppointments(appointments);
+      
+      return Result.success(appointments);
+    } catch (e) {
+      return Result.failure(AppointmentException(e.toString()));
+    }
+  }
+  
+  /// 取消预约
+  Future<Result<bool>> cancelAppointment(String appointmentId) async {
+    try {
+      await _networkService.put(
+        '/appointments/$appointmentId/cancel',
+      );
+      
+      // 更新本地缓存
+      await _repository.updateAppointmentStatus(
+        appointmentId,
+        AppointmentStatus.cancelled,
+      );
+      
+      return Result.success(true);
+    } catch (e) {
+      return Result.failure(AppointmentException(e.toString()));
+    }
+  }
+}
+```
+
+#### 服务进度服务
+```dart
+class ServiceProgressService {
+  final ServiceProgressRepository _repository;
+  final NetworkService _networkService;
+  
+  ServiceProgressService(this._repository, this._networkService);
+  
+  /// 获取服务进度
+  Future<Result<ServiceProgress>> getServiceProgress(
+    String appointmentId,
+  ) async {
+    try {
+      final apiResponse = await _networkService.get(
+        '/appointments/$appointmentId/progress',
+      );
+      
+      final progress = ServiceProgress.fromJson(apiResponse.data);
+      
+      // 缓存进度数据
+      await _repository.saveProgress(progress);
+      
+      return Result.success(progress);
+    } catch (e) {
+      return Result.failure(ServiceException(e.toString()));
+    }
+  }
+  
+  /// 更新服务步骤
+  Future<Result<ServiceStep>> updateServiceStep(
+    String appointmentId,
+    String stepId,
+    ServiceStepUpdate update,
+  ) async {
+    try {
+      final apiResponse = await _networkService.put(
+        '/appointments/$appointmentId/steps/$stepId',
+        data: update.toJson(),
+      );
+      
+      final updatedStep = ServiceStep.fromJson(apiResponse.data);
+      
+      // 更新本地缓存
+      await _repository.updateStep(appointmentId, updatedStep);
+      
+      return Result.success(updatedStep);
+    } catch (e) {
+      return Result.failure(ServiceException(e.toString()));
+    }
+  }
+  
+  /// 上传服务照片
+  Future<Result<ServicePhoto>> uploadServicePhoto(
+    String appointmentId,
+    String stepId,
+    File photoFile,
+  ) async {
+    try {
+      final formData = FormData.fromMap({
+        'file': await MultipartFile.fromFile(photoFile.path),
+        'appointmentId': appointmentId,
+        'stepId': stepId,
+      });
+      
+      final apiResponse = await _networkService.post(
+        '/service-photos/upload',
+        data: formData,
+      );
+      
+      final photo = ServicePhoto.fromJson(apiResponse.data);
+      
+      return Result.success(photo);
+    } catch (e) {
+      return Result.failure(ServiceException(e.toString()));
+    }
+  }
+}
+```
+
+### 2. 数据仓库 (`src/repositories/`)
+
+#### 预约数据仓库
+```dart
+abstract class AppointmentRepository {
+  Future<void> saveAppointment(Appointment appointment);
+  Future<List<Appointment>> getCachedAppointments({
+    String? status,
+    int page = 1,
+    int pageSize = 20,
+  });
+  Future<void> cacheAppointments(List<Appointment> appointments);
+  Future<void> updateAppointmentStatus(String id, AppointmentStatus status);
+  Future<void> clearCache();
+}
+
+class AppointmentRepositoryImpl implements AppointmentRepository {
+  final LocalStorage _localStorage;
+  final DatabaseHelper _databaseHelper;
+  
+  AppointmentRepositoryImpl(this._localStorage, this._databaseHelper);
+  
+  @override
+  Future<void> saveAppointment(Appointment appointment) async {
+    try {
+      // 保存到数据库
+      await _databaseHelper.insertAppointment(appointment);
+      
+      // 更新缓存
+      final cacheKey = 'appointment_${appointment.id}';
+      await _localStorage.setString(cacheKey, jsonEncode(appointment.toJson()));
+    } catch (e) {
+      throw RepositoryException('保存预约失败: $e');
+    }
+  }
+  
+  @override
+  Future<List<Appointment>> getCachedAppointments({
+    String? status,
+    int page = 1,
+    int pageSize = 20,
+  }) async {
+    try {
+      return await _databaseHelper.getAppointments(
+        status: status,
+        offset: (page - 1) * pageSize,
+        limit: pageSize,
+      );
+    } catch (e) {
+      throw RepositoryException('获取缓存预约失败: $e');
+    }
+  }
+  
+  @override
+  Future<void> updateAppointmentStatus(String id, AppointmentStatus status) async {
+    try {
+      await _databaseHelper.updateAppointmentStatus(id, status);
+      
+      // 更新内存缓存
+      final cacheKey = 'appointment_$id';
+      final cachedData = await _localStorage.getString(cacheKey);
+      if (cachedData != null) {
+        final appointment = Appointment.fromJson(jsonDecode(cachedData));
+        final updatedAppointment = appointment.copyWith(status: status);
+        await _localStorage.setString(
+          cacheKey,
+          jsonEncode(updatedAppointment.toJson()),
+        );
+      }
+    } catch (e) {
+      throw RepositoryException('更新预约状态失败: $e');
+    }
+  }
+}
+```
+
+### 3. 数据模型 (`src/models/`)
+
+#### 预约模型
+```dart
+@freezed
+class Appointment with _$Appointment {
+  const factory Appointment({
+    required String id,
+    required String userId,
+    required String storeId,
+    required ServiceType serviceType,
+    required DateTime appointmentTime,
+    required AppointmentStatus status,
+    required VehicleInfo vehicleInfo,
+    String? description,
+    List<String>? attachments,
+    @JsonKey(name: 'created_at') DateTime? createdAt,
+    @JsonKey(name: 'updated_at') DateTime? updatedAt,
+    Store? store,
+    List<ServiceItem>? serviceItems,
+    PaymentInfo? paymentInfo,
+  }) = _Appointment;
+
+  factory Appointment.fromJson(Map<String, dynamic> json) =>
+      _$AppointmentFromJson(json);
+}
+
+@freezed
+class AppointmentCreateRequest with _$AppointmentCreateRequest {
+  const factory AppointmentCreateRequest({
+    required String storeId,
+    required ServiceType serviceType,
+    required DateTime appointmentTime,
+    required VehicleInfo vehicleInfo,
+    String? description,
+    List<String>? attachments,
+    List<String>? serviceItemIds,
+  }) = _AppointmentCreateRequest;
+
+  factory AppointmentCreateRequest.fromJson(Map<String, dynamic> json) =>
+      _$AppointmentCreateRequestFromJson(json);
+}
+```
+
+#### 服务进度模型
+```dart
+@freezed
+class ServiceProgress with _$ServiceProgress {
+  const factory ServiceProgress({
+    required String appointmentId,
+    required ServiceStatus status,
+    required List<ServiceStep> steps,
+    required double progressPercentage,
+    @JsonKey(name: 'estimated_completion') DateTime? estimatedCompletion,
+    @JsonKey(name: 'actual_completion') DateTime? actualCompletion,
+    Technician? assignedTechnician,
+    List<ServicePhoto>? photos,
+    String? currentStepNote,
+  }) = _ServiceProgress;
+
+  factory ServiceProgress.fromJson(Map<String, dynamic> json) =>
+      _$ServiceProgressFromJson(json);
+}
+
+@freezed
+class ServiceStep with _$ServiceStep {
+  const factory ServiceStep({
+    required String id,
+    required String name,
+    required String description,
+    required ServiceStepStatus status,
+    required int orderIndex,
+    @JsonKey(name: 'started_at') DateTime? startedAt,
+    @JsonKey(name: 'completed_at') DateTime? completedAt,
+    String? note,
+    List<String>? photoIds,
+    Duration? estimatedDuration,
+    Duration? actualDuration,
+  }) = _ServiceStep;
+
+  factory ServiceStep.fromJson(Map<String, dynamic> json) =>
+      _$ServiceStepFromJson(json);
+}
+```
+
+### 4. 枚举定义 (`src/enums/`)
+
+```dart
+enum AppointmentStatus {
+  @JsonValue('pending')
+  pending,
+  @JsonValue('confirmed')
+  confirmed,
+  @JsonValue('inProgress')
+  inProgress,
+  @JsonValue('completed')
+  completed,
+  @JsonValue('cancelled')
+  cancelled,
+  @JsonValue('noShow')
+  noShow,
+}
+
+enum ServiceType {
+  @JsonValue('maintenance')
+  maintenance,
+  @JsonValue('repair')
+  repair,
+  @JsonValue('inspection')
+  inspection,
+  @JsonValue('bodywork')
+  bodywork,
+  @JsonValue('insurance')
+  insurance,
+  @JsonValue('emergency')
+  emergency,
+  @JsonValue('recall')
+  recall,
+}
+
+enum ServiceStatus {
+  @JsonValue('waiting')
+  waiting,
+  @JsonValue('inProgress')
+  inProgress,
+  @JsonValue('completed')
+  completed,
+  @JsonValue('paused')
+  paused,
+  @JsonValue('cancelled')
+  cancelled,
+}
+
+enum ServiceStepStatus {
+  @JsonValue('pending')
+  pending,
+  @JsonValue('inProgress')
+  inProgress,
+  @JsonValue('completed')
+  completed,
+  @JsonValue('skipped')
+  skipped,
+}
+```
+
+### 5. 异常定义 (`src/exceptions/`)
+
+```dart
+abstract class AfterSalesException implements Exception {
+  final String message;
+  final String? code;
+  final dynamic details;
+  
+  const AfterSalesException(this.message, {this.code, this.details});
+  
+  @override
+  String toString() => 'AfterSalesException: $message';
+}
+
+class AppointmentException extends AfterSalesException {
+  const AppointmentException(String message, {String? code, dynamic details})
+      : super(message, code: code, details: details);
+}
+
+class ServiceException extends AfterSalesException {
+  const ServiceException(String message, {String? code, dynamic details})
+      : super(message, code: code, details: details);
+}
+
+class PaymentException extends AfterSalesException {
+  const PaymentException(String message, {String? code, dynamic details})
+      : super(message, code: code, details: details);
+}
+
+class NetworkException extends AfterSalesException {
+  const NetworkException(String message, {String? code, dynamic details})
+      : super(message, code: code, details: details);
+}
+
+class RepositoryException extends AfterSalesException {
+  const RepositoryException(String message, {String? code, dynamic details})
+      : super(message, code: code, details: details);
+}
+```
+
+### 6. 结果封装 (`src/utils/result.dart`)
+
+```dart
+@freezed
+class Result<T> with _$Result<T> {
+  const factory Result.success(T data) = Success<T>;
+  const factory Result.failure(Exception error) = Failure<T>;
+  
+  bool get isSuccess => this is Success<T>;
+  bool get isFailure => this is Failure<T>;
+  
+  T? get data => mapOrNull(success: (success) => success.data);
+  Exception? get error => mapOrNull(failure: (failure) => failure.error);
+}
+
+extension ResultExtensions<T> on Result<T> {
+  R fold<R>(
+    R Function(T data) onSuccess,
+    R Function(Exception error) onFailure,
+  ) {
+    return when(
+      success: onSuccess,
+      failure: onFailure,
+    );
+  }
+  
+  Future<Result<R>> mapAsync<R>(
+    Future<R> Function(T data) mapper,
+  ) async {
+    return fold(
+      (data) async {
+        try {
+          final result = await mapper(data);
+          return Result.success(result);
+        } catch (e) {
+          return Result.failure(Exception(e.toString()));
+        }
+      },
+      (error) => Future.value(Result.failure(error)),
+    );
+  }
+}
+```
+
+## 使用示例
+
+### 基础使用
+```dart
+class AfterSalesExample {
+  final AppointmentService _appointmentService;
+  final ServiceProgressService _progressService;
+  
+  AfterSalesExample(this._appointmentService, this._progressService);
+  
+  Future<void> createAppointmentExample() async {
+    final request = AppointmentCreateRequest(
+      storeId: 'store_123',
+      serviceType: ServiceType.maintenance,
+      appointmentTime: DateTime.now().add(Duration(days: 1)),
+      vehicleInfo: VehicleInfo(
+        vin: 'WVWAA71K08W201030',
+        licensePlate: '京A12345',
+        model: 'ID.4 CROZZ',
+      ),
+      description: '常规保养',
+    );
+    
+    final result = await _appointmentService.createAppointment(request);
+    
+    result.fold(
+      (appointment) {
+        print('预约创建成功: ${appointment.id}');
+      },
+      (error) {
+        print('预约创建失败: ${error.toString()}');
+      },
+    );
+  }
+  
+  Future<void> trackServiceProgressExample(String appointmentId) async {
+    final result = await _progressService.getServiceProgress(appointmentId);
+    
+    result.fold(
+      (progress) {
+        print('服务进度: ${progress.progressPercentage}%');
+        print('当前步骤: ${progress.steps.where((s) => s.status == ServiceStepStatus.inProgress).first.name}');
+      },
+      (error) {
+        print('获取进度失败: ${error.toString()}');
+      },
+    );
+  }
+}
+```
+
+### 依赖注入配置
+```dart
+class AfterSalesDI {
+  static void setupDependencies(GetIt locator) {
+    // 注册仓库
+    locator.registerLazySingleton<AppointmentRepository>(
+      () => AppointmentRepositoryImpl(
+        locator<LocalStorage>(),
+        locator<DatabaseHelper>(),
+      ),
+    );
+    
+    locator.registerLazySingleton<ServiceProgressRepository>(
+      () => ServiceProgressRepositoryImpl(
+        locator<LocalStorage>(),
+        locator<DatabaseHelper>(),
+      ),
+    );
+    
+    // 注册服务
+    locator.registerLazySingleton<AppointmentService>(
+      () => AppointmentService(
+        locator<AppointmentRepository>(),
+        locator<NetworkService>(),
+      ),
+    );
+    
+    locator.registerLazySingleton<ServiceProgressService>(
+      () => ServiceProgressService(
+        locator<ServiceProgressRepository>(),
+        locator<NetworkService>(),
+      ),
+    );
+  }
+}
+```
+
+## 测试策略
+
+### 单元测试
+```dart
+void main() {
+  group('AppointmentService', () {
+    late AppointmentService appointmentService;
+    late MockAppointmentRepository mockRepository;
+    late MockNetworkService mockNetworkService;
+    
+    setUp(() {
+      mockRepository = MockAppointmentRepository();
+      mockNetworkService = MockNetworkService();
+      appointmentService = AppointmentService(mockRepository, mockNetworkService);
+    });
+    
+    test('should create appointment successfully', () async {
+      // Arrange
+      final request = AppointmentCreateRequest(
+        storeId: 'store_123',
+        serviceType: ServiceType.maintenance,
+        appointmentTime: DateTime.now().add(Duration(days: 1)),
+        vehicleInfo: VehicleInfo(vin: 'TEST123'),
+      );
+      
+      final expectedAppointment = Appointment(
+        id: 'appointment_123',
+        userId: 'user_123',
+        storeId: request.storeId,
+        serviceType: request.serviceType,
+        appointmentTime: request.appointmentTime,
+        status: AppointmentStatus.pending,
+        vehicleInfo: request.vehicleInfo,
+      );
+      
+      when(mockNetworkService.post('/appointments', data: any))
+          .thenAnswer((_) async => ApiResponse(data: expectedAppointment.toJson()));
+      
+      // Act
+      final result = await appointmentService.createAppointment(request);
+      
+      // Assert
+      expect(result.isSuccess, true);
+      expect(result.data?.id, 'appointment_123');
+      verify(mockRepository.saveAppointment(any)).called(1);
+    });
+  });
+}
+```
+
+## 最佳实践
+
+### API设计原则
+1. **统一响应格式**: 所有API使用统一的响应格式
+2. **错误处理**: 完善的错误码和错误信息
+3. **数据验证**: 严格的输入数据验证
+4. **幂等性**: 关键操作支持幂等性
+
+### 缓存策略
+1. **多级缓存**: 内存缓存 + 本地存储 + 网络
+2. **缓存失效**: 基于时间和事件的缓存失效
+3. **数据一致性**: 保证缓存与服务器数据一致
+4. **离线支持**: 关键数据支持离线访问
+
+## 总结
+
+`clr_after_sales` 模块作为售后服务的核心SDK，通过完善的架构设计和标准化的接口封装，为售后服务应用提供了稳定可靠的技术支撑。模块采用了领域驱动设计思想，具有良好的可测试性和可维护性，能够支撑复杂的售后业务场景。