# web_shell_core

Android 平板专用的 H5 壳核心库。所有品牌应用共享此库，只需传入 `ShellEnvironment` 即可启动。

## 功能

| 模块 | 说明 |
|---|---|
| **WebView 引擎** | 自动兼容低版本 Android WebView，支持 texture / hybrid 双渲染模式自动切换 |
| **启动恢复** | 看门狗超时检测 → 渲染模式降级 → 深度清理 → 自动重试 |
| **JS Bridge** | `window.AppShell` 协议，支持 8 种 Action（pickImage · captureImage · pickFile · openExternal · requestPermissions · reloadPage · goBack · closeApp） |
| **旧相机兼容** | Monkey-patch `openCamera` / `captureImage` 兼容老 H5 页面 |
| **媒体服务** | 相机拍照 · 图库选图 · 文件选择 · base64 / dataUrl / uri 三种序列化格式 |
| **权限服务** | camera · microphone · location · photos · videos · storage 统一映射 |
| **导航服务** | URL scheme 白名单路由，非 WebView 协议自动跳转外部应用 |
| **壳层 UI** | 启动加载动画 · 错误恢复页 · 进度条 · 不支持平台兜底页 |

## 使用方式

```dart
import 'package:web_shell_core/web_shell_core.dart';

void main() {
  runShellApp(
    ShellEnvironment(
      appName: '全学通',
      appKey: 'quanxue_prod',
      accentColor: Color(0xFF3ED37B),
      backgroundColor: Color(0xFFFFFFFF),
      textColor: Color(0xFF1F2937),
      mutedTextColor: Color(0xFF6B7280),
      initialUrl: 'example.com/login',  // 可选，不传使用默认地址
    ),
  );
}
```

## 代码结构

```
lib/
├── core_app.dart                 # 库入口 + part 指令 + runShellApp()
├── web_shell_core.dart           # 公开 API 导出
└── src/
    ├── config/
    │   ├── shell_environment.dart # 品牌配置数据类
    │   └── url_resolver.dart      # URL 解析与归一化
    ├── engine/
    │   ├── compatibility.dart     # Android WebView 兼容检测
    │   └── recovery.dart          # 启动看门狗 + 错误映射
    ├── bridge/
    │   ├── bridge_protocol.dart   # JS Bridge 注入与响应
    │   ├── bridge_actions.dart    # Action handler（占位）
    │   └── legacy_camera_compat.dart # 旧相机 JS 兼容层
    ├── services/
    │   ├── media_service.dart     # 相机/图库/文件 + 序列化
    │   ├── permission_service.dart # 权限类型映射
    │   └── navigation_service.dart # URL 路由 + 外链跳转
    ├── ui/
    │   ├── shell_app.dart         # MaterialApp 入口
    │   ├── shell_page.dart        # WebView 主页面
    │   ├── launch_overlay.dart    # 启动加载动画
    │   ├── error_overlay.dart     # 错误恢复页
    │   ├── progress_bar.dart      # 顶部进度条
    │   └── unsupported_platform_page.dart # 平台兜底页
    └── testing/
        └── test_hooks.dart        # 测试钩子（@visibleForTesting）
```

## 测试

```bash
cd packages/web_shell_core
flutter test
```

当前 **67 个测试用例**，覆盖：
- 平台检测 · URL 解析 · 兼容性策略 · 错误映射
- Bridge 注入/响应/异常处理 · 媒体序列化 · 权限映射
- 导航路由 · 所有独立 UI 组件

## 平台约束

仅支持 **Android**。其他平台会展示兜底提示页。

## Android 原生层

`CoreShellActivity`（Java）提供：
- WebView 数据目录隔离（避免多进程冲突）
- 旧进程自动终止
- WebView 信息查询（SDK 版本、WebView 包名/版本号）
- WebView 状态深度重置
