first commit
This commit is contained in:
512
account/clr_account.md
Normal file
512
account/clr_account.md
Normal file
@@ -0,0 +1,512 @@
|
||||
# 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)
|
||||
|
||||
#### 功能概述
|
||||
- 用户登录/登出
|
||||
- 密码认证
|
||||
- 生物识别认证
|
||||
- 多因素认证
|
||||
|
||||
#### 主要接口
|
||||
```dart
|
||||
// 基于实际项目的认证门面接口
|
||||
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)
|
||||
|
||||
#### 功能概述
|
||||
- 新用户注册
|
||||
- 手机号验证
|
||||
- 邮箱验证
|
||||
- 用户信息收集
|
||||
|
||||
#### 主要接口
|
||||
```dart
|
||||
// 基于实际项目的配置文件门面接口
|
||||
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)
|
||||
|
||||
#### 功能概述
|
||||
- 个人信息查看和编辑
|
||||
- 头像管理
|
||||
- 偏好设置
|
||||
- 隐私设置
|
||||
|
||||
#### 主要接口
|
||||
```dart
|
||||
// 基于实际项目的车库门面接口
|
||||
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)
|
||||
|
||||
#### 功能概述
|
||||
- 角色权限管理
|
||||
- 功能权限控制
|
||||
- 资源访问控制
|
||||
|
||||
#### 主要接口
|
||||
```dart
|
||||
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 事件总线系统，使用真实的账户事件处理机制。
|
||||
|
||||
```dart
|
||||
// 实际项目中的事件处理示例（从 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 接口设计
|
||||
|
||||
### 认证接口
|
||||
```dart
|
||||
// 登录
|
||||
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"
|
||||
}
|
||||
```
|
||||
|
||||
### 用户信息接口
|
||||
```dart
|
||||
// 获取用户信息
|
||||
GET /api/v1/user/profile
|
||||
|
||||
// 更新用户信息
|
||||
PUT /api/v1/user/profile
|
||||
{
|
||||
"nickname": "string",
|
||||
"avatar": "string",
|
||||
"birthday": "string"
|
||||
}
|
||||
```
|
||||
|
||||
## 安全特性
|
||||
|
||||
### 数据安全
|
||||
- 密码哈希存储
|
||||
- 敏感信息加密
|
||||
- 通信 HTTPS 加密
|
||||
|
||||
### 认证安全
|
||||
- JWT 令牌机制
|
||||
- 令牌过期机制
|
||||
- 设备绑定验证
|
||||
|
||||
### 隐私保护
|
||||
- 用户同意管理
|
||||
- 数据最小化收集
|
||||
- 隐私设置支持
|
||||
|
||||
## 错误处理
|
||||
|
||||
### 错误分类
|
||||
- 网络错误
|
||||
- 认证错误
|
||||
- 业务逻辑错误
|
||||
- 系统错误
|
||||
|
||||
### 错误处理策略
|
||||
基于实际项目中的异常处理模式，使用 Functional Programming 的 Either 模式。
|
||||
|
||||
```dart
|
||||
// 实际项目中的异常处理示例
|
||||
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，提供了完整的用户认证和管理功能。模块采用清晰的分层架构，具有良好的可扩展性和可维护性，为整个应用的用户体系提供了坚实的基础。
|
||||
Reference in New Issue
Block a user