95 lines
4.9 KiB
Markdown
95 lines
4.9 KiB
Markdown
[](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
|