oneapp_docs/basic_uis/ui_business.md

# UI Business - 业务UI组件模块文档

## 模块概述

`ui_business` 是 OneApp 基础UI模块群中的业务UI组件库，提供与具体业务场景相关的UI组件和工具。该模块包含账户相关组件、订单相关组件、同意书组件等业务特定的界面元素和交互逻辑。

### 基本信息
- **模块名称**: ui_business
- **模块路径**: oneapp_basic_uis/ui_business
- **类型**: Flutter Package Module
- **主要功能**: 业务UI组件、账户组件、订单组件、同意书组件

### 核心特性
- **账户UI组件**: 提供登录、短信验证、证书拍照等账户相关UI
- **订单UI组件**: 订单相关的业务界面组件
- **同意书组件**: 用户协议和同意书相关UI
- **国际化支持**: 支持中英文多语言
- **表单验证**: 集成表单验证和数据处理
- **路由守卫**: 业务路由保护和权限控制

## 目录结构

```
ui_business/
├── lib/
│   ├── ui_account.dart            # 账户相关组件导出
│   ├── ui_order.dart             # 订单相关组件导出
│   ├── ui_consent.dart           # 同意书相关组件导出
│   ├── ui_common.dart            # 通用业务组件导出
│   ├── route_guard.dart          # 路由守卫
│   ├── customer_care.dart        # 客服相关
│   ├── poi_to_car.dart          # POI到车功能
│   ├── src/                      # 源代码目录
│   │   ├── ui_account/          # 账户相关组件
│   │   │   ├── widgets/         # 账户UI组件
│   │   │   │   ├── sms_auth/    # 短信验证组件
│   │   │   │   ├── check_spin/  # 验证转动组件
│   │   │   │   ├── certificates_photo/ # 证书拍照
│   │   │   │   └── time_picker/ # 时间选择器
│   │   │   ├── models/          # 账户数据模型
│   │   │   ├── mgmt/           # 账户管理
│   │   │   └── ui_config.dart  # UI配置
│   │   ├── ui_order/           # 订单相关组件
│   │   └── constants/          # 常量定义
│   ├── generated/              # 生成的国际化文件
│   └── l10n/                   # 国际化资源
├── assets/                     # 资源文件
└── pubspec.yaml               # 依赖配置
```

## 核心架构组件

### 1. 短信验证组件 (SmsAuthWidget)

提供短信验证码输入和验证功能的完整UI组件：

```dart
/// 短信验证组件
class SmsAuthWidget extends StatelessWidget {
  /// 构造器
  ///
  /// [verificationType] 验证码类型：1-登录注册 2-重置密码 3-设置/重置spin
  /// [callback] 事件回调
  /// [formKey] 表单键
  /// [onSubmitBtnLockChanged] 确认按钮锁定回调
  /// [smsCallbackOverride] 覆盖默认操作
  /// [lockPhoneEdit] 是否锁定手机号修改
  SmsAuthWidget({
    required this.verificationType,
    required this.formKey,
    required this.callback,
    required this.lockPhoneEdit,
    this.onSubmitBtnLockChanged,
    this.smsCallbackOverride,
    Key? key,
  }) : super(key: key);

  /// 默认超时时间
  static const defaultTimeout = 60;

  /// 类型：1-登录注册 2-重置密码 3-设置/重置spin
  final String verificationType;

  /// 表单键
  final SmsAuthFormKey formKey;

  /// 结果回调
  final void Function(SmsAuthResult result) callback;

  /// 确认按钮锁定状态变化回调
  final OnSubmitBtnLockChanged? onSubmitBtnLockChanged;

  /// 短信校验覆盖回调
  final SmsCallbackOverride? smsCallbackOverride;

  /// 是否锁定手机号修改
  final bool lockPhoneEdit;

  @override
  Widget build(BuildContext context) => BlocProvider(
        create: (ctx) => _bloc = SmsAuthBloc(smsCallbackOverride)
          ..add(const SmsAuthEvent.getLocalProfile()),
        child: BlocConsumer<SmsAuthBloc, SmsAuthState>(
          listener: _pageListener,
          builder: _createLayout,
        ),
      );
}
```

### 2. 回调类型定义

```dart
/// 确认按钮锁定状态变化回调
typedef OnSubmitBtnLockChanged = void Function(bool locked);

/// 用于覆盖短信校验接口的回调
typedef SmsCallbackOverride = Future<bool> Function(
  PhoneNumber phone,
  VerificationCode smsCode,
);
```

### 3. 手机号掩码扩展

