# Kylin Retail

智慧零售门店领域包 — 商品管理、库存管理、收银结算、会员管理、数据报表。

## 功能特性

- **商品管理**（Product）：商品 CRUD、条码管理（EAN-13/UPC-A）、分类管理、价格管理、供应商管理
- **库存管理**（Inventory）：入库/出库、实时库存、安全库存预警、盘点管理、库存流水
- **收银结算**（Cashier）：扫码收银、多渠道支付、退换货、交易记录、收银对账
- **会员管理**（Member）：会员注册、积分管理、等级管理、优惠券、会员画像
- **数据报表**（Report）：销售报表、库存报表、会员报表、经营看板

## 安装

```bash
composer require kylin/retail
php artisan vendor:publish --tag=kylin-retail-config
php artisan vendor:publish --tag=kylin-retail-migrations
php artisan migrate
```

## 配置说明

```php
// config/kylin-retail.php
return [
    'barcode' => [
        'type' => 'ean13',                // 条码类型：ean13/upca
        'auto_generate' => true,          // 自动生成条码
    ],
    'inventory' => [
        'alert_threshold' => 10,          // 库存预警阈值
        'audit_retention_days' => 180,    // 库存流水保留天数
    ],
    'member' => [
        'privacy_consent_required' => true,  // 会员注册需隐私同意
        'data_retention_days' => 365,        // 注销后数据保留天数
        'points_expire_days' => 365,         // 积分过期天数
    ],
    'return' => [
        'max_days' => 7,                  // 退货最大天数（七日无理由）
        'refund_method' => 'original',    // 退款方式：original/balance
    ],
    'receipt' => [
        'retention_days' => 90,           // 交易记录保留天数
    ],
];
```

## 使用示例

### Facade

```php
use Kylin\Retail\Facades\KylinRetail;

// 创建商品
$product = KylinRetail::createProduct([
    'name' => '商品名称',
    'barcode' => '6901234567890',
    'price' => 9900, // 单位：分
    'category_id' => 1,
    'supplier_id' => 1,
]);

// 入库
KylinRetail::stockIn([
    'product_id' => 1,
    'quantity' => 100,
    'remark' => '采购入库',
]);

// 收银结算
$order = KylinRetail::checkout([
    'items' => [
        ['product_id' => 1, 'quantity' => 2],
        ['product_id' => 2, 'quantity' => 1],
    ],
    'payment_method' => 'wechat',
    'member_id' => 1, // 可选
]);

// 退货
KylinRetail::returnOrder($order->id, [
    'items' => [['product_id' => 1, 'quantity' => 1]],
    'reason' => '质量问题',
]);
```

### API 路由

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/kylin/retail/products | 商品列表 |
| POST | /api/kylin/retail/products | 创建商品 |
| GET | /api/kylin/retail/inventory | 库存查询 |
| POST | /api/kylin/retail/checkout | 收银结算 |
| GET | /api/kylin/retail/members | 会员列表 |
| POST | /api/kylin/retail/members | 会员注册 |
| GET | /api/kylin/retail/reports/sales | 销售报表 |

## 法律合规

详见 [LEGAL.md](./LEGAL.md)，涵盖：
- 《中华人民共和国电子商务法》(2019.1.1)
- 《中华人民共和国消费者权益保护法》(2014.3.15) — 七日无理由退货
- 《中华人民共和国个人信息保护法》(2021.11.1) — 会员信息保护
- GB/T 27917-2011《快递服务》

## 依赖

- PHP ^8.5
- Laravel ^13.0
- kylin/core
- kylin/payment

## 许可证

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