收货地址

address

//用户地址
address: {
    //获取地址列表
    index: domain + '/address/api-user/index',
    //获取城市列表
    city: domain + '/address/api/index',
    //获取地址详情
    view: domain + '/address/api-user/view',
    //获取默认地址
    default: domain + '/address/api-user/default',
    //创建地址
    create: domain + '/address/api-user/create',
    //更新地址
    update: domain + '/address/api-user/update',
    //删除地址
    del: domain + '/address/api-user/del',
},

字段

字段	事例值	描述
city	北京市	城市
detail	具体的地址	详细地址
district	西城区	区县
id	1	地址id
is_default	1	是否默认
name	大先生	收货人姓名
phone	19900000000	收货人手机号
province	北京市	省份
region	["北京市", "北京市", "东城区"]	区域

index 列表返回有 full_address 完整的收货地址

发送邮件

调用事例

//发送邮箱验证码
$code = rand(100000, 999999); 
add_mail_template('bind_account', "绑定邮箱", '绑定邮箱验证', '您正在绑定邮箱，您的验证码是<b>{code}</b>,5分钟有效，如非本人请求请忽略。');
cache("bind_account_{$email}", $code, 300);

send_mail('bind_account', $email, [
    'code' =>  $code,
]);

模板发送邮件

send_mail($template_code, $address, $replace = [])

添加模板

add_mail_template($name,$code,$title,$content)

测试模板

/email/site/code?email=你的邮件地址

原始发送邮件，一般建议使用上面的模板形式发送

use modules\email\lib\Mail;

Mail::send('to@example.com', 'subject', 'body');

多语言

language

小牛翻译

use modules\language\lib\Niutrans;
Niutrans::translate('你好');

小程序接口

minapp

//登录
login: {
    //微信小程序openid
    openid: domain + '/minapp/api-login/openid',
    //微信小程序手机号授权登录
    weixin: domain + '/minapp/api-login/phone',
},

取用户信息

/minapp/api-user/info

返回值

设置用户信息

/minapp/api-user/set-info

参数：

field: 字段
value: 值

订单模块文档

概述

订单模块提供了完整的订单管理功能，包括订单创建、支付信息管理、退款处理等功能。所有功能都遵循框架的数据库操作规范，使用正确的 Model 查询方法。

功能特性

订单创建和管理
订单支付信息处理
订单退款申请和审核
完整的数据验证和事务处理
支持批量操作
多语言支持
退款金额智能验证

数据库表结构

订单主表 (order)

存储订单基本信息
包含订单状态、金额、地址等信息
重要字段：
- can_refund_amount: 可退款金额
- has_refund_amount: 已退款金额
- real_get_amount: 实际获得金额

订单明细表 (order_item)

存储订单商品详情
关联订单主表

订单支付信息表 (order_paid_info)

存储订单支付相关信息
如优惠券、折扣等

订单退款表 (order_refund)

存储退款申请信息
包含退款原因、状态等

订单退款明细表 (order_refund_detail)

存储退款商品详情
关联退款表和订单明细表

使用示例

创建订单

php

// 基本使用
$orderCreator = new \modules\order\lib\OrderCreator();

// 创建订单
$orderData = [
    'user_id' => 1,
    'type' => 'product',
    'amount' => 100.00,
    'real_amount' => 95.00,
    'address' => lang('北京市朝阳区xxx'),
    'phone' => '13800138000',
    'name' => lang('张三'),
    'items' => [
        [
            'product_id' => 'P001',
            'title' => lang('商品名称'),
            'price' => 50.00,
            'num' => 2
        ]
    ]
];

$result = $orderCreator->create($orderData);

// 快速创建订单
$result = $orderCreator->quickCreate(1, [
    [
        'product_id' => 'P001',
        'title' => lang('商品名称'),
        'price' => 50.00,
        'num' => 2
    ]
], [
    'address' => lang('收货地址'),
    'phone' => lang('联系电话')
]);

订单支付信息管理

php

// 添加支付信息
$payment = new \modules\order\lib\OrderPayment();
$result = $payment->addPaymentInfo([
    'order_id' => 1,
    'title' => lang('优惠券抵扣'),
    'type' => 'coupon',
    'amount' => 10.00
]);

