AI_POC/oneapp_docs
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
40784642cf75964b71e2e822f47f1d107c640a41
oneapp_docs/account/clr_account.md
guangfei.zhao 40784642cf first commit
2025-09-24 14:08:54 +08:00

11 KiB
Raw Blame History

CLR Account 账户服务 SDK 文档

模块概述

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

基本信息

目录结构

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，提供了完整的用户认证和管理功能。模块采用清晰的分层架构，具有良好的可扩展性和可维护性，为整个应用的用户体系提供了坚实的基础。