fengketrade/doc/ccblife-implementation-guide.md

# 建行生活 H5 商城对接实施指南

## 项目概述

本文档描述了 Shopro 商城系统与建行生活 App 的完整对接方案实现。所有代码已根据您的实际数据库结构进行调整，确保与现有系统完美兼容。

## 已实现功能清单

### 1. 核心加密模块
- ✅ **RSA 加密解密** (`CcbRSA.php`)：支持 1024 位 RSA，117/128 字节分段处理
- ✅ **MD5 签名** (`CcbMD5.php`)：API 消息签名和支付串签名
- ✅ **URL 参数解密** (`CcbUrlDecrypt.php`)：双层 BASE64 + DES 解密

### 2. 业务服务类
- ✅ **HTTP 客户端** (`CcbHttpClient.php`)：处理与建行 API 的通信
- ✅ **订单服务** (`CcbOrderService.php`)：订单推送、查询、状态更新、退款
- ✅ **支付服务** (`CcbPaymentService.php`)：支付串生成、回调处理、支付验证

### 3. 控制器接口
- ✅ **用户登录** (`Ccblife.php`)：建行用户登录、自动登录、用户绑定
- ✅ **支付处理** (`Ccbpayment.php`)：生成支付串、处理回调、推送订单
- ✅ **测试接口** (`Ccbtest.php`)：全面的功能测试接口

### 4. 前端集成
- ✅ **JSBridge 库** (`ccblife-bridge.js`)：封装建行原生交互功能
- ✅ **示例页面** (`ccblife-demo.html`)：演示如何使用 JSBridge

## 数据库结构（已执行）

### 用户表改造
```sql
ALTER TABLE `fa_user`
ADD COLUMN `ccb_user_id` varchar(50) DEFAULT NULL COMMENT '建行用户ID';
```

### 订单表改造
```sql
ALTER TABLE `fa_shopro_order`
ADD COLUMN `ccb_user_id` varchar(30) DEFAULT NULL COMMENT '建行用户ID',
ADD COLUMN `ccb_pay_flow_id` varchar(50) DEFAULT NULL COMMENT '建行支付流水号',
ADD COLUMN `ccb_sync_status` tinyint(1) DEFAULT '0' COMMENT '建行同步状态',
ADD COLUMN `ccb_sync_time` int(11) DEFAULT NULL COMMENT '建行同步时间';
```

### 支付日志表
```sql
-- fa_ccb_payment_log 表用于记录支付流水
```

### 同步日志表
```sql
-- fa_ccb_sync_log 表用于记录与建行的同步日志
```

## 配置说明

配置文件位置：`/addons/shopro/config/ccblife.php`

关键配置项（从 .env 读取）：
- `CCB_SERVICE_ID`: 服务方编号（生产：YS44000009001853）
- `CCB_MERCHANT_ID`: 商户号
- `CCB_POS_ID`: POS 号
- `CCB_BRANCH_ID`: 分行号
- `CCB_PRIVATE_KEY`: RSA 私钥（BASE64 格式）
- `CCB_PUBLIC_KEY`: RSA 公钥（BASE64 格式）

## 接口调用流程

### 1. 用户登录流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant CCB as 建行App
    participant H5 as H5商城
    participant API as 后端API
    participant DB as 数据库

    U->>CCB: 点击进入商城
    CCB->>H5: 跳转URL(携带ccbParamSJ)
    H5->>API: 调用 /ccblife/login
    API->>API: 解密ccbParamSJ参数
    API->>DB: 查询/创建用户
    DB-->>API: 返回用户信息
    API->>API: 生成Token
    API-->>H5: 返回Token和用户信息
    H5-->>U: 显示商城首页
```

### 2. 支付流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant H5 as H5商城
    participant API as 后端API
    participant CCB as 建行App
    participant CCBAPI as 建行API

    U->>H5: 提交订单
    H5->>API: 创建订单
    API-->>H5: 返回订单信息
    H5->>API: 请求支付串 /ccbpayment/createPayment
    API->>API: 生成支付串和MAC签名
    API-->>H5: 返回支付串
    H5->>CCB: 调用JSBridge发起支付
    CCB->>U: 显示收银台
    U->>CCB: 确认支付
    CCB->>CCBAPI: 处理支付
    CCBAPI-->>CCB: 支付结果
    CCB->>H5: 返回支付结果
    H5->>API: 回调 /ccbpayment/callback
    API->>CCBAPI: 验证支付结果
    API->>API: 更新订单状态
    API->>CCBAPI: 推送订单信息
    API-->>H5: 返回最终结果
```

