[![中文](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 record-tool
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
