# 自研PMS本地计费引擎详细说明 v1.0.0

## 修订历史

| 版本号 | 修订日期 | 修订内容 | 修订人 | 状态 |
| :--- | :--- | :--- | :--- | :--- |
| v1.0.0 | 2026-03-14 | 初始版本：整合总PRD及模块说明，形成完整的本地计费引擎技术方案 | Antigravity | 草稿 |

---

## 1. 文档说明

### 1.1 文档目的

本文档详细描述自研PMS系统中本地计费引擎的技术架构、业务规则、数据流转及接口规范，为开发团队提供完整的技术实现指导。

### 1.2 适用范围

- 自研PMS模式下的停车场
- 边缘网关部署的计费引擎组件
- 云端与边缘的数据同步机制

### 1.3 相关文档

| 文档名称 | 版本 | 关联内容 |
| :--- | :--- | :--- |
| 停车系统总PRD | v1.9.0 | 系统架构、模块关系 |
| 车场管理模块 | v1.10.0 | PMS配置、离线同步 |
| 收费标准模块 | v1.9.0 | 计费规则、下发机制 |
| 设备管理模块 | v1.0.0 | 硬件对接、设备状态 |
| 进出纪录模块 | v1.5.0 | 通行记录、事件上报 |

---

## 2. 系统架构

### 2.1 整体架构图

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              物业管理平台（云端）                              │
│  ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐   │
│  │   车场管理    │ │   收费标准    │ │   车辆管理    │ │   车辆收费    │   │
│  └───────┬───────┘ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘   │
│          │                 │                 │                 │           │
│          └─────────────────┴─────────────────┴─────────────────┘           │
│                                     │                                       │
│                            ┌────────┴────────┐                              │
│                            │    云端计费     │  ← 云端计费模式使用           │
│                            │    服务中心     │                              │
│                            └────────┬────────┘                              │
└─────────────────────────────────────┼───────────────────────────────────────┘
                                      │
                    ┌─────────────────┼─────────────────┐
                    │            通信层                  │
                    │   MQTT / HTTP / TCP 双向通信      │
                    └─────────────────┼─────────────────┘
                                      │
