# Kylin Ecommerce

Kylin 智慧电商运营系统核心扩展包，严格遵守《电子商务法》《消费者权益保护法》《电子签名法》《个人信息保护法》。

## 功能特性

### 订单与交易
- **订单管理**：订单金额计算、订单号生成（`EC` + 日期 + 序号）
- **优惠券**：满减/折扣/无门槛优惠券折扣计算
- **库存管理**：乐观锁库存扣减、库存预警
- **交易配置**：订单超时、自动确认收货、退款天数

### 合规服务
- **退款服务** (`RefundService`)：7 天无理由退货、质量问题退款、欺诈退一赔三
- **地址脱敏** (`AddressMasker`)：收货人姓名/手机号/详细地址脱敏展示
- **电子签名** (`ESignatureService`)：HMAC-SHA256 合同签名，符合《电子签名法》
- **商家实名认证** (`MerchantVerificationService`)：企业/个人实名认证
- **支付安全验证** (`PaymentSecurityValidator`)：PCI DSS 合规，禁止存储 CVV/完整卡号

## 安装

```bash
composer require kylin/ecommerce
```

## 配置发布

```bash
php artisan vendor:publish --tag=kylin-ecommerce-config
```

## 使用示例

### 订单金额计算

```php
use Kylin\Ecommerce\Facades\KylinEcommerce;

$result = KylinEcommerce::calculateOrderAmount([
    ['price' => 99.00, 'quantity' => 2],
    ['price' => 49.00, 'quantity' => 1],
], couponId: 1);

// ['total_amount' => 247.00, 'discount_amount' => 20.00, 'pay_amount' => 227.00]
```

### 库存扣减（乐观锁）

```php
$success = KylinEcommerce::deductStock(productId: 100, specId: 201, quantity: 1);
```

### 订单号生成

```php
$orderNo = KylinEcommerce::generateOrderNo();
// 'EC202606191430250001'
```

### 库存预警

```php
$lowStockProducts = KylinEcommerce::getLowStockProducts(threshold: 10);
```

### 退款资格检查（含审计）

```php
use Kylin\Ecommerce\Services\RefundService;

// 检查退款资格（依据《消费者权益保护法》第二十五条）
$result = RefundService::checkEligibilityWithAudit($order, 'no_reason');
// ['eligible' => true, 'reason' => '...', 'law' => '《消费者权益保护法》第二十五条']

// 计算退款金额
$refund = RefundService::calculateRefund($order, 'quality');
```

### 收货地址脱敏

```php
use Kylin\Ecommerce\Services\AddressMasker;

// 脱敏地址（依据《个人信息保护法》第五十一条）
$masked = AddressMasker::mask($address);
// 姓名：张**  手机：138****5678  地址：北京市朝阳区****

// 订单展示用脱敏
$masked = AddressMasker::maskForDisplay($order);
```

### 电子合同签名

```php
use Kylin\Ecommerce\Services\ESignatureService;

// 签名（依据《电子签名法》第十四条）
$signature = ESignatureService::sign($userId, [
    'order_no' => 'EC202606191430250001',
    'amount' => 227.00,
    'items' => [...],
]);
// ['signature' => '...', 'signed_at' => '...', 'signer_ip' => '...', 'law' => '《电子签名法》']

// 验签
$isValid = ESignatureService::verify($contractData, $signature['signature']);
```

### 商家实名认证

```php
use Kylin\Ecommerce\Services\MerchantVerificationService;

// 提交认证（依据《电子商务法》第二十七条）
$result = MerchantVerificationService::verify([
    'type' => 'enterprise',
    'business_license' => '...',
    'legal_person_id' => '...',
    'bank_account' => '...',
]);

// 查询认证状态
$status = MerchantVerificationService::getStatus($merchantId);
```

### 支付数据安全处理

```php
use Kylin\Ecommerce\Services\PaymentSecurityValidator;

// 清理支付数据（依据 PCI DSS，禁止存储 CVV/完整卡号）
$clean = PaymentSecurityValidator::sanitize($paymentData);

// 验证支付回调
$result = PaymentSecurityValidator::validateCallback($callbackData);
```

## 配置项

| 配置键 | 默认值 | 说明 |
|------|------|------|
| `stock_warning_threshold` | 10 | 库存预警阈值 |
| `order_timeout_minutes` | 30 | 订单超时时间（分钟） |
| `auto_confirm_days` | 7 | 自动确认收货天数 |
| `refund_days_limit` | 15 | 退款天数限制 |

## 数据模型

| 模型 | 说明 | 合规要点 |
|------|------|------|
| `Order` | 订单 | 关联电子签名，合同成立凭证 |
| `Refund` | 退款 | 记录退款类型、原因、法律依据 |
| `Product` | 商品 | 库存乐观锁扣减 |
| `Merchant` | 商家 | 实名认证状态 |
| `Address` | 收货地址 | 敏感字段加密存储 |

## 法律合规

本包严格遵守以下法律法规：

### 《电子商务法》(2019.1.1)
- **第二十一条**：押金退还方式、程序需明示
- **第二十三条**：用户个人信息保护
- **第二十七条**：商家实名认证（`MerchantVerificationService`）
- **第四十九条**：订单生成即合同成立，电子签名确保效力（`ESignatureService`）

### 《消费者权益保护法》(2014.3.15)
- **第二十五条**：7 天无理由退货（`RefundService::TYPE_NO_REASON`）
- **第五十五条**：欺诈退一赔三（`RefundService::TYPE_FRAUD`）
- 不可无理由退货商品：定制、鲜活、已拆封数字化商品等

### 《电子签名法》(2019.4.23 修订)
- **第十三条**：可靠电子签名条件（签名人专有、仅由签名人控制、不可篡改）
- **第十四条**：可靠电子签名与手写签名同等法律效力

### 《个人信息保护法》(2021.11.1)
- **第二十八条**：支付信息为敏感个人信息（`PaymentSecurityValidator`）
- **第五十一条**：地址脱敏展示（`AddressMasker`）

### PCI DSS 支付卡行业数据安全标准
- 禁止存储 CVV/CVC 码
- 禁止存储完整卡号（仅保留后 4 位）
- 支付数据传输加密

详见 [LEGAL.md](LEGAL.md)。

## 依赖

- PHP ^8.5
- Laravel ^13.0
- kylin/core
- kylin/rbac
- kylin/auth
- kylin/media
- kylin/pay

## 许可证

私有软件，未经授权禁止使用。
