fengketrade/doc/建行App服务方接入文档分析.md

# 建行相关App服务方接入文档分析

## 一、文档概述

这份文档（v2.20_20250725）是建行生活App和中国建设银行App的服务方接入指南，涵盖了：
- 环境识别方法
- 收银台调用方式
- 支付参数规范
- 接口地址和协议

## 二、关键接口地址（确认）

### 2.1 后台接口地址

| 环境 | 地址 | 用途 |
|------|------|------|
| **测试环境** | `http://124.127.94.60:18088/uat_new/tp_service/txCtrl/server?txcode=xxx` | 后台交易接口 |
| **生产环境** | `https://yunbusiness.ccb.com/tp_service/txCtrl/server?txcode=xxx` | 后台交易接口 |

### 2.2 前端收银台地址

| 环境 | 地址 | 用途 |
|------|------|------|
| **测试环境** | `http://124.127.94.60:18088/uat_new/clp_service/txCtrl` | 收银台处理URL |
| **生产环境** | `https://yunbusiness.ccb.com/clp_service/txCtrl` | 收银台处理URL |

**调用格式**：
```
url?txcode=A3341OM01&svcid=服务方编号&cnt=加密内容&mac=签名
```

## 三、H5商城在建行App中的运行机制

### 3.1 环境识别

#### 建行生活App识别：
```javascript
// 方法1：检查URL参数
if (location.search.includes('platform=ccblife')) {
    console.log('在建行生活App中');
}

// 方法2：检查UA（更准确）
window.CCBBridge.requestNative(JSON.stringify({
    action: "getUA",
    params: {}
}), "getUACallBack");
```

#### 中国建设银行App识别：
```javascript
// 检查URL参数中是否有platform=ccb
if (location.search.includes('platform=ccb')) {
    console.log('在中国建设银行App中');
}
```

### 3.2 跳转URL格式

建行App跳转到H5商城时，URL格式为：
```
https://your-h5-mall.com?platform=ccblife&channel=mbs&ccbParamSJ=xxx&CITYID=330100&USERCITYID=440100
```

**参数说明**：
- `platform`：平台标识（ccblife或ccb）
- `ccbParamSJ`：加密参数串（包含用户信息）
- `CITYID`：用户所在城市
- `USERCITYID`：用户选择城市

## 四、支付接入详解

### 4.1 调起收银台方法

#### 在建行生活App中（iOS）：
```javascript
function MBS_DIRECT_PAY(payInfo) {
    // payInfo为支付参数串
    window.location = "mbspay://direct?" + payInfo;
}
```

#### 在建行生活App中（Android）：
```javascript
function MBS_DIRECT_PAY(payInfo) {
    window.mbspay.directpay(payInfo);
}
```

#### 在中国建设银行App中：
需要先进行RSA加密，然后跳转到收银台URL：
```javascript
// 1. 组装支付参数
// 2. RSA加密
// 3. 跳转到收银台URL
window.location = 'https://yunbusiness.ccb.com/clp_service/txCtrl?txcode=A3341OM01&svcid=' + serviceId + '&cnt=' + encryptedData + '&mac=' + signature;
```

### 4.2 支付参数详解

#### 必需参数：
| 字段 | 说明 | 示例 |
|------|------|------|
| MERCHANTID | 商户代码 | 由建行分配 |
| POSID | 柜台代码 | 由建行分配 |
| BRANCHID | 分行代码 | 由建行分配 |
| ORDERID | 订单号 | 商户订单号 |
| PAYMENT | 支付金额 | 单位：元 |
| CURCODE | 币种 | 01-人民币 |
| REMARK2 | 备注2 | **填写服务方编号（YS开头）** |
| MAC | MD5签名 | 见签名规则 |
| ENCPUB | 商户公钥密文 | RSA加密后的公钥 |

#### 重要字段说明：
- **REMARK2必须填写服务方编号**（如：YS44000098000600）
- **NOTIFY_URL**：支付通知回调地址（生产环境必须HTTPS）
- **PAYSUCCESSURL**：支付成功页面（可选）

### 4.3 支付成功回调设置

在调起收银台前，设置回调地址：
```javascript
var requestObj = {
    action: 'setCache',
    params: {
        key: 'YS44000098000600',  // 服务方编号，与REMARK2一致
        value: 'https://your-domain.com/payment/success'  // 回调URL
    }
};
window.CCBBridge.requestNative(JSON.stringify(requestObj), 'callBackName');
```

### 4.4 签名生成规则

MD5签名生成步骤：
1. 按参数名ASCII排序拼接成字符串
2. 在字符串末尾加上服务方公钥
3. 使用MD5算法生成签名

```php
// PHP示例
$params = [
    'MERCHANTID' => '105910100194086',
    'POSID' => '313368474',
    'ORDERID' => 'ORD123456',
    // ... 其他参数
];

// 1. 排序并拼接
ksort($params);
$signStr = http_build_query($params);

// 2. 加上服务方公钥
$signStr .= '&PLATFORMPUB=' . $platformPublicKey;

// 3. 生成MD5
$mac = md5($signStr . $privateKey);
```

## 五、完整对接流程

### 5.1 业务流程