// 批量添加支付信息
$result = $payment->batchAddPaymentInfo(1, [
    [
        'title' => lang('优惠券抵扣'),
        'type' => 'coupon',
        'amount' => 10.00
    ],
    [
        'title' => lang('积分抵扣'),
        'type' => 'points',
        'amount' => 5.00
    ]
]);

// 获取订单支付信息 - 使用正确的查询方法
$result = $payment->getOrderPaymentInfo(1);
// 内部使用: $this->orderPaidInfoModel->find(['order_id' => $orderId])

订单退款处理

php

// 创建退款申请 - 包含完整的金额验证
$refund = new \modules\order\lib\OrderRefund();
$result = $refund->createRefund([
    'user_id' => 1,
    'order_id' => 1,
    'amount' => 50.00,  // 会自动验证是否超过可退款金额
    'reason' => lang('商品质量问题'),
    'desc' => lang('商品有瑕疵'),
    'images' => ['image1.jpg', 'image2.jpg'],
    'items' => [
        ['order_item_id' => 1, 'num' => 1]
    ]
]);

// 审核退款申请
$result = $refund->approveRefund(1, 'approved', lang('审核通过'));

// 获取退款列表 - 使用正确的分页方法
$result = $refund->getRefundList([
    'user_id' => 1,
    'status' => 'wait'
], 1, 20);
// 内部使用: $this->orderRefundModel->pager($queryWhere, $page, $limit)

// 获取退款详情 - 使用正确的关联查询
$result = $refund->getRefundDetail(1);
// 内部使用: $this->orderRefundModel->relation(['order', 'refund_details'])->find($refundId)

数据库操作规范

本模块严格遵循框架的数据库操作规范：

查询方法

php

// 正确的查询方法
$model->find($id);                    // 查询单条记录
$model->find(['field' => 'value']);   // 按条件查询
$model->pager($where, $page, $limit); // 分页查询

更新和删除

php

// 正确的更新方法
$model->update($data, $where);

// 正确的删除方法
$model->del($where);

关联查询

php

// 正确的关联查询
$model->relation(['relation1', 'relation2'])->find($id);

退款金额验证逻辑

退款时会进行完整的金额验证：

php

// 检查可退款金额
$canRefundAmount = $order['can_refund_amount'] ?? ($order['real_get_amount'] - $order['has_refund_amount']);
if ($refundData['amount'] > $canRefundAmount) {
    throw new \Exception(lang('退款金额不能超过可退款金额'));
}

API 响应格式

所有API都遵循统一的响应格式：

json

{
    "code": 0,  // 0表示成功，其他值表示失败
    "msg": "操作成功",
    "data": {}  // 返回的数据
}

多语言支持

所有用户可见的消息都支持多语言：

php

// 使用 lang() 函数进行翻译
throw new \Exception(lang('订单不存在'));
return ['msg' => lang('操作成功')];

模型验证规则

所有模型都包含完整的数据验证规则，确保数据的完整性和正确性。验证失败时会自动返回错误信息。

事务处理

涉及多表操作的功能都使用了数据库事务，确保数据的一致性：

php

db_action(function() use ($data) {
    // 事务内的操作
});

错误处理

所有功能都包含完整的错误处理机制，确保系统的稳定性。# 支付

微信支付

payment_success action说明

$data = [
    'order_num' => $out_trade_no,
    'transaction_id' => $res['transaction_id'],
    'payment_method' => 'weixin',
    'currency' => $res['amount']['currency'],
    'amount' => bcdiv($res['amount']['total'], 100, 2),
    'openid' => $res['payer']['openid'],
    'paid_at' => $success_time,
    'app_id' => $res['appid'],
]; 
add_log('微信支付查寻', $data, 'debug');
do_action('payment_success', $data);

商品同步服务文档

概述

ProductSyncService 是一个用于同步商品信息、分类信息和规格信息到数据库的服务类。它提供了完整的商品数据同步解决方案，支持单个和批量操作。

功能特性

