oneapp_docs/account/clr_account.md

CLR Account 账户服务 SDK 文档

模块概述

clr_account 是 OneApp 账户系统的核心 SDK，提供用户认证、登录、注册、权限管理等基础服务。该模块采用领域驱动设计（DDD）架构，提供清晰的接口抽象和业务逻辑封装。

基本信息

• 模块名称: clr_account
• 版本: 0.2.24
• 仓库: https://gitlab-rd0.maezia.com/dssomobile/oneapp/dssomobile-oneapp-clr-account

目录结构

clr_account/
├── lib/
│   ├── account.dart              # 主要导出文件
│   ├── account_event.dart        # 账户事件定义
│   ├── third_account.dart        # 第三方账户集成
│   ├── generated/                # 代码生成文件
│   ├── l10n/                     # 国际化文件
│   └── src/                      # 源代码目录
│       ├── data/                 # 数据层
│       ├── domain/               # 领域层
│       ├── presentation/         # 表示层
│       └── infrastructure/       # 基础设施层
├── pubspec.yaml                  # 依赖配置
└── README.md                     # 项目说明

核心功能模块

1. 账户认证 (Authentication)

功能概述

• 用户登录/登出
• 密码认证
• 生物识别认证
• 多因素认证

主要接口

// 基于实际项目的认证门面接口
abstract class IAuthFacade {
  /// 当前登录状态
  bool get isLogin;
  
  /// 用户登出
  Future<void> logout();
  
  /// 撤销注销
  Future<Either<AuthFailure, Unit>> undoSignOut(String refCode);
}

// 实际的认证异常类型
sealed class AuthFailure {
  const AuthFailure();
}

class OtherError extends AuthFailure {
  final dynamic error;
  const OtherError(this.error);
}

2. 用户注册 (Registration)

功能概述

• 新用户注册
• 手机号验证
• 邮箱验证
• 用户信息收集

主要接口

// 基于实际项目的配置文件门面接口
abstract class IProfileFacade {
  /// 获取本地用户配置文件
  Either<ProfileFailure, UserProfile> getUserProfileLocal();
  
  /// 从云端获取用户配置文件
  Future<Either<ProfileFailure, UserProfile>> fetchUserProfile();
}

// 实际的配置文件异常类型
sealed class ProfileFailure {
  const ProfileFailure();
}

// 实际的用户配置模型
class UserProfile {
  final String id;
  final String name;
  final String email;
  final String? avatar;
  
  const UserProfile({
    required this.id,
    required this.name,
    required this.email,
    this.avatar,
  });
}

3. 用户信息管理 (Profile)

功能概述

• 个人信息查看和编辑
• 头像管理
• 偏好设置
• 隐私设置

主要接口

// 基于实际项目的车库门面接口
abstract class IGarageFacade {
  /// 获取车库绑车列表
  /// [refresh]为 true 则强制从网络获取，并刷新本地数据
  Future<Either<GarageFailure, List<VehicleDto>>> getEnrollmentVehicleList({
    bool refresh = false,
    bool local = false,
  });
  
  /// 获取默认车辆
  Future<Either<GarageFailure, VehicleDto?>> getDefaultEnrolledVehicle({
    bool refresh = false,
  });
  
  /// 快速获取默认车辆
  VehicleDto? getDefaultVehicleLocal();
  
  /// 设置车辆是否默认
  Future<Either<GarageFailure, bool>> setVehicleDefault({
    required String vin,
    required bool isDefault,
  });
  
  /// 修改车牌号
  Future<Either<GarageFailure, bool>> setVehiclePlateNo(
    String plateNo,
    String vin,
  );
  
  /// 扫码登录车机
  Future<Either<GarageFailure, Unit>> signInHUWithQrCode({
    required String uuid,
    required int? timestamp,
    required String? signature,
  });
}

// 实际的车辆数据传输对象
class VehicleDto {
  final String vin;
  final String? plateNo;
  final VehicleModel vehicleModel;
  final String accountType;
  