```mermaid
sequenceDiagram
    participant User as 用户
    participant H5 as H5商城
    participant Backend as 服务方后台
    participant CCBApp as 建行App
    participant CCBServer as 建行服务器

    User->>CCBApp: 打开建行App
    CCBApp->>H5: 跳转H5商城(带参数)
    H5->>H5: 识别运行环境
    User->>H5: 选购商品
    H5->>Backend: 创建订单
    Backend->>CCBServer: 推送订单(A3341TP01)
    Backend-->>H5: 返回支付参数
    H5->>CCBApp: 调起收银台
    User->>CCBApp: 确认支付
    CCBApp->>CCBServer: 支付请求
    CCBServer-->>Backend: 支付通知
    CCBServer-->>CCBApp: 支付结果
    CCBApp-->>H5: 跳转回调页
```

### 5.2 接入步骤

1. **环境准备**
   - 申请服务方编号（YS开头）
   - 生成RSA密钥对
   - 获取建行平台公钥

2. **H5页面适配**
   - 识别运行环境
   - 实现收银台调用方法
   - 设置支付回调

3. **后端接口开发**
   - 实现订单推送接口
   - 实现支付参数生成
   - 处理支付通知

4. **测试验证**
   - 在UAT环境测试
   - 验证支付流程
   - 确认回调正确

## 六、UniApp实现方案

### 6.1 环境识别封装
```javascript
// utils/ccb-env.js
export default {
    // 检查是否在建行环境
    isInCCBApp() {
        // #ifdef H5
        const search = location.search.toLowerCase();
        return search.includes('platform=ccblife') ||
               search.includes('platform=ccb');
        // #endif

        // #ifndef H5
        return false;
        // #endif
    },

    // 获取平台类型
    getPlatform() {
        // #ifdef H5
        if (location.search.includes('platform=ccblife')) {
            return 'ccblife';  // 建行生活
        }
        if (location.search.includes('platform=ccb')) {
            return 'ccb';  // 中国建设银行
        }
        // #endif
        return null;
    },

    // 获取加密参数
    getCCBParams() {
        // #ifdef H5
        const params = new URLSearchParams(location.search);
        return {
            ccbParamSJ: params.get('ccbParamSJ'),
            cityId: params.get('CITYID'),
            userCityId: params.get('USERCITYID')
        };
        // #endif
        return {};
    }
};
```

### 6.2 收银台调用封装
```javascript
// utils/ccb-payment.js
export default {
    // 调起建行收银台
    pay(paymentString) {
        // #ifdef H5
        const platform = this.getPlatform();

        if (platform === 'ccblife') {
            // 建行生活App
            if (this.isIOS()) {
                window.location = "mbspay://direct?" + paymentString;
            } else {
                // Android
                if (window.mbspay && window.mbspay.directpay) {
                    window.mbspay.directpay(paymentString);
                } else {
                    console.error('mbspay对象不存在');
                }
            }
        } else if (platform === 'ccb') {
            // 中国建设银行App - 需要跳转到收银台URL
            // 这里需要后端返回加密后的URL
            window.location = paymentString;  // 这里应该是完整的收银台URL
        }
        // #endif
    },

    // 设置支付回调
    setPayCallback(serviceId, callbackUrl) {
        // #ifdef H5
        if (window.CCBBridge && window.CCBBridge.requestNative) {
            const requestObj = {
                action: 'setCache',
                params: {
                    key: serviceId,
                    value: callbackUrl
                }
            };

            window.CCBBridge.requestNative(
                JSON.stringify(requestObj),
                'setPayCallbackResult'
            );
        }
        // #endif
    },

    // 判断是否iOS
    isIOS() {
        return /iPhone|iPad|iPod/i.test(navigator.userAgent);
    },

    getPlatform() {
        if (location.search.includes('platform=ccblife')) {
            return 'ccblife';
        }
        if (location.search.includes('platform=ccb')) {
            return 'ccb';
        }
        return null;
    }
};
```

## 七、重要注意事项

### 7.1 关键配置
- **REMARK2必须填写服务方编号**
- **生产环境必须使用HTTPS**
- **支付通知接口需要验签**

### 7.2 常见问题

**Q: 如何区分建行生活和中国建设银行App？**
A: 通过URL参数platform判断，ccblife是建行生活，ccb是中国建设银行。

**Q: 支付参数需要加密吗？**
A: 在建行生活App中直接传递，在中国建设银行App中需要RSA加密。

**Q: 支付成功后如何跳转？**
A: 通过setCache方法设置回调URL，或使用PAYSUCCESSURL参数。

### 7.3 测试要点
1. 环境识别是否准确
2. 收银台能否正常调起
3. 支付回调是否正常
4. 订单状态同步是否及时

## 八、总结

这份文档确认了：
1. ✅ **接口地址明确**：包括后台接口和收银台URL
2. ✅ **支付流程清晰**：不同App环境有不同调用方式
3. ✅ **参数规范完整**：包括签名、加密等要求
4. ✅ **PHP/UniApp可以实现**：通过HTTP接口和JavaScript调用

关键点：
- 服务方编号（REMARK2）是核心参数
- 建行生活和中国建设银行App调用方式不同
- 所有接口都是标准HTTP/HTTPS，PHP完全可以对接