# web_shell_core

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

## 功能

| 模块 | 说明 |
|---|---|
| **WebView 引擎** | 自动兼容低版本 Android WebView，支持 texture / hybrid 双渲染模式自动切换 |
| **启动恢复** | 看门狗超时检测 → 渲染模式降级 → 深度清理 → 自动重试 |
| **JS Bridge** | `window.AppShell` 协议，当前支持 12 个 Action |
| **旧相机兼容** | Monkey-patch `openCamera` / `captureImage` 兼容老 H5 页面 |
| **媒体服务** | 相机拍照 · 图库选图 · 文件选择 · base64 / dataUrl / uri 三种序列化格式 |
| **权限服务** | camera · microphone · location · photos · videos · storage 统一映射 |
| **导航服务** | URL scheme 白名单路由，非 WebView 协议自动跳转外部应用 |
| **壳层 UI** | 启动加载动画 · 错误恢复页 · 进度条 · 不支持平台兜底页 |
| **启动配置** | 支持本地默认启动配置文件、远程启动配置和缓存兜底 |
| **版本检查** | 升级配置独立请求，不再与启动配置共用一个 JSON |
| **方向控制** | 支持通过启动配置动态设置 `SystemChrome.setPreferredOrientations` |

## 使用方式

### 1. 准备本地默认启动配置文件

`assets/config/bootstrap.json`

```json
{
  "initialUrl": "https://example.com/login",
  "preferredOrientations": ["portraitUp", "portraitDown"]
}
```

### 2. 在应用入口传入环境配置

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

void main() {
  runShellApp(
    ShellEnvironment(
      appName: '全学通',
      appKey: 'quanxue_prod',
      accentColor: const Color(0xFF3ED37B),
      backgroundColor: const Color(0xFFFFFFFF),
      textColor: const Color(0xFF1F2937),
      mutedTextColor: const Color(0xFF6B7280),
      splashImage: const AssetImage('assets/branding/splash.png'),
      bootstrapConfigAsset: 'assets/config/bootstrap.json',
      bootstrapConfigUrl: 'https://example.com/bootstrap.json',
      upgradeConfigUrl: 'https://example.com/upgrade.json',
    ),
  );
}
```

- `bootstrapConfigAsset`：本地默认启动配置文件
- `bootstrapConfigUrl`：可选，远程启动配置地址
- `upgradeConfigUrl`：可选，远程升级配置地址
- `preferredOrientations`：也可以直接在 `ShellEnvironment` 中传入，作为默认值

### 3. 远程启动配置格式

```json
{
  "data": {
    "initialUrl": "https://example.com/login",
    "preferredOrientations": ["portraitUp", "portraitDown"]
  }
}
```

### 4. 远程升级配置格式

```json
{
  "data": {
    "versionName": "1.0.1",
    "version": 101,
    "isForce": 0,
    "remark": "1. 修复已知问题\n2. 优化启动体验",
    "filePath": "https://example.com/app-release.apk",
    "fileSize": 25000
  }
}
```

## 启动时序

```text
runShellApp(env)
  → 读取 bootstrapConfigAsset
  → 拉取 bootstrapConfigUrl（可选）
  → 合并 initialUrl / preferredOrientations
  → setupConfigUrl(upgradeConfigUrl)
  → SystemChrome.setPreferredOrientations(...)
  → runApp(ShellApp)

WebShellPage.initState()
  → 首帧后加载首页
  → 异步检查 upgradeConfigUrl
```

## 支持的 Bridge Action

- `pickImage`
- `captureImage`
- `pickFile`
- `openExternal`
- `requestPermissions`
- `reloadPage`
- `goBack`
- `closeApp`
- `getDeviceInfo`
- `getNetworkStatus`
- `showToast`
- `setStatusBar`

## 代码结构

```text
lib/
├── core_app.dart
├── web_shell_core.dart
└── src/
    ├── config/
    │   ├── shell_environment.dart
    │   └── url_resolver.dart
    ├── engine/
    │   ├── compatibility.dart
    │   └── recovery.dart
    ├── bridge/
    │   ├── bridge_protocol.dart
    │   ├── bridge_actions.dart
    │   └── legacy_camera_compat.dart
    ├── services/
    │   ├── config_service.dart
    │   ├── media_service.dart
    │   ├── permission_service.dart
    │   ├── navigation_service.dart
    │   └── upgrade_service.dart
    ├── ui/
    │   ├── shell_app.dart
    │   ├── shell_page.dart
    │   ├── launch_overlay.dart
    │   ├── error_overlay.dart
    │   ├── progress_bar.dart
    │   └── unsupported_platform_page.dart
    └── testing/
        └── test_hooks.dart
```

## 测试

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

当前测试覆盖：

- 平台检测 · URL 解析 · 启动配置解析 · 方向配置
- Bridge 注入/响应/异常处理 · 媒体序列化 · 权限映射
- 导航路由 · 兼容性策略 · 错误恢复 · 组件渲染

## 平台约束

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

## Android 原生层

`CoreShellActivity`（Java）提供：

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