  const VehicleDto({
    required this.vin,
    this.plateNo,
    required this.vehicleModel,
    required this.accountType,
  });
  
  static const String accountTypeP = 'P'; // 主账户
  static const String accountTypeS = 'S'; // 从账户
}

4. 权限管理 (Authorization)

功能概述

• 角色权限管理
• 功能权限控制
• 资源访问控制

主要接口

abstract class AuthorizationService {
  Future<Result<bool>> hasPermission(String permission);
  Future<Result<List<String>>> getUserRoles();
  Future<Result<bool>> canAccessResource(String resource);
}

技术架构

分层架构

1. 表示层 (Presentation Layer)

• 功能: 用户界面相关的状态管理和事件处理
• 组件:
  • Widget 组件
  • State 管理
  • Event 处理器

2. 领域层 (Domain Layer)

• 功能: 业务逻辑和业务规则
• 组件:
  • Entity 实体
  • Value Object 值对象
  • Domain Service 领域服务
  • Repository 接口

3. 数据层 (Data Layer)

• 功能: 数据访问和存储
• 组件:
  • Repository 实现
  • Data Source 数据源
  • Model 数据模型

4. 基础设施层 (Infrastructure Layer)

• 功能: 外部服务集成
• 组件:
  • 网络服务
  • 存储服务
  • 第三方 SDK 集成

状态管理

事件驱动架构

基于 OneApp 事件总线系统，使用真实的账户事件处理机制。

// 实际项目中的事件处理示例（从 PersonalCenterBloc）
class PersonalCenterBloc extends Bloc<PersonalCenterEvent, PersonalCenterState> {
  PersonalCenterBloc(
    this._signInFacade,
    this._profileFacade,
    this._garageFacade,
  ) : super(PersonalCenterState.initial()) {
    // 监听推送事件
    _eventListener = pushFacade.subscribeOn(
      topics: [
        userProfileChangedTopic,
        logoutTopic,
        loginSuccessTopic,
        loginFailedTopic,
      ],
    ).listen((event) async {
      // 当收到用户信息更变、登出事件、登录成功事件时，重新加载用户信息
      if (event.topic == logoutTopic || event.topic == loginSuccessTopic) {
        OneAppEventBus.fireEvent(UserLoginEvent(loginType: LoginOutType.all));
        add(const PersonalCenterEvent.loadUserProfile());
        add(const PersonalCenterEvent.loadSocialInfor());
      }
    });
    
    // 监听积分变更事件
    _pointsChageEvent = OneAppEventBus.addListen<PointsChangeEvent>((event) {
      add(const PersonalCenterEvent.loadUserPoints());
    });
  }
}

// 实际的账户事件类型
abstract class AccountEvent {
  const AccountEvent();
}

class UserLoginEvent extends AccountEvent {
  final LoginOutType loginType;
  const UserLoginEvent({required this.loginType});
}

enum LoginOutType { all }

数据持久化

本地存储

• 基于 basic_storage 的统一存储接口
• 用户信息安全存储
• 登录凭证加密存储

缓存策略

• 用户信息内存缓存
• 权限信息缓存
• 网络请求缓存

依赖关系

核心依赖

• basic_network: 网络请求服务
• basic_storage: 本地存储服务
• basic_modular: 模块化框架
• basic_error: 错误处理
• basic_consent: 用户同意管理

第三方集成

• fluwx: 微信 SDK 集成
• dartz: 函数式编程支持
• freezed_annotation: 不可变类生成

业务依赖

• clr_setting: 设置服务
• basic_track: 埋点追踪
• basic_webview: WebView 服务

API 接口设计

认证接口

// 登录
POST /api/v1/auth/login
{
  "username": "string",
  "password": "string",
  "deviceId": "string"
}

// 登出
POST /api/v1/auth/logout
{
  "token": "string"
}

