flu-cli-core 1.0.0

package/templates/core_files/base/base_list_viewmodel.dart.template

@@ -0,0 +1,164 @@
+import 'base_viewmodel.dart';
+
+/// 列表基础 ViewModel（轻量版）
+///
+/// - 提供分页/刷新/加载更多的最小实现
+abstract class BaseListViewModel<T> extends BaseViewModel {
+  final List<T> items = <T>[];
+  int page = 1;
+  int pageSize = 20;
+  bool hasMore = true;
+  bool isLoadingMore = false;
+  bool loadMoreFailed = false;
+  Object? loadMoreError;
+
+  /// 子类必须实现：拉取一页数据（函数级注释）
+  Future<List<T>> fetchPage({required int page, required int pageSize});
+
+  /// 初始化加载（函数级注释）
+  @override
+  Future<void> onInit() async {
+    super.onInit();
+    await loadData();
+  }
+
+  /// 首屏加载（函数级注释）
+  Future<void> loadData() async {
+    setState(ViewState.loading);
+    page = 1;
+    hasMore = true;
+    try {
+      final list = await fetchPage(page: page, pageSize: pageSize);
+      if (isDisposed) return; // 异步完成后检查是否已释放
+
+      items
+        ..clear()
+        ..addAll(list);
+      _configHasMore(list);
+      setState(ViewState.success);
+    } catch (e) {
+      if (isDisposed) return; // 捕获异常后也需检查
+      setState(ViewState.error, error: e.toString());
+    }
+  }
+
+  /// 下拉刷新（函数级注释）
+  @override
+  Future<void> refreshData() async {
+    if (isRefreshing || isDisposed) return; // 添加释放检查
+    setRefreshing(true);
+    final old = state;
+    try {
+      page = 1;
+      hasMore = true;
+      final list = await fetchPage(page: page, pageSize: pageSize);
+      if (isDisposed) return; // 异步完成后检查是否已释放
+
+      items
+        ..clear()
+        ..addAll(list);
+      _configHasMore(list);
+      setState(ViewState.success);
+    } catch (_) {
+      if (isDisposed) return; // 捕获异常后也需检查
+      // 刷新失败回退原状态
+      setState(old);
+    } finally {
+      setRefreshing(false);
+    }
+  }
+
+  /// 加载更多（函数级注释）
+  Future<void> loadMore() async {
+    if (!hasMore || isLoadingMore || isDisposed) return; // 添加释放检查
+    isLoadingMore = true;
+    loadMoreFailed = false;
+    loadMoreError = null;
+    try {
+      final next = page + 1;
+      final list = await fetchPage(page: next, pageSize: pageSize);
+      if (isDisposed) return; // 异步完成后检查是否已释放
+
+      if (list.isNotEmpty) {
+        items.addAll(list);
+        page = next;
+      }
+      _configHasMore(list);
+    } catch (e) {
+      if (isDisposed) return; // 捕获异常后也需检查
+      loadMoreFailed = true;
+      loadMoreError = e;
+    } finally {
+      isLoadingMore = false;
+      notifyDataChange();
+    }
+  }
+
+  /// 重置分页（函数级注释）
+  void resetPaging({int initialPage = 1, int pageSize = 20}) {
+    page = initialPage;
+    this.pageSize = pageSize;
+    hasMore = true;
+    items.clear();
+    loadMoreFailed = false;
+    loadMoreError = null;
+    setState(ViewState.idle);
+  }
+
+  /// 计算是否还有更多（函数级注释）
+  void _configHasMore(List<T> data) {
+    hasMore = data.length >= pageSize;
+    loadMoreFailed = false;
+    loadMoreError = null;
+  }
+
+  /// 清空列表
+  void clearItems() {
+    items.clear();
+    page = 1;
+    hasMore = true;
+    notifyDataChange();
+  }
+
+  /// 数据操作：添加（函数级注释）
+  void addItem(T item) {
+    items.add(item);
+    notifyDataChange();
+  }
+
+  /// 数据操作：移除（函数级注释）
+  void removeItem(T item) {
+    items.remove(item);
+    notifyDataChange();
+  }
+
+  /// 数据操作：更新（函数级注释）
+  void updateItem(int index, T item) {
+    if (index >= 0 && index < items.length) {
+      items[index] = item;
+      notifyDataChange();
+    }
+  }
+
+  /// 批量操作：批量添加
+  void addItems(List<T> newItems) {
+    if (newItems.isEmpty) return;
+    items.addAll(newItems);
+    notifyDataChange();
+  }
+
+  /// 批量操作：批量移除
+  void removeItems(List<T> targets) {
+    if (targets.isEmpty) return;
+    items.removeWhere((item) => targets.contains(item));
+    notifyDataChange();
+  }
+
+  /// 批量操作：替换整个列表
+  void replaceItems(List<T> newItems) {
+    items
+      ..clear()
+      ..addAll(newItems);
+    notifyDataChange();
+  }
+}