## 测试步骤

### 1. 环境检查
访问：`http://fengketrade.test/addons/shopro/ccbtest`

检查项：
- 配置检查：`/ccbtest/checkConfig`
- 数据库检查：`/ccbtest/checkDatabase`

### 2. 功能测试

#### 基础功能
- RSA 测试：`/ccbtest/testRsa`
- MD5 测试：`/ccbtest/testMd5`
- URL 解密：`/ccbtest/testUrlDecrypt`

#### 业务功能
- 用户登录：`POST /ccbtest/testUserLogin`
- 订单推送：`/ccbtest/testOrderPush?order_id=1`
- 支付串生成：`/ccbtest/testPaymentString?order_id=1`

### 3. 前端测试
1. 访问示例页面：`http://fengketrade.test/ccblife-demo.html`
2. 测试各项功能：
   - 检测运行环境
   - 获取用户信息
   - 自动登录
   - 模拟支付

## 前端集成示例

### 初始化 JSBridge
```javascript
// 在页面加载时初始化
CcbLifeBridge.init({
    debug: true,
    apiBaseUrl: '/addons/shopro'
});
```

### 获取用户信息
```javascript
CcbLifeBridge.getUserInfo(function(result) {
    if (result.success) {
        console.log('用户信息：', result.data);
        // result.data 包含: ccb_user_id, mobile, nickname, avatar
    }
});
```

### 调起支付
```javascript
// 先调用后端生成支付串
fetch('/addons/shopro/ccbpayment/createPayment', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'token': localStorage.getItem('ccb_token')
    },
    body: JSON.stringify({ order_id: orderId })
})
.then(response => response.json())
.then(data => {
    if (data.code === 1) {
        // 调起建行支付
        CcbLifeBridge.payment({
            payment_string: data.data.payment_string
        }, function(result) {
            if (result.success) {
                // 支付成功，通知后端
                notifyPaymentSuccess(orderId);
            }
        });
    }
});
```

## 注意事项

### 1. 安全要求
- 所有敏感配置必须存储在 `.env` 文件中
- RSA 密钥必须是 BASE64 格式（不含 PEM 头尾）
- 生产环境必须启用 HTTPS

### 2. 数据同步
- 订单状态变更必须同步到建行
- 使用 `fa_ccb_sync_log` 表记录所有同步操作
- 支持批量同步未同步的订单

### 3. 错误处理
- 所有 API 调用都有重试机制（默认 3 次）
- 失败的同步任务会记录到日志表
- 支付失败需要明确提示用户

### 4. 兼容性
- iOS：通过 URL Scheme 调起支付（comccbpay://）
- Android：通过 window.mbspay 对象调用
- H5：在非建行环境降级处理

## 部署检查清单

- [ ] 确认 `.env` 配置正确
- [ ] 数据库表结构已更新
- [ ] RSA 密钥已配置
- [ ] HTTPS 证书已安装
- [ ] 前端 JS 文件已部署
- [ ] 测试接口访问正常
- [ ] 日志目录可写

## 常见问题

### Q: RSA 加密失败
A: 检查密钥格式是否为 BASE64，不要包含 PEM 头尾标记

### Q: 用户登录失败
A: 确认 ccbParamSJ 参数正确，服务方编号与配置一致

### Q: 订单推送失败
A: 检查必需的 34 个字段是否都已填充，特别注意日期格式

### Q: 支付无响应
A: 确认在建行 App 内访问，检查 JSBridge 是否就绪

## 技术支持

如有问题，请检查：
1. 系统日志：`runtime/log/ccblife/`
2. 同步日志：`fa_ccb_sync_log` 表
3. 支付日志：`fa_ccb_payment_log` 表

---

*最后更新：2025-01-17*
*作者：Billy*