// 刷新令牌
POST /api/v1/auth/refresh
{
  "refreshToken": "string"
}

用户信息接口

// 获取用户信息
GET /api/v1/user/profile

// 更新用户信息
PUT /api/v1/user/profile
{
  "nickname": "string",
  "avatar": "string",
  "birthday": "string"
}

安全特性

数据安全

• 密码哈希存储
• 敏感信息加密
• 通信 HTTPS 加密

认证安全

• JWT 令牌机制
• 令牌过期机制
• 设备绑定验证

隐私保护

• 用户同意管理
• 数据最小化收集
• 隐私设置支持

错误处理

错误分类

• 网络错误
• 认证错误
• 业务逻辑错误
• 系统错误

错误处理策略

基于实际项目中的异常处理模式，使用 Functional Programming 的 Either 模式。

// 实际项目中的异常处理示例
sealed class AuthFailure {
  const AuthFailure();
}

class OtherError extends AuthFailure {
  final dynamic error;
  const OtherError(this.error);
}

sealed class ProfileFailure {
  const ProfileFailure();
}

sealed class GarageFailure {
  const GarageFailure();
}

// 错误处理方法示例（来自 PersonalCenterBloc）
void _onLoginFailed(LoginFailure failure) {
  final authFailure = failure.cause;
  
  if (authFailure is OtherError) {
    // 其他异常
    _handleOtherAuthFailure(authFailure.error);
  }
}

void _handleOtherAuthFailure(dynamic error) {
  if (error is ErrorGlobalBusiness) {
    // 云端异常
    final Map<String, dynamic> errorConfig = error.errorConfig;
    final String? originalCode = errorConfig['originalCode'] as String?;
    
    // 处理特定错误码
    if (originalCode == '10444105') {
      // 预注销状态处理
      _showPreSignOutDialog(/*参数*/);
    }
  }
}

// 使用 Either 模式的接口返回值
Future<Either<ProfileFailure, UserProfile>> fetchUserProfile();
Future<Either<GarageFailure, List<VehicleDto>>> getEnrollmentVehicleList();
Future<Either<AuthFailure, Unit>> undoSignOut(String refCode);

国际化支持

支持语言

• 中文（简体）
• 英文
• 其他地区语言扩展

配置方式

• 基于 basic_intl 的国际化框架
• 动态语言切换
• 文本资源管理

测试策略

单元测试

• 领域逻辑测试
• 服务接口测试
• 工具类测试

集成测试

• API 接口测试
• 数据存储测试
• 第三方服务集成测试

UI 测试

• 登录流程测试
• 注册流程测试
• 用户信息管理测试

性能优化

网络优化

• 请求缓存
• 批量请求
• 网络重试机制

内存优化

• 对象池管理
• 图片缓存优化
• 内存泄漏防护

启动优化

• 懒加载机制
• 预加载策略
• 冷启动优化

监控与统计

用户行为统计

• 登录成功率
• 注册转化率
• 功能使用统计

性能监控

• 接口响应时间
• 错误率统计
• 崩溃率监控

业务指标

• 活跃用户数
• 用户留存率
• 功能使用频次

开发指南

环境搭建

1. 安装 Flutter SDK >=2.10.5
2. 配置依赖项目路径
3. 运行 flutter pub get

代码规范

• 遵循 Dart 编码规范
• 使用 analysis_options.yaml 静态分析
• 提交前代码格式化

调试技巧

• 使用 basic_logger 记录日志
• 网络请求调试
• 状态变更追踪

版本历史

v0.2.24 (当前版本)

• 支持微信登录集成
• 优化用户信息缓存机制
• 增强安全认证流程

后续规划

• 支持更多第三方登录
• 增强生物识别认证
• 优化性能和用户体验

总结

clr_account 作为 OneApp 的账户核心 SDK，提供了完整的用户认证和管理功能。模块采用清晰的分层架构，具有良好的可扩展性和可维护性，为整个应用的用户体系提供了坚实的基础。