[![English](https://img.shields.io/badge/Lang-English-blue)](README.en.md)

# Flutter Template

一个从实际项目中提炼的 Flutter 通用快速开发模板，开箱即用，避免重复搭建工程基础设施。

## 目标

- 支持 Android 和 iOS
- 不包含原业务页面、接口、Model、资源、文案和私有配置
- 保留通用工程化能力：路由、主题、网络、缓存、日志、权限、工具类、状态管理和常用 UI 组件
- 默认首页为 demo 页面，可直接替换为新业务首页

## 技术栈

| 类别 | 依赖 | 用途 |
|---|---|---|
| 状态管理 | flutter_riverpod | 编译安全、可测试的状态管理 |
| 网络请求 | dio | HTTP 客户端，支持拦截器链 |
| 本地缓存 | shared_preferences | KV 持久化存储 |
| 网络监听 | connectivity_plus | 实时网络状态监测 |
| 权限申请 | permission_handler | 运行时权限请求 |
| 屏幕适配 | flutter_screenutil | 设计稿尺寸适配 |
| 图片加载 | cached_network_image | 网络图片缓存 |
| SVG | flutter_svg | SVG 渲染 |
| 下拉刷新 | pull_to_refresh | 下拉刷新 / 上拉加载 |
| 加载提示 | flutter_easyloading | Toast 和 loading |
| 设备信息 | device_info_plus | 设备元数据 |
| 应用信息 | package_info_plus | 版本号等应用信息 |
| 链接跳转 | url_launcher | 外部 URL 打开 |
| 代码规范 | flutter_lints | Dart 推荐 lint 规则 |

## 目录结构

```
lib/
├── app/                          # 应用壳
│   ├── app.dart                  # MaterialApp、主题、国际化、全局配置
│   ├── bootstrap.dart            # 启动初始化
│   ├── config/                   # 多环境配置 (dev/staging/prod)
│   ├── router/                   # Navigator 工具和路由栈跟踪
│   └── theme/                    # 亮色/暗色主题、颜色、间距
├── core/                         # 框架层基础设施
│   ├── cache/                    # SharedPreferences 封装和通用 key
│   ├── extensions/               # BuildContext 扩展
│   ├── logging/                  # 日志工具
│   ├── mixins/                   # 通用 mixin
│   ├── network/                  # Dio 封装、响应包装、异常处理
│   │   └── offline_queue/        # 拦截器、网络监听、离线请求队列
│   ├── permission/               # 权限请求封装
│   └── utils/                    # 日期、表单校验、防抖节流、设备、URL 工具
├── shared/
│   └── widgets/                  # 通用 UI 组件库
├── features/
│   └── demo/                     # 模板能力演示页，可删除
└── main.dart                     # 入口
```

## 内置能力

- **网络层** — ApiClient (Dio) + ApiResponse + ApiException + 请求头拦截器
- **网络监听** — 基于 connectivity_plus 的实时状态追踪
- **离线队列** — 请求入队、持久化、网络恢复自动重放
- **本地缓存** — AppStorage 封装 SharedPreferences
- **状态管理** — Riverpod Provider 体系
- **主题系统** — Material 3 亮/暗双主题 + 屏幕适配
- **UI 组件** — AppButton、AppTextField、AppCard、AppDialog、AppToast、AppEmptyView、AppErrorView、AppLoadingView、AppStatusView、AppAvatar、AppTag、AppSearchBar、AppRefreshList、AppNetworkImage、SafeAreaWrapper
- **工具类** — 日期格式化、表单校验、防抖节流、设备信息、URL 工具
- **工程配置** — flutter_lints、Android/iOS 平台工程

## 快速开始

```bash
cd flutter-template
flutter pub get
flutter analyze
flutter test
flutter run
```

```bash
flutter run -d <device-id>
flutter build apk --debug
flutter build ios --debug --no-codesign
```

## 新业务接入指引

1. 修改 `lib/app/config/app_config.dart` 中的环境地址
2. 在 `lib/features/` 下新增业务模块
3. 通过 `core/network/providers/dio_providers.dart` 获取 ApiClient
4. 业务缓存 key 放在业务模块内，`core/cache/storage_keys.dart` 只放真正通用的 key
5. 删除 `features/demo/` 或替换为业务首页