package/templates/core_files/base/base_page.dart.template

@@ -0,0 +1,252 @@
+import 'package:flutter/material.dart';
+
+import '../theme/status_views_theme.dart';
+import 'base_viewmodel.dart';
+
+/// Page 基类
+///
+/// 提供统一的页面结构和状态处理
+///
+/// 示例：
+/// ```dart
+/// class HomePage extends BasePage<HomeViewModel> {
+///   const HomePage({super.key});
+///
+///   @override
+///   State<HomePage> createState() => _HomePageState();
+/// }
+///
+/// class _HomePageState extends BasePageState<HomeViewModel, HomePage> {
+///   @override
+///   HomeViewModel createViewModel() => HomeViewModel();
+///
+///   @override
+///   String get title => '首页';
+///
+///   @override
+///   Widget buildContent(BuildContext context) {
+///     return Center(
+///       child: Text('Counter: ${viewModel.counter}'),
+///     );
+///   }
+/// }
+/// ```
+abstract class BasePage<VM extends BaseViewModel> extends StatefulWidget {
+  const BasePage({super.key});
+
+  @override
+  State<BasePage<VM>> createState();
+}
+
+/// Page State 基类
+abstract class BasePageState<VM extends BaseViewModel, T extends BasePage<VM>>
+    extends State<T> {
+  /// ViewModel 实例
+  late final VM viewModel;
+
+  // ==================== 子类需要实现的方法 ====================
+
+  /// 创建 ViewModel
+  VM createViewModel();
+
+  /// 构建内容区域
+  Widget buildContent(BuildContext context);
+
+  // ==================== 可选重写的 UI 配置 ====================
+
+  /// 是否显示 AppBar（默认 true）
+  bool get showAppBar => true;
+
+  /// AppBar 标题（默认空串）
+  String get title => '';
+
+  /// AppBar 操作按钮（默认 null）
+  List<Widget>? get actions => null;
+
+  /// 是否显示返回按钮（默认自动判断）
+  bool get showBackButton => true;
+
+  /// 背景颜色（默认 null）
+  Color? get backgroundColor => null;
+
+  /// 是否启用 SafeArea（默认 true）
+  bool get useSafeArea => true;
+
+  /// SafeArea 上边框（默认 true）
+  bool get safeAreaTop => true;
+
+  /// SafeArea 下边框（默认 true）
+  bool get safeAreaBottom => true;
+
+  // ==================== 生命周期 ====================
+
+  @override
+  void initState() {
+    super.initState();
+    viewModel = createViewModel();
+    _setupListener();
+    viewModel.onInit();
+  }
+
+  /// 设置监听器
+  void _setupListener() {
+    // 所有状态管理器都使用统一的 addListener 方式
+    viewModel.addListener(_onViewModelChanged);
+  }
+
+  @override
+  void dispose() {
+    viewModel.removeListener(_onViewModelChanged);
+    viewModel.dispose();
+    super.dispose();
+  }
+
+  /// ViewModel 变化回调
+  void _onViewModelChanged() {
+    if (mounted) {
+      setState(() {});
+    }
+  }
+
+  // ==================== UI 构建 ====================
+
+  @override
+  Widget build(BuildContext context) {
+    Widget body = _buildBody();
+    body = buildSafeArea(child: body);
+    body = buildScaffold(body: body);
+    return body;
+  }
+
+  /// 构建 SafeArea
+  Widget buildSafeArea({required Widget child}) {
+    return useSafeArea
+        ? SafeArea(
+            top: safeAreaTop,
+            bottom: safeAreaBottom,
+            child: child,
+          )
+        : child;
+  }
+
+  /// 构建 AppBar
+  PreferredSizeWidget? buildAppBar() {
+    return AppBar(
+      title: Text(title),
+      actions: actions,
+      automaticallyImplyLeading: showBackButton,
+    );
+  }
+
+  /// 构建 Scaffold
+  Widget buildScaffold({required Widget body}) {
+    return Scaffold(
+      appBar: showAppBar ? buildAppBar() : null,
+      backgroundColor: backgroundColor,
+      body: body,
+    );
+  }
+
+  /// 构建 Body
+  Widget _buildBody() {
+    final theme = Theme.of(context).extension<StatusViewsTheme>();
+
+    if (viewModel.isLoading) {
+      final global = theme?.loadingBuilder?.call(context);
+      return global ?? buildLoading();
+    }
+
+    if (viewModel.isError) {
+      final global = theme?.errorBuilder?.call(context, viewModel.errorMessage);
+      return global ?? buildError();
+    }
+
+    if (isEmptyContent) {
+      final global = theme?.emptyBuilder?.call(context);
+      return global ?? buildEmpty();
+    }
+
+    return buildContent(context);
+  }
+
+  // ==================== 可重写的 UI 组件 ====================
+
+  /// 构建 Loading 视图
+  Widget buildLoading() {
+    return const Center(
+      child: CircularProgressIndicator(),
+    );
+  }
+
+  /// 构建错误视图
+  Widget buildError() {
+    return Center(
+      child: Column(
+        mainAxisAlignment: MainAxisAlignment.center,
+        children: [
+          const Icon(
+            Icons.error_outline,
+            size: 64,
+            color: Colors.red,
+          ),
+          const SizedBox(height: 16),
+          Text(
+            viewModel.errorMessage ?? '加载失败',
+            style: const TextStyle(fontSize: 16),
+          ),
+          const SizedBox(height: 24),
+          ElevatedButton.icon(
+            onPressed: viewModel.refreshData,
+            icon: const Icon(Icons.refresh),
+            label: const Text('重试'),
+          ),
+        ],
+      ),
+    );
+  }
+
+  /// 构建空视图
+  Widget buildEmpty() {
+    return const Center(
+      child: Text('暂无数据'),
+    );
+  }
+
+  /// 页面是否为空（默认 false，子类可重写）
+  bool get isEmptyContent => false;
+
+  /// 显示 SnackBar
+  void showSnackBar(String message, {Duration? duration}) {
+    if (!mounted) return;
+    ScaffoldMessenger.of(context).showSnackBar(
+      SnackBar(
+        content: Text(message),
+        duration: duration ?? const Duration(seconds: 2),
+      ),
+    );
+  }
+
+  /// 显示 Loading Dialog
+  void showLoadingDialog({String? message}) {
+    showDialog(
+      context: context,
+      barrierDismissible: false,
+      builder: (context) => AlertDialog(
+        content: Row(
+          children: [
+            const CircularProgressIndicator(),
+            const SizedBox(width: 16),
+            Text(message ?? '加载中...'),
+          ],
+        ),
+      ),
+    );
+  }
+
+  /// 隐藏 Loading Dialog
+  void hideLoadingDialog() {
+    if (mounted) {
+      Navigator.of(context).pop();
+    }
+  }
+}