```dart
extension _PhoneStringExtension on String {
  /// 手机号掩码显示，中间4位用*替换
  String get maskPhone {
    final buffer = StringBuffer();
    int i = 0;
    for (final c in characters) {
      if ([3, 4, 5, 6].contains(i)) {
        buffer.write('*');
      } else {
        buffer.write(c);
      }
      i++;
    }
    return buffer.toString();
  }
}
```

### 4. 通用项目组件 (ItemAComponent)

来自general_ui_component模块的通用组件：

```dart
/// 通用项目组件A
class ItemAComponent extends StatelessWidget {
  ItemAComponent({
    required this.title,
    required this.logoImg,
    required this.onItemAClick,
    required this.index,
    this.size,
  });

  /// Logo图片URL
  String logoImg = '';
  
  /// 标题文本
  String title = '';
  
  /// 点击回调
  OnItemAClick onItemAClick;
  
  /// 索引
  int index;
  
  /// 自定义尺寸
  double? size;

  @override
  Widget build(BuildContext context) {
    return InkWell(
      highlightColor: Colors.transparent,
      splashColor: Colors.transparent,
      child: Column(
        children: [
          Stack(
            alignment: Alignment.center,
            children: [
              Container(
                width: width(designWidgetWidth: 48),
                height: width(designWidgetWidth: 48),
                decoration: BoxDecoration(
                  shape: BoxShape.circle,
                  color: OneColors.bgcSub2,
                ),
              ),
              SizedBox(
                height: size ?? width(designWidgetWidth: 40),
                width: size ?? width(designWidgetWidth: 40),
                child: CacheImageComponent(
                  imageUrl: logoImg,
                ),
              ),
            ],
          ),
          Padding(
            padding: EdgeInsets.only(top: 5.0),
            child: Text(
              title,
              style: OneTextStyle.content(
                color: const Color(0xFF7C7F81),
              ),
            ),
          )
        ],
      ),
      onTap: () => onItemAClick(index),
    );
  }
}

typedef OnItemAClick = Function(int index);
```

## 使用指南

### 1. 短信验证组件使用

```dart
import 'package:ui_business/ui_account.dart';

class LoginPage extends StatefulWidget {
  @override
  _LoginPageState createState() => _LoginPageState();
}

class _LoginPageState extends State<LoginPage> {
  late SmsAuthFormKey _formKey;
  bool _submitBtnLocked = true;

  @override
  void initState() {
    super.initState();
    _formKey = SmsAuthFormKey();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('短信验证')),
      body: Padding(
        padding: EdgeInsets.all(16.0),
        child: Column(
          children: [
            SmsAuthWidget(
              verificationType: '1', // 登录注册类型
              formKey: _formKey,
              lockPhoneEdit: false,
              callback: _handleSmsResult,
              onSubmitBtnLockChanged: (locked) {
                setState(() {
                  _submitBtnLocked = locked;
                });
              },
            ),
            SizedBox(height: 20),
            ElevatedButton(
              onPressed: _submitBtnLocked ? null : _handleSubmit,
              child: Text('确认'),
            ),
          ],
        ),
      ),
    );
  }

  void _handleSmsResult(SmsAuthResult result) {
    switch (result.state) {
      case SmsAuthResultEnum.success:
        // 验证成功，处理登录逻辑
        print('验证成功，UUID: ${result.uuid}');
        Navigator.pushReplacementNamed(context, '/home');
        break;
      case SmsAuthResultEnum.failed:
        // 验证失败
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(content: Text('验证失败，请重试')),
        );
        break;
    }
  }

  void _handleSubmit() {
    // 触发表单验证和提交
    _formKey.controllerList.forEach((controller) => controller());
  }
}
```

### 2. 自定义短信验证回调

```dart
// 自定义短信验证逻辑
Future<bool> customSmsVerification(
  PhoneNumber phone, 
  VerificationCode smsCode
) async {
  try {
    // 调用自定义API进行验证
    final response = await MyApiService.verifySms(
      phone: phone.value,
      code: smsCode.value,
    );
    return response.success;
  } catch (e) {
    print('短信验证异常: $e');
    return false;
  }
}

// 使用自定义验证回调
SmsAuthWidget(
  verificationType: '1',
  formKey: _formKey,
  lockPhoneEdit: false,
  callback: _handleSmsResult,
  smsCallbackOverride: customSmsVerification, // 使用自定义验证
)
```

### 3. 通用组件列表使用

