flu-cli-core 1.0.5 → 1.1.0

package/templates/helper_examples/permission_example_page.dart.template

@@ -0,0 +1,365 @@
+import 'package:flutter/material.dart';
+
+import 'package:{{projectName}}/helpers/permission/index.dart';
+
+/// 权限申请示例页。
+///
+/// 示例页提供“申请前说明 -> 系统授权 -> 状态更新 -> 前往设置”的完整闭环。
+class PermissionExamplePage extends StatefulWidget {
+  const PermissionExamplePage({super.key});
+
+  @override
+  State<PermissionExamplePage> createState() => _PermissionExamplePageState();
+}
+
+class _PermissionExampleItem {
+  const _PermissionExampleItem({
+    required this.permission,
+    required this.title,
+    required this.subtitle,
+    required this.icon,
+    required this.dialogTitle,
+    required this.dialogMessage,
+  });
+
+  final AppPermission permission;
+  final String title;
+  final String subtitle;
+  final IconData icon;
+  final String dialogTitle;
+  final String dialogMessage;
+}
+
+class _PermissionExamplePageState extends State<PermissionExamplePage>
+    with WidgetsBindingObserver {
+  static const _items = [
+    _PermissionExampleItem(
+      permission: AppPermission.camera,
+      title: '相机权限',
+      subtitle: '用于拍照、扫码和头像上传等需要即时拍摄的场景。',
+      icon: Icons.photo_camera_outlined,
+      dialogTitle: '申请相机权限',
+      dialogMessage: '我们只会在你主动点击拍照或扫码时请求相机权限，不会在后台持续访问相机。',
+    ),
+    _PermissionExampleItem(
+      permission: AppPermission.photos,
+      title: '相册权限',
+      subtitle: '用于从系统相册选择图片或读取图片资源。',
+      icon: Icons.photo_library_outlined,
+      dialogTitle: '申请相册权限',
+      dialogMessage: '我们只会在你主动选择图片时读取相册资源，不会扫描或上传无关内容。',
+    ),
+  ];
+
+  final _helper = const PermissionHelper();
+  final Map<AppPermission, PermissionGrantResult> _statuses = {};
+  AppPermission? _requestingPermission;
+  String? _lastFeedback;
+
+  @override
+  void initState() {
+    super.initState();
+    WidgetsBinding.instance.addObserver(this);
+    _refreshStatuses();
+  }
+
+  @override
+  void dispose() {
+    WidgetsBinding.instance.removeObserver(this);
+    super.dispose();
+  }
+
+  @override
+  void didChangeAppLifecycleState(AppLifecycleState state) {
+    if (state == AppLifecycleState.resumed) {
+      _refreshStatuses();
+    }
+  }
+
+  Future<void> _refreshStatuses() async {
+    final entries = await Future.wait(
+      _items.map((item) async {
+        final status = await _helper.check(item.permission);
+        return MapEntry(item.permission, status);
+      }),
+    );
+    if (!mounted) return;
+    setState(() {
+      _statuses
+        ..clear()
+        ..addEntries(entries);
+    });
+  }
+
+  Future<void> _requestPermission(_PermissionExampleItem item) async {
+    final confirmed = await showDialog<bool>(
+      context: context,
+      builder: (dialogContext) => AlertDialog(
+        title: Text(item.dialogTitle),
+        content: Text(item.dialogMessage),
+        actions: [
+          TextButton(
+            onPressed: () => Navigator.of(dialogContext).pop(false),
+            child: const Text('暂不授权'),
+          ),
+          FilledButton(
+            onPressed: () => Navigator.of(dialogContext).pop(true),
+            child: const Text('继续'),
+          ),
+        ],
+      ),
+    );
+
+    if (confirmed != true) return;
+
+    setState(() => _requestingPermission = item.permission);
+    try {
+      final result = await _helper.request(item.permission);
+      await _refreshStatuses();
+      if (!mounted) return;
+
+      setState(() {
+        _requestingPermission = null;
+        _lastFeedback = _buildFeedback(item.title, result);
+      });
+
+      final messenger = ScaffoldMessenger.of(context);
+      messenger
+        ..hideCurrentSnackBar()
+        ..showSnackBar(SnackBar(content: Text(_lastFeedback!)));
+    } catch (error) {
+      if (!mounted) return;
+      setState(() {
+        _requestingPermission = null;
+        _lastFeedback = '${item.title} 申请失败，请检查平台权限配置或插件状态。';
+      });
+      final messenger = ScaffoldMessenger.of(context);
+      messenger
+        ..hideCurrentSnackBar()
+        ..showSnackBar(SnackBar(content: Text(_lastFeedback!)));
+    }
+  }
+
+  Future<void> _openSettings(_PermissionExampleItem item) async {
+    final opened = await _helper.openSettings();
+    if (!mounted) return;
+    final messenger = ScaffoldMessenger.of(context);
+    messenger
+      ..hideCurrentSnackBar()
+      ..showSnackBar(
+        SnackBar(
+          content: Text(
+            opened
+                ? '已打开系统设置，返回应用后会自动刷新 ${item.title} 状态。'
+                : '当前设备无法直接打开系统设置，请手动前往设置检查 ${item.title}。',
+          ),
+        ),
+      );
+  }
+
+  String _statusLabel(PermissionGrantResult? result) {
+    switch (result) {
+      case PermissionGrantResult.granted:
+        return '已授权';
+      case PermissionGrantResult.permanentlyDenied:
+        return '需去设置';
+      case PermissionGrantResult.restricted:
+        return '受限';
+      case PermissionGrantResult.denied:
+        return '未申请';
+      case null:
+        return '检查中';
+    }
+  }
+
+  Color _statusColor(PermissionGrantResult? result, BuildContext context) {
+    final scheme = Theme.of(context).colorScheme;
+    switch (result) {
+      case PermissionGrantResult.granted:
+        return Colors.green.shade600;
+      case PermissionGrantResult.permanentlyDenied:
+        return scheme.error;
+      case PermissionGrantResult.restricted:
+        return Colors.orange.shade700;
+      case PermissionGrantResult.denied:
+        return scheme.primary;
+      case null:
+        return scheme.outline;
+    }
+  }
+
+  String _buildFeedback(String permissionName, PermissionGrantResult result) {
+    switch (result) {
+      case PermissionGrantResult.granted:
+        return '$permissionName 已授权，现在可以继续对应功能。';
+      case PermissionGrantResult.permanentlyDenied:
+        return '$permissionName 已被永久拒绝，请前往系统设置手动开启。';
+      case PermissionGrantResult.restricted:
+        return '$permissionName 当前受系统限制，可能需要检查设备策略或家长控制。';
+      case PermissionGrantResult.denied:
+        return '$permissionName 尚未授权，你可以稍后再次发起申请。';
+    }
+  }
+
+  Widget _buildPermissionCard(_PermissionExampleItem item) {
+    final status = _statuses[item.permission];
+    final color = _statusColor(status, context);
+    final isBusy = _requestingPermission == item.permission;
+    final shouldOpenSettings = status == PermissionGrantResult.permanentlyDenied;
+
+    return Container(
+      margin: const EdgeInsets.only(bottom: 14),
+      padding: const EdgeInsets.all(16),
+      decoration: BoxDecoration(
+        color: Colors.white,
+        borderRadius: BorderRadius.circular(18),
+        border: Border.all(color: const Color(0xFFE5E7EB)),
+        boxShadow: const [
+          BoxShadow(
+            color: Color(0x080F172A),
+            blurRadius: 16,
+            offset: Offset(0, 8),
+          ),
+        ],
+      ),
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.start,
+        children: [
+          Row(
+            crossAxisAlignment: CrossAxisAlignment.start,
+            children: [
+              Container(
+                width: 44,
+                height: 44,
+                decoration: BoxDecoration(
+                  color: color.withOpacity(0.12),
+                  borderRadius: BorderRadius.circular(14),
+                ),
+                child: Icon(item.icon, color: color),
+              ),
+              const SizedBox(width: 14),
+              Expanded(
+                child: Column(
+                  crossAxisAlignment: CrossAxisAlignment.start,
+                  children: [
+                    Text(
+                      item.title,
+                      style: const TextStyle(fontSize: 16, fontWeight: FontWeight.w700),
+                    ),
+                    const SizedBox(height: 4),
+                    Text(
+                      item.subtitle,
+                      style: const TextStyle(
+                        fontSize: 13,
+                        height: 1.45,
+                        color: Color(0xFF475569),
+                      ),
+                    ),
+                  ],
+                ),
+              ),
+              const SizedBox(width: 12),
+              Container(
+                padding: const EdgeInsets.symmetric(horizontal: 10, vertical: 6),
+                decoration: BoxDecoration(
+                  color: color.withOpacity(0.12),
+                  borderRadius: BorderRadius.circular(999),
+                ),
+                child: Text(
+                  _statusLabel(status),
+                  style: TextStyle(fontSize: 12, fontWeight: FontWeight.w700, color: color),
+                ),
+              ),
+            ],
+          ),
+          const SizedBox(height: 14),
+          Text(
+            '申请前会先弹出用途说明，只有你点击同意后才会继续触发系统授权。',
+            style: TextStyle(fontSize: 12, color: Colors.grey.shade600, height: 1.45),
+          ),
+          const SizedBox(height: 14),
+          Row(
+            children: [
+              Expanded(
+                child: FilledButton(
+                  onPressed: isBusy || shouldOpenSettings ? null : () => _requestPermission(item),
+                  child: Text(isBusy ? '申请中...' : '申请授权'),
+                ),
+              ),
+              const SizedBox(width: 10),
+              Expanded(
+                child: OutlinedButton(
+                  onPressed: shouldOpenSettings ? () => _openSettings(item) : _refreshStatuses,
+                  child: Text(shouldOpenSettings ? '前往设置' : '刷新状态'),
+                ),
+              ),
+            ],
+          ),
+        ],
+      ),
+    );
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: const Text('权限申请示例')),
+      body: ListView(
+        padding: const EdgeInsets.all(20),
+        children: [
+          Container(
+            padding: const EdgeInsets.all(18),
+            decoration: BoxDecoration(
+              color: const Color(0xFFF8FAFC),
+              borderRadius: BorderRadius.circular(20),
+            ),
+            child: const Column(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              children: [
+                Text(
+                  '权限申请最小闭环',
+                  style: TextStyle(fontSize: 22, fontWeight: FontWeight.w800),
+                ),
+                SizedBox(height: 10),
+                Text(
+                  '示例会先展示申请原因，再由用户确认是否继续授权；授权结果会实时回写到列表状态，永久拒绝时会引导前往系统设置。',
+                  style: TextStyle(fontSize: 14, height: 1.55, color: Color(0xFF475569)),
+                ),
+              ],
+            ),
+          ),
+          const SizedBox(height: 20),
+          ..._items.map(_buildPermissionCard),
+          if (_lastFeedback != null) ...[
+            const SizedBox(height: 6),
+            Container(
+              padding: const EdgeInsets.all(14),
+              decoration: BoxDecoration(
+                color: const Color(0xFFF8FAFC),
+                borderRadius: BorderRadius.circular(16),
+              ),
+              child: Row(
+                crossAxisAlignment: CrossAxisAlignment.start,
+                children: [
+                  const Icon(Icons.info_outline, size: 18, color: Color(0xFF475569)),
+                  const SizedBox(width: 10),
+                  Expanded(
+                    child: Text(
+                      _lastFeedback!,
+                      style: const TextStyle(fontSize: 13, height: 1.5, color: Color(0xFF334155)),
+                    ),
+                  ),
+                ],
+              ),
+            ),
+          ],
+          const SizedBox(height: 10),
+          const Text(
+            '权限声明、用途文案与平台落点说明可查看 lib/helpers/README.platform-permissions.md。',
+            style: TextStyle(fontSize: 12, height: 1.5, color: Color(0xFF64748B)),
+          ),
+        ],
+      ),
+    );
+  }
+}

