# 风七六用户端架构标准规范说明书

> 本文档作为骑手端改造的唯一参考标准

---

## 1. 目录结构规范

### 1.1 完整目录结构

```
lib/
├── assets/              # 静态资源
│   └── legal/           # 法律文档
├── components/          # 可复用 UI 组件
├── config/             # 应用配置
├── features/           # 特性模块（可选）
├── l10n/               # 国际化
├── middlewares/        # 中间件
├── models/            # 数据模型
├── providers/         # Provider 状态管理
├── repositories/      # 数据仓库层
├── router/            # 路由配置
├── screens/           # 页面
├── services/          # 服务层
├── theme/             # 主题
├── utils/             # 工具类
├── viewmodels/        # ViewModel 层
└── main.dart          # 入口文件
```

### 1.2 核心目录职责

- **components/**: 纯 UI 组件，无业务逻辑
- **config/**: 应用配置、API 配置
- **models/**: 数据模型，包含 fromJson/toJson
- **providers/**: 全局状态管理
- **repositories/**: 数据仓库，负责数据获取
- **services/**: 服务层（API、存储、定位等）
- **viewmodels/**: 视图模型，连接 UI 和 Repository
- **screens/**: 页面，只负责 UI 渲染
- **utils/**: 工具函数

---

## 2. 各层职责规范

### 2.1 ViewModel 层

**职责**: 业务逻辑处理、状态管理

**标准实现** ([base_viewmodel.dart](d:\FzxBDSH\frontend\user_app\lib\viewmodels\base_viewmodel.dart)):

```dart
abstract class BaseViewModel extends ChangeNotifier {
  bool _isLoading = false;
  String? _errorMessage;
  DateTime? _lastRefreshTime;

  // 标准方法
  void setLoading(bool loading) { ... }
  void setError(String? message) { ... }
  void reset() { ... }
}
```

**文件命名**: `*_viewmodel.dart`

**示例**: `home_viewmodel.dart`, `order_viewmodel.dart`

### 2.2 Repository 层

**职责**: 数据获取、缓存管理、错误处理

**标准实现** ([base_repository.dart](d:\FzxBDSH\frontend\user_app\lib\repositories\base_repository.dart)):

```dart
abstract class BaseRepository {
  final ApiClient apiClient;
  final CacheService? cacheService;
  final String cacheKeyPrefix;

  // 标准方法
  Future<Result<T>> safeExecute<T>(...);
  Future<Result<T>> executeWithCache<T>(...);
}
```

**文件命名**: `*_repository.dart`

### 2.3 Provider 层

**职责**: 全局状态管理、跨页面状态共享

**文件命名**: `*_provider.dart`

### 2.4 Service 层

**职责**: 封装第三方服务、基础设施服务

**标准服务**:

- `api_client.dart` - 统一 API 客户端
- `secure_storage_service.dart` - 安全存储
- `cache_service.dart` - 缓存服务
- `location_service.dart` - 定位服务

### 2.5 Screen/Widget 层

**职责**: UI 渲染、事件处理

**原则**: 只处理 UI 展示，业务逻辑委托给 ViewModel

---

## 3. 状态管理规范

### 3.1 Provider 注册

**标准注册方式** ([main.dart](d:\FzxBDSH\frontend\user_app\lib\main.dart)):

```dart
MultiProvider(
  providers: [
    ChangeNotifierProvider(create: (_) => AuthProvider()),
    ChangeNotifierProvider(create: (_) => UserProvider()),
    // ...
  ],
  child: MaterialApp.router(...)
)
```

### 3.2 状态使用

```dart
// 读取状态
final userProvider = context.watch<UserProvider>();

// 读取不监听
final authProvider = context.read<AuthProvider>();

// Selective 监听
final userName = context.select<UserProvider, String>(
  (provider) => provider.user?.name ?? '',
);
```

---

## 4. 网络请求规范

### 4.1 ApiClient 标准

**标准实现** ([api_client.dart](d:\FzxBDSH\frontend\user_app\lib\services\api_client.dart)):

```dart
class ApiClient {
  static ApiClient? _instance;
  late final Dio _dio;

  // 拦截器职责
  // - 请求：添加 Token、设备信息、签名
  // - 响应：业务状态码检查
  // - 错误：统一错误处理、认证错误处理

  // 标准方法
  Future<T> get<T>(...);
  Future<T> post<T>(...);
  Future<T> put<T>(...);
  Future<T> delete<T>(...);
}
```

### 4.2 错误处理

**标准错误类** ([errors.dart](d:\FzxBDSH\frontend\user_app\lib\utils\errors.dart)):

```dart
enum ErrorType { network, authentication, authorization, ... }

class AppError implements Exception {
  final ErrorType type;
  final String message;
  final int? code;
}

class Result<T> {
  final T? data;
  final AppError? error;
  final bool isSuccess;
}
```

---

## 5. 数据模型规范

### 5.1 标准模型结构

```dart
class User {
  final String id;
  final String name;
  final String? avatar;

  User({
    required this.id,
    required this.name,
    this.avatar,
  });

  factory User.fromJson(Map<String, dynamic> json) { ... }

  Map<String, dynamic> toJson() { ... }

  User copyWith({
    String? id,
    String? name,
    String? avatar,
  }) { ... }
}
```

### 5.2 命名规范

- 使用 `camelCase` 命名字段
- 对应 JSON 字段使用 `snake_case`
- 可选字段使用 `?` 类型

---

## 6. 代码风格规范

### 6.1 命名规范

| 类型    | 规范                                    | 示例                              |
|-------|---------------------------------------|---------------------------------|
| 文件    | `snake_case`                          | `user_profile.dart`             |
| 类     | `PascalCase`                          | `UserProfileScreen`             |
| 函数/方法 | `camelCase`                           | `getUserProfile()`              |
| 常量    | `lowerCamelCase` 或 `UPPER_SNAKE_CASE` | `apiTimeout`, `MAX_RETRY_COUNT` |
| 私有字段  | `_camelCase`                          | `_isLoading`                    |

### 6.2 导入顺序

```dart
// 1. Dart SDK
import 'dart:async';

// 2. Flutter
import 'package:flutter/material.dart';

// 3. 第三方依赖
import 'package:provider/provider.dart';

// 4. 内部依赖
import 'package:user_app/utils/app_logger.dart';
import 'package:user_app/config/app_config.dart';
```

### 6.3 注释规范

- 公共 API 使用 `///` 文档注释
- 复杂逻辑使用 `//` 行注释
- 不写无意义的注释

---

## 7. 安全规范

### 7.1 加密存储

**标准实现** ([secure_storage_service.dart](d:\FzxBDSH\frontend\user_app\lib\services\secure_storage_service.dart)):

```dart
class SecureStorageService {
  static const AndroidOptions _androidOptions = AndroidOptions(
    encryptedSharedPreferences: true,
  );

  // 标准存储键
  static const String _keyAuthToken = 'auth_token';
  static const String _keyRefreshToken = 'refresh_token';

  // 标准方法
  static Future<void> saveToken(String token);
  static Future<String?> getToken();
  static Future<void> deleteToken();
}
```

### 7.2 日志脱敏

**标准实现** ([app_logger.dart](d:\FzxBDSH\frontend\user_app\lib\utils\app_logger.dart)):

- 敏感字段自动脱敏：`password`, `token`, `secret`, `creditCard`
- API 请求/响应自动脱敏
- 手机号、身份证号脱敏

### 7.3 请求签名

- 添加 `X-Timestamp` 时间戳
- 添加 `X-Nonce` 随机串
- 添加 `X-Sign` SHA256 签名

---

## 8. 工具命令规范

### 8.1 静态分析

```bash
flutter analyze
```

**目标**: 0 issues

### 8.2 依赖管理

```bash
flutter pub get          # 获取依赖
flutter pub upgrade      # 升级依赖
flutter pub outdated     # 检查过期依赖
```

### 8.3 构建

```bash
# Android
flutter build apk --release

# iOS
flutter build ios --release
```

### 8.4 测试

```bash
flutter test              # 运行所有测试
flutter test --coverage   # 生成覆盖率报告
```

---

## 9. 核心依赖列表

| 依赖                       | 版本      | 用途   |
|--------------------------|---------|------|
| `provider`               | ^6.1.2  | 状态管理 |
| `dio`                    | ^5.4.3  | 网络请求 |
| `flutter_secure_storage` | ^9.2.2  | 安全存储 |
| `shared_preferences`     | ^2.2.2  | 本地存储 |
| `go_router`              | ^17.1.0 | 路由管理 |
| `cached_network_image`   | ^3.3.1  | 图片缓存 |

---

## 10. 架构最佳实践

### 10.1 MVVM 分层

```
UI (Screen)
    ↓ 调用
ViewModel (业务逻辑)
    ↓ 调用
Repository (数据获取)
    ↓ 调用
Service (API/存储)
```

### 10.2 单向数据流

1. View 触发事件
2. ViewModel 处理事件
3. ViewModel 更新状态
4. View 监听状态变化
5. View 重新渲染

### 10.3 Repository 模式

- Repository 是唯一的数据入口
- Repository 处理缓存逻辑
- Repository 返回统一的 `Result<T>`

---

## 11. 新页面开发流程

1. 在 `models/` 定义数据模型
2. 在 `repositories/` 定义 Repository
3. 在 `viewmodels/` 定义 ViewModel
4. 在 `screens/` 实现 Screen
5. 在 `router/` 配置路由（如果有）

---

## 12. 注意事项

- ❌ 不要在 Screen 中直接调用 API
- ❌ 不要在 ViewModel 中持有 BuildContext
- ✅ 使用 `Result<T>` 包装所有异步结果
- ✅ 使用 `BaseViewModel` 管理通用状态
- ✅ 所有敏感数据通过 `SecureStorageService` 存储