✅ 商品分类同步（支持层级分类）
✅ 商品信息同步（单规格/多规格）
✅ 商品规格同步
✅ 批量同步操作
✅ 智能去重（基于SKU/商品编号）
✅ 数据验证
✅ 错误处理
✅ 查询功能

类文件位置

modules/product/lib/ProductSyncService.php

基本用法

1. 引入和初始化

php

use modules\product\lib\ProductSyncService;

// 创建同步服务实例
$syncService = new ProductSyncService();

2. 同步商品分类

单个分类同步

php

// 分类数据
$typeData = [
    'title' => '电子产品',
    'slug' => 'electronics',
    'description' => '各种电子产品分类',
    'image' => '/uploads/category/electronics.jpg',
    'pid' => 0, // 顶级分类
    'sort' => 10
];

// 同步分类
$typeId = $syncService->syncProductType($typeData);
echo "分类同步成功，ID: {$typeId}";

批量分类同步

php

$types = [
    [
        'title' => '手机',
        'slug' => 'mobile-phone',
        'description' => '智能手机分类',
        'pid' => $typeId, // 作为电子产品的子分类
        'sort' => 1
    ],
    [
        'title' => '电脑',
        'slug' => 'computer',
        'description' => '电脑设备分类',
        'pid' => $typeId,
        'sort' => 2
    ]
];

$typeResults = $syncService->batchSyncTypes($types);
echo "批量分类同步结果: 成功 {$typeResults['success_count']} 个，失败 {$typeResults['error_count']} 个";

3. 同步单规格商品

php

$productData = [
    'title' => 'iPhone 15 Pro',
    'desc' => '苹果最新款智能手机',
    'body' => '<p>详细的商品描述内容</p>',
    'image' => '/uploads/product/iphone15pro.jpg',
    'images' => ['/uploads/product/iphone15pro_1.jpg', '/uploads/product/iphone15pro_2.jpg'],
    'product_num' => 'IP15PRO001',
    'sku' => 'APPLE-IP15PRO-256GB',
    'type_id' => [$typeId], // 分类ID数组
    'price' => 8999.00,
    'market_price' => 9999.00,
    'stock' => 100,
    'spec_type' => 1 // 单规格
];

$productId = $syncService->syncProduct($productData);
echo "单规格商品同步成功，ID: {$productId}";

4. 同步多规格商品

php

// 商品基本信息
$productData = [
    'title' => 'MacBook Pro',
    'desc' => '苹果专业级笔记本电脑',
    'body' => '<p>MacBook Pro详细介绍</p>',
    'image' => '/uploads/product/macbook_pro.jpg',
    'images' => ['/uploads/product/macbook_pro_1.jpg'],
    'product_num' => 'MBP2024001',
    'type_id' => [$typeId], // 分类ID
    'spec_type' => 2 // 多规格
];

// 规格数据
$specs = [
    [
        'title' => '14英寸 M3 512GB',
        'sku' => 'MBP-14-M3-512GB',
        'price' => 15999.00,
        'market_price' => 16999.00,
        'stock' => 50,
        'image' => '/uploads/product/macbook_14.jpg'
    ],
    [
        'title' => '16英寸 M3 Pro 1TB',
        'sku' => 'MBP-16-M3PRO-1TB',
        'price' => 19999.00,
        'market_price' => 21999.00,
        'stock' => 30,
        'image' => '/uploads/product/macbook_16.jpg'
    ]
];

$productId = $syncService->syncProduct($productData, $specs);
echo "多规格商品同步成功，ID: {$productId}";

5. 批量同步商品

php

$products = [
    [
        'product' => [
            'title' => 'iPad Air',
            'desc' => '轻薄平板电脑',
            'product_num' => 'IPAD-AIR-001',
            'sku' => 'APPLE-IPAD-AIR-64GB',
            'price' => 4399.00,
            'stock' => 80,
            'type_id' => [$typeId]
        ]
    ],
    [
        'product' => [
            'title' => 'AirPods Pro',
            'desc' => '无线降噪耳机',
            'product_num' => 'AIRPODS-PRO-001',
            'price' => 1999.00,
            'stock' => 200,
            'type_id' => [$typeId]
        ],
        'specs' => [
            [
                'title' => '标准版',
                'sku' => 'AIRPODS-PRO-STANDARD',
                'price' => 1999.00,
                'stock' => 200
            ]
        ]
    ]
];

