oneapp_docs/app_car/app_avatar.md

# App Avatar - 虚拟形象模块文档

## 模块概述

`app_avatar` 是 OneApp 的虚拟形象管理模块，为用户提供个性化的虚拟车载助手服务。该模块集成了语音克隆技术、3D 虚拟形象渲染、支付服务等功能，让用户可以创建和定制自己的专属虚拟助手。

### 基本信息
- **模块名称**: app_avatar
- **版本**: 0.6.1+2
- **仓库**: https://gitlab-rd0.maezia.com/dssomobile/oneapp/dssomobile-oneapp-app-avatar
- **Flutter 版本**: >=3.0.0
- **Dart 版本**: >=2.16.2 <4.0.0

## 目录结构

```
app_avatar/
├── lib/
│   ├── app_avatar.dart           # 主导出文件
│   └── src/                      # 源代码目录
│       ├── avatar/               # 虚拟形象核心功能
│       │   ├── pages/           # 页面组件
│       │   │   ├── avatar_building/    # 形象生成页面
│       │   │   ├── avatar_copy/        # 形象复制页面
│       │   │   ├── avatar_display/     # 形象展示页面
│       │   │   ├── no_avatar/          # 未生成形象页面
│       │   │   ├── prepare_resource_page/ # 资源准备页面
│       │   │   ├── pta_camera/         # 拍照相机页面
│       │   │   ├── pta_sex_check/      # 性别确认页面
│       │   │   ├── rename/             # 重命名页面
│       │   │   └── server_data_dress_up/ # 捏脸界面
│       │   ├── provide_external/       # 对外提供组件
│       │   └── util/                   # 工具类
│       ├── common_import.dart          # 通用导入
│       └── route_export.dart           # 路由导出
├── assets/                             # 静态资源
├── pubspec.yaml                        # 依赖配置
└── README.md                           # 项目说明
```

## 核心功能模块

### 1. 主导出模块

**文件**: `lib/app_avatar.dart`

```dart
library app_avatar;
import 'package:basic_modular/modular.dart';
import 'package:basic_modular_route/basic_modular_route.dart';
import 'src/route_export.dart';

// 导出路由和对外组件
export 'src/route_export.dart';
export 'src/avatar/provide_external/in_use_avatar_icon.dart';
export 'src/avatar/provide_external/avatar_header.dart';
export 'src/avatar/util/config.dart';
export 'src/avatar/util/avatar_engine_manage.dart';

/// App Avatar 模块定义
class AppAvatarModule extends Module with RouteObjProvider {
  @override
  List<Module> get imports => [];

  @override
  List<Bind> get binds => [];

  @override
  List<ModularRoute> get routes {
    // 获取路由元数据
    final r1 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyHome);
    final r4 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyAvatarUiAvatarDisplayPage);
    final r7 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyAvatarUiPtaAvatarCamera);
    final r8 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyAvatarUiBuilding);
    final r10 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyAvatarUiDressUpServerDataPage);
    final r11 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyAvatarUiNonAvatar);
    final r12 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyAvatarUiRename);
    final r13 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyAvatarUiStep2GenderCheck);
    final r14 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyAvatarUiAvatarCopy);
    final r15 = RouteCenterAPI.routeMetaBy(AvatarRouteExport.keyAvatarUiPrepareResourcePage);
    
    // 返回子路由列表
    return [
      ChildRoute(r1.path, child: (_, args) => r1.provider(args).as()),
      ChildRoute(r4.path, child: (_, args) => r4.provider(args).as()),
      ChildRoute(r7.path, child: (_, args) => r7.provider(args).as()),
      ChildRoute(r8.path, child: (_, args) => r8.provider(args).as()),
      ChildRoute(r10.path, child: (_, args) => r10.provider(args).as()),
      ChildRoute(r11.path, child: (_, args) => r11.provider(args).as()),
      ChildRoute(r12.path, child: (_, args) => r12.provider(args).as()),
      ChildRoute(r13.path, child: (_, args) => r13.provider(args).as()),
      ChildRoute(r14.path, child: (_, args) => r14.provider(args).as()),
      ChildRoute(r15.path, child: (_, args) => r15.provider(args).as()),
    ];
  }
}
```

### 2. 路由导出管理

## 核心功能与实现

### 1. 页面路由系统

app_avatar 模块基于真实的路由系统实现，主要包含以下功能页面：

#### 核心页面组件
- **AvatarReplaceChild**: 虚拟形象展示页面
- **PtaAvatarCamera**: 拍照相机页面
- **AvatarBuildingPage**: 形象生成页面
- **DressUpServerDataPage**: 捏脸编辑页面
- **AvatarCopy**: 形象复制页面
- **NonAvatar**: 非形象页面

