ssh/smct-sdk-php

智慧食堂第三方API & 人脸采集API PHP SDK

Maintainers

Package info

github.com/yn-ssh/smct-sdk-php

pkg:composer/ssh/smct-sdk-php

Transparency log

Statistics

Installs: 0

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

v1.0.0 2026-07-27 01:41 UTC

Requires

MIT 7e3a2c29212f99cab2a43ab07a2fefe37be5e775

Published on Packagist.org on 2026-07-27 01:51 UTC

This package is auto-updated.

Last update: 2026-07-27 01:51:42 UTC

README

智慧食堂第三方 API & 人脸采集 API PHP SDK 组件包。

功能概览

模块 客户端类 说明
智慧食堂 API SmctClient 支付、订单、菜品、客餐券、统计等 26 个接口
人脸采集 API FaceClient H5 人脸绑定 + 后台同步管理 5 个接口

环境要求

  • PHP >= 7.4
  • ext-json, ext-curl, ext-mbstring, ext-gmp

安装

composer require smct/sdk-php

或不使用 Composer，手动引入：

require 'path/to/smct-sdk-php/autoload.php';

快速开始

智慧食堂 API

use Smct\Config;
use Smct\SmctClient;

$config = new Config([
    'appId'          => 'SYSTEM002',
    'channelCode'    => 'F1001',
    'appChannelCode' => 'JKWB',
    'baseUrl'        => 'https://smct-test.fintechabchina.com', // 测试环境
    'deviceNum'      => 'YOUR_DEVICE_NUM',
    'sm2PublicKey'   => 'YOUR_SM2_PUBLIC_KEY_HEX',
]);

$smct = new SmctClient($config);

// 获取食堂基础信息
$result = $smct->getCanteenId();

// 刷脸支付
$result = $smct->flexiblePay(
    amtTrans: '10.50',
    idCanteen: 'CANTEEN_ID',
    transId: 'UNIQUE_TRANS_ID',
    payType: 'FPAY',
    personId: 'USER_ID'
);

// 获取饭卡余额
$result = $smct->getCardBalance('FTYPE', 'CANTEEN_ID', personId: 'USER_ID');

// 交易退款
$result = $smct->refund('ORDER_NO', 'CANTEEN_ID');

人脸采集 API

use Smct\Config;
use Smct\FaceClient;

$config = new Config([
    'faceBaseUrl' => 'https://face-api.example.com',
    'faceAppId'   => 'SYSTEM002',
    'faceAesKey'  => 'YOUR_AES_KEY',
]);

$face = new FaceClient($config);

// 查询绑定状态
$result = $face->queryBindStatus('userId', 'companyId', '张三');

// 提交人脸绑定
$result = $face->submitFaceBind('userId', 'companyId', '张三', $base64Image);

// 后台查询采集情况（AES 加密）
$result = $face->queryFaceBindInfo('2025-01-01 00:00:00', '2025-12-31 23:59:59', 'companyId');

更多用法见 examples/ 目录。

配置说明

Config 参数

参数 说明 默认值
appId 应用标识 SYSTEM002
channelCode 渠道代码 F1001
appChannelCode 应用部署渠道代码 JKWB
baseUrl 基础 URL 测试环境地址
deviceNum 设备号 -
timeout 请求超时(秒) 30
sm2PrivateKey SM2 私钥(Hex/Base64,可选) -
sm2PublicKey SM2 公钥(Hex) -
faceBaseUrl 人脸采集 API 地址 -
faceAppId 人脸采集 appId SYSTEM002
faceAesKey 人脸采集 AES 密钥 -

环境地址

环境 baseUrl
测试 https://smct-test.fintechabchina.com
生产 https://smct.fintechabchina.com

API 接口清单

SmctClient - 智慧食堂 API

基础功能

方法 接口
getCanteenId() 获取食堂基础信息
getUserCard($groupId) 获取公司下所有实体卡号
getCardBalance($type, $canteenId, ...) 获取饭卡余额

支付

方法 接口
flexiblePay(...) 设备端灵活支付
syncOfflineOrders($orders, ...) 离线模式订单同步
getMealTime($canteenId) 获取固定餐餐段信息
fixedMealPay($deals) 固定餐消费支付
refund($orderNo, $canteenId, ...) 交易退款（冲正）

线上订单