$batchResults = $syncService->batchSyncProducts($products);
echo "批量商品同步结果: 成功 {$batchResults['success_count']} 个，失败 {$batchResults['error_count']} 个";

// 显示详细结果
foreach ($batchResults['results'] as $result) {
    if ($result['success']) {
        echo "商品 {$result['index']} 同步成功，ID: {$result['product_id']}";
    } else {
        echo "商品 {$result['index']} 同步失败: {$result['message']}";
    }
}

6. 查询功能

php

// 根据商品编号查询
$product = $syncService->getProductByNum('IP15PRO001');
if ($product) {
    echo "根据商品编号查询到商品: {$product['title']}";
}

// 根据SKU查询
$product = $syncService->getProductBySku('APPLE-IP15PRO-256GB');
if ($product) {
    echo "根据SKU查询到商品: {$product['title']}";
}

// 根据分类别名查询
$type = $syncService->getTypeBySlug('electronics');
if ($type) {
    echo "根据别名查询到分类: {$type['title']}";
}

API 方法说明

分类相关方法

`syncProductType($typeData)`

同步商品分类信息

参数：

$typeData (array): 分类数据数组

必填字段：

title: 分类名称
slug: 分类别名

可选字段：

description: 分类描述
image: 分类图片
pid: 父分类ID（默认0）
sort: 排序（默认0）
status: 状态（默认'success'）

返回值： 分类ID

`batchSyncTypes($types)`

批量同步分类

参数：

$types (array): 分类数据数组

返回值： 同步结果数组

商品相关方法

`syncProduct($productData, $specs = [])`

同步商品信息

参数：

$productData (array): 商品数据
$specs (array): 规格数据（可选）

必填字段：

title: 商品名称

重要字段：

product_num: 商品编号（用于去重）
sku: 商品SKU（用于去重）
type_id: 分类ID数组
spec_type: 规格类型（1单规格，2多规格）
price: 商品价格
stock: 库存

返回值： 商品ID

`batchSyncProducts($products)`

批量同步商品

参数：

$products (array): 商品数据数组，每个元素包含 product 和可选的 specs

返回值： 同步结果数组

规格相关方法

`syncProductSpecs($productId, $specs)`

同步商品规格

参数：

$productId (int): 商品ID
$specs (array): 规格数据数组

规格必填字段：

title: 规格名称
price: 规格价格

查询方法

`getProductByNum($productNum)`

根据商品编号查询商品

`getProductBySku($sku)`

根据SKU查询商品

`getTypeBySlug($slug)`

根据分类别名查询分类

数据表结构

商品表 (product)

主要字段：

id: 主键
title: 商品名称
desc: 商品描述
body: 商品详情
image: 主图
images: 图片列表（JSON）
product_num: 商品编号
sku: 商品SKU
type_id: 分类ID（JSON）
type_id_last: 最后一级分类ID
spec_type: 规格类型（1单规格，2多规格）
price: 价格
market_price: 市场价
stock: 库存
status: 状态

分类表 (product_type)

主要字段：

id: 主键
title: 分类名称
slug: 分类别名
description: 分类描述
image: 分类图片
pid: 父分类ID
sort: 排序
status: 状态

规格表 (product_spec)

主要字段：

id: 主键
product_id: 商品ID
title: 规格名称
sku: 规格SKU
image: 规格图片
price: 规格价格
market_price: 市场价
stock: 库存
status: 状态

注意事项

去重机制：系统会根据 sku 或 product_num 判断商品是否已存在，存在则更新，不存在则新增
分类处理：type_id 支持数组格式，系统会自动转换为JSON存储，并设置 type_id_last 为最后一级分类
规格处理：多规格商品必须设置 spec_type = 2 并提供规格数据
图片处理：images 字段支持数组格式，系统会自动转换为JSON存储
错误处理：所有验证错误都会通过 json_error() 返回，符合框架规范
时间戳：系统会自动设置 created_at 和 updated_at 时间戳

