# 华为快应用 HwService JS SDK 集成指南

## 概述

本文档介绍如何将该 uni-app 项目以 H5 壳模式部署到华为快应用平台，并集成华为 HwService JS SDK（帐号服务 + 分析服务）。

## 项目架构

```
H5 壳模式快应用架构：
┌─────────────────────────────────────┐
│      华为快应用引擎 (QuickApp Runtime)     │
│  ┌─────────────────────────────────┐ │
│  │     WebView (H5 页面)            │ │
│  │  ┌───────────────────────────┐  │ │
│  │  │  uni-app 应用              │  │ │
│  │  │  ├─ common/js/hw-jssdk.js │  │ │
│  │  │  ├─ common/js/auth.js     │  │ │
│  │  │  └─ store/index.js        │  │ │
│  │  └───────────────────────────┘  │ │
│  └─────────────────────────────────┘ │
│              │ HwService Bridge       │
│              ▼                       │
│  ┌─────────────────────────────────┐ │
│  │  HMS Core (华为移动服务)          │ │
│  │  ├─ Account Kit (帐号服务)       │ │
│  │  ├─ Analytics Kit (分析服务)     │ │
│  │  └─ Push Kit (推送服务，可选)    │ │
│  └─────────────────────────────────┘ │
└─────────────────────────────────────┘
```

## 部署前准备

### 1. 华为 AppGallery Connect 配置

1. 登录 [AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html)
2. 创建应用（选择「快应用」类型）
3. 开启以下服务：
   - **华为帐号服务 (Account Kit)**
   - **华为分析服务 (Analytics Kit)**（可选）
   - **华为推送服务 (Push Kit)**（可选）
4. 下载 `agconnect-services.json` 配置文件
5. 将配置文件放入项目根目录

### 2. 安装 npm 依赖

```bash
# 基础桥接库（必装，提供 hmsjsb.invoke 桥接能力）
npm install --save @hw-hmscore/hms-js-base

# 华为分析服务封装包（可选，提供更完善的 API 封装）
npm install --save @hw-hmscore/analytics-sdk-quickapp
```

**注意：**
- **Account Kit（帐号服务）** 和 **Push Kit（推送服务）** 没有独立的 quickapp npm 包，统一通过 `@hw-hmscore/hms-js-base` 的 `hmsjsb.invoke()` 桥接调用
- `@hw-hmscore/analytics-sdk-quickapp` 版本 `6.10.0-301`（ISC 许可证），**可选安装**——不装则走 invoke 桥接
- 相关 npm 包由华为官方发布（`hmscore@huawei.com`）

### 3. 配置 HUAWEI 条件编译

本项目的 `package.json` 已为各快应用域名定义自定义发行脚本：

| 脚本名 | 条件编译标记 | 用途 |
|--------|------------|------|
| `h5-xcx20.5g-quickapp.com` | `H5_XCX_5G_QUICKAPP_COM` | 5G 快应用 |
| `h5-xcx.aigc-quickapp.com` | `H5_XCX_AIGC_QUICKAPP_COM` | AIGC 快应用 |
| `h5-5g.aigc-quickapp.com` | `H5_5G_AIGC_QUICKAPP_COM` | 5G AIGC 快应用 |
| `h5-test.aigc-quickapp.com` | `H5_TEST_AIGC_QUICKAPP_COM` | 测试快应用 |

当使用 HBuilderX → 发行 → 自定义发行 时，对应的 `#ifdef` 条件编译块会被激活。

### 4. 配置华为参数

编辑 `common/js/config.js` 中的 `huawei` 配置项：

```javascript
huawei: {
    appId: '你的AGC应用ID',
    clientId: '你的客户端ID',
    clientSecret: '你的客户端密钥（建议由后端下发）',
    redirectUri: window.location.origin + '/hwappx/common/',
}
```

**注意**：`clientSecret` 敏感信息建议由后端接口动态下发，避免在前端硬编码。

## 后端配合

### 新增接口

华为帐号登录需要后端增加以下接口：

| 接口路径 | 方法 | 说明 |
|---------|------|------|
| `/wechat/api/quickapp/huawei_auth` | POST | 华为 openId 换 token |

**请求参数**：
| 字段 | 类型 | 说明 |
|------|------|------|
| `openid` | string | 华为帐号 openId |
| `unionid` | string | 华为帐号 unionId（可选） |
| `nickname` | string | 用户昵称 |
| `avatar` | string | 头像 URL |
| `gender` | int | 性别（0:未知 1:男 2:女） |

**返回格式**（需与现有登录接口保持一致）：
```json
{
    "code": 0,
    "data": {
        "openid": "华为openId",
        "unionid": "华为unionId"
    }
}
```

## 已修改的文件清单

| 文件 | 变更类型 | 说明 |
|------|---------|------|
| `common/js/hw-jssdk.js` | **新增** | HwService 统一封装（Account/Analytics/Push） |
| `common/js/auth.js` | 修改 | 新增 `_huaweiSignIn` 方法，快应用环境下使用华为帐号登录 |
| `common/js/http.js` | 修改 | 新增 `H5_XCX_*_QUICKAPP_COM` 条件编译，请求类型为 `quickapp` |
| `common/js/event-bus.js` | 修改 | 新增 `quickapp` 平台检测分支 |
| `common/js/config.js` | 修改 | 新增 `huawei` 配置项 |
| `store/index.js` | 修改 | 新增 `huaweiAccountInfo` 状态/`initHwService` action |

## 发布流程

1. 使用 HBuilderX 打开项目
2. 修改 `manifest.json` → Web 配置 → 基础路径（`/hwappx/common/`）
3. 选择「发行」→「自定义发行」→ 选择对应的快应用脚本
4. 构建完成后，将 `unpackage/dist/build/web/` 目录打包为 zip
5. 使用华为快应用 IDE 导入并发布

## 验证方式

### 检查 HwService 是否可用
```javascript
const HwService = require('@/common/js/hw-jssdk.js').default;
console.log('是否快应用环境:', HwService.isQuickAppEnv());
```

### 验证华为帐号登录
在华为手机上打开快应用，点击登录，应弹出华为帐号授权窗口。

### 验证分析服务
集成后可在 AppGallery Connect 控制台查看埋点数据。

## 注意事项

1. **H5 壳模式限制**：HwService 依赖华为快应用引擎注入的 Bridge，在普通浏览器中不可用
2. **真机测试**：必须在华为手机上测试，模拟器可能无法完整模拟 Bridge
3. **条件编译生效**：必须通过 HBuilderX 的自定义发行脚本构建，`#ifdef` 标记才会生效
4. **clientSecret 安全**：建议由后端接口动态下发，不要前端硬编码
5. **登录降级**：如果华为帐号服务不可用，建议提供短信验证码或其他登录方式作为降级方案