```dart
import 'package:general_ui_component/ItemAComponent.dart';

class ServiceListPage extends StatelessWidget {
  final List<ServiceItem> services = [
    ServiceItem('充电服务', 'assets/images/charging.png'),
    ServiceItem('维修保养', 'assets/images/maintenance.png'),
    ServiceItem('道路救援', 'assets/images/rescue.png'),
  ];

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('服务列表')),
      body: GridView.builder(
        padding: EdgeInsets.all(16.0),
        gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
          crossAxisCount: 3,
          childAspectRatio: 1.0,
          crossAxisSpacing: 16.0,
          mainAxisSpacing: 16.0,
        ),
        itemCount: services.length,
        itemBuilder: (context, index) {
          final service = services[index];
          return ItemAComponent(
            title: service.name,
            logoImg: service.iconUrl,
            index: index,
            onItemAClick: _handleServiceClick,
          );
        },
      ),
    );
  }

  void _handleServiceClick(int index) {
    final service = services[index];
    print('点击了服务: ${service.name}');
    // 处理服务点击逻辑
  }
}
```

### 4. 国际化支持

```dart
import 'package:ui_business/generated/l10n.dart';

class LocalizedWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text(S.of(context).smsVerificationPage_hint_code),
        Text(S.of(context).smsVerificationPage_btn_get),
      ],
    );
  }
}
```

## 依赖配置

### pubspec.yaml 关键依赖

```yaml
dependencies:
  flutter:
    sdk: flutter

  # 基础UI组件
  ui_basic:
    path: ../ui_basic
    
  # 基础工具
  basic_utils:
    path: ../../oneapp_basic_utils/basic_utils
    
  # 模块化路由
  basic_modular:
    path: ../../oneapp_basic_utils/basic_modular
    
  # 账户服务
  clr_account:
    path: ../../oneapp_account/clr_account
    
  # 状态管理
  flutter_bloc: ^8.0.0
  
  # 国际化
  flutter_localizations:
    sdk: flutter
  intl: ^0.17.0

dev_dependencies:
  # 国际化代码生成
  intl_utils: ^2.8.0
```

## 国际化配置

### l10n/intl_zh.arb (中文)
```json
{
  "smsVerificationPage_hint_code": "请输入验证码",
  "smsVerificationPage_btn_get": "获取验证码",
  "smsVerificationsPage_error_invalidCode": "验证码格式不正确"
}
```

### l10n/intl_en.arb (英文)
```json
{
  "smsVerificationPage_hint_code": "Please enter verification code",
  "smsVerificationPage_btn_get": "Get Code",
  "smsVerificationsPage_error_invalidCode": "Invalid verification code format"
}
```

## 表单验证

### SmsAuthFormKey 使用

```dart
class CustomFormPage extends StatefulWidget {
  @override
  _CustomFormPageState createState() => _CustomFormPageState();
}

class _CustomFormPageState extends State<CustomFormPage> {
  late SmsAuthFormKey _formKey;

  @override
  void initState() {
    super.initState();
    _formKey = SmsAuthFormKey();
  }

  @override
  Widget build(BuildContext context) {
    return Form(
      key: _formKey,
      child: Column(
        children: [
          // 表单字段
          ElevatedButton(
            onPressed: () {
              if (_formKey.validate()) {
                _formKey.save();
                // 使用表单数据
                print('手机号: ${_formKey.phone}');
                print('短信码: ${_formKey.sms}');
              }
            },
            child: Text('提交'),
          ),
        ],
      ),
    );
  }
}
```

## 最佳实践

### 1. 错误处理
```dart
// 推荐：完整的错误处理
void _handleSmsResult(SmsAuthResult result) {
  switch (result.state) {
    case SmsAuthResultEnum.success:
      // 成功处理
      _navigateToNextPage(result);
      break;
    case SmsAuthResultEnum.failed:
      // 失败处理，显示用户友好的错误信息
      _showErrorMessage('验证失败，请检查验证码是否正确');
      break;
    case SmsAuthResultEnum.timeout:
      // 超时处理
      _showErrorMessage('验证超时，请重新获取验证码');
      break;
  }
}
```

### 2. 资源管理
```dart
// 推荐：及时释放资源
@override
void dispose() {
  _formKey.dispose();
  super.dispose();
}
```

### 3. 无障碍支持
```dart
// 推荐：添加语义标签
Semantics(
  label: '验证码输入框',
  hint: '请输入6位数字验证码',
  child: SmsAuthWidget(
    // 配置参数
  ),
)
```

## 问题排查

### 常见问题
1. **验证码收不到**: 检查手机号格式和网络连接
2. **倒计时不工作**: 确认CountDownButton状态管理正确
3. **国际化文本不显示**: 检查l10n配置和S.of(context)使用

### 调试技巧
- 使用Flutter Inspector查看Widget树
- 检查BLoC状态变化日志
- 验证表单验证逻辑