init

2026-06-03 14:07:10 +08:00
parent 3bdece45c3
commit 9eb8d1cc37
118 changed files with 5689 additions and 2 deletions
--- a/README.en.md
+++ b/README.en.md
@@ -0,0 +1,94 @@
+[![中文](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