# flutter-scaffold

**Repository Path**: nacker/flutter-scaffold

## Basic Information

- **Project Name**: flutter-scaffold
- **Description**: 企业级 Flutter 脚手架工程，开箱即用，覆盖 99% 商业 App 需求。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-14
- **Last Updated**: 2026-05-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flutter Scaffold

企业级 Flutter 脚手架工程，开箱即用，覆盖 99% 商业 App 需求。

## 功能特性

### 基础架构
- ✅ 模块化目录结构（core、pages、widgets、services、utils）
- ✅ 多环境配置（dev / test / prod）
- ✅ go_router 路由管理（命名路由、路由拦截、登录鉴权）
- ✅ Provider 状态管理
- ✅ 亮色/暗色主题切换
- ✅ 多语言国际化（中文/英文）
- ✅ 统一初始化入口

### 网络请求
- ✅ Dio 封装（统一请求/响应拦截）
- ✅ Token 自动携带与刷新
- ✅ 请求头自动添加设备信息
- ✅ 统一错误处理（401、500、网络异常、超时）
- ✅ 请求日志打印
- ✅ 文件上传/下载
- ✅ 请求重试机制

### 本地存储
- ✅ SharedPreferences 轻量存储
- ✅ Hive 数据库
- ✅ 全局配置持久化

### UI 组件
- ✅ Toast 提示
- ✅ Loading 加载
- ✅ 空状态/错误状态组件
- ✅ 通用按钮/输入框
- ✅ 图片加载组件（占位图、缓存）
- ✅ 头像组件
- ✅ 通用对话框/底部弹窗

### 工具类
- ✅ 日期时间格式化
- ✅ 金额/数字格式化
- ✅ 设备信息获取
- ✅ 权限管理
- ✅ 日志工具
- ✅ 加密工具（MD5、SHA256）
- ✅ 防抖/节流
- ✅ JSON 解析工具

### 用户体系
- ✅ 登录/注册/退出
- ✅ Token 自动刷新
- ✅ 登录态过期拦截
- ✅ 全局用户状态管理

### 监控埋点
- ✅ 全局异常捕获
- ✅ 用户行为埋点
- ✅ 页面浏览追踪

## 项目结构

```
lib/
├── config/                 # 应用配置
│   └── app_config.dart
├── core/                   # 核心模块
│   ├── app_initializer.dart
│   ├── constants/          # 常量定义
│   ├── env/                # 环境配置
│   ├── interceptor/        # 网络拦截器
│   ├── network/            # 网络请求封装
│   ├── router/             # 路由管理
│   └── storage/            # 本地存储
├── i18n/                   # 国际化
│   ├── app_localizations.dart
│   └── translations/
├── models/                 # 数据模型
├── pages/                  # 页面
│   ├── common/             # 公共页面
│   ├── home/
│   ├── login/
│   ├── settings/
│   └── splash/
├── providers/              # 状态管理
├── services/               # 服务层
│   ├── api/
│   └── user/
├── theme/                  # 主题配置
├── utils/                  # 工具类
├── widgets/                # 通用组件
│   ├── common/
│   ├── dialog/
│   └── list/
└── main.dart
```

## 快速开始

### 环境要求
- Flutter SDK >= 3.11.0
- Dart SDK >= 3.11.0

### 安装依赖
```bash
flutter pub get
```

### 运行项目
```bash
flutter run
```

### 打包发布

```bash
# Android
./scripts/build.sh -p android -e prod -v 1.0.0 -n 1

# iOS
./scripts/build.sh -p ios -e prod -v 1.0.0 -n 1
```

## 配置说明

### 1. 修改 API 地址

编辑 `lib/core/env/env_config.dart`：

```dart
static final Map<Environment, EnvConfig> _configs = {
  Environment.dev: const EnvConfig(
    envName: 'dev',
    baseUrl: 'https://your-dev-api.com',  // 修改为你的开发环境地址
  ),
  Environment.prod: const EnvConfig(
    envName: 'prod',
    baseUrl: 'https://your-api.com',  // 修改为你的生产环境地址
  ),
};
```

