fengketrade/doc/ccblife-uniapp-integration.md

# 建行生活 uni-app 前端集成指南

## 概述

本文档介绍了如何在 Shopro uni-app 前端项目中集成建行生活功能，包括用户登录、支付、专属页面等功能。

## 已实现的前端功能

### 1. 平台集成模块

**位置**: `/frontend/sheep/platform/provider/ccblife/`

- `index.js` - 建行生活平台核心模块
  - 环境检测（检测是否在建行App内）
  - JSBridge 初始化和管理
  - 用户信息获取
  - 自动登录
  - 支付调起
  - 原生方法调用

- `api.js` - API 接口封装
  - URL 跳转登录
  - 自动登录
  - 支付串生成
  - 支付回调

### 2. 支付集成

**位置**: `/frontend/sheep/platform/pay.js`

已在现有支付系统中添加了建行支付（ccb）支持：

```javascript
// 支付方式现在支持
payment = ['wechat','alipay','ccb','money','offline']
```

### 3. 平台识别

**位置**: `/frontend/sheep/platform/index.js`

系统会自动识别建行生活环境：
- 平台名称：`CcbLife`
- 提供商：`ccb`
- 平台标识：`ccblife`

### 4. 建行专属页面

**位置**: `/frontend/pages/ccblife/index.vue`

建行生活专属页面，展示：
- 建行用户信息
- 专属优惠活动
- 专享商品
- 建行特色功能

## 使用指南

### 1. 检测建行环境

```javascript
import sheep from '@/sheep';

// 检查是否在建行App内
if (sheep.$platform.provider === 'ccb') {
    console.log('在建行生活App内');
}

// 或直接使用平台对象
import CcbLifePlatform from '@/sheep/platform/provider/ccblife/index';

if (CcbLifePlatform.isInCcbApp) {
    console.log('在建行生活App内');
}
```

### 2. 获取建行用户信息

```javascript
import CcbLifePlatform from '@/sheep/platform/provider/ccblife/index';

// 获取用户信息
CcbLifePlatform.getUserInfo().then(result => {
    if (result.code === 0) {
        console.log('用户信息:', result.data);
        // data包含: ccb_user_id, mobile, nickname, avatar
    }
}).catch(error => {
    console.error('获取用户信息失败:', error);
});
```

### 3. 自动登录流程

平台会自动处理登录流程，无需手动调用：

1. 用户从建行App进入H5页面
2. 系统自动检测建行环境
3. 自动获取用户信息并登录
4. 保存Token到本地存储

手动触发登录：

```javascript
import CcbLifePlatform from '@/sheep/platform/provider/ccblife/index';

// 手动触发自动登录
CcbLifePlatform.autoLogin();
```

### 4. 建行支付集成

#### 在订单支付页面

```javascript
// 支付方式选择
const payMethods = [
    {
        value: 'wechat',
        name: '微信支付',
        icon: 'wechat'
    },
    {
        value: 'alipay',
        name: '支付宝',
        icon: 'alipay'
    },
    {
        value: 'ccb',
        name: '建行支付',
        icon: 'ccb',
        // 只在建行App内显示
        show: sheep.$platform.provider === 'ccb'
    }
];
```

#### 发起支付

```javascript
import sheep from '@/sheep';

// 调起支付
sheep.$platform.pay('ccb', 'goods', orderSN);
```

### 5. 监听事件

```javascript
// 监听登录成功事件
uni.$on('ccb:login:success', (data) => {
    console.log('建行用户登录成功', data);
    // 更新UI或执行其他操作
});

// 在页面销毁时移除监听
onUnmounted(() => {
    uni.$off('ccb:login:success');
});
```

### 6. 条件编译

在需要区分平台的代码中使用条件编译：

```javascript
// #ifdef H5
import CcbLifePlatform from '@/sheep/platform/provider/ccblife/index';

if (CcbLifePlatform.isInCcbApp) {
    // 建行App内的特殊处理
}
// #endif
```

## 页面路由配置

在 `pages.json` 中添加建行相关页面：

```json
{
    "pages": [
        {
            "path": "pages/ccblife/index",
            "style": {
                "navigationBarTitleText": "建行生活",
                "navigationBarBackgroundColor": "#F51C13",
                "navigationBarTextStyle": "white"
            }
        }
    ]
}
```

## 测试流程

### 1. 本地测试

```bash
# 进入前端目录
cd frontend

# 安装依赖
npm install

# 运行H5
npm run dev:h5
```

### 2. 模拟建行环境

在浏览器中添加URL参数模拟建行环境：
```
http://localhost:3000/#/pages/index/index?from=ccblife&ccbParamSJ=xxx
```

### 3. 真机测试

1. 使用 HBuilderX 打包H5应用
2. 部署到测试服务器
3. 在建行生活App内访问测试地址

## 注意事项

### 1. 平台判断优先级

系统按以下优先级判断平台：
1. 建行生活 (`CcbLife`)
2. 微信公众号 (`WechatOfficialAccount`)
3. 普通H5 (`H5`)

### 2. JSBridge 兼容性

- iOS：使用 WebViewJavascriptBridge
- Android：使用 window.mbspay 对象

### 3. 支付流程

1. 用户选择建行支付
2. 调用后端生成支付串
3. 通过JSBridge调起建行收银台
4. 支付完成后回调通知后端
5. 更新订单状态

### 4. 错误处理

```javascript
try {
    const result = await CcbLifePlatform.payment(options);
    // 处理成功
} catch (error) {
    if (error.code === -1) {
        // 不在建行App内
        uni.showToast({
            title: '请在建行生活App内使用',
            icon: 'none'
        });
    } else {
        // 其他错误
        console.error(error);
    }
}
```

## 常见问题

### Q: 如何判断是否在建行App内？

```javascript
import sheep from '@/sheep';

// 方式1：通过平台对象
if (sheep.$platform.provider === 'ccb') {
    // 在建行App内
}

// 方式2：直接使用建行平台模块
import CcbLifePlatform from '@/sheep/platform/provider/ccblife/index';
if (CcbLifePlatform.isInCcbApp) {
    // 在建行App内
}
```

### Q: 自动登录失败怎么办？

1. 检查是否在建行App内
2. 确认后端接口正常
3. 查看控制台错误信息
4. 清除本地缓存重试

```javascript
// 清除缓存
uni.removeStorageSync('token');
uni.removeStorageSync('userInfo');

// 重新触发登录
CcbLifePlatform.autoLogin();
```

### Q: 支付无响应？

1. 确认在建行App内
2. 检查JSBridge是否就绪
3. 验证支付串格式
4. 查看原生日志

```javascript
// 检查JSBridge状态
CcbLifePlatform.ready(() => {
    console.log('JSBridge已就绪');
});
```

### Q: 如何调试？

在建行平台模块中开启调试模式：

```javascript
// frontend/sheep/platform/provider/ccblife/index.js
const config = {
    debug: true  // 开启调试
};
```

## 扩展开发

### 添加新的原生方法调用

```javascript
// 在 CcbLifePlatform 中添加新方法
async customMethod() {
    return new Promise((resolve, reject) => {
        this.callNative('customMethod', {
            // 参数
        }, (result) => {
            if (result.success) {
                resolve(result);
            } else {
                reject(result);
            }
        });
    });
}
```

### 添加新的API接口

```javascript
// 在 api.js 中添加
newApi: (data) => {
    return request({
        url: '/ccblife/newApi',
        method: 'POST',
        data: data
    });
}
```

---

*文档版本：1.0.0*
*最后更新：2025-01-17*
*作者：Billy*