125 lines
4.5 KiB
Markdown
125 lines
4.5 KiB
Markdown
# 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 消息并路由到对应原生方法的逻辑。 |