┌─────────────────────────────────────┼───────────────────────────────────────┐
│                              边缘网关（本地）                                 │
│                                     │                                       │
│  ┌──────────────────────────────────┴──────────────────────────────────┐   │
│  │                         本地计费引擎                                 │   │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐   │   │
│  │  │  规则管理   │ │  费用计算   │ │  白名单     │ │  缓存管理   │   │   │
│  │  │   模块     │ │    模块     │ │   模块     │ │    模块     │   │   │
│  │  └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘   │   │
│  │         └───────────────┴───────────────┴───────────────┘           │   │
│  │                                 │                                    │   │
│  │                    ┌────────────┴────────────┐                       │   │
│  │                    │      本地数据库         │                       │   │
│  │                    │  (SQLite / LevelDB)    │                       │   │
│  │                    └────────────┬────────────┘                       │   │
│  └─────────────────────────────────┼────────────────────────────────────┘   │
│                                    │                                        │
│  ┌─────────────────────────────────┴────────────────────────────────────┐   │
│  │                          设备通信层                                   │   │
│  │         道闸控制  │  车牌识别  │  LED显示  │  语音播报               │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
┌─────────────────────────────────────┼───────────────────────────────────────┐
│                              硬件设备层                                      │
│      ┌──────────┐      ┌──────────┐      ┌──────────┐      ┌──────────┐    │
│      │  道闸    │      │  相机    │      │  一体机  │      │  LED屏   │    │
│      └──────────┘      └──────────┘      └──────────┘      └──────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘
```

### 2.2 计费模式选择

| 模式 | 计费执行位置 | 网络依赖 | 适用场景 |
| :--- | :--- | :--- | :--- |
| **云端计费** | 物业管理平台(云端) | 强依赖 | 网络稳定、规则频繁变更、需实时对账 |
| **边缘计费** | 边缘网关(本地) | 弱依赖 | 网络不稳定、高可用要求、响应速度要求高 |

**配置入口**：车场管理 → 编辑车场 → PMS配置 → 计费模式

---

## 3. 核心模块详解

### 3.1 规则管理模块

#### 3.1.1 功能职责

- 接收并存储云端下发的收费规则
- 管理规则版本，支持增量/全量更新
- 提供规则查询接口供费用计算模块调用

#### 3.1.2 规则数据结构

```json
{
  "rule_id": "RULE_20260314_001",
  "park_id": "PARK_001",
  "rule_name": "临停标准收费",
  "rule_type": "临停收费",
  "is_default": true,
  "vehicle_types": ["临时车", "访客车"],
  "params": {
    "billing_mode": "阶梯计时",
    "first_hour_free": true,
    "free_duration_minutes": 60,
    "hourly_rate": 5.00,
    "daily_cap": 50.00,
    "daily_cap_type": "24小时封顶",
    "buffer_minutes": 15,
    "precision": "分钟",
    "cross_day_rule": "连续计时"
  },
  "effective_time": "2026-03-01T00:00:00Z",
  "expire_time": null,
  "version": 3,
  "sync_time": "2026-03-14T10:30:00Z"
}
```

#### 3.1.3 规则类型定义

**时效租赁规则**

```json
{
  "rule_type": "时效租赁",
  "params": {
    "cycle_unit": "月",
    "cycle_length": 1,
    "price": 300.00,
    "require_bindSpace": true
  }
}
```

**临停收费规则**

```json
{
  "rule_type": "临停收费",
  "params": {
    "billing_mode": "首小时免费+阶梯计时",
    "first_hour_free": true,
    "free_duration_minutes": 60,
    "hourly_rate": 5.00,
    "daily_cap": 50.00,
    "daily_cap_type": "24小时封顶",
    "buffer_minutes": 15
  }
}
```

**免费规则**

```json
{
  "rule_type": "免费",
  "params": {
    "free_type": "全时段免费",
    "remark": "物业工作用车"
  }
}
```

#### 3.1.4 规则存储表结构

```sql
CREATE TABLE fee_rules (
    rule_id         VARCHAR(64) PRIMARY KEY,
    park_id         VARCHAR(64) NOT NULL,
    rule_name       VARCHAR(128) NOT NULL,
    rule_type       VARCHAR(32) NOT NULL,
    is_default      BOOLEAN DEFAULT FALSE,
    vehicle_types   TEXT,                    -- JSON数组
    params          TEXT NOT NULL,           -- JSON对象
    effective_time  DATETIME NOT NULL,
    expire_time     DATETIME,
    version         INTEGER NOT NULL,
    sync_time       DATETIME NOT NULL,
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_park_id ON fee_rules(park_id);
CREATE INDEX idx_is_default ON fee_rules(park_id, is_default);
```

---

### 3.2 白名单模块

#### 3.2.1 功能职责

- 存储已授权车辆信息（业主车、长租车等）
- 快速判定车辆是否免费放行
- 支持增量同步和全量同步

#### 3.2.2 白名单数据结构

```json
{
  "plate_number": "粤B12345",
  "park_id": "PARK_001",
  "vehicle_type": "业主车",
  "owner_name": "张三",
  "bindSpace_id": "A-101",
  "fee_rule_id": "RULE_20260314_001",
  "valid_from": "2026-01-01T00:00:00Z",
  "valid_to": "2026-12-31T23:59:59Z",
  "status": "有效",
  "version": 2,
  "sync_time": "2026-03-14T10:30:00Z"
}
```

#### 3.2.3 车辆类型定义

| 类型 | 计费规则 | 白名单 | 说明 |
| :--- | :--- | :--- | :--- |
| **业主车** | 绑定规则 | 是 | 长期有效，绑定收费规则 |
| **长租车** | 绑定规则 | 是 | 有时效，到期需续费 |
| **临时车(已登记)** | 默认规则 | 否 | 临时进入，按默认规则计费 |
| **访客车** | 默认规则 | 否 | 业主邀请，按默认规则计费 |
| **物业车** | 免费规则 | 是 | 物业用车，免费通行 |
| **黑名单** | - | 特殊 | 禁止入场 |

#### 3.2.4 白名单存储表结构

```sql
CREATE TABLE whitelist (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    plate_number    VARCHAR(16) NOT NULL,
    park_id         VARCHAR(64) NOT NULL,
    vehicle_type    VARCHAR(32) NOT NULL,
    owner_name      VARCHAR(64),
    bindSpace_id    VARCHAR(64),
    fee_rule_id     VARCHAR(64),
    valid_from      DATETIME NOT NULL,
    valid_to        DATETIME,
    status          VARCHAR(16) DEFAULT '有效',
    version         INTEGER NOT NULL,
    sync_time       DATETIME NOT NULL,
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(plate_number, park_id)
);

CREATE INDEX idx_plate ON whitelist(plate_number);
CREATE INDEX idx_valid ON whitelist(valid_from, valid_to);
```

---

### 3.3 费用计算模块

#### 3.3.1 功能职责

- 根据进出场时间和收费规则计算停车费用
- 支持多种计费模式的算法实现
- 处理跨日、封顶等复杂计费场景

#### 3.3.2 计费流程

```
车辆出场请求
    │
    ▼
┌───────────────────┐
│ 1. 查询白名单     │
└─────────┬─────────┘
          │
    ┌─────┴─────┐
    │ 是否白名单 │
    └─────┬─────┘
          │
    ┌─────┴─────┐
    │           │
    ▼           ▼
  [是]        [否]
    │           │
    ▼           ▼
┌─────────┐ ┌─────────────────┐
│查询绑定 │ │查询车场默认规则 │
│收费规则 │ └────────┬────────┘
└────┬────┘          │
     │               │
     └───────┬───────┘
             │
             ▼
┌───────────────────────────┐
│ 2. 获取进场记录           │
│    - 进场时间             │
│    - 进场道口             │
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│ 3. 计算停车时长           │
│    出场时间 - 进场时间    │
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│ 4. 应用收费规则计算费用   │
│    - 免费时长判定         │
│    - 阶梯计费             │
│    - 封顶处理             │
│    - 跨日处理             │
└─────────────┬─────────────┘
              │
              ▼
┌───────────────────────────┐
│ 5. 返回计费结果           │
│    - 应付金额             │
│    - 费用明细             │
│    - 缓冲时间             │
└───────────────────────────┘
```

#### 3.3.3 计费算法实现

**临停计费算法（首小时免费+阶梯计时）**

```python
def calculate_temp_parking_fee(entry_time, exit_time, rule):
    """
    临停计费算法
    :param entry_time: 进场时间 datetime
    :param exit_time: 出场时间 datetime
    :param rule: 收费规则
    :return: 费用金额
    """
    # 1. 计算总停车时长（分钟）
    total_minutes = (exit_time - entry_time).total_seconds() / 60

    # 2. 免费时长判定
    if total_minutes <= rule.free_duration_minutes:
        return 0.00

    # 3. 扣除免费时长
    billable_minutes = total_minutes - rule.free_duration_minutes

    # 4. 根据计费精度向上取整
    precision_map = {"分钟": 1, "5分钟": 5, "15分钟": 15, "小时": 60}
    precision = precision_map.get(rule.precision, 1)
    billable_units = math.ceil(billable_minutes / precision)

    # 5. 计算费用（按小时费率）
    if rule.precision == "小时":
        fee = billable_units * rule.hourly_rate
    else:
        fee = (billable_units * precision / 60) * rule.hourly_rate

    # 6. 封顶处理
    if rule.daily_cap_type == "24小时封顶":
        # 每24小时周期计算封顶
        days = math.ceil(total_minutes / (24 * 60))
        max_fee = days * rule.daily_cap
        fee = min(fee, max_fee)
    elif rule.daily_cap_type == "每日封顶":
        # 按自然日计算封顶
        # ... 跨日分段计算逻辑
        pass

    return round(fee, 2)
```

**时效租赁计费算法**

```python
def calculate_rental_fee(vehicle, rule):
    """
    时效租赁计费算法
    :param vehicle: 车辆信息（含有效期）
    :param rule: 收费规则
    :return: 费用金额（0表示有效期内免费）
    """
    now = datetime.now()

    # 判断是否在有效期内
    if vehicle.valid_from <= now <= vehicle.valid_to:
        return 0.00

    # 已过期，按临停规则计费或提示续费
    # 此处根据业务需求处理
    return None  # 返回None表示需要续费
```

#### 3.3.4 计费结果数据结构

```json
{
  "calculation_id": "CALC_20260314_123456",
  "plate_number": "粤B12345",
  "park_id": "PARK_001",
  "entry_time": "2026-03-14T09:30:00Z",
  "exit_time": "2026-03-14T12:05:00Z",
  "duration_minutes": 155,
  "rule_id": "RULE_20260314_001",
  "rule_name": "临停标准收费",
  "fee_details": {
    "total_minutes": 155,
    "free_minutes": 60,
    "billable_minutes": 95,
    "hourly_rate": 5.00,
    "raw_fee": 10.00,
    "daily_cap_applied": false,
    "final_fee": 10.00
  },
  "amount": 10.00,
  "buffer_minutes": 15,
  "buffer_expire_time": "2026-03-14T12:20:00Z",
  "status": "待缴费",
  "calculated_at": "2026-03-14T12:05:01Z"
}
```

---

### 3.4 缓存管理模块

#### 3.4.1 功能职责

- 管理本地进出场记录缓存
- 管理待上报数据队列
- 实现数据过期清理策略

#### 3.4.2 缓存数据类型

| 数据类型 | 存储策略 | 有效期 | 清理条件 |
| :--- | :--- | :--- | :--- |
| 进场记录 | 持久化 | 7天 | 出场完成且已上报 |
| 出场记录 | 持久化 | 7天 | 已上报云端确认 |
| 待缴账单 | 持久化 | 无限 | 缴费完成且已上报 |
| 支付记录 | 持久化 | 30天 | 已上报云端确认 |
| 上报队列 | 内存+持久化 | 直到成功 | 上报成功 |

#### 3.4.3 进出场记录表结构

```sql
-- 进场记录表
CREATE TABLE entry_records (
    record_id       VARCHAR(64) PRIMARY KEY,
    plate_number    VARCHAR(16) NOT NULL,
    park_id         VARCHAR(64) NOT NULL,
    gate_id         VARCHAR(64) NOT NULL,
    entry_time      DATETIME NOT NULL,
    capture_image   TEXT,                    -- 抓拍图片URL/Base64
    confidence      DECIMAL(5,2),            -- 识别置信度
    vehicle_type    VARCHAR(32),
    is_synced       BOOLEAN DEFAULT FALSE,
    sync_time       DATETIME,
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- 出场记录表
CREATE TABLE exit_records (
    record_id       VARCHAR(64) PRIMARY KEY,
    entry_record_id VARCHAR(64),
    plate_number    VARCHAR(16) NOT NULL,
    park_id         VARCHAR(64) NOT NULL,
    gate_id         VARCHAR(64) NOT NULL,
    exit_time       DATETIME NOT NULL,
    capture_image   TEXT,
    duration_minutes INTEGER,
    fee_amount      DECIMAL(10,2),
    payment_status  VARCHAR(16),             -- 待缴费/已缴费/免费
    payment_time    DATETIME,
    is_synced       BOOLEAN DEFAULT FALSE,
    sync_time       DATETIME,
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (entry_record_id) REFERENCES entry_records(record_id)
);

-- 待上报队列表
CREATE TABLE sync_queue (
    id              INTEGER PRIMARY KEY AUTOINCREMENT,
    data_type       VARCHAR(32) NOT NULL,    -- entry/exit/payment/fee
    data_id         VARCHAR(64) NOT NULL,
    payload         TEXT NOT NULL,           -- JSON数据
    priority        INTEGER DEFAULT 0,
    retry_count     INTEGER DEFAULT 0,
    max_retry       INTEGER DEFAULT 3,
    status          VARCHAR(16) DEFAULT 'pending',
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    last_retry_at   DATETIME
);

CREATE INDEX idx_sync_status ON sync_queue(status, priority);
```

---

## 4. 数据同步机制

### 4.1 云端→边缘同步（下发）

#### 4.1.1 同步触发条件

| 触发场景 | 同步内容 | 同步方式 |
| :--- | :--- | :--- |
| 收费规则变更 | 变更的规则 | 增量推送 |
| 车辆信息变更 | 变更的白名单 | 增量推送 |
| 车场启用自研PMS | 全量规则+白名单 | 全量推送 |
| 边缘网关重启 | 全量规则+白名单 | 全量拉取 |
| 手动触发同步 | 指定内容 | 按需 |

#### 4.1.2 下发协议格式

**请求（云端→边缘）**

```json
{
  "msg_type": "SYNC_PUSH",
  "sync_id": "SYNC_20260314_001",
  "park_id": "PARK_001",
  "sync_type": "incremental",
  "timestamp": "2026-03-14T10:30:00Z",
  "data": {
    "rules": [...],
    "whitelist": [...]
  },
  "checksum": "sha256:abc123..."
}
```

**响应（边缘→云端）**

```json
{
  "msg_type": "SYNC_ACK",
  "sync_id": "SYNC_20260314_001",
  "status": "success",
  "applied_at": "2026-03-14T10:30:01Z",
  "current_versions": {
    "rules": 5,
    "whitelist": 128
  }
}
```

### 4.2 边缘→云端同步（上报）

#### 4.2.1 上报数据类型

| 数据类型 | 上报时机 | 优先级 |
| :--- | :--- | :--- |
| 进场事件 | 实时 | 中 |
| 出场事件 | 实时 | 高 |
| 计费结果 | 出场时 | 高 |
| 支付结果 | 支付完成时 | 最高 |
| 设备状态 | 定时(30s) | 低 |
| 对账摘要 | 定时(每日) | 低 |

#### 4.2.2 上报协议格式

**进出场事件上报**

```json
{
  "msg_type": "EVENT_REPORT",
  "event_id": "EVT_20260314_123456",
  "event_type": "ENTRY",
  "park_id": "PARK_001",
  "gate_id": "GATE_001",
  "plate_number": "粤B12345",
  "timestamp": "2026-03-14T09:30:00Z",
  "capture_image": "https://oss.xxx.com/capture/xxx.jpg",
  "confidence": 98.5,
  "is_offline_data": false
}
```

**计费结果上报**

```json
{
  "msg_type": "FEE_REPORT",
  "calculation_id": "CALC_20260314_123456",
  "park_id": "PARK_001",
  "plate_number": "粤B12345",
  "entry_time": "2026-03-14T09:30:00Z",
  "exit_time": "2026-03-14T12:05:00Z",
  "duration_minutes": 155,
  "rule_id": "RULE_20260314_001",
  "amount": 10.00,
  "fee_details": {...},
  "is_offline_data": false
}
```

### 4.3 离线数据同步

#### 4.3.1 离线期间处理

```
网络断开
    │
    ▼
┌───────────────────────────────┐
│ 本地计费引擎独立运行          │
│ - 使用本地缓存的规则和白名单  │
│ - 进出场记录存入本地数据库    │
│ - 计费结果存入待上报队列      │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ 队列数据持久化                │
│ - 按时间顺序存储              │
│ - 携带离线标记                │
│ - 最大缓存10000条             │
└───────────────────────────────┘
```

#### 4.3.2 恢复在线后同步

```
网络恢复
    │
    ▼
┌───────────────────────────────┐
│ 1. 上报网关在线状态           │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ 2. 拉取离线期间的规则更新     │
│    (增量同步)                 │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ 3. 按时间顺序上报离线数据     │
│    - 标记 is_offline_data=true│
│    - 优先上报支付记录         │
│    - 其次上报出场记录         │
│    - 最后上报进场记录         │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ 4. 云端确认接收               │
│    - 返回同步确认             │
│    - 本地清除已同步数据       │
└───────────────────────────────┘
```

#### 4.3.3 数据对账机制

**每日对账流程**（默认凌晨2:00执行）

```
┌───────────────────────────────┐
│ 边缘网关生成前日数据摘要      │
│ - 进场记录数、出场记录数      │
│ - 总收费金额、收费笔数        │
│ - 各规则使用次数              │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ 上报摘要至云端                │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ 云端比对本地记录              │
└───────────────┬───────────────┘
                │
        ┌───────┴───────┐
        │               │
        ▼               ▼
    [一致]          [不一致]
        │               │
        ▼               ▼
┌─────────────┐ ┌───────────────────┐
│ 对账完成    │ │ 生成差异报告      │
│ 标记已对账  │ │ - 缺失记录        │
└─────────────┘ │ - 金额差异        │
                │ - 推送告警        │
                └───────────────────┘
```

**对账摘要数据结构**

```json
{
  "msg_type": "RECONCILIATION",
  "park_id": "PARK_001",
  "date": "2026-03-13",
  "summary": {
    "entry_count": 156,
    "exit_count": 148,
    "total_fee": 2350.00,
    "fee_count": 89,
    "free_count": 59,
    "rule_usage": {
      "RULE_001": 45,
      "RULE_002": 34,
      "RULE_003": 10
    }
  },
  "checksum": "sha256:def456..."
}
```

---

## 5. 支付集成

### 5.1 支付流程

#### 5.1.1 云端计费模式

```
用户扫码缴费
    │
    ▼
┌───────────────────────────────┐
│ 小程序调用云端接口查询费用    │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ 用户确认支付                  │
│ 调用微信支付                  │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ 支付成功回调至云端            │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ 云端下发放行指令至边缘网关    │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ 边缘网关控制道闸开启          │
└───────────────────────────────┘
```

#### 5.1.2 边缘计费模式

```
用户扫码缴费
    │
    ▼
┌───────────────────────────────┐
│ 小程序调用云端接口            │
│ 云端转发至边缘网关查询费用    │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ 用户确认支付                  │
│ 调用微信支付                  │
└───────────────┬───────────────┘
                │
                ▼
┌───────────────────────────────┐
│ 支付成功回调                  │
│ 同时通知云端和边缘网关        │
└───────────────┬───────────────┘
                │
        ┌───────┴───────┐
        │               │
        ▼               ▼
┌─────────────┐ ┌─────────────────┐
│ 云端记录    │ │ 边缘网关        │
│ 支付成功    │ │ 本地标记已缴费  │
└─────────────┘ │ 触发道闸开启    │
                └─────────────────┘
```

### 5.2 支付回调处理

#### 5.2.1 回调接口（边缘网关）

```
POST /api/v1/payment/callback

请求体:
{
  "payment_id": "PAY_20260314_123456",
  "calculation_id": "CALC_20260314_123456",
  "plate_number": "粤B12345",
  "amount": 10.00,
  "payment_channel": "微信支付",
  "payment_time": "2026-03-14T12:10:00Z",
  "transaction_id": "WX20260314123456789"
}

响应:
{
  "code": 0,
  "message": "success",
  "data": {
    "gate_opened": true,
    "buffer_expire_time": "2026-03-14T12:25:00Z"
  }
}
```

#### 5.2.2 支付状态同步

```json
{
  "msg_type": "PAYMENT_REPORT",
  "payment_id": "PAY_20260314_123456",
  "calculation_id": "CALC_20260314_123456",
  "park_id": "PARK_001",
  "plate_number": "粤B12345",
  "amount": 10.00,
  "payment_channel": "微信支付",
  "payment_time": "2026-03-14T12:10:00Z",
  "transaction_id": "WX20260314123456789",
  "gate_opened": true,
  "gate_open_time": "2026-03-14T12:10:01Z"
}
```

---

## 6. 设备控制

### 6.1 道闸控制

#### 6.1.1 控制指令

| 指令类型 | 触发条件 | 参数 |
| :--- | :--- | :--- |
| **自动开闸** | 白名单车辆/已缴费 | gate_id, plate_number, reason |
| **手动开闘** | 岗亭人员操作 | gate_id, operator_id, reason |
| **保持关闭** | 黑名单/未缴费 | gate_id, plate_number, reason |

#### 6.1.2 控制协议

```json
{
  "cmd_type": "GATE_CONTROL",
  "cmd_id": "CMD_20260314_123456",
  "gate_id": "GATE_001",
  "action": "OPEN",
  "plate_number": "粤B12345",
  "reason": "payment_completed",
  "duration_seconds": 10,
  "timestamp": "2026-03-14T12:10:01Z"
}
```

### 6.2 显示屏控制

#### 6.2.1 显示内容

| 场景 | 显示内容 |
| :--- | :--- |
| 空闲 | 车位剩余: XXX |
| 车辆进场 | 欢迎光临 粤B12345 |
| 待缴费 | 粤B12345 请缴费 ¥10.00 |
| 缴费成功 | 粤B12345 一路顺风 |
| 黑名单 | 禁止通行 请联系管理员 |

#### 6.2.2 语音播报

| 场景 | 播报内容 |
| :--- | :--- |
| 车辆进场 | "欢迎光临" |
| 待缴费 | "请扫码缴费" |
| 缴费成功 | "缴费成功，一路顺风" |
| 免费放行 | "一路顺风" |
| 黑名单 | "禁止通行，请联系管理员" |

---

## 7. 异常处理

### 7.1 异常场景与处理

| 异常场景 | 检测方式 | 处理策略 |
| :--- | :--- | :--- |
| **网络断开** | 心跳超时 | 切换至离线模式，使用本地缓存 |
| **规则缺失** | 计费时查询失败 | 告警 + 人工干预 |
| **白名单过期** | 有效期校验 | 按临停规则计费 |
| **存储空间不足** | 定时检查 | 告警 + 清理旧数据 |
| **设备故障** | 心跳/状态上报 | 告警 + 切换备用设备 |
| **支付回调超时** | 超时检测 | 重试 + 人工查询 |

### 7.2 告警机制

#### 7.2.1 告警级别

| 级别 | 说明 | 响应时效 | 通知方式 |
| :--- | :--- | :--- | :--- |
| **紧急** | 系统不可用 | 立即 | 短信+电话+推送 |
| **重要** | 功能异常 | 15分钟内 | 短信+推送 |
| **一般** | 预警提示 | 1小时内 | 推送 |
| **信息** | 运行日志 | 日报 | 邮件 |

#### 7.2.2 告警事件

```json
{
  "alert_type": "DEVICE_OFFLINE",
  "alert_level": "重要",
  "park_id": "PARK_001",
  "device_id": "GATE_001",
  "message": "道闸设备离线超过5分钟",
  "timestamp": "2026-03-14T12:00:00Z",
  "context": {
    "last_heartbeat": "2026-03-14T11:55:00Z",
    "offline_duration_seconds": 300
  }
}
```

---

## 8. 配置参数

### 8.1 计费引擎配置

| 配置项 | 类型 | 默认值 | 说明 |
| :--- | :--- | :--- | :--- |
| `billing.precision` | 枚举 | 分钟 | 计费精度：分钟/5分钟/15分钟/小时 |
| `billing.free_duration` | 整数 | 15 | 默认免费时长（分钟） |
| `billing.buffer_duration` | 整数 | 15 | 缴费后缓冲时长（分钟） |
| `billing.cross_day_rule` | 枚举 | 连续计时 | 跨日计费：连续计时/按自然日分段 |

### 8.2 同步配置

| 配置项 | 类型 | 默认值 | 说明 |
| :--- | :--- | :--- | :--- |
| `sync.heartbeat_interval` | 整数 | 30 | 心跳间隔（秒） |
| `sync.retry_count` | 整数 | 3 | 上报重试次数 |
| `sync.retry_interval` | 整数 | 5 | 重试间隔（秒） |
| `sync.reconciliation_time` | 时间 | 02:00 | 每日对账时间 |

### 8.3 缓存配置

| 配置项 | 类型 | 默认值 | 说明 |
| :--- | :--- | :--- | :--- |
| `cache.max_records` | 整数 | 10000 | 最大缓存记录数 |
| `cache.retention_days` | 整数 | 7 | 记录保留天数 |
| `cache.cleanup_interval` | 整数 | 3600 | 清理间隔（秒） |

---

## 9. 部署要求

### 9.1 硬件要求

| 组件 | 最低配置 | 推荐配置 |
| :--- | :--- | :--- |
| CPU | 双核 1.5GHz | 四核 2.0GHz |
| 内存 | 2GB | 4GB |
| 存储 | 16GB SSD | 32GB SSD |
| 网络 | 100Mbps | 千兆 |

### 9.2 软件要求

| 组件 | 版本要求 |
| :--- | :--- |
| 操作系统 | Linux (Ubuntu 20.04+ / Debian 11+) |
| 数据库 | SQLite 3.35+ 或 LevelDB |
| 运行时 | Node.js 18+ 或 Go 1.20+ |
| 通信协议 | MQTT 5.0 / HTTP/2 |

---

## 10. 附录

### 10.1 术语表

| 术语 | 说明 |
| :--- | :--- |
| **PMS** | Parking Management System，停车管理系统 |
| **边缘网关** | 部署在停车场本地的计算设备，负责设备通信和本地计费 |
| **云端计费** | 费用计算在云端物业管理平台执行 |
| **边缘计费** | 费用计算在本地边缘网关执行 |
| **白名单** | 已授权的车辆列表，包含业主车、长租车等 |
| **缓冲时间** | 缴费后允许出场的时间窗口 |

### 10.2 接口汇总

| 接口 | 方向 | 用途 |
| :--- | :--- | :--- |
| `/api/v1/sync/rules` | 云端→边缘 | 收费规则同步 |
| `/api/v1/sync/whitelist` | 云端→边缘 | 白名单同步 |
| `/api/v1/events/entry` | 边缘→云端 | 进场事件上报 |
| `/api/v1/events/exit` | 边缘→云端 | 出场事件上报 |
| `/api/v1/fee/calculate` | 本地 | 费用计算 |
| `/api/v1/payment/callback` | 云端→边缘 | 支付回调 |
| `/api/v1/gate/control` | 本地 | 道闸控制 |
| `/api/v1/reconciliation` | 边缘→云端 | 对账上报 |

---

## 11. 待确认事项

1. 边缘计费模式下，用户在小程序缴费后，如何确保本地快速收到缴费成功通知？
   - **建议方案**：支付回调同时推送云端和边缘，或通过云端中转实时推送

2. 跨多个车场的通行（如场中场），计费归属如何判定？
   - **建议方案**：按实际进出场记录归属，子场优先、主场兜底

3. 本地数据库选型：SQLite vs LevelDB？
   - **建议方案**：中小规模用SQLite（便于查询），大规模用LevelDB（高性能）

4. 边缘网关升级策略？
   - **建议方案**：支持OTA远程升级，升级前自动备份，失败自动回滚