#### 页面导航实现
```dart
// 页面跳转示例
class AvatarNavigationHelper {
  // 跳转到虚拟形象展示页面
  static void gotoAvatarDisplay() {
    Modular.to.pushNamed('/avatar/avatarDisplayPage');
  }
  
  // 跳转到拍照创建页面
  static void gotoPtaCamera() {
    Modular.to.pushNamed('/avatar/PtaAvatarCamera');
  }
  
  // 跳转到捏脸编辑页面
  static void gotoDressUp() {
    Modular.to.pushNamed('/avatar/DressUpServerDataPage');
  }
  
  // 跳转到形象生成页面
  static void gotoAvatarBuilding({
    required String sex,
    required String name,
    required String photoPath,
  }) {
    Modular.to.pushNamed('/avatar/AvatarBuildingPage', arguments: {
      'sex': sex,
      'name': name,
      'photoPath': photoPath,
    });
  }
}
```

### 2. 模块架构设计

#### 基本模块结构
```dart
// 模块入口点
class AppAvatarModule extends Module implements RouteObjProvider {
  @override
  List<Bind> get binds => [
    // 依赖注入配置将在这里定义
  ];
  
  @override
  List<ModularRoute> get routes => [
    // 路由配置通过 AvatarRouteExport 管理
  ];
  
  @override
  RouteCenterAPI? get routeObj => RouteCenterAPI(
    routeExporter: AvatarRouteExport(),
  );
}
```

#### 页面状态管理
```dart
// 简化的页面状态管理
class AvatarPageState {
  final bool isLoading;
  final String? errorMessage;
  final Map<String, dynamic> data;
  
  const AvatarPageState({
    this.isLoading = false,
    this.errorMessage,
    this.data = const {},
  });
  
  AvatarPageState copyWith({
    bool? isLoading,
    String? errorMessage,
    Map<String, dynamic>? data,
  }) {
    return AvatarPageState(
      isLoading: isLoading ?? this.isLoading,
      errorMessage: errorMessage ?? this.errorMessage,
      data: data ?? this.data,
    );
  }
}
```

### 3. 核心功能实现

#### 虚拟形象创建流程
虚拟形象创建遵循以下步骤：

1. **用户拍照**: 通过 `PtaAvatarCamera` 页面获取用户照片
2. **信息确认**: 收集用户基本信息（姓名、性别等）
3. **形象生成**: `AvatarBuildingPage` 显示生成进度
4. **结果展示**: `AvatarReplaceChild` 展示最终形象

#### 形象管理功能
- **形象展示**: 3D/2D 虚拟形象渲染展示
- **形象编辑**: 通过捏脸系统进行外观定制
- **形象切换**: 支持多个虚拟形象间的切换
- **形象分享**: 虚拟形象内容的分享功能

### 4. 数据模型定义

#### 基础数据结构
```dart
// 虚拟形象基本信息
class AvatarInfo {
  final String id;
  final String name;
  final String sex;
  final String photoPath;
  final DateTime createdAt;
  final Map<String, dynamic> customData;
  
  const AvatarInfo({
    required this.id,
    required this.name,
    required this.sex,
    required this.photoPath,
    required this.createdAt,
    this.customData = const {},
  });
  
  Map<String, dynamic> toMap() {
    return {
      'id': id,
      'name': name,
      'sex': sex,
      'photoPath': photoPath,
      'createdAt': createdAt.toIso8601String(),
      'customData': customData,
    };
  }
  
  factory AvatarInfo.fromMap(Map<String, dynamic> map) {
    return AvatarInfo(
      id: map['id'] ?? '',
      name: map['name'] ?? '',
      sex: map['sex'] ?? '',
      photoPath: map['photoPath'] ?? '',
      createdAt: DateTime.parse(map['createdAt'] ?? DateTime.now().toIso8601String()),
      customData: map['customData'] ?? const {},
    );
  }
}

// 形象配置信息
class AvatarConfiguration {
  final String avatarId;
  final Map<String, dynamic> appearanceConfig;
  final Map<String, dynamic> behaviorConfig;
  final DateTime updatedAt;
  
  const AvatarConfiguration({
    required this.avatarId,
    required this.appearanceConfig,
    required this.behaviorConfig,
    required this.updatedAt,
  });
}
```

### 5. UI 组件实现

#### 通用 UI 组件
```dart
// 形象展示组件
class AvatarDisplayWidget extends StatelessWidget {
  final AvatarInfo avatarInfo;
  final VoidCallback? onTap;
  
  const AvatarDisplayWidget({
    Key? key,
    required this.avatarInfo,
    this.onTap,
  }) : super(key: key);
  
  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: onTap,
      child: Container(
        width: 200,
        height: 300,
        decoration: BoxDecoration(
          borderRadius: BorderRadius.circular(10),
          border: Border.all(color: Colors.grey.shade300),
        ),
        child: Column(
          children: [
            Expanded(
              child: Container(
                decoration: BoxDecoration(
                  borderRadius: BorderRadius.vertical(top: Radius.circular(10)),
                  image: avatarInfo.photoPath.isNotEmpty
                    ? DecorationImage(
                        image: FileImage(File(avatarInfo.photoPath)),
                        fit: BoxFit.cover,
                      )
                    : null,
                ),
                child: avatarInfo.photoPath.isEmpty
                  ? Center(child: Icon(Icons.person, size: 50, color: Colors.grey))
                  : null,
              ),
            ),
            Container(
              padding: EdgeInsets.all(8),
              child: Text(
                avatarInfo.name,
                style: TextStyle(fontSize: 16, fontWeight: FontWeight.bold),
              ),
            ),
          ],
        ),
      ),
    );
  }
}

// 操作按钮组件
class AvatarActionButton extends StatelessWidget {
  final String label;
  final IconData icon;
  final VoidCallback onPressed;
  final bool isLoading;
  
  const AvatarActionButton({
    Key? key,
    required this.label,
    required this.icon,
    required this.onPressed,
    this.isLoading = false,
  }) : super(key: key);
  
  @override
  Widget build(BuildContext context) {
    return ElevatedButton.icon(
      onPressed: isLoading ? null : onPressed,
      icon: isLoading 
        ? SizedBox(
            width: 16, 
            height: 16, 
            child: CircularProgressIndicator(strokeWidth: 2)
          )
        : Icon(icon),
      label: Text(label),
      style: ElevatedButton.styleFrom(
        padding: EdgeInsets.symmetric(horizontal: 24, vertical: 12),
        shape: RoundedRectangleBorder(
          borderRadius: BorderRadius.circular(8),
        ),
      ),
    );
  }
}
```

