web_shell_flutter/doc/plan.md

Role & Context

你是一个精通 Flutter 混合架构（Hybrid App）与移动端 APM（应用性能监控）的资深架构师。

当前任务：为一款基于“单工程多风味（Flavors）”架构的教育平板应用（包含“劝学”和“点智学”两个 Flavor）生成核心 MVP 代码框架与监控埋点方案。

底层环境约定：兼容 Android 14（量产基线）并向下兼容处理 Android 15 的 WindowInsets（Edge-to-Edge）特性。

Product Architecture (Flutter 壳与 H5 的边界界定)

本 MVP 采用“瘦壳重网页”模式：

1. Flutter 壳职责： 仅负责生命周期管理、沉浸式/Kiosk 模式控制、设备硬件能力桥接（相机/录音/持久化存储）、全局骨架屏（Loading）、以及高可用 WebView 容器的维护。

2. H5 职责： 承载所有教学业务逻辑（题库、视频播放、个人中心）。

3. 通信机制： 统一通过注入的 JSBridge 进行双向通信。

MVP Core Modules (核心功能模块需求)

1. 动态环境与配置引擎 (Config Engine)

• 需求： 读取 --dart-define=APP_FLAVOR。

• 功能： 根据 Flavor 动态下发不同的 baseUrl（H5 首页地址）、主题色、以及持久化缓存策略。

2. 高可用 WebView 容器 (Core Web Container)

• 核心依赖： 使用 webview_flutter 或 flutter_inappwebview。

• Android 15 兼容性（关键）： WebView Widget 必须包裹在自定义的 SafeArea 或响应 WindowInsets 的布局中，将顶部的 statusBarHeight 和底部的 navigationBarHeight 动态获取，并作为 URL 参数或注入的 JS 变量传给 H5，供前端写 CSS 避让区。

• Cookie 策略： 必须显式开启 Third-Party Cookies 和 DOM Storage，确保跨域 SSO 单点登录不掉线。

3. 标准化 JSBridge 协议层

要求实现一个健壮的 JSBridge 类，至少包含以下基础方法，供 H5 调用：

• getDeviceInfo(): 返回系统版本、电量、当前网络状态（WiFi/4G）。

• setImmersiveMode(boolean): 控制隐藏/显示系统状态栏和底部导航栏。

• openCamera(config): 唤起原生相机并返回 Base64 或文件路径。

• reportEvent(eventName, params): H5 将核心业务埋点转发给 Flutter 壳进行统一上报。

4. Kiosk Mode (专注模式/设备管控)

• 预留 MethodChannel 接口，命名为 DeviceControlChannel。

• 包含方法 enableKioskMode() 和 disableKioskMode()（具体 Android 原生端 startLockTask 逻辑暂用 TODO 占位，需定义好 Dart 侧的调用规范）。

---

APM & Observability Metrics (应用性能与稳定性指标体系)

请在代码中创建一个 AppMonitor 单例类，负责拦截并上报以下三大类核心指标（目前先在控制台打印日志，预留后续接入 Firebase / Sentry / 自研后端的接口）：

1. 容器加载性能指标 (Performance)

• Shell_Launch_Time: Flutter 引擎初始化到原生首屏（Splash 结束）的耗时。

• WebView_Init_Time: 从触发加载到 WebView 实例创建完成的耗时。

• H5_TTFB (Time to First Byte): Web 页面发出请求到收到第一个字节的耗时（需注入 JS 获取）。

• H5_FCP (First Contentful Paint): 白屏时间（从 onPageStarted 到 onPageFinished，结合 JS 注入获取真实渲染时间）。

2. 稳定性指标 (Stability)

• WebView_Crash_Rate: 捕获 onWebResourceError，特别是 OOM（内存溢出）导致的白屏终止。

• JSBridge_Fail_Count: 统计 H5 调用原生能力失败的次数与错误码（如权限被拒、参数格式错误）。

• Http_Error_Rate: 拦截并统计 WebView 内发生的 404/500 等静态资源或接口请求错误。

3. 业务与设备指标 (Business & Device)

• Session_Duration: 从应用 resumed 到 paused 的有效停留时间。

• Network_Switch_Count: 监听网络状态，记录用户在弱网/断网环境下的掉线频次。

---

Execution Steps for Code X (执行步骤)

请一步步为我生成上述方案的代码骨架：

1. Step 1: 生成目录结构建议（基于 feature 驱动或分层架构）。

2. Step 2: 生成 Config Engine 与 AppMonitor 的单例类代码，实现核心指标的日志打印结构。

3. Step 3: 编写核心的 HybridWebView Widget，包含 Insets 处理、Cookie 策略配置和首屏加载时间计算。

4. Step 4: 编写 JSBridge 核心处理类，实现拦截 H5 消息并路由到对应原生方法的逻辑。