package/templates/helper_examples/webview_example_page.dart.template

@@ -0,0 +1,44 @@
+import 'package:flutter/material.dart';
+
+import 'package:{{projectName}}/helpers/webview/index.dart';
+
+/// WebView 示例页。
+///
+/// 示例只负责展示入口；真正的 WebView 打开能力由 lib/helpers/webview 提供。
+class WebviewExamplePage extends StatelessWidget {
+  const WebviewExamplePage({super.key});
+
+  static const _demoUrl = 'https://huozhiye.cn/flu-cli';
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: const Text('WebView 示例')),
+      body: ListView(
+        padding: const EdgeInsets.all(20),
+        children: [
+          const Text(
+            'WebView 功能已生成默认闭环，可直接打开网页。',
+            style: TextStyle(fontSize: 18, fontWeight: FontWeight.w700),
+          ),
+          const SizedBox(height: 12),
+          const Text('默认示例会打开 Flu CLI 官方文档，业务项目可以在 lib/helpers/webview 中扩展 header、登录态或外部浏览器策略。'),
+          const SizedBox(height: 20),
+          FilledButton.icon(
+            onPressed: () {
+              const WebviewHelper().open(
+                context,
+                const WebviewRequest(
+                  url: _demoUrl,
+                  title: 'Flu CLI',
+                ),
+              );
+            },
+            icon: const Icon(Icons.open_in_browser),
+            label: const Text('打开 Flu CLI 官方文档'),
+          ),
+        ],
+      ),
+    );
+  }
+}

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