### 2. 修改应用名称和包名

**应用名称**：修改 `pubspec.yaml` 中的 `name` 和 `description`

**Android 包名**：修改 `android/app/build.gradle.kts` 中的 `applicationId`

**iOS Bundle ID**：修改 `ios/Runner.xcodeproj` 中的 Bundle Identifier

### 3. 添加图片资源

在 `assets/images/` 目录下添加以下图片：

```
assets/images/
├── splash_logo.png        # 启动页 Logo
├── splash_logo_dark.png   # 启动页 Logo (暗色)
├── app_icon.png           # 应用图标
└── app_icon_fg.png        # 应用图标前景图
```

### 4. iOS 权限配置

编辑 `ios/Runner/Info.plist`，添加需要的权限描述：

```xml
<key>NSCameraUsageDescription</key>
<string>需要访问相机以拍照</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>需要访问相册以选择图片</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>需要获取位置信息</string>
```

### 5. Android 签名配置

编辑 `android/app/build.gradle.kts`，配置签名：

```kotlin
android {
    signingConfigs {
        create("release") {
            storeFile = file("your-keystore.jks")
            storePassword = "your-store-password"
            keyAlias = "your-key-alias"
            keyPassword = "your-key-password"
        }
    }
    buildTypes {
        release {
            signingConfig = signingConfigs.getByName("release")
        }
    }
}
```

## 主要依赖

| 依赖 | 版本 | 说明 |
|------|------|------|
| dio | ^5.4.0 | 网络请求 |
| provider | ^6.1.1 | 状态管理 |
| go_router | ^13.0.0 | 路由管理 |
| shared_preferences | ^2.2.2 | 轻量存储 |
| hive | ^2.2.3 | 数据库 |
| cached_network_image | ^3.3.1 | 图片缓存 |
| webview_flutter | ^4.4.2 | WebView |
| share_plus | ^7.0.2 | 分享 |
| url_launcher | ^6.2.2 | 打开链接 |
| permission_handler | ^11.1.0 | 权限管理 |
| device_info_plus | ^9.1.1 | 设备信息 |
| package_info_plus | ^6.0.0 | 应用信息 |
| logger | ^2.0.2+1 | 日志 |
| intl | any | 国际化 |
| crypto | ^3.0.3 | 加密 |

## 使用示例

### 网络请求

```dart
// GET 请求
final response = await HttpClient().get<UserModel>(
  '/user/info',
  fromJson: (json) => UserModel.fromJson(json),
);

if (response.isSuccess) {
  print(response.data);
}

// POST 请求
final response = await HttpClient().post(
  '/user/login',
  data: {'username': 'test', 'password': '123456'},
);
```

### 状态管理

```dart
// 定义 Provider
class CounterProvider extends BaseChangeNotifier {
  int _count = 0;
  int get count => _count;
  
  void increment() {
    _count++;
    notifyListeners();
  }
}

// 使用 Provider
Consumer<CounterProvider>(
  builder: (context, provider, child) {
    return Text('${provider.count}');
  },
)
```

### 路由导航

```dart
// 命名路由跳转
context.goNamed('home');
context.pushNamed('settings');

// 带参数跳转
context.goNamed('webview', params: {'url': 'https://example.com'});

// 返回
context.pop();
```

### 本地存储

```dart
// 存储
await StorageService.instance.setToken('your-token');
await StorageService.instance.setUserInfo(user);

// 读取
final token = StorageService.instance.getToken();
final user = StorageService.instance.getUserInfo();

// 清除
await StorageService.instance.clearUserData();
```

### 埋点追踪

```dart
// 页面浏览
AnalyticsService.instance.pageView('home');

// 点击事件
AnalyticsService.instance.click('submit_button');

// 自定义事件
AnalyticsService.instance.track('purchase', properties: {
  'amount': 99.9,
  'product': 'vip',
});
```

## License

MIT License