@_nazmiforreal/flutter-ota 0.1.25 → 0.1.27

package/dart-src/root/README.md

@@ -0,0 +1,394 @@
+# flutter_ota_kit
+
+**English** | [简体中文](README-zh.md)
+
+[![pub package](https://img.shields.io/pub/v/flutter_ota_kit.svg)](https://pub.dev/packages/flutter_ota_kit)
+[![Platform](https://img.shields.io/badge/platform-Android-brightgreen)](https://flutter.dev)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Open-source code push for Flutter Android.**
+
+Ship Dart code and asset hotfixes over the air — no store release, no
+forced vendor lock-in, no per-month fees. Patches live on **your** backend
+(Supabase, Postgres, Cloudflare, AWS, or your own object storage) and load
+on the next cold start.
+
+If you've used [Shorebird](https://shorebird.dev/),
+[CodePush](https://learn.microsoft.com/en-us/appcenter/distribution/codepush/),
+or [Expo EAS Update](https://docs.expo.dev/eas-update/introduction/) —
+flutter_ota_kit is the same OTA update model for Flutter Android, MIT-licensed,
+with your choice of cloud backend.
+
+![Feature demo: apply a patch, cold restart, and rollback](doc/feature-presentation.gif)
+
+---
+
+## How it compares
+
+|                       | flutter_ota_kit                                 | Shorebird                     | CodePush (React Native)       |
+|-----------------------|--------------------------------------------------|-------------------------------|-------------------------------|
+| **Framework**         | Flutter                                         | Flutter                       | React Native                  |
+| **Platforms**         | Android                                         | Android + iOS                 | Android + iOS (retired 2025)  |
+| **Hosting**           | Your backend or your own CDN — see [Backends](doc/backends.md) | Shorebird cloud (managed)     | AppCenter cloud (deprecated)  |
+| **Update scope**      | Dart AOT + Flutter assets                        | Dart code (engine-level diff) | JS bundle                     |
+| **Takes effect**      | Next cold start                                  | Next restart                  | Next restart                  |
+| **Cost**              | Free (MIT)                                      | Free tier + paid plans        | —                             |
+| **Backend flexibility** | Supabase / Postgres / Cloudflare / AWS / bring-your-own | Cloud-managed only            | —                             |
+| **Forced updates**     | Yes — built-in progress UI                       | Yes                           | Yes                           |
+| **Crash rollback**     | Automatic + bad-patch blacklist                  | Yes                           | Yes                           |
+| **Signing**            | Ed25519 (Android 13+) + MD5                      | Yes                           | —                             |
+
+**Choose Shorebird** if you need iOS support today or want a fully managed cloud.
+
+**Choose flutter_ota_kit** if you need OTA on infrastructure you control —
+enterprise apps, regional distribution, air-gapped deployments, or non-Play
+distribution channels. Bring your own backend, your own CDN, your own auth.
+
+> Google Play and some stores restrict downloading executable code at runtime.
+> flutter_ota_kit targets self-controlled, enterprise, or permissive
+> distribution channels. Verify your channel's policy before shipping.
+
+---
+
+## Features
+
+- **OTA code push** — replace the Dart AOT `libapp.so` and Flutter assets on the
+  next cold start, with MD5 + Ed25519 integrity checks.
+- **Five cloud backends** — Supabase (fully automated), Postgres, Cloudflare (D1 + R2),
+  AWS (S3), **PocketBase** (single-binary self-hosted). Or bring your own CDN.
+- **Crash rollback** — automatic on boot failure with a bad-patch blacklist.
+  Configurable via `maxCrashCount` and `verifyAfter`.
+- **Forced updates with built-in UI** — opt into zero-click updates with
+  `autoApplyUpdates: true`; the SDK shows a download spinner, progress bar, and
+  the server's OTA message during the install. No UI code from you.
+- **Staged rollout** — server-side cohort math (per-mille, target-cohorts) lets
+  you ship 1% → 5% → 20% → 50% → 100% safely.
+- **Tooling included** — `pack` CLI (builds patches from release APKs),
+  `flutter_ota_kit console` (web-based admin UI for the sidecar server),
+  runtime diagnostics, sample app.
+- **No native plugin churn** — the patch system uses the Android
+  `ContentProvider` to stage files; no platform channel gymnastics, no
+  per-vendor SDKs to upgrade.
+
+---
+
+## Try it in 5 minutes (no server needed)
+
+```bash
+git clone https://github.com/HYPER12755/flutter-ota-kit.git
+cd flutter_ota_kit/example
+flutter pub get
+flutter build apk --release
+flutter install
+```
+
+1. Launch the app — it shows the **original** `assets/patch_demo.png`.
+2. Tap **Apply patch**.
+3. Swipe the app away from recents and reopen.
+4. The image has changed — the asset patch took effect.
+5. Tap **Rollback** → restart → original image is back.
+
+The example bundles a precompiled `patch.zip`. Everything runs offline on
+the device. For HTTP-based testing with a real backend, see
+[Getting Started](doc/getting-started.md) or the
+[Beginner Guide](doc/beginner-guide.md) (the human-narrated walkthrough).
+
+---
+
+## Requirements
+
+| Item                       | Requirement                                                        |
+|----------------------------|--------------------------------------------------------------------|
+| **Platform**               | Android only (iOS / macOS / Windows / Linux / Web are no-op)         |
+| **Dart SDK**               | `>=3.13.0 <4.0.0`                                                  |
+| **Flutter**                | `>=3.47.0`                                                          |
+| **Android `minSdk`**       | 24                                                                  |
+| **Android `compileSdk`**   | 36                                                                  |
+| **ABI**                    | `armeabi-v7a` / `arm64-v8a` / `x86_64`                              |
+| **NDK**                    | 27.0.12077973+                                                      |
+| **AGP**                    | 8.11.1+ (including AGP 9.x)                                         |
+| **Kotlin**                 | 2.2.20+ (or AGP 9 built-in Kotlin)                                  |
+| **Java / JVM**             | 17                                                                  |
+
+On iOS / macOS / Windows / Linux / Web, every API is safe to call but is a
+**no-op** — the plugin logs a one-time warning and returns safe defaults.
+This makes it safe to ship `flutter_ota_kit` in cross-platform code without
+guarding every call site.
+
+---
+
+## Quick start
+
+### 1. Install
+
+```yaml
+# pubspec.yaml
+dependencies:
+  flutter_ota_kit: ^0.1.10
+```
+
+### 2. Initialize
+
+Call `setupFlutterOta()` (or the bare `FlutterPatcher.init()`) before `runApp()`:
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:flutter_ota_kit/flutter_ota_kit.dart';
+import 'flutter_ota_kit_setup.dart';   // generated by `flutter-ota init <backend>`
+
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  await setupFlutterOta();              // configures the backend + zero-click forced updates
+  runApp(const FlutterOtaApp(child: MyApp()));
+}
+```
+
+`FlutterOtaApp` is the zero-code wrapper that gives the SDK an
+`Overlay` to render the built-in forced-update progress UI into. The user
+sees a download spinner + progress bar + the server's OTA message during
+the install — no UI from you.
+
+Disable the overlay app-wide with `FlutterPatcher.showUpdateUi = false`
+(or `FlutterOtaApp(showUpdateUi: false)`), or host it yourself by
+assigning `MaterialApp.navigatorKey = FlutterPatcher.navigatorKey`.
+
+### 3. Build a patch
+
+Rebuild the release APK, then run `pack` against the new APK to produce
+`dist/patch.zip` and `dist/manifest.json`:
+
+```bash
+dart run flutter_ota_kit:pack \
+  --apk build/app/outputs/flutter-apk/app-release.apk \
+  --version 1.0.0-h1 \
+  --target-version-code 100
+```
+
+To include assets (since 0.1.3), append `--assets`:
+
+```bash
+dart run flutter_ota_kit:pack \
+  --apk build/app/outputs/flutter-apk/app-release.apk \
+  --version 1.0.1 \
+  --target-version-code 100 \
+  --assets assets/hero.png,assets/strings/zh.json
+```
+
+Each asset must be registered in the new APK's `pubspec.yaml`. Upload
+`patch.zip` to your backend (or CDN) and have your update endpoint return
+a `PatchInfo` pointing at it.
+
+### 4. Apply a patch (most apps just do this)
+
+```dart
+final result = await FlutterPatcher.applyPatch(
+  PatchInfo(
+    version: 'fix-1',
+    patchUrl: 'https://your-cdn.com/v100/patch.zip',
+    md5: '0123456789abcdef0123456789abcdef',
+    targetVersionCode: 100,
+  ),
+);
+
+if (result.ok) {
+  // Patch takes effect on the next cold start.
+}
+```
+
+If you manage the download yourself, use `applyPatchBytes`:
+
+```dart
+final bytes = await loadPatchFromYourSource();
+final result = await FlutterPatcher.applyPatchBytes(
+  bytes,
+  version: '1.0.0-h1',
+  targetVersionCode: 100,
+);
+```
+
+### 5. Roll back
+
+```dart
+await FlutterPatcher.rollback();
+```
+
+Deletes the current patch. The app reverts to the APK's built-in version on
+the next cold start. This is **not** the same as a server-side rollback —
+this deletes the local patch, it doesn't change what's in your backend.
+
+---
+
+## How it works
+
+```text
+  ┌─────────────────┐
+  │  Your backend    │  Supabase / Postgres / Cloudflare / AWS / PocketBase / your CDN
+  │  (or CDN)        │  stores: patch.zip (the diff) + manifest.json (the metadata)
+  └────────▲────────┘
+           │  1. check-for-update on launch
+           │  2. server returns PatchInfo (url, md5, signature, version, shouldForceUpdate)
+           │
+  ┌────────┴────────┐
+  │   The app       │
+  │                 │  3. download patch.zip
+  │                 │  4. verify MD5 + Ed25519 signature
+  │                 │  5. write to local patch dir (atomic rename)
+  │                 │  6. cold-restart (forced) OR next cold start (staged)
+  │                 │  7. loader hook reads patched libapp.so + asset overlays
+  │                 │  8. boot succeeds → keep patch
+  │                 │     boot fails    → auto-rollback + blacklist
+  └─────────────────┘
+```
+
+A patch is a **byte-for-byte diff** of the new APK's `libapp.so` against the
+old one (the versionCode the user has installed). Asset patches overlay
+`flutter_assets/` files by path. The patch never ships inside the running
+process — it loads on the next cold start. The cold-restart for forced
+updates goes through `restart_app` (with `RestartMode.process`, which
+actually exits the process so the new code reloads).
+
+Full internals: [Architecture](doc/architecture.md).
+
+---
+
+## What can and can't be patched
+
+| ✅ Hot-patchable                                                | ❌ Not hot-patchable                                                  |
+|-----------------------------------------------------------------|-----------------------------------------------------------------------|
+| Anything in `lib/` — widgets, logic, routes, constants, tests  | Native code (Kotlin / Java / C++ in `android/src/main/`)              |
+| Pure-Dart package upgrades (same native side)                  | `AndroidManifest.xml` changes                                       |
+| Flutter asset files (registered in `pubspec.yaml`)            | APK `res/` (icons, layouts, strings.xml)                            |
+| New `Image.asset()` / `rootBundle.load()` calls pick up new bytes | Flutter Engine upgrades                                            |
+|                                                                 | Adding or removing native plugins                                   |
+|                                                                 | Removing assets that exist in the base APK                           |
+|                                                                 | `pubspec.yaml` font registration changes                              |
+
+For edge cases (ProGuard/R8, multi-ABI / flavors, state migrations, asset
+overlay quirks), see [API Reference → What can be patched](doc/api-reference.md#what-can-and-cannot-be-patched).
+
+---
+
+## Safety
+
+### Crash protection (on by default)
+
+The plugin is **fail-fast**: if a patch causes a boot failure, it auto-rolls
+back and blacklists the offending version so it won't be retried. Tunable
+via `maxCrashCount` (default 1) and `verifyAfter` (default 5s).
+
+Design and Android version differences:
+[Crash Protection](doc/crash-protection.md).
+
+### Integrity & signing
+
+- **MD5** verification is strongly recommended; omit only for quick testing.
+- **Ed25519 signature** verification is available on Android 13+ (API 33).
+  Falls back to MD5-only on older Android (with a warning).
+- Patches are bound to the host APK's `versionCode` — old patches expire
+  after an APK upgrade and the server stops serving them.
+- Always download over HTTPS. Keep private signing keys on the server only,
+  never in the app bundle.
+
+### Production tips
+
+- **Stage your rollout** (1% → 5% → 20% → 50% → 100%) and monitor crash
+  rate at each stage. The SDK records `lastBootDiagnostic` per device.
+- **Report diagnostics** to your analytics pipeline so you can spot a bad
+  patch before users hit the app.
+- **Prepare for emergency rollback** — stop returning the bad patch from
+  your endpoint; devices that already tripped crash protection have
+  rolled back locally and won't re-download.
+
+Full release workflow + diagnostic-reporting code:
+[Production Playbook](doc/production-playbook.md).
+
+---
+
+## FAQ
+
+**Q: Must the patch and base APK use the same Flutter version?**
+A: Yes. `libapp.so` is tightly coupled to the Flutter Engine ABI.
+After upgrading the SDK, ship a new release.
+
+**Q: Why doesn't a patch take effect immediately?**
+A: Once `libapp.so` is loaded by the current process, it can't be swapped
+at runtime. The patch is written to disk and loaded on the next cold
+start. Forced updates trigger a process restart so the new code loads
+immediately.
+
+**Q: Why does each patch need a `targetVersionCode`?**
+A: Two reasons: (1) old patches expire after an APK upgrade (so a user on
+v2 doesn't accidentally load a v1-targeted patch), and (2) the server
+won't ship a patch built for v1 to a user on v2 (the SDK filters them
+out at update-check time).
+
+**Q: How does the client report its app version, and why must it match `--target-app-version`?**
+A: The client reports an `appVersion` that the backend matches against
+each bundle's `target_app_version`. By default this is **auto-detected at
+runtime** from the host app's `versionName` via `package_info_plus` — no
+build flag needed. You can override it explicitly with
+`--dart-define=APP_VERSION=1.2.3` or `SupabaseUpdateConfig.appVersion`.
+The backend keeps only bundles whose `target_app_version` is
+semver-compatible with the reported version. **If they don't match, the
+backend returns no bundle and the app silently stays "up to date"** — so
+always deploy with `--target-app-version` equal to the app's real
+`versionName` (e.g. `1.0.1` for a `version: 1.0.1+2` pubspec). A mismatched
+version is the most common cause of "the update never arrives".
+
+More questions: [Full FAQ](doc/faq.md).
+
+---
+
+## Documentation
+
+**Guides** (narrative, in reading order)
+
+- [Beginner Guide](doc/beginner-guide.md) — zero-to-first-OTA walkthrough, as a human would do it
+- [Getting Started](doc/getting-started.md) — scaffold → build → deploy in 5 minutes
+- [Developer Guide](doc/developer-guide.md) — full workflow reference (init, migrate, build, deploy, SDK API, targeting, troubleshooting)
+- [Configuration](doc/configuration.md) — every env var, `.env`, resolution order, secrets policy
+- [Backends](doc/backends.md) — Supabase / Postgres / Cloudflare / AWS / PocketBase setup, env vars, CLI snippets
+- [Production Playbook](doc/production-playbook.md) — staged rollout, diagnostics, emergency rollback
+
+**Reference**
+
+- [API Reference](doc/api-reference.md) — `FlutterPatcher` methods, error codes, asset patching
+- [Architecture](doc/architecture.md) — internals, server protocol, signing, advanced config
+- [CLI Reference](doc/cli-reference.md) — every command, subcommand, and flag
+- [Crash Protection](doc/crash-protection.md) — auto-rollback, blacklist, Android version differences
+- [Golden Testing](doc/golden-testing.md) — how Flutter's pixel-perfect test system works (and how this project uses it)
+
+**Other**
+
+- [FAQ](doc/faq.md) — versioning, cold start, store policy
+- [CHANGELOG.md](CHANGELOG.md) — release notes
+
+中文文档: [README-zh.md](README-zh.md) · [api-reference-zh](doc/api-reference-zh.md) ·
+[architecture-zh](doc/architecture-zh.md) · [crash-protection-zh](doc/crash-protection-zh.md) ·
+[getting-started-zh](doc/getting-started-zh.md) · [production-playbook-zh](doc/production-playbook-zh.md) ·
+[faq-zh](doc/faq-zh.md)
+
+---
+
+## Who's using it?
+
+If you run flutter_ota_kit in production, [open an issue](https://github.com/HYPER12755/flutter-ota-kit/issues) and tell us about your use case — we'd love to list you here.
+
+---
+
+## Contributing
+
+Issues and PRs are welcome.
+
+Before submitting, please make sure:
+
+- `flutter analyze` reports no warnings
+- `flutter test` is fully green
+- If you touched native code, you've run a real-device end-to-end patch / rollback flow
+- If you added a new public API, you've documented it on `dartdoc_options.yaml` topics (the doc appears on pub.dev)
+
+---
+
+## License
+
+MIT

package/dart-src/root/analysis_options.yaml

@@ -0,0 +1,21 @@
+# Root analysis options for the flutter_ota_kit monorepo.
+#
+# The repo is a monorepo: `packages/*`, `plugins/*`, and `example/` are each
+# standalone Dart/Flutter packages that are analyzed (and lint-configured)
+# independently. Excluding them here keeps `dart analyze .` focused on the root
+# device-SDK package (`lib/` + `test/`), which is the only thing the root
+# package owns. Each sub-package is analyzed on its own and is already clean.
+analyzer:
+  exclude:
+    - packages/**
+    - plugins/**
+    - example/**
+    - node_modules/**
+    - npm/**
+    - build/**
+    - android/**
+    - ios/**
+    - web/**
+    - windows/**
+    - macos/**
+    - linux/**

package/dart-src/root/android/build.gradle

@@ -0,0 +1,116 @@
+group = "com.flutter_patcher.flutter_patcher"
+version = "1.0-SNAPSHOT"
+
+buildscript {
+    ext.kotlin_version = "2.2.20"
+    repositories {
+        google()
+        mavenCentral()
+    }
+
+    dependencies {
+        classpath("com.android.tools.build:gradle:8.11.1")
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version")
+    }
+}
+
+allprojects {
+    repositories {
+        google()
+        mavenCentral()
+    }
+}
+
+apply plugin: "com.android.library"
+
+// AGP 9 compiles Kotlin itself ("built-in Kotlin") and rejects the
+// kotlin-android plugin. AGP 9 hosts that opt out via
+// `android.builtInKotlin=false` -- which is what the Flutter 3.44 template
+// generates -- still need us to bring our own KGP, exactly like AGP 8 hosts.
+// So the switch is built-in Kotlin, not the AGP major on its own.
+def agpMajor = com.android.Version.ANDROID_GRADLE_PLUGIN_VERSION.tokenize('.')[0] as int
+def builtInKotlinFlag = project.findProperty("android.builtInKotlin")
+def builtInKotlin = agpMajor >= 9 &&
+    (builtInKotlinFlag == null || Boolean.parseBoolean(builtInKotlinFlag.toString()))
+
+// Keep this as a literal `apply plugin:` at line start even though it is
+// guarded. The Flutter Gradle Plugin regex-matches this file's text to decide
+// whether a subproject brings its own KGP; when it finds none it applies
+// kotlin-android to us itself, which hard-fails under built-in Kotlin. The cost
+// is that FGP prints its "plugin applies KGP" warning on AGP 9 even when this
+// branch never runs.
+if (!builtInKotlin) {
+    apply plugin: "kotlin-android"
+}
+
+tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
+    // Kotlin incremental cache path relativization can fail on Windows when a
+    // Flutter plugin is compiled from Pub Cache on C: into an app on another
+    // drive. Keep this library compile non-incremental; app modules are
+    // unaffected.
+    incremental = false
+}
+
+android {
+    namespace = "com.flutter_patcher.flutter_patcher"
+
+    compileSdk = 36
+    ndkVersion = "27.0.12077973"
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    if (!builtInKotlin) {
+        // Contributed by KGP, not by AGP -- only exists where KGP was applied.
+        kotlinOptions {
+            jvmTarget = JavaVersion.VERSION_17
+        }
+    }
+
+    sourceSets {
+        main.java.srcDirs += "src/main/kotlin"
+        test.java.srcDirs += "src/test/kotlin"
+    }
+
+    defaultConfig {
+        minSdk = 24
+
+        // ABI 白名单：覆盖主流 Android 设备。Flutter 默认只出 arm64-v8a，
+        // 但插件要兼容 32 位旧机型和 x86_64 模拟器。
+        ndk {
+            abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86_64'
+        }
+
+        // 让 AGP 把本插件的 consumer R8 规则合并到宿主 release build
+        consumerProguardFiles 'consumer-rules.pro'
+    }
+
+    dependencies {
+        testImplementation("org.jetbrains.kotlin:kotlin-test")
+        testImplementation("org.json:json:20240303")
+        testImplementation("org.mockito:mockito-core:5.0.0")
+    }
+
+    testOptions {
+        unitTests.all {
+            useJUnitPlatform()
+            jvmArgs "-Dnet.bytebuddy.experimental=true"
+
+            testLogging {
+               events "passed", "skipped", "failed", "standardOut", "standardError"
+               outputs.upToDateWhen {false}
+               showStandardStreams = true
+            }
+        }
+    }
+}
+
+if (builtInKotlin) {
+    kotlin {
+        compilerOptions {
+            jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17
+        }
+    }
+}

package/dart-src/root/android/consumer-rules.pro

@@ -0,0 +1,23 @@
+# flutter_patcher consumer ProGuard / R8 rules.
+# AGP merges this file into the host app release R8 configuration.
+# Goal: keep the small set of Android / Flutter classes referenced by manifest
+# entries or startup reflection.
+
+# Application: referenced by AndroidManifest android:name.
+-keep class com.flutter_patcher.flutter_patcher.FlutterPatcherApplication { *; }
+
+# Auto-init ContentProvider: declared by the plugin manifest.
+-keep class com.flutter_patcher.flutter_patcher.FlutterPatcherAutoInitProvider { *; }
+
+# Flutter plugin: registered by GeneratedPluginRegistrant.
+-keep class com.flutter_patcher.flutter_patcher.FlutterPatcherPlugin { *; }
+
+# PatchedFlutterLoader is installed reflectively and overrides engine init.
+-keep class com.flutter_patcher.flutter_patcher.PatchedFlutterLoader {
+    <init>(...);
+    public void ensureInitializationComplete(android.content.Context, java.lang.String[]);
+}
+
+# Flutter Engine reflection targets used by LoaderHook.
+-keep class io.flutter.FlutterInjector { *; }
+-keep class io.flutter.embedding.engine.loader.FlutterLoader { *; }

package/dart-src/root/android/settings.gradle

@@ -0,0 +1 @@
+rootProject.name = 'flutter_patcher'

package/dart-src/root/android/src/main/AndroidManifest.xml

@@ -0,0 +1,21 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+  package="com.flutter_patcher.flutter_patcher">
+  <!-- 宿主 App 必须自行声明 INTERNET 权限以允许补丁下载 / checkUpdate 发起 HTTP 请求 -->
+
+  <application>
+    <!--
+      自动初始化：在 ContentProvider.onCreate 阶段（早于 Application.onCreate /
+      任何 FlutterActivity.onCreate）完成熔断检查 + FlutterLoader 反射替换，宿主
+      无需接入 Application。
+
+      需要关掉的极少数场景（如在 Application.attachBaseContext 预热 FlutterEngine）
+      可在宿主 Manifest 里用 tools:node="remove" 移除本 provider，然后显式调
+      FlutterPatcherApplication.attachPatcher(base)。详见 README。
+    -->
+    <provider
+      android:name="com.flutter_patcher.flutter_patcher.FlutterPatcherAutoInitProvider"
+      android:authorities="${applicationId}.flutter_patcher.autoinit"
+      android:exported="false"
+      android:initOrder="100" />
+  </application>
+</manifest>

package/dart-src/root/android/src/main/kotlin/com/flutter_patcher/flutter_patcher/ApplyResult.kt

@@ -0,0 +1,52 @@
+package com.flutter_patcher.flutter_patcher
+
+/**
+ * [PatchManager.applyPatch] 的结构化返回值。
+ *
+ * 通过 MethodChannel 以 `Map<String, Any?>` 形式序列化到 Dart 侧，由
+ * `PatchApplyResult.fromNative()` 反解。
+ *
+ * 错误码与使用建议见 [ApplyErrorCode]。
+ */
+internal data class ApplyResult(
+    val ok: Boolean,
+    val errorCode: String? = null,
+    val message: String? = null
+) {
+    fun toMap(): Map<String, Any?> = mapOf(
+        "ok" to ok,
+        "error" to errorCode,
+        "message" to message
+    )
+
+    companion object {
+        val SUCCESS = ApplyResult(ok = true)
+
+        fun failure(code: String, message: String? = null): ApplyResult =
+            ApplyResult(ok = false, errorCode = code, message = message)
+    }
+}
+
+/**
+ * applyPatch 可能的失败原因。调用方（Dart 业务层）按需要做不同处理：
+ *
+ * - [INVALID_ARGS]：服务端下发的 JSON 缺字段 → 告警服务端
+ * - [BLACKLISTED]：(version, md5) 已在本地黑名单 → 服务端告警，下架补丁
+ * - [NETWORK]：下载失败（重试后依然失败）→ 稍后重试
+ * - [MD5_MISMATCH]：下载文件 md5 不匹配 → CDN 脏数据或服务端 md5 算错，检查后重试
+ * - [SIGNATURE_INVALID]：Ed25519 验签失败（或 strict 模式下 API < 33 直接拒绝）→
+ *   可能被篡改，**不建议**自动重试
+ * - [IO_ERROR]：磁盘 / 文件系统错误（磁盘满、权限）→ 稍后重试
+ * - [UNKNOWN]：未被分类的异常 → 上报到监控，看日志定位
+ */
+internal object ApplyErrorCode {
+    const val INVALID_ARGS = "INVALID_ARGS"
+    const val BLACKLISTED = "BLACKLISTED"
+    const val NETWORK = "NETWORK"
+    const val MD5_MISMATCH = "MD5_MISMATCH"
+    const val SIGNATURE_INVALID = "SIGNATURE_INVALID"
+    const val UNSUPPORTED_ABI = "UNSUPPORTED_ABI"
+    const val ASSET_PACKAGE_INVALID = "ASSET_PACKAGE_INVALID"
+    const val IO_ERROR = "IO_ERROR"
+    const val UNKNOWN = "UNKNOWN"
+}