package/templates/core_files/base/base_viewmodel.dart.template

@@ -0,0 +1,68 @@
+import 'package:flutter/foundation.dart';
+
+enum ViewState { idle, loading, success, error }
+
+class BaseViewModel extends ChangeNotifier {
+  ViewState _state = ViewState.idle;
+  String? _errorMessage;
+  bool _isRefreshing = false;
+  bool _disposed = false;
+
+  // ==================== Getters ====================
+  // 当前视图状态
+  ViewState get state => _state;
+  // 错误信息
+  String? get errorMessage => _errorMessage;
+  // 是否正在加载
+  bool get isLoading => _state == ViewState.loading;
+  // 是否加载失败
+  bool get isError => _state == ViewState.error;
+  // 是否加载成功
+  bool get isSuccess => _state == ViewState.success;
+  // 是否空闲状态
+  bool get isIdle => _state == ViewState.idle;
+  // 是否正在刷新
+  bool get isRefreshing => _isRefreshing;
+  // 是否已释放
+  bool get isDisposed => _disposed;
+
+  // ==================== 状态设置 ====================
+
+  /// 设置视图状态
+  void setState(ViewState state, {String? error}) {
+    if (_disposed) return;
+    _state = state;
+    _errorMessage = error;
+    notifyListeners();
+  }
+
+  /// 设置刷新状态
+  void setRefreshing(bool refreshing) {
+    if (_disposed) return;
+    _isRefreshing = refreshing;
+    notifyListeners();
+  }
+
+  /// 通知数据变化（仅用于局部刷新）
+  void notifyDataChange() {
+    if (_disposed) return;
+    notifyListeners();
+  }
+
+  // ==================== 生命周期 ====================
+  /// 初始化钩子
+  Future<void> onInit() async {
+    // 子类可以重写此方法进行初始化
+  }
+
+  /// 刷新数据（钩子）
+  Future<void> refreshData() async {
+    // 子类可以重写此方法实现刷新逻辑
+  }
+
+  @override
+  void dispose() {
+    _disposed = true;
+    super.dispose();
+  }
+}