### 6. 错误处理与异常管理

#### 异常定义
```dart
// 虚拟形象相关异常
abstract class AvatarException implements Exception {
  final String message;
  const AvatarException(this.message);
  
  @override
  String toString() => 'AvatarException: $message';
}

class AvatarCreationException extends AvatarException {
  const AvatarCreationException(String message) : super(message);
}

class AvatarLoadException extends AvatarException {
  const AvatarLoadException(String message) : super(message);
}

class AvatarSaveException extends AvatarException {
  const AvatarSaveException(String message) : super(message);
}
```

#### 错误处理机制
```dart
// 错误处理工具类
class AvatarErrorHandler {
  static void handleError(
    BuildContext context,
    Exception error, {
    VoidCallback? onRetry,
  }) {
    String message = '发生未知错误';
    
    if (error is AvatarException) {
      message = error.message;
    }
    
    showDialog(
      context: context,
      builder: (context) => AlertDialog(
        title: Text('错误'),
        content: Text(message),
        actions: [
          if (onRetry != null)
            TextButton(
              onPressed: () {
                Navigator.of(context).pop();
                onRetry();
              },
              child: Text('重试'),
            ),
          TextButton(
            onPressed: () => Navigator.of(context).pop(),
            child: Text('确定'),
          ),
        ],
      ),
    );
  }
}
```
## 技术架构与设计模式

### 1. 模块化架构

app_avatar 模块采用标准的 OneApp 模块化架构：

- **模块定义**: `AppAvatarModule` 继承自 `Module` 并实现 `RouteObjProvider`
- **路由管理**: 通过 `AvatarRouteExport` 统一管理所有路由
- **依赖注入**: 使用 basic_modular 的依赖注入机制
- **页面组织**: 按功能分组的页面结构

### 2. 核心功能实现

#### 虚拟形象创建流程
1. **拍照页面**: 用户使用相机拍摄照片
2. **信息填写**: 确认性别和姓名信息
3. **形象生成**: 后台处理生成虚拟形象
4. **形象展示**: 展示生成结果

#### 形象管理功能
- **形象展示**: 3D/2D 虚拟形象渲染
- **形象编辑**: 捏脸和装扮功能
- **形象复制**: 形象模板复制功能
- **重命名**: 形象名称管理

### 3. 与其他模块集成

```dart
// 集成示例 - 从其他模块跳转到虚拟形象相关页面
class AvatarNavigationHelper {
  // 跳转到虚拟形象展示页面
  static void gotoAvatarDisplay() {
    Modular.to.pushNamed('/avatar/avatarDisplayPage');
  }
  
  // 跳转到拍照创建页面
  static void gotoPtaCamera() {
    Modular.to.pushNamed('/avatar/PtaAvatarCamera');
  }
  
  // 跳转到捏脸编辑页面
  static void gotoDressUp() {
    Modular.to.pushNamed('/avatar/DressUpServerDataPage');
  }
}
```

## 依赖管理与技术栈

### 核心依赖
- **basic_modular**: 模块化框架
- **basic_modular_route**: 路由管理
- **flutter**: Flutter 框架

### UI 组件
- **Material Design**: 基础 UI 组件
- **Custom Widgets**: 虚拟形象专用组件

### 数据存储
- **SharedPreferences**: 配置信息本地存储
- **文件系统**: 图片和资源文件存储

## 最佳实践与规范

### 1. 代码组织
- 页面文件统一放在 `src/avatar/pages/` 目录
- 按功能模块分别组织（拍照、生成、编辑、展示）
- 对外组件放在 `provide_external` 目录

### 2. 路由管理
- 采用 `RouteExporter` 接口统一路由导出
- 使用 `RouteMeta` 配置路由元数据
- 支持路由参数传递和嵌套路由

### 3. 用户体验优化
- 流畅的页面转场动画
- 友好的加载进度提示
- 响应式布局适配不同屏幕

### 4. 性能优化
- 合理的资源加载和释放
- 动画性能优化
- 内存使用管理