flu-cli-core 1.0.5 → 1.1.0

package/templates/helpers/permission/index.dart.template

@@ -0,0 +1,67 @@
+import 'package:permission_handler/permission_handler.dart' as permission_handler;
+
+/// 项目常用权限枚举。
+enum AppPermission {
+  camera,
+  photos,
+  microphone,
+  location,
+  notification,
+  storage,
+  custom,
+}
+
+/// 权限申请结果。
+enum PermissionGrantResult {
+  granted,
+  denied,
+  permanentlyDenied,
+  restricted,
+}
+
+class PermissionHelper {
+  const PermissionHelper();
+
+  /// 申请权限。
+  Future<PermissionGrantResult> request(AppPermission permission) async {
+    final status = await _toPluginPermission(permission).request();
+    return _fromPluginStatus(status);
+  }
+
+  /// 查询权限状态。
+  Future<PermissionGrantResult> check(AppPermission permission) async {
+    final status = await _toPluginPermission(permission).status;
+    return _fromPluginStatus(status);
+  }
+
+  /// 打开系统设置页，适用于 permanentlyDenied 后的引导跳转。
+  Future<bool> openSettings() {
+    return permission_handler.openAppSettings();
+  }
+
+  permission_handler.Permission _toPluginPermission(AppPermission permission) {
+    switch (permission) {
+      case AppPermission.camera:
+        return permission_handler.Permission.camera;
+      case AppPermission.photos:
+        return permission_handler.Permission.photos;
+      case AppPermission.microphone:
+        return permission_handler.Permission.microphone;
+      case AppPermission.location:
+        return permission_handler.Permission.locationWhenInUse;
+      case AppPermission.notification:
+        return permission_handler.Permission.notification;
+      case AppPermission.storage:
+        return permission_handler.Permission.storage;
+      case AppPermission.custom:
+        return permission_handler.Permission.camera;
+    }
+  }
+
+  PermissionGrantResult _fromPluginStatus(permission_handler.PermissionStatus status) {
+    if (status.isGranted || status.isLimited) return PermissionGrantResult.granted;
+    if (status.isPermanentlyDenied) return PermissionGrantResult.permanentlyDenied;
+    if (status.isRestricted) return PermissionGrantResult.restricted;
+    return PermissionGrantResult.denied;
+  }
+}

package/templates/helpers/webview/README.md.template

