# Kylin Parking

Kylin 智慧停车管理扩展包 — 车牌识别、车位检测、计费引擎、月卡管理。

## 功能特性

- **车辆入场**：车牌识别置信度校验（GA/T 1028.3-2022，阈值 0.85）
- **车辆出场**：自动计费，支持免费时长、首段、周期、日封顶
- **计费引擎**：透明计费规则（`calculateFee()`），符合《价格法》明码标价要求
- **月卡管理**：办理、续费、到期提醒（提前 7 天）
- **数据安全**：车牌号、车主手机号加密存储
- **用户注销清理**：按车牌清理停车记录和月卡（`purgeByPlate()`）
- **审计日志**：所有关键操作写入审计日志

## 安装

```bash
composer require kylin/parking
```

## 配置发布

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

## 配置说明

```php
// config/kylin-parking.php
return [
    'default_free_minutes' => 15,                    // 免费时长（分钟）
    'default_first_period_minutes' => 60,            // 首段时长（分钟）
    'default_first_period_fee' => 600,               // 首段费用（分）
    'default_period_minutes' => 30,                  // 计时周期（分钟）
    'default_period_fee' => 300,                     // 周期费用（分）
    'default_daily_cap' => 5000,                     // 日封顶（分，50 元）
    'plate_confidence_threshold' => 0.85,            // 车牌识别置信度阈值
    'device_heartbeat_timeout' => 300,               // 设备心跳超时（秒）
    'monthly_card_renewal_remind_days' => 7,         // 月卡到期提醒天数
];
```

## 使用示例

### Facade

```php
use Kylin\Parking\Facades\KylinParking;

// 车辆入场（车牌识别置信度校验）
$record = KylinParking::vehicleEntry([
    'lot_id' => 1,
    'plate_no' => '京A12345',
    'confidence' => 0.92,
]);

// 车辆出场并计费
$result = KylinParking::vehicleExit(lotId: 1, plateNo: '京A12345');
// 返回 ['record' => ..., 'fee' => 1800, 'free' => false]

// 计算费用（不实际出场）
$fee = KylinParking::calculateFee(durationMinutes: 90);  // 返回分

// 办理月卡
$card = KylinParking::createMonthlyCard([
    'lot_id' => 1,
    'plate_no' => '京A12345',
    'owner_name' => '张三',
    'owner_phone' => '13800138000',
    'duration_months' => 1,
]);

// 月卡续费
KylinParking::renewMonthlyCard(cardId: 1, durationMonths: 3);

// 获取即将到期月卡（用于提醒）
$cards = KylinParking::getExpiringSoonCards();

// 用户注销时清理数据（PIPL 第 47 条）
$result = KylinParking::purgeByPlate(plateNo: '京A12345');
// 返回 ['records' => 15, 'cards' => 1]
```

### 服务注入

```php
use Kylin\Parking\Services\ParkingService;

public function __construct(private readonly ParkingService $parking) {}

public function enter(): void
{
    $this->parking->vehicleEntry([...]);
}
```

### API 路由

所有路由需通过 `auth:sanctum` 鉴权。

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/kylin/parking/entry | 车辆入场 |
| POST | /api/kylin/parking/exit | 车辆出场 |
| POST | /api/kylin/parking/monthly-cards | 办理月卡 |
| POST | /api/kylin/parking/monthly-cards/{id}/renew | 月卡续费 |
| GET | /api/kylin/parking/monthly-cards/expiring-soon | 即将到期月卡 |

## 计费规则

| 项目 | 默认值 | 说明 |
|------|------|------|
| 免费时长 | 15 分钟 | 免费时长内免费 |
| 首段时长 | 60 分钟 | 首段计费时长 |
| 首段费用 | 6 元（600 分） | 首段费用 |
| 计时周期 | 30 分钟 | 后续计费周期 |
| 周期费用 | 3 元（300 分） | 每周期费用 |
| 日封顶 | 50 元（5000 分） | 单日最高收费 |

## 数据库表

| 表名 | 说明 |
|------|------|
| `kylin_parking_lots` | 停车场表 |
| `kylin_parking_records` | 停车记录表（车牌号加密） |
| `kylin_parking_monthly_cards` | 月卡表（车牌号、手机号加密） |

## 合规要点

| 合规项 | 实现方式 | 法律依据 |
|------|------|------|
| 明码标价 | `calculateFee()` 计费规则公开透明 | 《价格法》第十三条 |
| 车牌识别校验 | `vehicleEntry()` 置信度校验 | GA/T 1028.3-2022 |
| 车牌号加密 | `encrypted` cast | 《个人信息保护法》第四十二条 |
| 手机号加密 | `MonthlyCard.owner_phone` `encrypted` cast | 《个人信息保护法》第四十二条 |
| 用户注销清理 | `purgeByPlate()` | 《个人信息保护法》第四十七条 |
| 审计日志 | 所有关键操作写入 `kylin/audit-log` | 《网络安全法》第二十一条 |
| 并发控制 | `lockForUpdate()` 防止车位超卖 | — |

## 审计事件

| 事件 | 说明 |
|------|------|
| `vehicle_entry` | 车辆入场 |
| `vehicle_exit` | 车辆出场 |
| `plate_recognition_low_confidence` | 车牌识别低置信度 |
| `monthly_card_created` | 月卡办理 |
| `monthly_card_renewed` | 月卡续费 |
| `parking_data_purged` | 用户注销清理 |

## 法律合规

详见 [LEGAL.md](./LEGAL.md)，涵盖：
- 《中华人民共和国价格法》(1998.5.1)
- 各地停车收费管理办法
- 《中华人民共和国个人信息保护法》(2021.11.1)
- 《中华人民共和国道路交通安全法》(2021.4.29 修订)
- 《中华人民共和国数据安全法》(2021.9.1)
- 《中华人民共和国网络安全法》(2017.6.1)
- GA/T 1028.3-2022

## 依赖

- PHP ^8.5
- Laravel ^13.0
- kylin/core
- 建议：kylin/audit-log（审计日志）

## 许可证

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