init

README.md

@@ -1,3 +1,93 @@
-# record-tool
+[![English](https://img.shields.io/badge/Lang-English-blue)](README.en.md)
 
-录制助手 flutter 端
+# 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/` 或替换为业务首页