[![中文](https://img.shields.io/badge/Lang-中文-red)](README.md)

# Flutter Template

A production-ready Flutter quick-start template extracted from real-world projects. Ships with a proven architecture, curated dependency stack, and ready-to-use infrastructure — start writing business features on day one.

## Goals

- Android & iOS support
- Zero business residue — no business pages, API models, assets, copy, or private configuration
- Production infrastructure included: routing, theming, networking, caching, logging, permissions, utilities, state management, and common UI components
- Demo page as default home — delete or replace with your own

## Tech Stack

| Category | Package | Purpose |
|---|---|---|
| State Management | flutter_riverpod | Compile-safe, testable state management |
| Networking | dio | HTTP client with interceptor chain |
| Local Cache | shared_preferences | Key-value persistence |
| Network Monitor | connectivity_plus | Real-time connectivity tracking |
| Permissions | permission_handler | Runtime permission requests |
| Screen Adaptation | flutter_screenutil | Design-dimension-based layout |
| Image Loading | cached_network_image | Network image caching |
| SVG | flutter_svg | SVG rendering |
| Pull to Refresh | pull_to_refresh | Refresh and load-more |
| Loading HUD | flutter_easyloading | Toast and loading indicator |
| Device Info | device_info_plus | Device metadata |
| Package Info | package_info_plus | App version info |
| URL Launcher | url_launcher | Open external URLs |
| Linting | flutter_lints | Recommended Dart lint rules |

## Directory Structure

```
lib/
├── app/                          # Application shell
│   ├── app.dart                  # MaterialApp, theme, localization, global config
│   ├── bootstrap.dart            # Startup initialization
│   ├── config/                   # Multi-environment config (dev/staging/prod)
│   ├── router/                   # Navigator utilities and route stack tracking
│   └── theme/                    # Light/dark themes, colors, spacing
├── core/                         # Framework-level infrastructure
│   ├── cache/                    # SharedPreferences wrapper and common keys
│   ├── extensions/               # BuildContext extensions
│   ├── logging/                  # Logger
│   ├── mixins/                   # Reusable mixins
│   ├── network/                  # Dio client, response wrapper, exceptions,
│   │   └── offline_queue/        #   interceptors, network monitor, offline queue
│   ├── permission/               # Permission request abstraction
│   └── utils/                    # Date, form validation, debounce/throttle,
│                                 #   device info, URL utilities
├── shared/
│   └── widgets/                  # Reusable UI components
├── features/
│   └── demo/                     # Capability demo page — removable
└── main.dart                     # Entry point
```

## Built-in Capabilities

- **Networking** — ApiClient (Dio) + ApiResponse + ApiException + header interceptor
- **Network Monitoring** — Real-time connectivity via connectivity_plus
- **Offline Queue** — Request queuing, persistence, and auto-replay on reconnect
- **Local Cache** — AppStorage wrapping SharedPreferences
- **State Management** — Riverpod provider system
- **Theming** — Material 3 light/dark themes + screen adaptation
- **UI Components** — AppButton, AppTextField, AppCard, AppDialog, AppToast, AppEmptyView, AppErrorView, AppLoadingView, AppStatusView, AppAvatar, AppTag, AppSearchBar, AppRefreshList, AppNetworkImage, SafeAreaWrapper
- **Utilities** — Date formatting, form validation, debounce/throttle, device info, URL utils
- **Project Config** — flutter_lints, Android/iOS platform projects

## Getting Started

```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
```

## Onboarding a New Project

1. Update API base URLs in `lib/app/config/app_config.dart`
2. Add feature modules under `lib/features/`
3. Use ApiClient via `core/network/providers/dio_providers.dart`
4. Keep business-specific cache keys in your feature module; `core/cache/storage_keys.dart` for truly shared keys only
5. Delete `features/demo/` or replace it with your own home page