# Tencent Qian H5 WebView Container SDK — Android (Java)

纯 Java 实现的腾讯电子签 H5 WebView 容器 SDK，与 `android-kotlin/` 版本功能完全一致，API 保持对等。

## 项目结构

```
android-java/
├── webview-container/       # SDK Library 模块（输出 .aar）
│   ├── src/main/java/       # 源码
│   ├── src/main/res/        # 资源
│   ├── src/test/java/       # 单元测试（JUnit 4 + Robolectric）
│   ├── build.gradle         # 模块级 Groovy DSL
│   ├── consumer-rules.pro   # 消费方 ProGuard 规则
│   └── proguard-rules.pro   # 自身 ProGuard 规则
├── app/                     # Demo Application 模块
│   ├── src/main/java/       # Demo 源码
│   ├── src/main/res/        # Demo 资源
│   └── build.gradle         # 模块级 Groovy DSL
├── gradle/                  # Version Catalog + Wrapper
│   ├── libs.versions.toml
│   └── wrapper/
├── build.gradle             # 根级 Groovy DSL
├── settings.gradle          # 项目设置
├── gradle.properties        # Gradle 配置
├── gradlew / gradlew.bat    # Gradle Wrapper 脚本
└── README.md                # 本文件
```

## 技术栈

| 项目 | 版本/说明 |
|------|-----------|
| 语言 | Java 17 (sourceCompatibility/targetCompatibility) |
| Android Gradle Plugin | 8.7.3 |
| Gradle | 8.9 (via Wrapper) |
| compileSdk | 35 |
| minSdk | 24 |
| targetSdk | 35 |
| 依赖管理 | Version Catalog (`gradle/libs.versions.toml`) |
| 测试框架 | JUnit 4 + Robolectric 4.14.1 |

## 构建

### 前提条件

- JDK 17+（推荐 Temurin / Zulu）
- Android SDK（通过 Android Studio 或 `$ANDROID_HOME` 环境变量）

### 1. 准备本机 Android SDK 路径

```bash
cd android-java
cp local.properties.template local.properties
# 编辑 local.properties，填入 sdk.dir=<本机 Android SDK 路径>
```

### 2. 命令行构建

```bash
# 构建 SDK AAR（Release）
bash scripts/build-android-java.sh sdk

# 构建 Demo APK（Debug）
bash scripts/build-android-java.sh demo

# 全量构建
bash scripts/build-android-java.sh all
```

### 运行单元测试

```bash
bash scripts/test-android-java.sh
```

测试报告输出在 `webview-container/build/reports/tests/` 目录下。

## 集成方式

### 容器模式（推荐）

SDK 提供一个内建的全屏 Activity，客户只需一行代码即可打开签署页：

```java
TencentQianWebView.open(
    activity,
    "https://quick.qian.tencent.cn/sign/...?flowId=...",
    new TencentQianWebViewConfig.Builder()
        .topBarTitle("电子签署")
        .confirmBeforeClose(true)
        .build(),
    new SignCallback() {
        @Override
        public void onSignResult(SignResult result) {
            if (SignResultStatus.SUCCESS.equals(result.getResult())) {
                // 签署成功
            }
        }
    }
);
```

### 配置模式

客户已有自己的 WebView 容器，只需注入 SDK 能力：

```java
TencentQianWebViewConfigurator.Handle handle = TencentQianWebViewConfigurator.apply(
    activity,
    existingWebView,
    new TencentQianWebViewConfig.Builder()
        .userAgentExtra("YourApp/1.0")
        .build(),
    callback
);

// Activity 销毁时清理
handle.detachAndDestroy();
```

### 自检模式

```java
TencentQianWebView.openCompatibilityTest(activity, null, callback);
```

## 与 Kotlin 版本的差异

| 方面 | Kotlin 版本 | Java 版本 |
|------|-------------|-----------|
| Config 构建 | 命名参数构造器 | Builder 模式 |
| 事件类型判断 | `when (event)` | `if-else instanceof` |
| 密封类 | `sealed class SdkEvent` | `abstract class` + `static final` 子类 |
| 数据类 | `data class` | 手写 POJO (equals/hashCode/toString) |
| 内部可见性 | `internal` | package-private（无修饰符） |
| 构建脚本 | Kotlin DSL (.kts) | Groovy DSL (.gradle) |
| 依赖 | core-ktx, activity-ktx, fragment-ktx | core, activity, fragment |

## 许可证

本 SDK 为腾讯电子签内部产品组件，不对外公开发布。