package/templates/core_files/base/index.dart.template

@@ -0,0 +1,5 @@
+// 导出基础类 (按字母顺序排列)
+export 'base_list_page.dart';
+export 'base_list_viewmodel.dart';
+export 'base_page.dart';
+export 'base_viewmodel.dart';

package/templates/core_files/config/app_config.dart.template

@@ -0,0 +1,142 @@
+import 'package:flutter/foundation.dart';
+
+import '../storage/storage_keys.dart';
+import '../storage/storage_util.dart';
+
+/// 应用常量
+class AppConstants {
+  AppConstants._();
+
+  static const String appName = '火叶';
+  static const String appVersion = '1.0.0';
+
+  /// 免责声明
+  static const String disclaimer =
+      '本应用仅供学习交流使用，API 数据由第三方提供，本应用不保证数据的准确性、完整性及安全性。如有侵权，请联系删除。';
+
+  /// 国内可直接访问的 API 地址 (示例使用 图虫API)
+  static const String apiBaseUrl = 'https://api.tuchong.com';
+
+  static const int apiTimeout = 30000;
+  static const int pageSize = 20;
+}
+
+/// 应用配置
+///
+/// 统一管理应用配置和生命周期状态
+///
+/// 使用示例：
+/// ```dart
+/// void main() async {
+///   WidgetsFlutterBinding.ensureInitialized();
+///   await AppConfig.init();
+///   runApp(const App());
+/// }
+/// ```
+class AppConfig {
+  static AppConfig? _instance;
+  static AppConfig get I => _instance!;
+
+  // ==================== 配置 ====================
+
+  /// API 基础地址
+  final String apiBaseUrl;
+
+  /// 连接超时时间
+  final Duration connectTimeout;
+
+  /// 接收超时时间
+  final Duration receiveTimeout;
+
+  /// 是否启用日志
+  final bool enableLog;
+
+  /// 是否使用 Mock 数据 (用于网络示例演示)
+  final bool useMockData;
+
+  // ==================== 生命周期状态 ====================
+
+  /// 是否首次启动
+  final bool isFirstLaunch;
+
+  /// 是否更新后首次启动
+  final bool isFirstLaunchAfterUpdate;
+
+  /// 当前版本号
+  final String currentVersion;
+
+  /// 上一个版本号
+  final String previousVersion;
+
+  AppConfig._({
+    required this.apiBaseUrl,
+    required this.connectTimeout,
+    required this.receiveTimeout,
+    required this.enableLog,
+    required this.useMockData,
+    required this.isFirstLaunch,
+    required this.isFirstLaunchAfterUpdate,
+    required this.currentVersion,
+    required this.previousVersion,
+  });
+
+  /// 初始化应用配置
+  ///
+  /// 必须在应用启动时调用（runApp 之前）
+  static Future<void> init({
+    String? apiBaseUrl,
+    Duration connectTimeout =
+        const Duration(milliseconds: AppConstants.apiTimeout),
+    Duration receiveTimeout =
+        const Duration(milliseconds: AppConstants.apiTimeout),
+    bool? enableLog,
+    bool useMockData = false,
+  }) async {
+    // 1. 初始化存储
+    await StorageUtil.init();
+
+    // 2. 获取版本信息
+    const currentVersion = AppConstants.appVersion;
+    final previousVersion = StorageUtil.getString(StorageKeys.appVersion) ?? '';
+
+    // 3. 判断启动状态
+    final isFirstLaunch = !StorageUtil.containsKey(StorageKeys.isFirstLaunch);
+    final isFirstLaunchAfterUpdate =
+        previousVersion.isNotEmpty && previousVersion != currentVersion;
+
+    // 4. 更新存储
+    if (isFirstLaunch) {
+      await StorageUtil.setBool(StorageKeys.isFirstLaunch, false);
+    }
+    await StorageUtil.setString(StorageKeys.appVersion, currentVersion);
+
+    // 5. 创建实例
+    _instance = AppConfig._(
+      apiBaseUrl: apiBaseUrl ?? AppConstants.apiBaseUrl,
+      connectTimeout: connectTimeout,
+      receiveTimeout: receiveTimeout,
+      enableLog: enableLog ?? kDebugMode,
+      useMockData: useMockData,
+      isFirstLaunch: isFirstLaunch,
+      isFirstLaunchAfterUpdate: isFirstLaunchAfterUpdate,
+      currentVersion: currentVersion,
+      previousVersion: previousVersion,
+    );
+
+    _printInitLog();
+  }
+
+  static void _printInitLog() {
+    if (!_instance!.enableLog) return;
+    debugPrint('┌─────────────────────────────────────');
+    debugPrint('│ AppConfig 初始化完成');
+    debugPrint('│ API: ${_instance!.apiBaseUrl}');
+    debugPrint('│ 版本: ${_instance!.currentVersion}');
+    debugPrint('│ 首次启动: ${_instance!.isFirstLaunch}');
+    debugPrint('│ 更新后首次: ${_instance!.isFirstLaunchAfterUpdate}');
+    debugPrint('└─────────────────────────────────────');
+  }
+
+  /// 是否已初始化
+  static bool get isInitialized => _instance != null;
+}