方法 接口
getOrderInfo($qrCode, $canteenId) 取餐码获取订单详情
scanCodeVerify($qrCode, $canteenId, $transId) 取餐码核销
pullOrders($canteenId, ...) 拉取订单数据
getEquipOrders(...) 设备订单分页查询
getScanOrders($canteenId, $type, ...) 获取待核销餐
handleOrder($canteenId, $operType, $orderIds) 订单处理
getDishInfos($canteenId, ...) 餐段菜品信息查询
orderPay($params) 设备选菜下单支付
getUserOrders($params) 用户订单查询
getEquipDishInfo(...) 设备可取菜品查询

客餐券

方法 接口
checkCoupon($qrCode, $canteenId) 获取客餐券信息
useCoupon($qrCode, $canteenId, $transId) 核销客餐券

统计

方法 接口
getCanteenPaymentStatistics($canteenId) 食堂每日收款汇总
getDishOrderStatistics(...) 菜品订单统计
getIntervalOrderStatistics(...) 餐段订单统计
getGradeDishOrderStatistics(...) 年级班级菜品统计
getFoodWasteStatistics(...) 厨余垃圾统计
getCanteenDevPaymentStatistics($canteenId) 设备今日消费汇总

FaceClient - 人脸采集 API

H5 页面接口

方法 接口
queryBindStatus($userId, $companyId, $username) 查询绑定状态
submitFaceBind($userId, $companyId, $username, $base64) 提交人脸绑定
deleteFaceBind($userId, $companyId) 删除人脸绑定

后台同步接口（AES 加密）

方法 接口
queryFaceBindInfo($start, $end, ...) 查询人脸采集情况
batchDeleteFaceBindInfo($companyId, $userIds) 批量删除人脸绑定

加密算法

智慧食堂 API（SM2 + SM3 + SM4）

请求加密流程：

  1. 生成随机 16 字节 → SM4-CBC(OpenSSL) 加密业务数据
  2. SM2 公钥加密随机密钥和盐值 → extension (C1C3C2, 加“04”前缀)
  3. 在原始业务数据上计算 SM3 签名 → SM4 加密签名 → nonceString
  4. 传输时 data 字段为密文

响应处理：SM4 解密（使用客户端请求时的随机密钥）→ SM3 验签

人脸采集 API（AES）

  • 算法：AES-128-ECB + PKCS5Padding
  • 密钥派生：SHA1(password) 取前 16 字节
  • 编码：双重 Base64

项目结构

smct-sdk-php/
├── README.md                     # 项目文档
├── composer.json                 # Composer 配置
├── .env.example                  # 环境变量模板
├── .gitignore
├── autoload.php                  # 非 Composer 自动加载
├── bin/
│   └── test                      # 测试执行脚本
├── src/
│   ├── Config.php                # 配置类
│   ├── SmctClient.php            # 智慧食堂 API 客户端
│   ├── FaceClient.php            # 人脸采集 API 客户端
│   ├── Encrypt/
│   │   └── Encryptor.php         # SM2/SM3/SM4 加签加解密
│   ├── Http/
│   │   └── HttpClient.php        # HTTP 请求封装
│   └── Exceptions/
│       └── SmctException.php     # 异常类
├── tests/
│   ├── EnvLoader.php             # .env 加载器
│   ├── EncryptorTest.php         # 加密算法单元测试
│   ├── SmctClientTest.php        # 智慧食堂 API 测试
│   └── FaceClientTest.php        # 人脸采集 API 测试
└── examples/
    ├── smct_example.php           # 智慧食堂 API 示例
    └── face_example.php          # 人脸采集 API 示例

测试

1. 配置环境变量

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 填入实际密钥
vim .env

2. 执行测试

# 运行全部测试
./bin/test

# 仅运行加密算法单元测试（无需 .env）
./bin/test unit

# 加密算法按分类过滤
./bin/test unit sm2      # SM2 非对称加密
./bin/test unit sm3      # SM3 哈希
./bin/test unit sm4      # SM4 对称加密
./bin/test unit aes      # AES 加解密
./bin/test unit e2e      # 端到端流程
./bin/test unit tool     # 工具方法

# 仅运行智慧食堂 API 测试（需要 .env）
./bin/test smct                    # 全部
./bin/test smct getCanteenId       # 指定接口

# 仅运行人脸采集 API 测试（需要 .env）
./bin/test face                    # 全部
./bin/test face queryBindStatus    # 指定接口

# 使用 Composer 命令
composer test          # 加密算法测试
composer test:smct     # 智慧食堂 API 测试
composer test:face     # 人脸采集 API 测试
composer test:all      # 全部测试

许可证

MIT