junny_dev_kit 3.0.3

JunnySoft开发工具包.

JunnySoft Dev Kit

企业级Flutter开发工具包，提供统计分析、数据库管理、多语言翻译等完整解决方案。

📚 文档中心

📖 查看完整文档 - 包含API参考、最佳实践、示例代码、故障排除等完整文档

🚀 核心功能

• 📊 统计分析系统 - 企业级用户行为追踪和性能监控
• 🗄️ 数据库管理 - 高性能多实例数据库解决方案
• 🌐 多语言翻译 - 动态国际化和本地化支持
• 🔧 开发工具 - ISpect Console集成的调试和监控工具

Getting Started

dependencies:
  junny_dev_kit: ^latest_version // 替换成最新的版本号

内嵌附件预览

dev_kit 使用 pub.dev 发布的 junny_previewer: ^0.1.3 和 junny_previewer_assets_full: ^0.1.2，默认使用 full 档位，在 Android/iOS 页面内嵌 File Viewer。full 档位覆盖当前资源包注册的 Office、PDF、表格、文本、 图片、压缩包、音视频、邮件、CAD、3D、地图、脑图和电子书等格式；带鉴权 headers 的文件由 Dart/Dio 下载流注入 WebView，预览器失败时回退原有图片、PDF、 系统打开和分享链路。

宿主初始化时可以覆盖档位、来源白名单和大小上限：

await JunnyKitConfig.init(
  package: 'com.example.app',
  filePreviewConfig: const JunnyFilePreviewConfig(
    maxFileBytes: 50 * 1024 * 1024,
    allowedOrigins: <String>{'https://files.example.com'},
  ),
);

完整 full 档位需要同时依赖 junny_previewer_assets_full，资源约 201 MB； 发布前应根据应用格式覆盖需求选择资源档位，并在 Android WebView 和 iOS WKWebView 真机上验证 Worker、WASM、超大文件和回退行为。

导入开发包

import 'package:junny_dev_kit/junny_dev_kit.dart';

🚀 快速使用

统计分析

// 页面访问统计
AnalyticsUtils.instance.trackPageView(pageName: '/home');

// 按钮点击统计
AnalyticsUtils.instance.trackButtonClick(buttonName: 'submit');

// 性能监控
AnalyticsUtils.instance.trackPerformance(
  operationType: 'api_call',
  duration: Duration(milliseconds: 200),
);

ISpect Console 调试

在ISpect Console中新增了统计功能：

• 📊 统计导出 - 支持JSON、CSV、报告格式
• 🧪 统计测试 - 一键测试所有统计功能

ISpect 日志模式

dev_kit 内置三种 ISpect 日志 profile：

• daily：默认日常排查模式。保留 warning、error、route、HTTP request/response 摘要，默认关闭完整 headers/body、重复网络 analytics 和 loading diagnostic。
• deepNetwork：现场深度网络排查模式。可在 debug、profile、release 中通过 ISpect 面板按钮切换，后续请求会采集更详细的 headers/body、network analytics 和 loading diagnostic。
• productionSafe：导出、分享和高敏场景的安全模式。默认只输出摘要；内部排障可显式选择 redactedPayload 保留非敏感 headers/body/data；完整 rawPayload 只用于授权后的本机排查。

ISpect 的上游编译门默认关闭。需要面板的 debug、profile 或 release 构建都必须显式传入：

flutter run --dart-define=ISPECT_ENABLED=true

编译启用后，debug 面板默认显示；profile/release 保留隐藏的 ISpectScope，可由宿主的开发者模式入口在运行时开启。

宿主应通过 JunnyISpectUtils 查询和切换面板，避免直接读取不存在的 ISpectScope：

DeveloperModeListener(
  onActivated: () => JunnyISpectUtils.togglePanel(context),
  child: const Text('Version 1.0.0'),
);

JunnyISpectUtils.isPanelEnabled(context) 可用于生成开启或关闭提示。未编入 ISpect、因而不存在 Scope 时，两个方法都会安全返回 false。

推荐接入方式：

const ispectLogConfig = JunnyISpectLogConfig(
  profile: JunnyISpectLogProfile.daily,
  additionalSensitiveKeys: <String>{'attendanceUserId'},
);

void main() async {
  runWithConsole(
    const MyApp(),
    ispectLogConfig: ispectLogConfig,
  );

  await JunnyKitConfig.init(
    package: 'com.example.app',
    inspectorConfig: JunnyInspectorConfig(
      ispectLogConfig: ispectLogConfig,
    ),
  );
}