@@ -0,0 +1,30 @@
+# Image Picker Helper
+
+图片选择 Helper 提供项目级图片选择能力，生成后已包含 `image_picker` 默认实现。
+
+## 生成定位
+
+- 落点：`lib/helpers/image_picker`
+- 边界：不属于 Core，不从 `lib/core/index.dart` 导出
+- 普通 Flutter 依赖：`image_picker`
+- 最小闭环：`ImagePickerHelper().pick(...)` 可直接从相册或相机选择图片
+- 示例入口：只有选择 `imagePickerBasic` 时，首页才展示图片选择示例入口
+
+## 平台权限
+
+- Android：CLI 会默认写入相机与图片读取权限，落点 `android/app/src/main/AndroidManifest.xml`。
+- iOS：CLI 会默认补 `ios/Runner/Info.plist` 中的 `NSCameraUsageDescription`、`NSPhotoLibraryUsageDescription`。
+- 修改入口：统一查看 `lib/helpers/README.platform-permissions.md`，按真实业务文案调整权限用途说明。
+- Web：受浏览器文件选择能力影响，不同浏览器表现可能不同。
+
+{{#if_harmony}}
+## Harmony 注意
+
+当前项目包含 ohos 平台。CLI 会默认尝试在 `ohos/entry/src/main/module.json5` 的 `requestPermissions` 中补相机 / 相册读取权限；图片选择插件依赖和实际权限声明仍需按当前 Harmony Flutter SDK 的三方插件规范确认。
+
+鸿蒙插件适配参考：
+
+- 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/image_picker/index.dart.template

@@ -0,0 +1,73 @@
+import 'dart:typed_data';
+
+import 'package:image_picker/image_picker.dart' as image_picker;
+
+/// 图片来源。
+enum ImagePickerSource {
+  camera,
+  gallery,
+}
+
+/// 图片选择参数。
+class ImagePickerRequest {
+  const ImagePickerRequest({
+    this.source = ImagePickerSource.gallery,
+    this.maxCount = 1,
+    this.compressQuality,
+  });
+
+  final ImagePickerSource source;
+  final int maxCount;
+  final int? compressQuality;
+}
+
+/// 图片选择结果。
+class PickedImageAsset {
+  const PickedImageAsset({
+    required this.path,
+    this.name,
+    this.mimeType,
+    this.size,
+    this.bytes,
+  });
+
+  final String path;
+  final String? name;
+  final String? mimeType;
+  final int? size;
+  final Uint8List? bytes;
+}
+
+/// Image picker helper 入口。
+///
+/// 默认实现使用 image_picker，生成后即可在 Android/iOS/Web 的常规插件能力
+/// 范围内运行；Harmony 场景按 README 替换插件源或适配层。
+class ImagePickerHelper {
+  ImagePickerHelper({image_picker.ImagePicker? picker})
+      : _picker = picker ?? image_picker.ImagePicker();
+
+  final image_picker.ImagePicker _picker;
+
+  /// 选择图片。
+  Future<List<PickedImageAsset>> pick(ImagePickerRequest request) async {
+    final source = request.source == ImagePickerSource.camera
+        ? image_picker.ImageSource.camera
+        : image_picker.ImageSource.gallery;
+    final image = await _picker.pickImage(
+      source: source,
+      imageQuality: request.compressQuality,
+    );
+    if (image == null) return const [];
+    final size = await image.length();
+    final bytes = await image.readAsBytes();
+    return [
+      PickedImageAsset(
+        path: image.path,
+        name: image.name,
+        mimeType: image.mimeType,
+        size: size,
+        bytes: bytes,
+      ),
+    ];
+  }
+}

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

@@ -0,0 +1,29 @@
+# Payment Helper
+
+支付 Helper 只提供项目级统一入口，不绑定任何具体支付 SDK。
+
+## 生成定位
+
+- 落点：`lib/helpers/payment`
+- 边界：不属于 Core，不从 `lib/core/index.dart` 导出
+- 适用：微信/支付宝/应用内购买/鸿蒙渠道支付等支付能力的统一适配层
+- 例外：Payment 只生成协议、说明和壳子，不承诺真实支付 SDK 最小闭环
+- 示例入口：只有选择 `paymentShell` 时，首页才展示支付协议壳示例
+
+## 接入方式
+
+1. 根据项目渠道选择真实支付 SDK。
+2. 实现 `PaymentExecutor`。
+3. 通过 `PaymentHelper(executor: yourExecutor)` 注入项目自己的支付逻辑。
+
+{{#if_harmony}}
+## Harmony 注意
+
+当前项目包含 ohos 平台。支付 SDK 需要按鸿蒙渠道与当前 Harmony Flutter SDK 的插件规范单独确认，CLI 不会自动写入普通 Flutter 支付插件依赖。
+
+鸿蒙插件适配参考：
+
+- 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/payment/index.dart.template

@@ -0,0 +1,66 @@
+/// 支付 Helper 入口。
+///
+/// 这里只定义统一适配协议，不绑定任何支付 SDK。
+/// 具体的微信、支付宝、IAP 或鸿蒙渠道支付由业务侧实现 [PaymentExecutor]。
+typedef PaymentExecutor = Future<PaymentResult> Function(PaymentRequest request);
+
+/// 支付渠道。
+enum PaymentChannel {
+  wechat,
+  alipay,
+  iap,
+  harmony,
+  custom,
+}
+
+/// 支付状态。
+enum PaymentStatus {
+  success,
+  cancelled,
+  failed,
+}
+
+/// 支付请求参数。
+class PaymentRequest {
+  const PaymentRequest({
+    required this.channel,
+    required this.orderId,
+    this.payload = const <String, Object?>{},
+  });
+
+  final PaymentChannel channel;
+  final String orderId;
+  final Map<String, Object?> payload;
+}
+
+/// 支付结果。
+class PaymentResult {
+  const PaymentResult({
+    required this.status,
+    this.message,
+    this.raw,
+  });
+
+  final PaymentStatus status;
+  final String? message;
+  final Object? raw;
+
+  bool get isSuccess => status == PaymentStatus.success;
+}
+
+class PaymentHelper {
+  const PaymentHelper({PaymentExecutor? executor}) : _executor = executor;
+
+  final PaymentExecutor? _executor;
+
+  /// 发起支付。
+  ///
+  /// 默认不内置 SDK 实现，避免 Core 或 Helper 强绑定某个支付渠道。
+  Future<PaymentResult> pay(PaymentRequest request) {
+    final executor = _executor;
+    if (executor == null) {
+      throw StateError('PaymentExecutor is not configured.');
+    }
+    return executor(request);
+  }
+}

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

@@ -0,0 +1,30 @@
+# Permission Helper
+
+权限 Helper 提供项目级权限申请能力，生成后已包含 `permission_handler` 默认实现。
+
+## 生成定位
+
+- 落点：`lib/helpers/permission`
+- 边界：不属于 Core，不从 `lib/core/index.dart` 导出
+- 普通 Flutter 依赖：`permission_handler`
+- 最小闭环：`PermissionHelper().request(AppPermission.camera)` 可直接触发权限申请
+- 示例入口：只有选择 `permissionBasic` 时，首页才展示权限示例入口
+
+## 平台权限
+
+- Android：CLI 会默认写入相机与图片读取权限，落点 `android/app/src/main/AndroidManifest.xml`。
+- iOS：CLI 会默认补 `ios/Runner/Info.plist` 中的 `NSCameraUsageDescription`、`NSPhotoLibraryUsageDescription`，并在 `ios/Podfile` 中启用 `PERMISSION_CAMERA=1`、`PERMISSION_PHOTOS=1`。
+- 修改入口：统一查看 `lib/helpers/README.platform-permissions.md`，按真实业务文案调整权限用途说明。
+- Web / Desktop：按 `permission_handler` 当前平台支持情况决定是否可用。
+
+{{#if_harmony}}
+## Harmony 注意
+
+当前项目包含 ohos 平台。CLI 会默认尝试在 `ohos/entry/src/main/module.json5` 的 `requestPermissions` 中补 `ohos.permission.CAMERA` 与 `ohos.permission.READ_IMAGEVIDEO`；如你的工程目录不同，请按当前 Harmony Flutter SDK 和鸿蒙应用权限规范核对。
+
+鸿蒙插件适配参考：
+
+- 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}}