flu-cli 0.0.5 → 2.0.0

package/templates/README.md

@@ -0,0 +1,138 @@
+# Flutter 模板
+
+## 📁 独立仓库架构
+
+从 V2 开始，每个模板都有自己的独立 Git 仓库：
+
+| 模板        | 仓库地址                                                       | 说明                                    |
+| ----------- | -------------------------------------------------------------- | --------------------------------------- |
+| **lite**    | [template-lite](https://gitee.com/flu-cli/template-lite)       | 轻量级模板，适合快速原型开发            |
+| **modular** | [template-modular](https://gitee.com/flu-cli/template-modular) | 模块化模板，适合中大型项目              |
+| **clean**   | [template-clean](https://gitee.com/flu-cli/template-clean)     | Clean Architecture 模板，适合企业级应用 |
+
+## 🎯 为什么使用独立仓库？
+
+### 优势
+
+1. **独立维护**
+
+    - 每个模板可以独立更新和发版
+    - 不同团队可以维护不同模板
+    - 版本控制更清晰
+
+2. **减小主仓库体积**
+
+    - flu-cli 主仓库不包含模板代码
+    - 下载和克隆更快
+
+3. **灵活的版本控制**
+
+    - 用户可以选择特定版本的模板
+    - 支持模板的独立版本号
+
+4. **更好的协作**
+    - 模板贡献者不需要访问主仓库
+    - 降低协作门槛
+
+## 🚀 使用方式
+
+### 通过 flu-cli 使用（推荐）
+
+```bash
+# flu-cli 会自动从远程下载模板
+flu-cli new my_app --template lite
+
+# 或使用本地模板（如果已克隆）
+flu-cli new my_app --template lite
+```
+
+### 直接克隆模板
+
+```bash
+# 克隆模板仓库
+git clone https://gitee.com/flu-cli/template-lite.git my_app
+cd my_app
+
+# 初始化（创建 pubspec.yaml）
+./init.sh
+
+# 运行
+flutter run
+```
+
+## 📝 本地开发模板
+
+如果你想在本地开发和测试模板：
+
+```bash
+# 1. 克隆模板到 templates/ 目录
+cd templates/
+git clone https://gitee.com/flu-cli/template-lite.git lite
+git clone https://gitee.com/flu-cli/template-modular.git modular
+git clone https://gitee.com/flu-cli/template-clean.git clean
+
+# 2. 进入模板目录开发
+cd lite
+./init.sh
+flutter run
+
+# 3. 提交更改到模板仓库
+git add .
+git commit -m "Update template"
+git push
+```
+
+## 🔄 模板更新流程
+
+### 更新模板
+
+```bash
+# 进入模板目录
+cd templates/lite
+
+# 拉取最新代码
+git pull
+
+# 测试
+./init.sh
+flutter run
+
+# 提交更改
+git add .
+git commit -m "Update: xxx"
+git push
+```
+
+### 用户更新模板
+
+```bash
+# flu-cli 会自动检查更新
+flu-cli update
+
+# 或强制更新
+flu-cli new my_app --template lite --no-cache
+```
+
+## 📚 相关文档
+
+-   [双文件策略说明](../MIGRATION_PLAN.md#双文件策略)
+-   [迁移到 Gitee 组织](../MIGRATION_PLAN.md)
+-   [模板开发指南](https://gitee.com/flu-cli/flu-cli-docs)
+
+## 💡 注意事项
+
+1. **flu-cli 主仓库不跟踪 templates/ 内容**
+
+    - templates/ 已添加到 .gitignore
+    - 只保留此 README.md
+
+2. **每个模板都是独立的 Git 仓库**
+
+    - 有自己的 .git 目录
+    - 独立的提交历史
+    - 独立的版本号
+
+3. **本地开发时**
+    - 可以在 templates/ 下克隆模板仓库
+    - 修改后提交到对应的模板仓库
+    - 不会影响 flu-cli 主仓库

package/templates/base_files/base_list_page.dart.template

@@ -0,0 +1,174 @@
+import 'package:flutter/material.dart';
+
+import 'base_list_viewmodel.dart';
+import 'base_page.dart';
+import 'theme/status_views_theme.dart';
+
+/// 列表页面基类：在 BasePage 基础上扩展列表体与触底加载能力
+abstract class BaseListPage<T, VM extends BaseListViewModel<T>>
+    extends BasePage<VM> {
+  /// 构造函数
+  const BaseListPage({super.key});
+
+  /// 子类必须实现：创建 ViewModel 实例
+  VM createListViewModel();
+
+  /// 渲染单个条目
+  Widget buildItem(BuildContext context, VM vm, T item, int index);
+
+  /// 可选：头部、尾部、状态页覆盖（函数级注释）
+
+  /// 构建成功态的列表体（函数级注释）
+  /// 返回 null 使用默认 ListView.builder；可自定义 SliverList/GridView 等容器
+  Widget? buildListWidget(BuildContext context, VM vm) => null;
+  Widget? buildHeader(BuildContext context, VM vm) => null;
+  Widget? buildFooter(BuildContext context, VM vm) => null;
+  Widget? buildLoading(BuildContext context, VM vm) => null;
+  Widget? buildError(BuildContext context, VM vm, String? msg) => null;
+  Widget? buildEmpty(BuildContext context, VM vm) => null;
+
+  /// 可选：替换底部“加载更多”视图
+  Widget? loadMoreFooterBuilder(
+    BuildContext context,
+    VM vm,
+    bool hasMore,
+    bool isLoadingMore,
+  ) =>
+      null;
+
+  /// 刷新容器包裹（用于接入第三方刷新库）
+  Widget refreshWrapperBuilder(BuildContext context, Widget child, VM vm) =>
+      child;
+
+  /// 列表体外层包裹（函数级注释）
+  /// 用于添加 Scrollbar、NotificationListener、吸顶 Header 等额外结构
+  Widget listWrapperBuilder(BuildContext context, Widget list, VM vm) => list;
+
+  /// 提供自定义 ScrollController（函数级注释）
+  /// 返回 null 使用内部控制器；非空时由外部管理其生命周期
+  ScrollController? provideScrollController(BuildContext context, VM vm) =>
+      null;
+
+  /// 滚动事件回调（函数级注释）
+  /// 可用于自定义触底策略或滚动埋点
+  void onScroll(BuildContext context, ScrollPosition position, VM vm) {}
+
+  /// 是否启用自动触底加载
+  bool get enableAutoLoadMore => true;
+
+  /// 触底阈值
+  double get loadMoreThreshold => 100;
+
+  /// 是否启用下拉刷新（透传到 BasePageState）
+  bool get enableRefresh => false;
+
+  @override
+  State<BaseListPage<T, VM>> createState() => _BaseListPageState<T, VM>();
+}
+
+class _BaseListPageState<T, VM extends BaseListViewModel<T>>
+    extends BasePageState<VM, BaseListPage<T, VM>> {
+  late final ScrollController _controller =
+      widget.provideScrollController(context, viewModel) ?? ScrollController();
+
+  /// 创建 ViewModel（使用注入的实例）
+  @override
+  VM createViewModel() => widget.createListViewModel();
+
+  /// 页面是否为空：依据列表数据判断
+  @override
+  bool get isEmptyContent => viewModel.items.isEmpty;
+
+  @override
+  void initState() {
+    super.initState();
+    _controller.addListener(_onScroll);
+  }
+
+  @override
+  void dispose() {
+    _controller.removeListener(_onScroll);
+    _controller.dispose();
+    super.dispose();
+  }
+
+  /// 触底检测：接近底部时尝试加载更多
+  void _onScroll() {
+    widget.onScroll(context, _controller.position, viewModel);
+    if (!widget.enableAutoLoadMore) return;
+    if (!_controller.hasClients) return;
+    final max = _controller.position.maxScrollExtent;
+    final offset = _controller.offset;
+    if (offset >= max - widget.loadMoreThreshold) {
+      viewModel.loadMore();
+    }
+  }
+
+  /// 构建成功态内容：列表 + 底部 Footer
+  @override
+  Widget buildContent(BuildContext context) {
+    Widget body = _buildListWidget();
+    if (widget.enableRefresh) {
+      body = widget.refreshWrapperBuilder(context, body, viewModel);
+    }
+    return body;
+  }
+
+  /// 构建列表视图：支持自定义或默认实现
+  Widget _buildListWidget() {
+    final vm = viewModel;
+    final theme = Theme.of(context).extension<StatusViewsTheme>();
+    final list = widget.buildListWidget(context, vm) ??
+        ListView.builder(
+          controller: _controller,
+          itemCount: vm.items.length + 1,
+          itemBuilder: (ctx, i) {
+            if (i == 0) {
+              final header = widget.buildHeader(ctx, vm);
+              if (header != null) return header;
+            }
+            final last = i == vm.items.length;
+            if (last) {
+              final localFooter = widget.buildFooter(ctx, vm);
+              if (localFooter != null) return localFooter;
+
+              if (vm.loadMoreFailed) {
+                return Padding(
+                  padding: const EdgeInsets.all(16),
+                  child: Column(
+                    mainAxisSize: MainAxisSize.min,
+                    children: [
+                      Text(
+                        vm.loadMoreError?.toString() ?? '加载更多失败',
+                        style: const TextStyle(color: Colors.red),
+                      ),
+                      const SizedBox(height: 8),
+                      ElevatedButton(
+                        onPressed: vm.loadMore,
+                        child: const Text('重试'),
+                      ),
+                    ],
+                  ),
+                );
+              }
+
+              final globalFooter =
+                  theme?.loadMoreBuilder?.call(ctx, vm.hasMore);
+              if (globalFooter != null) return globalFooter;
+
+              return Padding(
+                padding: const EdgeInsets.all(16),
+                child: Center(
+                  child: vm.hasMore
+                      ? const CircularProgressIndicator()
+                      : const Text('没有更多了'),
+                ),
+              );
+            }
+            final item = vm.items[i];
+            return widget.buildItem(ctx, vm, item, i);
+          },
+        );
+    return widget.listWrapperBuilder(context, list, vm);
+  }
+}

package/templates/base_files/base_list_viewmodel.dart.template

@@ -0,0 +1,134 @@
+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);
+      items
+        ..clear()
+        ..addAll(list);
+      _configHasMore(list);
+      setState(ViewState.success);
+    } catch (e) {
+      setState(ViewState.error, error: e.toString());
+    }
+  }
+
+  /// 下拉刷新（函数级注释）
+  @override
+  Future<void> refreshData() async {
+    if (isRefreshing) return;
+    setRefreshing(true);
+    final old = state;
+    try {
+      page = 1;
+      hasMore = true;
+      final list = await fetchPage(page: page, pageSize: pageSize);
+      items
+        ..clear()
+        ..addAll(list);
+      _configHasMore(list);
+      setState(ViewState.success);
+    } catch (_) {
+      // 刷新失败回退原状态
+      setState(old);
+    } finally {
+      setRefreshing(false);
+    }
+  }
+
+  /// 加载更多（函数级注释）
+  Future<void> loadMore() async {
+    if (!hasMore || isLoadingMore) return;
+    isLoadingMore = true;
+    loadMoreFailed = false;
+    loadMoreError = null;
+    try {
+      final next = page + 1;
+      final list = await fetchPage(page: next, pageSize: pageSize);
+      if (list.isNotEmpty) {
+        items.addAll(list);
+        page = next;
+      }
+      _configHasMore(list);
+    } catch (e) {
+      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;
+    notifyListeners();
+    setState(ViewState.idle);
+  }
+
+  /// 计算是否还有更多（函数级注释）
+  void _configHasMore(List<T> data) {
+    hasMore = data.length >= pageSize;
+    loadMoreFailed = false;
+    loadMoreError = null;
+  }
+
+  /// 清空列表
+  void clearItems() {
+    items.clear();
+    page = 1;
+    hasMore = true;
+    notifyListeners();
+  }
+
+  /// 数据操作：添加（函数级注释）
+  void addItem(T item) {
+    items.add(item);
+    notifyListeners();
+  }
+
+  /// 数据操作：移除（函数级注释）
+  void removeItem(T item) {
+    items.remove(item);
+    notifyListeners();
+  }
+
+  /// 数据操作：更新（函数级注释）
+  void updateItem(int index, T item) {
+    if (index >= 0 && index < items.length) {
+      items[index] = item;
+      notifyListeners();
+    }
+  }
+}

package/templates/base_files/base_page.dart.template

@@ -0,0 +1,251 @@
+import 'package:flutter/material.dart';
+
+import 'base_viewmodel.dart';
+import 'theme/status_views_theme.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});
+
+  /// 是否显示 AppBar（默认 true）
+  bool get showAppBar => true;
+
+  /// AppBar 标题（默认空串）
+  String get title => '';
+
+  /// AppBar 操作按钮（默认 null）
+  List<Widget>? get actions => null;
+
+  /// 是否显示返回按钮（默认自动判断）
+  bool? get showBackButton => null;
+
+  /// 背景颜色（默认 null）
+  Color? get backgroundColor => null;
+
+  /// 是否启用 SafeArea（默认 true）
+  bool get useSafeArea => true;
+
+  @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);
+
+  // ==================== 可选重写的方法 ====================
+
+  /// 是否显示 AppBar（透传自 Widget 层）
+  bool get showAppBar => widget.showAppBar;
+
+  /// AppBar 标题（透传自 Widget 层）
+  String get title => widget.title;
+
+  /// AppBar 操作按钮（透传自 Widget 层）
+  List<Widget>? get actions => widget.actions;
+
+  /// 是否显示返回按钮（透传自 Widget 层）
+  bool? get showBackButton => widget.showBackButton;
+
+  /// 背景颜色（透传自 Widget 层）
+  Color? get backgroundColor => widget.backgroundColor;
+
+  /// 是否安全区域（透传自 Widget 层）
+  bool get useSafeArea => widget.useSafeArea;
+
+  // ==================== 生命周期 ====================
+
+  @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();
+
+    if (useSafeArea) {
+      body = SafeArea(child: body);
+    }
+
+    return Scaffold(
+      appBar: showAppBar ? _buildAppBar() : null,
+      backgroundColor: backgroundColor,
+      body: body,
+    );
+  }
+
+  /// 构建 AppBar
+  PreferredSizeWidget? _buildAppBar() {
+    return AppBar(
+      title: Text(title),
+      actions: actions,
+      automaticallyImplyLeading: showBackButton ?? true,
+    );
+  }
+
+  /// 构建 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();
+    }
+  }
+}