ISpect 面板会显示日志模式切换按钮，用于 daily <-> deepNetwork 运行时切换；该能力不因 release 构建被隐式关闭。切换只影响后续采集：从 deepNetwork 切回 daily 后，历史中已经采集到的详细日志仍然存在，分享前请清空历史或使用 productionSafe 导出路径。

如果需要分析完整接口参数或响应体，可在面板中打开 原始数据。该开关会让后续请求进入 deepNetwork + enableRedaction:false + rawPayload，用于本机或内部授权排查；关闭后恢复进入前的日志 profile。ISpect 默认分享入口仍会强制转为 productionSafe + summaryOnly，不会因为当前处于原始数据模式而自动外发 raw payload。

ISpect JSON 日志分析 CLI

CLI 可读取 ISpect 导出的 JSON 文件并生成 Markdown 排障报告：

dart run bin/ispect_log_analyzer.dart path/to/ispect_logs.json \
  --output build/ispect-report.md \
  --slow-ms 1000 \
  --context-seconds 3 \
  --sensitive-key attendanceUserId

报告会包含总日志数、时间范围、日志类型分布、warning/error、慢请求、网络事务摘要、问题链上下文和敏感字段风险。默认 --payload summary 不展开 headers/body/data，适合外发分享。

内部排查接口参数或响应字段不一致时，可以显式保留脱敏后的 payload：

dart run bin/ispect_log_analyzer.dart path/to/ispect_logs.json \
  --output build/ispect-report.md \
  --payload redacted \
  --sensitive-key attendanceUserId

--payload redacted 会保留 JSON 结构和非敏感字段值，只遮蔽 token、authorization、password、mobile、userId、tenantId 以及业务补充敏感字段。--payload raw 会输出完整原文并带 RAW_PAYLOAD_INTERNAL_ONLY 提示，只应在本机或内部授权场景使用，禁止直接外发。

更多功能

查看 📖 完整文档 了解数据库、翻译等更多功能的使用方法。

安卓的权限依赖

    <!-- 访问网络状态-->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />

    <!-- 外置存储存取权限 -->
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.ACCESS_MEDIA_LOCATION" />
    
    <!-- For android 13/API33 -->
    <!-- Add this if you need to take photos. -->
    <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
    
    <!--Starting with API 33. this permission is needed for notifications-->
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

    <!-- 控制呼吸灯，振动器等，用于新消息提醒 -->
    <uses-permission android:name="android.permission.FLASHLIGHT" />
    <uses-permission android:name="android.permission.VIBRATE" />

    <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
    
    <queries>
        <!-- Place inside the <queries> element. -->
        <intent>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data android:scheme="https" />
        </intent>

        <!-- If your app checks for SMS support -->
        <intent>
            <action android:name="android.intent.action.VIEW" />
            <data android:scheme="sms" />
        </intent>

        <!-- If your app checks for call support -->
        <intent>
            <action android:name="android.intent.action.VIEW" />
            <data android:scheme="tel" />
        </intent>
    </queries>

---

一些依赖包需要在项目做的各种配置

background_downloader

Android

No setup is required if you don't use notifications. If you do:

• Starting with API 33, you need to add <uses-permission android:name="android.permission.POST_NOTIFICATIONS" /> to your app's AndroidManifest.xml
• If needed, localize the button text by overriding string resources bg_downloader_cancel, bg_downloader_pause, bg_downloader_resume and descriptions bg_downloader_notification_channel_name, bg_downloader_notification_channel_description.

Using foreground service on Android targeting API 34

If targeting API 34 or greater, you must add to your AndroidManifest.xml a permission declaration <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" /> and the foreground service type definition (under the application element):

<service
  android:name="androidx.work.impl.foreground.SystemForegroundService"
  android:foregroundServiceType="dataSync"
  tools:node="merge" />

iOS

On iOS, ensure that you have the Background Fetch capability enabled:

• Select the Runner target in XCode
• Select the Signing & Capabilities tab
• Click the + icon to add capabilities
• Select 'Background Modes'
• Tick the 'Background Fetch' mode

Note that iOS by default requires all URLs to be https (and not http). See here for more details and how to address issues.

If using notifications, add the following to your AppDelegate.swift:

UNUserNotificationCenter.current().delegate = self as UNUserNotificationCenterDelegate

or if using Objective C, add to AppDelegate.m:

[UNUserNotificationCenter currentNotificationCenter].delegate = (id<UNUserNotificationCenterDelegate>) self;

back_button_interceptor

To make it work on Android 13 and up, set this to false in the Android manifest:

<activity
    android:name=".MainActivity"
    android:enableOnBackInvokedCallback="false">