@@ -0,0 +1,29 @@
+# WebView Helper
+
+WebView Helper 提供项目级网页打开入口，生成后已包含 `webview_flutter` 默认实现和可运行页面。
+
+## 生成定位
+
+- 落点：`lib/helpers/webview`
+- 边界：不属于 Core，不从 `lib/core/index.dart` 导出
+- 普通 Flutter 依赖：`webview_flutter`
+- 最小闭环：`WebviewHelper().open(context, request)` 会打开内置 `WebviewPage`
+- 示例入口：只有选择 `webviewBasic` 时，首页才展示 WebView 示例入口
+
+## 扩展位置
+
+- 登录态 header：扩展 `WebviewRequest.headers`
+- 外部浏览器策略：扩展 `WebviewHelper.open`
+- 页面导航拦截：扩展 `WebviewPage` 中的 `NavigationDelegate`
+
+{{#if_harmony}}
+## Harmony 注意
+
+当前项目包含 ohos 平台。CLI 会先写入普通 Flutter WebView 依赖以保证 Android/iOS/Web 可用；运行 Harmony 前，请按当前 Harmony Flutter SDK 的三方插件规范替换插件源、path 和 ref。
+
+鸿蒙插件适配参考：
+
+- Flutter packages 适配仓库：https://gitcode.com/openharmony-tpc/flutter_packages
+- Plus plugins 适配仓库：https://gitcode.com/openharmony-sig/flutter_plus_plugins
+- 指导参考：https://gitee.com/openharmony-sig/flutter_plus_plugins/blob/master/GUIDE_DOCUMENT.md
+{{/if_harmony}}

package/templates/helpers/webview/index.dart.template

@@ -0,0 +1,88 @@
+import 'package:flutter/material.dart';
+import 'package:webview_flutter/webview_flutter.dart';
+
+/// WebView 打开参数。
+class WebviewRequest {
+  const WebviewRequest({
+    required this.url,
+    this.title,
+    this.headers = const <String, String>{},
+    this.openInExternalBrowser = false,
+  });
+
+  final String url;
+  final String? title;
+  final Map<String, String> headers;
+  final bool openInExternalBrowser;
+}
+
+/// WebView helper 入口。
+///
+/// 默认实现使用 webview_flutter 打开内置页面，生成后即可运行；业务侧仍可在
+/// 这里扩展外部浏览器、登录态 header 或自定义导航策略。
+class WebviewHelper {
+  const WebviewHelper();
+
+  /// 打开 WebView 页面。
+  Future<void> open(BuildContext context, WebviewRequest request) {
+    return Navigator.of(context).push(
+      MaterialPageRoute<void>(
+        builder: (_) => WebviewPage(request: request),
+      ),
+    );
+  }
+}
+
+/// 可直接运行的 WebView 页面。
+class WebviewPage extends StatefulWidget {
+  const WebviewPage({
+    super.key,
+    required this.request,
+  });
+
+  final WebviewRequest request;
+
+  @override
+  State<WebviewPage> createState() => _WebviewPageState();
+}
+
+class _WebviewPageState extends State<WebviewPage> {
+  late final WebViewController _controller;
+  var _progress = 0;
+
+  @override
+  void initState() {
+    super.initState();
+    _controller = WebViewController()
+      ..setJavaScriptMode(JavaScriptMode.unrestricted)
+      ..setNavigationDelegate(
+        NavigationDelegate(
+          onProgress: (progress) {
+            if (!mounted) return;
+            setState(() => _progress = progress);
+          },
+        ),
+      )
+      ..loadRequest(
+        Uri.parse(widget.request.url),
+        headers: widget.request.headers,
+      );
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final title = widget.request.title ?? widget.request.url;
+    return Scaffold(
+      appBar: AppBar(
+        title: Text(title, maxLines: 1, overflow: TextOverflow.ellipsis),
+      ),
+      body: Column(
+        children: [
+          if (_progress < 100)
+            LinearProgressIndicator(value: _progress <= 0 ? null : _progress / 100),
+          Expanded(child: WebViewWidget(controller: _controller)),
+        ],
+      ),
+    );
+  }
+}

package/templates/starter_project/.env.dev.template

@@ -0,0 +1,14 @@
+APP_ENV=dev
+APP_NAME={{projectDisplayName}}
+APP_VERSION=1.0.0
+APP_OPERATOR_NAME={{projectDisplayName}} Team
+PRIVACY_CONTACT_EMAIL=privacy@example.com
+AGREEMENT_EFFECTIVE_DATE=2026-01-01
+API_BASE_URL=https://example.com
+ENABLE_LOG=true
+USE_MOCK_DATA=true
+DEMO_LIST_MODE=finite
+ENABLE_AGREEMENT_DIALOG=true
+AGREEMENT_VERSION=1.0.0
+USER_AGREEMENT_URL=https://example.com/agreement
+PRIVACY_POLICY_URL=https://example.com/privacy

package/templates/starter_project/.env.prod.example.template

@@ -0,0 +1,14 @@
+APP_ENV=prod
+APP_NAME={{projectDisplayName}}
+APP_VERSION=1.0.0
+APP_OPERATOR_NAME={{projectDisplayName}} Team
+PRIVACY_CONTACT_EMAIL=privacy@example.com
+AGREEMENT_EFFECTIVE_DATE=2026-01-01
+API_BASE_URL=https://api.example.com
+ENABLE_LOG=false
+USE_MOCK_DATA=false
+DEMO_LIST_MODE=standard
+ENABLE_AGREEMENT_DIALOG=true
+AGREEMENT_VERSION=1.0.0
+USER_AGREEMENT_URL=https://example.com/agreement
+PRIVACY_POLICY_URL=https://example.com/privacy

package/templates/starter_project/.env.staging.template

@@ -0,0 +1,14 @@
+APP_ENV=staging
+APP_NAME={{projectDisplayName}}
+APP_VERSION=1.0.0
+APP_OPERATOR_NAME={{projectDisplayName}} Team
+PRIVACY_CONTACT_EMAIL=privacy@example.com
+AGREEMENT_EFFECTIVE_DATE=2026-01-01
+API_BASE_URL=https://jsonplaceholder.typicode.com
+ENABLE_LOG=true
+USE_MOCK_DATA=false
+DEMO_LIST_MODE=load_more_error
+ENABLE_AGREEMENT_DIALOG=true
+AGREEMENT_VERSION=1.0.0
+USER_AGREEMENT_URL=https://example.com/agreement
+PRIVACY_POLICY_URL=https://example.com/privacy

package/templates/starter_project/.vscode/launch.json.template

@@ -0,0 +1,54 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+{{#if_fvm}}
+    {
+      "name": "{{projectName}} (FVM dev)",
+      "request": "launch",
+      "type": "node-terminal",
+      "cwd": "${workspaceFolder}",
+      "command": "fvm flutter run --dart-define-from-file=.env.dev"
+    },
+    {
+      "name": "{{projectName}} (FVM staging)",
+      "request": "launch",
+      "type": "node-terminal",
+      "cwd": "${workspaceFolder}",
+      "command": "fvm flutter run --dart-define-from-file=.env.staging"
+    },
+    {
+      "name": "{{projectName}} (FVM release)",
+      "request": "launch",
+      "type": "node-terminal",
+      "cwd": "${workspaceFolder}",
+      "command": "fvm flutter run --release --dart-define-from-file=.env.prod"
+    }
+{{else}}
+    {
+      "name": "{{projectName}} (dev)",
+      "request": "launch",
+      "type": "dart",
+      "cwd": "${workspaceFolder}",
+      "program": "lib/main.dart",
+      "toolArgs": ["--dart-define-from-file=.env.dev"]
+    },
+    {
+      "name": "{{projectName}} (staging)",
+      "request": "launch",
+      "type": "dart",
+      "cwd": "${workspaceFolder}",
+      "program": "lib/main.dart",
+      "toolArgs": ["--dart-define-from-file=.env.staging"]
+    },
+    {
+      "name": "{{projectName}} (release)",
+      "request": "launch",
+      "type": "dart",
+      "cwd": "${workspaceFolder}",
+      "program": "lib/main.dart",
+      "flutterMode": "release",
+      "toolArgs": ["--dart-define-from-file=.env.prod"]
+    }
+{{/if_fvm}}
+  ]
+}

package/templates/starter_project/DEVELOPER_GUIDE.md.template

@@ -0,0 +1,150 @@
+# {{projectDisplayName}} 开发指南
+
+本文档面向接手当前项目的开发者，说明从哪里改代码、如何扩展能力、哪些配置上线前必须替换。模板介绍只作为目录理解背景，不作为主要内容。
+
+## 1. 当前项目画像
+
+- 模板结构：`{{templateLabel}}`
+- 状态管理：`{{stateManager}}`
+- 网络层：{{networkStatus}}
+- Lint：{{lintDescription}}
+
+{{templateDescription}}
+
+## 2. 开发入口
+
+1. 先运行 `{{flutterPubGetCommand}}`。
+2. 用 `{{flutterRunDevCommand}}` 启动开发环境。
+3. 从 `lib/app.dart` 看应用壳、路由和协议弹框。
+4. 从当前模板的页面目录开始写业务页面。
+
+常用命令：
+
+```bash
+{{flutterPubGetCommand}}
+{{flutterRunDevCommand}}
+{{flutterRunStagingCommand}}
+{{flutterBuildReleaseCommand}}
+```
+
+## 3. 目录职责
+
+{{structureSummary}}
+
+### Lite
+
+页面、ViewModel、Service、Model 按类型平铺，适合小团队和早期业务。新增页面时优先放在 `lib/pages`，对应状态和服务放到 `lib/viewmodels` / `lib/services`。
+
+### Modular
+
+业务按 `features/<feature>` 收口，适合多页面和多业务模块。新增业务时优先新建 feature，并在 feature 内维护页面、状态、服务和模型。
+
+### Clean
+
+业务按 `data / domain / presentation` 分层，适合长期维护和多人协作。新增能力时先确认 domain 边界，再补 data 实现和 presentation 页面。
+
+## 4. 配置文件
+
+项目默认生成：
+
+| 文件 | 用途 |
+| --- | --- |
+| `.env.dev` | 本地开发 |
+| `.env.staging` | 预发布或测试环境 |
+| `.env.prod.example` | 生产配置模板 |
+| `analysis_options.yaml` | Dart/Flutter 代码规范 |
+| `.vscode/launch.json` | IDE 调试入口 |
+
+生产环境通常这样创建：
+
+```bash
+cp .env.prod.example .env.prod
+```
+
+关键环境变量：
+
+| 变量 | 用途 |
+| --- | --- |
+| `APP_ENV` | 当前环境标识 |
+| `APP_NAME` / `APP_VERSION` | 应用名称与版本 |
+| `API_BASE_URL` | 接口基础地址 |
+| `ENABLE_LOG` | 是否启用调试日志 |
+| `USE_MOCK_DATA` | 是否使用本地样板数据 |
+| `DEMO_LIST_MODE` | 首页样板列表状态：`finite`、`standard`、`empty`、`first_page_error`、`load_more_error` |
+| `ENABLE_AGREEMENT_DIALOG` | 是否启用首次协议弹框 |
+| `AGREEMENT_VERSION` | 协议版本门禁，正文变化后应递增 |
+| `USER_AGREEMENT_URL` / `PRIVACY_POLICY_URL` | 在线协议链接 |
+
+## 5. 代码规范
+
+当前 Lint 配置来自 `analysis_options.yaml`，默认跟随创建配置中的 `stack.lint`。
+
+Strict 规则会额外约束：
+
+- 单引号
+- import/directive 排序
+- const 构造与 const 字面量
+- 尾随逗号
+- 不必要容器
+- 异步后使用 `BuildContext` 的安全检查
+
+生成代码或手写代码都应先通过：
+
+```bash
+{{flutterCommand}} analyze
+```
+
+## 6. 能力扩展
+
+{{#if_network}}
+当前项目已启用网络层。网络入口位于 `lib/core/network`，示例服务和页面只作为业务样板，不应把示例模型当成通用 Core。
+{{else}}
+当前项目未启用网络层；网络层不是默认基座。后续需要网络能力时，可以重新通过 Flu-CLI 生成，或手动引入 Dio/AppHttp 相关结构。
+{{/if_network}}
+
+首页只保留一个主列表槽位：
+
+- 开发和离线验收时，用 `USE_MOCK_DATA=true` 读取本地样板数据。
+- 接入网络示例或真实接口时，把数据源替换到同一个列表槽位，不再额外并排一份 mock 列表。
+- 默认 staging 环境使用 `https://jsonplaceholder.typicode.com/posts` 作为可运行网络样板。
+- `DEMO_LIST_MODE` 只用于验证 starter 状态表达；真实业务上线前应删减或替换为业务自己的状态策略。
+
+可选能力边界：
+
+- WebView：生成网页承载能力与平台说明
+- Permission：生成权限申请协议
+- Image Picker：生成图片选择协议
+- Payment：仅生成支付协议壳，不内置真实 SDK
+- 示例入口：只追加首页入口和示例页，不代表 Core 必选能力
+
+## 7. SDK 与平台
+
+{{#if_fvm}}
+当前项目使用 FVM 工作区 SDK。推荐使用 `{{flutterCommand}}` 执行项目命令。
+
+标准 FVM 项目默认不在 `.vscode/settings.json` 中写死 `dart.flutterSdkPath` / `dart.sdkPath`，避免同账号多设备同步时把无效绝对路径带到其他机器。
+
+`.vscode/launch.json` 会使用 `node-terminal` 显式执行 `fvm flutter run`，不要用普通 Dart Debug 配置隐式选择系统 Flutter。
+{{else}}
+当前项目使用 System Flutter 或用户选择的 Custom Flutter。如果 VSCode 和终端识别的 Flutter 不一致，先检查 PATH、VSCode 用户设置和项目 `.vscode/settings.json`。
+{{/if_fvm}}
+{{#if_harmony}}
+当前项目包含 Harmony/ohos 目标平台。Harmony 等非官方 Flutter SDK 可能存在版本元数据或插件适配差异，`pub get`、`analyze`、原生插件运行结果要以实际 SDK 为准。
+{{/if_harmony}}
+
+## 8. 上线前检查
+
+上线前至少完成：
+
+- 替换 `.env.*` 中的运营主体、隐私邮箱、协议生效日期
+- 协议正文变化时递增 `.env.*` 中的 `AGREEMENT_VERSION`
+- 替换用户协议与隐私政策正文
+- 核对第三方 SDK、权限用途和数据保存期限
+- 执行 `{{flutterCommand}} analyze`
+- 使用目标环境运行一次 `{{flutterRunStagingCommand}}`
+
+## 9. 项目升级建议
+
+当前项目是单包 Flutter Starter，不默认进入多包 workspace。只有当业务稳定后确实出现共享包、多个 App、跨团队复用或版本治理需求，再考虑升级到 `apps/ + packages/`。
+
+模板结构可以演进，但不要为了目录更复杂而迁移。先让 README、环境、路由、协议和代码规范保持可运行、可解释、可维护。

package/templates/starter_project/README.md.template

@@ -0,0 +1,99 @@
+# {{projectDisplayName}}
+
+这是使用 Flu-CLI 创建的 Flutter 项目。本文档只说明当前项目如何安装、运行、配置和继续开发；模板差异只在需要理解目录组织时保留。
+
+## 快速开始
+
+```bash
+{{flutterPubGetCommand}}
+{{flutterRunDevCommand}}
+```
+
+常用环境：
+
+- 开发：`.env.dev`
+- 预发布：`.env.staging`
+- 生产模板：`.env.prod.example`，首次使用时复制为 `.env.prod`
+
+```bash
+cp .env.prod.example .env.prod
+```
+
+## 当前项目配置
+
+| 项目项 | 当前值 |
+| --- | --- |
+| 项目名 | `{{projectName}}` |
+| Dart 包名 | `{{dartPackageName}}` |
+| 应用包名 | `{{packageName}}` |
+| 模板结构 | `{{templateLabel}}` |
+| 状态管理 | `{{stateManager}}` |
+| 网络层 | {{networkStatus}} |
+| Mock 数据 | 由 `.env.*` 中的 `USE_MOCK_DATA` 控制 |
+| 首页样板 | 由 `.env.*` 中的 `DEMO_LIST_MODE` 控制样板状态 |
+| Lint | {{lintDescription}} |
+
+## 目录入口
+
+{{structureSummary}}
+
+优先从这些文件开始看：
+
+- `lib/main.dart`：应用启动入口，先执行 `AppInitializer.init()`
+- `lib/app.dart`：`MaterialApp`、路由和首次协议弹框挂载点
+- `lib/core/`：路由、主题、配置、工具、协议弹框和通用能力
+- `.env.*`：环境变量与协议信息
+- `.vscode/launch.json`：IDE 调试入口
+
+## 首页样板
+
+默认首页只保留一个主列表槽位，用来验证刷新、分页、空态、错误态和基础状态表达。
+
+- `USE_MOCK_DATA=true`：使用本地样板数据，适合开发和离线验收。
+- `USE_MOCK_DATA=false`：使用真实接口数据填充同一个列表槽位。
+- `DEMO_LIST_MODE=finite`：有限分页，用来验证“没有更多了”的默认表达。
+- `DEMO_LIST_MODE=standard`：标准分页，用来验证持续加载体验。
+- `DEMO_LIST_MODE=empty` / `first_page_error` / `load_more_error`：分别用于验证空态、首屏错误和分页错误。
+
+启用网络示例时，不建议再额外堆一份 mock 列表或做双列表 TabBar；应把网络数据接入这个主列表槽位，让首页保持真实项目的默认入口心智。默认 staging 环境使用 `https://jsonplaceholder.typicode.com/posts` 作为可运行网络样板。
+
+## 运行与调试
+
+```bash
+{{flutterRunDevCommand}}
+{{flutterRunStagingCommand}}
+{{flutterBuildReleaseCommand}}
+```
+
+VSCode 调试面板中可直接选择：
+
+- `{{projectName}} (dev)`
+- `{{projectName}} (staging)`
+- `{{projectName}} (release)`
+
+## SDK 说明
+
+{{#if_fvm}}
+- 当前项目使用 FVM 工作区 SDK。
+- 标准 FVM 项目默认不写死 `dart.flutterSdkPath` / `dart.sdkPath`，避免多设备同步污染。
+- VSCode 调试入口会通过 `node-terminal` 显式执行 `fvm flutter run`，避免 Dart 扩展隐式切到系统 Flutter。
+{{else}}
+- 当前项目使用 System Flutter 或用户选择的 Custom Flutter。
+{{/if_fvm}}
+{{#if_harmony}}
+- 当前项目包含 Harmony/ohos 目标平台；原生插件和 SDK 能力仍需按实际 Harmony Flutter 版本确认。
+{{/if_harmony}}
+
+## 首次协议与上线前配置
+
+项目默认包含首次协议弹框与本地协议页面。上线前至少需要检查：
+
+- `.env.*` 中的 `APP_OPERATOR_NAME`
+- `.env.*` 中的 `PRIVACY_CONTACT_EMAIL`
+- `.env.*` 中的 `AGREEMENT_EFFECTIVE_DATE`
+- `.env.*` 中的 `AGREEMENT_VERSION`，协议正文变化后必须递增
+- 用户协议、隐私政策正文与第三方 SDK 说明
+
+## 继续开发
+
+更多关于目录职责、能力扩展、网络层、资源配置、SDK 绑定和项目升级的说明，请看 [DEVELOPER_GUIDE.md](./DEVELOPER_GUIDE.md)。

package/templates/starter_project/analysis_options.yaml.template

@@ -0,0 +1,28 @@
+# Flu CLI 生成的项目级 Dart/Flutter 静态检查配置。
+# 默认保持 strict 规则，确保生成代码和后续扩展在提交前就暴露 import、const、
+# 尾随逗号、异步 BuildContext 等常见问题；如需放宽规则，请优先在下方 rules 中
+# 按团队约定逐项调整，不建议直接删除本文件。
+include: package:flutter_lints/flutter.yaml
+
+analyzer:
+  exclude:
+    - "**/*.g.dart"
+    - "**/*.freezed.dart"
+    - build/**
+
+linter:
+  rules:
+{{#if_strict_lint}}
+    prefer_single_quotes: true
+    directives_ordering: true
+    prefer_const_constructors: true
+    prefer_const_literals_to_create_immutables: true
+    require_trailing_commas: true
+    prefer_final_fields: true
+    prefer_final_locals: false
+    sized_box_for_whitespace: true
+    avoid_unnecessary_containers: true
+    use_build_context_synchronously: true
+{{else}}
+    prefer_single_quotes: false
+{{/if_strict_lint}}

package/templates/starter_project/lib/app.dart.template

@@ -0,0 +1,22 @@
+import 'package:flutter/material.dart';
+import 'core/index.dart';
+
+class App extends StatelessWidget {
+  const App({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      navigatorKey: NavigatorUtil.navigatorKey,
+      scaffoldMessengerKey: NavigatorUtil.scaffoldMessengerKey,
+      title: AppConstants.appName,
+      theme: AppTheme.light(),
+      darkTheme: AppTheme.dark(),
+      themeMode: ThemeMode.system,
+      initialRoute:
+          AppConfig.I.shouldShowSplash ? AppRoutes.splash : AppRoutes.home,
+      routes: AppRoutes.routes,
+      debugShowCheckedModeBanner: false,
+    );
+  }
+}

package/templates/starter_project/lib/main.dart.template

@@ -0,0 +1,34 @@
+import 'dart:async';
+
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+
+import 'app.dart';
+import 'core/index.dart';
+
+void main() {
+  runZonedGuarded(
+    () async => _bootstrap(),
+    (error, stackTrace) {
+      if (kDebugMode) {
+        debugPrint(
+          FlutterErrorDetails(exception: error, stack: stackTrace).toString(),
+        );
+      }
+    },
+  );
+}
+
+Future<void> _bootstrap() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  FlutterError.onError = (details) {
+    FlutterError.presentError(details);
+    Zone.current.handleUncaughtError(
+      details.exception,
+      details.stack ?? StackTrace.current,
+    );
+  };
+
+  await AppInitializer.init();
+  runApp(const App());
+}