flu-cli-core 1.0.5 → 1.1.0

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

@@ -2,20 +2,20 @@ import 'package:flutter/foundation.dart';
 
 import '../storage/storage_keys.dart';
 import '../storage/storage_util.dart';
+import 'app_env.dart';
 
-/// 应用常量
+/// 应用常量（不随环境变化的固定值）
 class AppConstants {
   AppConstants._();
 
-  static const String appName = '火叶';
-  static const String appVersion = '1.0.0';
+  /// 应用名称 (便捷访问)
+  static String get appName => EnvConfig.appName;
+  static String get appVersion => EnvConfig.appVersion;
 
-  /// 免责声明
-  static const String disclaimer =
-      '本应用仅供学习交流使用，API 数据由第三方提供，本应用不保证数据的准确性、完整性及安全性。如有侵权，请联系删除。';
-
-  /// 国内可直接访问的 API 地址 (示例使用 图虫API)
-  static const String apiBaseUrl = 'https://api.tuchong.com';
+  /// API 基础地址。
+  ///
+  /// 默认值仅作为占位，真实业务项目应通过 env 文件或 dart-define 覆盖。
+  static String get apiBaseUrl => EnvConfig.apiBaseUrl;
 
   static const int apiTimeout = 30000;
   static const int pageSize = 20;
@@ -23,7 +23,7 @@ class AppConstants {
 
 /// 应用配置
 ///
-/// 统一管理应用配置和生命周期状态
+/// 合并编译期环境变量 + 运行时状态，统一对外提供
 ///
 /// 使用示例：
 /// ```dart
@@ -37,23 +37,38 @@ class AppConfig {
   static AppConfig? _instance;
   static AppConfig get I => _instance!;
 
-  // ==================== 配置 ====================
+  // ==================== 环境配置（来自 .env） ====================
+
+  /// 当前运行环境
+  final AppEnv env;
 
   /// API 基础地址
   final String apiBaseUrl;
 
+  /// 是否启用日志
+  final bool enableLog;
+
+  /// 应用名称 (便捷访问)
+  String get appName => EnvConfig.appName;
+
+  // ==================== 运行时配置 ====================
+
   /// 连接超时时间
   final Duration connectTimeout;
 
   /// 接收超时时间
   final Duration receiveTimeout;
 
-  /// 是否启用日志
-  final bool enableLog;
-
-  /// 是否使用 Mock 数据 (用于网络示例演示)
+  /// 是否使用 Mock 数据。
+  ///
+  /// 只有选择示例时，示例服务才会读取该开关。
   final bool useMockData;
 
+  /// 已接受的协议版本。
+  ///
+  /// 空字符串表示尚未接受当前协议。
+  String agreementAcceptedVersion;
+
   // ==================== 生命周期状态 ====================
 
   /// 是否首次启动
@@ -68,7 +83,12 @@ class AppConfig {
   /// 上一个版本号
   final String previousVersion;
 
+  // ==================== 扩展配置 ====================
+
+  final dynamic extra;
+
   AppConfig._({
+    required this.env,
     required this.apiBaseUrl,
     required this.connectTimeout,
     required this.receiveTimeout,
@@ -78,25 +98,26 @@ class AppConfig {
     required this.isFirstLaunchAfterUpdate,
     required this.currentVersion,
     required this.previousVersion,
+    required this.agreementAcceptedVersion,
+    this.extra,
   });
 
   /// 初始化应用配置
   ///
   /// 必须在应用启动时调用（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,
+    dynamic extra,
   }) async {
     // 1. 初始化存储
     await StorageUtil.init();
 
     // 2. 获取版本信息
-    const currentVersion = AppConstants.appVersion;
+    final currentVersion = AppConstants.appVersion;
     final previousVersion = StorageUtil.getString(StorageKeys.appVersion) ?? '';
 
     // 3. 判断启动状态
@@ -104,23 +125,33 @@ class AppConfig {
     final isFirstLaunchAfterUpdate =
         previousVersion.isNotEmpty && previousVersion != currentVersion;
 
-    // 4. 更新存储
+    // 4. 获取协议状态。兼容早期只存 bool 的 demo 版本。
+    final legacyPrivacyAgreed =
+        StorageUtil.getBool(StorageKeys.privacyAgreed) ?? false;
+    final agreementAcceptedVersion =
+        StorageUtil.getString(StorageKeys.agreementAcceptedVersion) ??
+            (legacyPrivacyAgreed ? EnvConfig.agreementVersion : '');
+
+    // 5. 更新存储
     if (isFirstLaunch) {
       await StorageUtil.setBool(StorageKeys.isFirstLaunch, false);
     }
     await StorageUtil.setString(StorageKeys.appVersion, currentVersion);
 
-    // 5. 创建实例
+    // 6. 创建实例
     _instance = AppConfig._(
-      apiBaseUrl: apiBaseUrl ?? AppConstants.apiBaseUrl,
+      env: AppEnv.fromString(EnvConfig.env),
+      apiBaseUrl: EnvConfig.apiBaseUrl,
       connectTimeout: connectTimeout,
       receiveTimeout: receiveTimeout,
-      enableLog: enableLog ?? kDebugMode,
+      enableLog: EnvConfig.enableLog,
       useMockData: useMockData,
       isFirstLaunch: isFirstLaunch,
       isFirstLaunchAfterUpdate: isFirstLaunchAfterUpdate,
       currentVersion: currentVersion,
       previousVersion: previousVersion,
+      agreementAcceptedVersion: agreementAcceptedVersion,
+      extra: extra,
     );
 
     _printInitLog();
@@ -130,13 +161,41 @@ class AppConfig {
     if (!_instance!.enableLog) return;
     debugPrint('┌─────────────────────────────────────');
     debugPrint('│ AppConfig 初始化完成');
+    debugPrint('│ 环境: ${_instance!.env.name}');
     debugPrint('│ API: ${_instance!.apiBaseUrl}');
+    debugPrint('│ 应用: ${_instance!.appName}');
     debugPrint('│ 版本: ${_instance!.currentVersion}');
     debugPrint('│ 首次启动: ${_instance!.isFirstLaunch}');
     debugPrint('│ 更新后首次: ${_instance!.isFirstLaunchAfterUpdate}');
+    debugPrint('│ 协议版本: ${EnvConfig.agreementVersion}');
+    debugPrint('│ 协议已同意: ${_instance!.hasAcceptedAgreement}');
+    if (_instance!.extra != null) {
+      debugPrint('│ 扩展配置: ${_instance!.extra}');
+    }
     debugPrint('└─────────────────────────────────────');
   }
 
+  /// 便捷判断
+  bool get isDev => env == AppEnv.dev;
+  bool get isStaging => env == AppEnv.staging;
+  bool get isProduction => env == AppEnv.production;
+
+  bool get hasAcceptedAgreement =>
+      agreementAcceptedVersion == EnvConfig.agreementVersion;
+
+  bool get shouldShowSplash =>
+      EnvConfig.enableAgreementDialog && !hasAcceptedAgreement;
+
+  /// 接受当前协议版本。
+  static Future<void> acceptCurrentAgreement() async {
+    _instance?.agreementAcceptedVersion = EnvConfig.agreementVersion;
+    await StorageUtil.setString(
+      StorageKeys.agreementAcceptedVersion,
+      EnvConfig.agreementVersion,
+    );
+    await StorageUtil.setBool(StorageKeys.privacyAgreed, true);
+  }
+
   /// 是否已初始化
   static bool get isInitialized => _instance != null;
 }

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

@@ -0,0 +1,107 @@
+// 编译期环境变量读取。
+// 所有值都可通过 `--dart-define-from-file` 或 `--dart-define` 覆盖。
+
+/// 运行环境
+enum AppEnv {
+  dev,
+  staging,
+  production;
+
+  /// 从 .env 文件的 APP_ENV 字符串解析
+  static AppEnv fromString(String value) {
+    return AppEnv.values.firstWhere(
+      (e) => e.name == value,
+      orElse: () => AppEnv.dev,
+    );
+  }
+}
+
+class EnvConfig {
+  EnvConfig._();
+
+  /// 当前运行环境
+  static const String env = String.fromEnvironment(
+    'APP_ENV',
+    defaultValue: 'dev',
+  );
+
+  /// 应用名称
+  static const String appName = String.fromEnvironment(
+    'APP_NAME',
+    defaultValue: '{{projectDisplayName}}',
+  );
+
+  /// 应用版本
+  static const String appVersion = String.fromEnvironment(
+    'APP_VERSION',
+    defaultValue: '1.0.0',
+  );
+
+  /// 应用运营商名称
+  static const String appOperatorName = String.fromEnvironment(
+    'APP_OPERATOR_NAME',
+    defaultValue: '{{projectDisplayName}} Team',
+  );
+
+  /// 隐私联系邮箱
+  static const String privacyContactEmail = String.fromEnvironment(
+    'PRIVACY_CONTACT_EMAIL',
+    defaultValue: 'privacy@example.com',
+  );
+
+  /// 隐私协议生效日期
+  static const String agreementEffectiveDate = String.fromEnvironment(
+    'AGREEMENT_EFFECTIVE_DATE',
+    defaultValue: '2026-01-01',
+  );
+
+  /// API 基础地址
+  static const String apiBaseUrl = String.fromEnvironment(
+    'API_BASE_URL',
+    defaultValue: 'https://example.com',
+  );
+
+  /// 是否启用日志
+  static const bool enableLog = bool.fromEnvironment(
+    'ENABLE_LOG',
+    defaultValue: true,
+  );
+
+  /// 是否使用 Mock 数据
+  static const bool useMockData = bool.fromEnvironment(
+    'USE_MOCK_DATA',
+    defaultValue: true,
+  );
+
+  /// 首页样板列表模式。
+  ///
+  /// 仅用于 starter 验收样板；真实网络示例接入时应替换同一首页列表槽位。
+  static const String demoListMode = String.fromEnvironment(
+    'DEMO_LIST_MODE',
+    defaultValue: 'finite',
+  );
+
+  /// 是否启用隐私协议对话框
+  static const bool enableAgreementDialog = bool.fromEnvironment(
+    'ENABLE_AGREEMENT_DIALOG',
+    defaultValue: true,
+  );
+
+  /// 隐私协议版本
+  static const String agreementVersion = String.fromEnvironment(
+    'AGREEMENT_VERSION',
+    defaultValue: '1.0.0',
+  );
+
+  /// 用户协议 URL
+  static const String userAgreementUrl = String.fromEnvironment(
+    'USER_AGREEMENT_URL',
+    defaultValue: 'https://example.com/agreement',
+  );
+
+  /// 隐私政策 URL
+  static const String privacyPolicyUrl = String.fromEnvironment(
+    'PRIVACY_POLICY_URL',
+    defaultValue: 'https://example.com/privacy',
+  );
+}

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

@@ -1,11 +1,11 @@
- 
- 
 {{#if_network}}
 import '../network/app_http.dart';
 import '../network/interceptors/index.dart';
 import '../network/response_adapter.dart';
 {{/if_network}}
+
 import 'app_config.dart';
+import 'app_env.dart';
 /// 应用初始化器
 ///
 /// 统一管理应用启动前的所有初始化逻辑
@@ -23,15 +23,13 @@ class AppInitializer {
 
   /// 初始化应用
   static Future<void> init({
-    String? apiBaseUrl,
-    bool? enableLog,
-    bool useMockData = false,
+    dynamic extra,
+    bool? useMockData,
   }) async {
     // 1. 初始化应用配置
     await AppConfig.init(
-      apiBaseUrl: apiBaseUrl,
-      enableLog: enableLog,
-      useMockData: useMockData,
+      useMockData: useMockData ?? EnvConfig.useMockData,
+      extra: extra,
     );
 
     {{#if_network}}
@@ -46,26 +44,21 @@ class AppInitializer {
   /// 初始化网络层配置
   static void _initNetwork() {
     AppHttp.init(
-      // 使用图虫 API 适配器 {result, message, feedList}
-      adapter: TuChongAdapter(),
+      // 默认使用通用 {code, msg/message, data} 响应适配器。
+      adapter: DefaultResponseAdapter(),
 
       // 自动显示错误弹窗 (默认 true)
       autoShowError: true,
-
-      interceptors: [
-        // Token 自动注入
-        AuthInterceptor(
-          getToken: () {
-            // 从本地存储获取 token
-            // return StorageUtil.getString('token') ?? '';
-            return '';
-          },
-        ),
+      globalParams: () => {
+        'appVersion': AppConfig.I.currentVersion,
+        'appEnv': AppConfig.I.env.name,
+      },
+      interceptorBuilder: (dio) => [
+{{AUTH_INTERCEPTOR_BLOCK}}
         // 请求重试
         RetryInterceptor(
-          dio: AppHttp().dio,
-          maxRetries: 3,
-          retryDelay: const Duration(seconds: 1),
+          dio: dio,
+          maxRetries: 2,
         ),
       ],
     );

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

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

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

@@ -0,0 +1,158 @@
+import 'package:flutter/gestures.dart';
+import 'package:flutter/material.dart';
+
+import '../index.dart';
+
+/// 隐私协议确认弹窗
+class PrivacyDialog extends StatelessWidget {
+  const PrivacyDialog({super.key});
+
+  /// 显示弹窗
+  static Future<bool?> show(BuildContext context) {
+    return showDialog<bool>(
+      context: context,
+      barrierDismissible: false,
+      barrierColor: Colors.black.withOpacity(0.32),
+      builder: (context) => const PrivacyDialog(),
+    );
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final titleStyle = AppTextStyleConfig.I.titleSmall();
+    final contentStyle = AppTextStyleConfig.I.body();
+    final linkStyle = AppTextStyleConfig.I.body().copyWith(
+          color: AppColorConfig.I.primary,
+        );
+
+    return PopScope(
+      canPop: false,
+      child: Center(
+        child: Container(
+          margin: const EdgeInsets.symmetric(horizontal: 32),
+          padding: const EdgeInsets.all(24),
+          decoration: BoxDecoration(
+            color: Colors.white,
+            borderRadius: BorderRadius.circular(16),
+            boxShadow: const [
+              BoxShadow(
+                color: Color(0x0D000000),
+                blurRadius: 24,
+                offset: Offset(0, 8),
+              ),
+            ],
+          ),
+          child: Column(
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              Text('用户协议与隐私政策', style: titleStyle),
+              const SizedBox(height: 20),
+              ConstrainedBox(
+                constraints: const BoxConstraints(maxHeight: 320),
+                child: SingleChildScrollView(
+                  child: RichText(
+                    text: TextSpan(
+                      style: contentStyle.copyWith(height: 1.6),
+                      children: [
+                        const TextSpan(
+                          text: '欢迎使用 ${EnvConfig.appName}！在您使用前，请您务必仔细阅读',
+                        ),
+                        TextSpan(
+                          text: '《用户协议》',
+                          style: linkStyle,
+                          recognizer: TapGestureRecognizer()
+                            ..onTap = () {
+                              _openAgreementDocument(
+                                context,
+                                AgreementDocumentType.userAgreement,
+                              );
+                            },
+                        ),
+                        const TextSpan(text: '与'),
+                        TextSpan(
+                          text: '《隐私政策》',
+                          style: linkStyle,
+                          recognizer: TapGestureRecognizer()
+                            ..onTap = () {
+                              _openAgreementDocument(
+                                context,
+                                AgreementDocumentType.privacyPolicy,
+                              );
+                            },
+                        ),
+                        const TextSpan(
+                          text: '。我们将严格按照政策规定保护您的个人信息。\n\n'
+                              '1. 我们会收集您的设备信息用于基础统计。\n'
+                              '2. 为了提供更好的服务，我们需要部分系统权限。\n\n'
+                              '如果您同意上述协议，请点击“同意”开始使用。',
+                        ),
+                      ],
+                    ),
+                  ),
+                ),
+              ),
+              const SizedBox(height: 24),
+              Row(
+                children: [
+                  Expanded(
+                    child: OutlinedButton(
+                      onPressed: () {
+                        Navigator.pop(context, false);
+                      },
+                      style: OutlinedButton.styleFrom(
+                        padding: const EdgeInsets.symmetric(vertical: 12),
+                        side: BorderSide(color: AppColorConfig.I.divider),
+                        shape: RoundedRectangleBorder(
+                          borderRadius: BorderRadius.circular(12),
+                        ),
+                      ),
+                      child: Text(
+                        '不同意并退出',
+                        style: AppTextStyleConfig.I.body().copyWith(
+                              color: AppColorConfig.I.titleSecondary,
+                            ),
+                      ),
+                    ),
+                  ),
+                  const SizedBox(width: 16),
+                  Expanded(
+                    child: ElevatedButton(
+                      onPressed: () {
+                        Navigator.pop(context, true);
+                      },
+                      style: ElevatedButton.styleFrom(
+                        backgroundColor: AppColorConfig.I.primary,
+                        padding: const EdgeInsets.symmetric(vertical: 12),
+                        shape: RoundedRectangleBorder(
+                          borderRadius: BorderRadius.circular(12),
+                        ),
+                      ),
+                      child: Text(
+                        '同意',
+                        style: AppTextStyleConfig.I.body().copyWith(
+                              color: Colors.white,
+                            ),
+                      ),
+                    ),
+                  ),
+                ],
+              ),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+
+  Future<void> _openAgreementDocument(
+    BuildContext context,
+    AgreementDocumentType type,
+  ) async {
+    Navigator.push(
+      context,
+      MaterialPageRoute(
+        builder: (context) => AgreementDocumentPage(type: type),
+      ),
+    );
+  }
+}

package/templates/core_files/index.dart.template

@@ -1,4 +1,7 @@
 // 导出核心模块 (按字母顺序排列)
+{{#if_auth}}
+export 'auth/index.dart';
+{{/if_auth}}
 export 'base/index.dart';
 export 'config/index.dart';
 export 'network/index.dart';

package/templates/core_files/mixins/page/keep_alive_mixin.dart.template

@@ -0,0 +1,6 @@
+import 'package:flutter/widgets.dart';
+
+mixin KeepAliveMixin<T extends StatefulWidget> on State<T> {
+  @override
+  bool get wantKeepAlive => true;
+}

package/templates/core_files/mixins/page/scroll_controller_mixin.dart.template

@@ -0,0 +1,7 @@
+mixin ScrollControllerMixin {
+  double lastOffset = 0;
+
+  void cacheScrollOffset(double offset) {
+    lastOffset = offset;
+  }
+}

package/templates/core_files/mixins/service/request_guard_mixin.dart.template

@@ -0,0 +1,18 @@
+mixin RequestGuardMixin {
+  bool _requestInFlight = false;
+
+  bool get hasRequestInFlight => _requestInFlight;
+
+  Future<T> guardRequest<T>(Future<T> Function() action) async {
+    if (_requestInFlight) {
+      throw StateError('A guarded request is already running.');
+    }
+
+    _requestInFlight = true;
+    try {
+      return await action();
+    } finally {
+      _requestInFlight = false;
+    }
+  }
+}

package/templates/core_files/mixins/viewmodel/debounce_mixin.dart.template

@@ -0,0 +1,18 @@
+import 'dart:async';
+
+mixin DebounceMixin {
+  Timer? _debounceTimer;
+
+  void debounce({
+    required Duration duration,
+    required void Function() action,
+  }) {
+    _debounceTimer?.cancel();
+    _debounceTimer = Timer(duration, action);
+  }
+
+  void disposeDebounceMixin() {
+    _debounceTimer?.cancel();
+    _debounceTimer = null;
+  }
+}

package/templates/core_files/network/app_http.dart.template

@@ -40,6 +40,8 @@ class AppHttp {
   static void init({
     AppResponseAdapter? adapter,
     List<Interceptor>? interceptors,
+    List<Interceptor> Function(Dio dio)? interceptorBuilder,
+    Map<String, dynamic> Function()? globalParams,
     bool autoShowError = true,
   }) {
     final instance = AppHttp._instance;
@@ -58,7 +60,14 @@ class AppHttp {
       ),
     );
 
-    // 1. 添加日志拦截器（完整输出，不截断）
+    // 1. 添加全局请求参数拦截器，保证日志记录的是最终请求。
+    if (globalParams != null) {
+      instance._dio.interceptors.add(
+        GlobalParamsInterceptor(getParams: globalParams),
+      );
+    }
+
+    // 2. 添加日志拦截器（完整输出，不截断）
     if (config.enableLog) {
       instance._dio.interceptors.add(
         FullLogInterceptor(
@@ -68,7 +77,7 @@ class AppHttp {
       );
     }
 
-    // 2. 添加响应处理拦截器 (核心)
+    // 3. 添加响应处理拦截器 (核心)
     instance._dio.interceptors.add(
       AppResponseInterceptor(
         adapter: adapter ?? DefaultResponseAdapter(),
@@ -76,12 +85,18 @@ class AppHttp {
       ),
     );
 
-    // 2.5 添加网络错误拦截器
+    // 4. 添加网络错误拦截器
     instance._dio.interceptors.add(
       NetworkErrorInterceptor(autoShowError: autoShowError),
     );
 
-    // 3. 添加自定义拦截器
+    // 5. 添加需要复用当前 Dio 实例的自定义拦截器。
+    final builtInterceptors = interceptorBuilder?.call(instance._dio);
+    if (builtInterceptors != null) {
+      instance._dio.interceptors.addAll(builtInterceptors);
+    }
+
+    // 6. 添加普通自定义拦截器。
     if (interceptors != null) {
       instance._dio.interceptors.addAll(interceptors);
     }

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

@@ -8,5 +8,9 @@ export 'app_http.dart';
 export 'app_response.dart';
 // 网络拦截器
 export 'interceptors/index.dart';
+{{#if_network_monitor}}
+// 网络状态监听
+export 'network_monitor.dart';
+{{/if_network_monitor}}
 // 网络响应适配器
 export 'response_adapter.dart';