package/templates/core_files/config/app_initializer.dart.template

@@ -0,0 +1,74 @@
+ 
+ 
+{{#if_network}}
+import '../network/app_http.dart';
+import '../network/interceptors/index.dart';
+import '../network/response_adapter.dart';
+{{/if_network}}
+import 'app_config.dart';
+/// 应用初始化器
+///
+/// 统一管理应用启动前的所有初始化逻辑
+///
+/// 使用示例:
+/// ```dart
+/// void main() async {
+///   WidgetsFlutterBinding.ensureInitialized();
+///   await AppInitializer.init();
+///   runApp(const App());
+/// }
+/// ```
+class AppInitializer {
+  AppInitializer._();
+
+  /// 初始化应用
+  static Future<void> init({
+    String? apiBaseUrl,
+    bool? enableLog,
+    bool useMockData = false,
+  }) async {
+    // 1. 初始化应用配置
+    await AppConfig.init(
+      apiBaseUrl: apiBaseUrl,
+      enableLog: enableLog,
+      useMockData: useMockData,
+    );
+
+    {{#if_network}}
+    // 2. 初始化网络层
+    _initNetwork();
+    {{/if_network}}
+
+    // 3. 其他初始化 (埋点、推送等) - 可根据需要添加
+  }
+
+  {{#if_network}}
+  /// 初始化网络层配置
+  static void _initNetwork() {
+    AppHttp.init(
+      // 使用图虫 API 适配器 {result, message, feedList}
+      adapter: TuChongAdapter(),
+
+      // 自动显示错误弹窗 (默认 true)
+      autoShowError: true,
+
+      interceptors: [
+        // Token 自动注入
+        AuthInterceptor(
+          getToken: () {
+            // 从本地存储获取 token
+            // return StorageUtil.getString('token') ?? '';
+            return '';
+          },
+        ),
+        // 请求重试
+        RetryInterceptor(
+          dio: AppHttp().dio,
+          maxRetries: 3,
+          retryDelay: const Duration(seconds: 1),
+        ),
+      ],
+    );
+  }
+  {{/if_network}}
+}

package/templates/core_files/config/index.dart.template

@@ -0,0 +1,3 @@
+// 导出配置类 (按字母顺序排列)
+export 'app_config.dart';
+export 'app_initializer.dart';