完整示例

参考文件：modules/product/lib/ProductSyncExample.php

该文件包含了所有功能的完整使用示例，可以直接运行查看效果。# 商品

商品分类

/product/api-type

短信

短信服务由第三方提供

调用事例

//发送验证码
$code = rand(100000, 999999); 
add_sms_template('bind_account', "绑定手机号", '绑定手机号验证', '您正在绑定邮箱，您的验证码是<b>{code}</b>,5分钟有效，如非本人请求请忽略。');
cache("bind_account_{$phone}", $code, 300);

send_sms('bind_account', $phone, [
    'code' =>  $code,
]);

send_sms($phone, $template_code, $replace = [])

添加模板

add_sms_template($code, $name, $title, $content)

用法与邮箱类似

验证短信时模板代码是 login ，需要验证码的变量是 {code}

收货地址 ​

发送邮件 ​

多语言 ​

小牛翻译 ​

小程序接口 ​

取用户信息 ​

设置用户信息 ​

订单模块文档 ​

概述 ​

功能特性 ​

数据库表结构 ​

订单主表 (order) ​

订单明细表 (order_item) ​

订单支付信息表 (order_paid_info) ​

订单退款表 (order_refund) ​

订单退款明细表 (order_refund_detail) ​

使用示例 ​

创建订单 ​

订单支付信息管理 ​

订单退款处理 ​

数据库操作规范 ​

查询方法 ​

更新和删除 ​

关联查询 ​

退款金额验证逻辑 ​

API 响应格式 ​

多语言支持 ​

模型验证规则 ​

事务处理 ​

错误处理 ​

微信支付 ​

商品同步服务文档 ​

概述 ​

功能特性 ​

类文件位置 ​

基本用法 ​

1. 引入和初始化 ​

2. 同步商品分类 ​

单个分类同步 ​

批量分类同步 ​

3. 同步单规格商品 ​

4. 同步多规格商品 ​

5. 批量同步商品 ​

6. 查询功能 ​

API 方法说明 ​

分类相关方法 ​

syncProductType($typeData) ​

batchSyncTypes($types) ​

商品相关方法 ​

syncProduct($productData, $specs = []) ​

batchSyncProducts($products) ​

规格相关方法 ​

syncProductSpecs($productId, $specs) ​

查询方法 ​

getProductByNum($productNum) ​

getProductBySku($sku) ​

getTypeBySlug($slug) ​

数据表结构 ​

商品表 (product) ​

分类表 (product_type) ​

规格表 (product_spec) ​

注意事项 ​

完整示例 ​

商品分类 ​

短信 ​

调用事例 ​

添加模板 ​

收货地址

发送邮件

多语言

小牛翻译

小程序接口

取用户信息

设置用户信息

订单模块文档

概述

功能特性

数据库表结构

订单主表 (order)

订单明细表 (order_item)

订单支付信息表 (order_paid_info)

订单退款表 (order_refund)

订单退款明细表 (order_refund_detail)

使用示例

创建订单

订单支付信息管理

订单退款处理

数据库操作规范

查询方法

更新和删除

关联查询

退款金额验证逻辑

API 响应格式

多语言支持

模型验证规则

事务处理

错误处理

微信支付

商品同步服务文档

概述

功能特性

类文件位置

基本用法

1. 引入和初始化

2. 同步商品分类

单个分类同步

批量分类同步

3. 同步单规格商品

4. 同步多规格商品

5. 批量同步商品

6. 查询功能

API 方法说明

分类相关方法

`syncProductType($typeData)`

`batchSyncTypes($types)`

商品相关方法

`syncProduct($productData, $specs = [])`

`batchSyncProducts($products)`

规格相关方法

`syncProductSpecs($productId, $specs)`

查询方法

`getProductByNum($productNum)`

`getProductBySku($sku)`

`getTypeBySlug($slug)`

数据表结构

商品表 (product)

分类表 (product_type)

规格表 (product_spec)

注意事项

完整示例

商品分类

短信

调用事例

添加模板