jsowell-charger-web/docs/qcyun停车优惠新站点配置指南.md

# qcyun 停车优惠新站点配置指南

本文用于配置一个新站点的 qcyun 停车优惠功能。配置完成后，订单在满足充电门槛、时间段、车牌等条件时，会自动向 qcyun 下发停车优惠。

## 配置目标

一个站点要能发 qcyun 停车优惠，需要同时具备三类数据：

1. 停车场平台配置：qcyun 分配的车场、机构、密钥等参数。
2. 站点绑定关系：站点绑定到哪一条停车场平台配置。
3. 停车优惠规则：该站点满足什么条件后发什么优惠。

## 一、停车场平台配置

数据表：`thirdparty_parking_config`

该表记录停车场平台的接口参数。qcyun 多站点配置的核心是：不同站点可以绑定不同的 `thirdparty_parking_config.id`。

| 字段 | 是否必填 | qcyun 配置说明 |
| --- | --- | --- |
| `id` | 新增后记录 | 停车场配置主键，后续站点通过 `pile_station_info.parking_id` 绑定它。 |
| `parking_name` | 建议填 | 停车场/商户名称；qcyun 发券时如果没有站点名称，会作为 `storeName` 备用值。 |
| `platform_type` | 是 | qcyun 固定填 `3`。 |
| `secret_key` | 是 | qcyun 分配的签名密钥。 |
| `org_id` | 是 | qcyun 分配的机构 ID。 |
| `park_id` | 是 | qcyun 分配的车场 ID。 |
| `api_url` | 建议填 | qcyun 接口地址；为空时使用配置文件 `parking.qcyuns.url`。 |
| `app_id` | qcyun 可不填 | 其他停车平台可能使用，qcyun 发券逻辑当前不使用。 |
| `parking_merchant_id` | qcyun 可不填 | 其他停车平台可能使用，qcyun 发券逻辑当前不使用。 |
| `coupon_id` | qcyun 可不填 | 其他停车平台可能使用，qcyun 发券逻辑当前不使用。 |
| `del_flag` | 是 | 正常数据填 `0`。 |

生产 qcyun 默认接口地址：

```text
https://g.qcyuns.com/park-data-api/data/centre/api/v1
```

测试 qcyun 默认接口地址：

```text
http://test-gateway.qcyuns.com/park-data-api/data/centre/api/v1
```

示例：

```sql
insert into thirdparty_parking_config (
    parking_name,
    platform_type,
    secret_key,
    org_id,
    park_id,
    api_url,
    create_time,
    create_by,
    del_flag
) values (
    '示例站点停车场',
    '3',
    'QCYUN_SECRET_KEY',
    'QCYUN_ORG_ID',
    'QCYUN_PARK_ID',
    'https://g.qcyuns.com/park-data-api/data/centre/api/v1',
    now(),
    'admin',
    '0'
);
```

系统现有代码提供停车平台列表查询和站点绑定接口。如果没有停车场配置维护页面，可以通过数据库脚本先写入 `thirdparty_parking_config`，再把生成的 `id` 绑定到站点。

## 二、站点绑定停车场配置

数据表：`pile_station_info`

| 字段 | 是否必填 | 说明 |
| --- | --- | --- |
| `id` | 是 | 站点 ID。 |
| `parking_id` | 是 | 绑定 `thirdparty_parking_config.id`。 |

后台接口：

```http
POST /pile/station/bindParkingPlatform
```

请求体：

```json
{
  "stationId": "站点ID",
  "parkingId": "thirdparty_parking_config.id"
}
```

等价 SQL：

```sql
update pile_station_info
set parking_id = '停车场配置ID'
where id = '站点ID';
```

注意：一个站点当前只绑定一个 `parking_id`。如果多个站点使用不同 qcyun 车场，需要分别新增多条 `thirdparty_parking_config`，再让各站点绑定各自的配置。

## 三、站点停车优惠规则

数据表：`charge_parking_discount`

该表按站点保存“达到什么充电条件后，发放什么停车优惠”。

| 字段 | 是否必填 | 说明 |
| --- | --- | --- |
| `station_id` | 是 | 站点 ID。 |
| `parking_platform_id` | 是 | qcyun 固定填 `3`。 |
| `condition_type` | 是 | 发券门槛类型：`1` 固定电量；`2` 固定时长。 |
| `condition_value` | 是 | 门槛值。`condition_type=1` 时表示充电度数；`condition_type=2` 时表示充电时长，单位分钟。 |
| `discount_type` | 是 | 优惠类型：`1` 减时间；`2` 减金额。 |
| `discount_value` | 是 | 优惠值。`discount_type=1` 时单位分钟；`discount_type=2` 时单位元，系统发给 qcyun 前会转成分。 |
| `start_time` | 是 | 优惠生效开始时间，例如 `00:00:00`。 |
| `end_time` | 是 | 优惠生效结束时间，例如 `23:59:00`。支持跨天判断。 |
| `del_flag` | 是 | 正常数据填 `0`。 |

示例：站点充电满 10 度后，减免 120 分钟停车费。

```sql
insert into charge_parking_discount (
    station_id,
    parking_platform_id,
    condition_type,
    condition_value,
    discount_type,
    discount_value,
    start_time,
    end_time,
    create_time,
    create_by,
    del_flag
) values (
    '站点ID',
    3,
    '1',
    '10',
    '1',
    '120',
    '00:00:00',
    '23:59:00',
    now(),
    'admin',
    '0'
);
```

示例：站点充电满 30 分钟后，减免 10 元停车费。

```sql
insert into charge_parking_discount (
    station_id,
    parking_platform_id,
    condition_type,
    condition_value,
    discount_type,
    discount_value,
    start_time,
    end_time,
    create_time,
    create_by,
    del_flag
) values (
    '站点ID',
    3,
    '2',
    '30',
    '2',
    '10',
    '00:00:00',
    '23:59:00',
    now(),
    'admin',
    '0'
);
```

建议同一个 `station_id` 只保留一条 `del_flag = '0'` 的有效优惠规则。后台查询按 `station_id` 取规则，多条有效规则可能导致查询异常或规则不确定。

## 四、发券生效条件

订单自动下发 qcyun 停车优惠时，会依次检查：

1. 订单有车牌号：`order_basic_info.plate_number` 不能为空。
2. 站点存在停车优惠规则：`charge_parking_discount.station_id = 订单 station_id` 且 `del_flag = '0'`。
3. 订单创建时间在 `start_time` 到 `end_time` 的优惠时间段内。
4. 订单充电度数或充电时长达到 `condition_type/condition_value` 配置的门槛。
5. 该订单没有发过券：`car_coupon_record.order_code` 不存在有效记录。
6. 优惠规则的平台是 qcyun：`parking_platform_id = 3`。
7. 站点绑定的停车场配置存在，并且 `platform_type = '3'`。
8. qcyun 配置里的 `park_id`、`org_id`、`secret_key` 不为空。

满足以上条件后，系统会先向 qcyun 查询车辆停车信息，再调用 qcyun 商家减免接口。发券成功后，会写入 `car_coupon_record`。

## 五、配置完成后的检查清单

配置新站点后，建议逐项确认：

| 检查项 | 期望结果 |
| --- | --- |
| `thirdparty_parking_config` 有 qcyun 配置 | `platform_type = '3'`，`del_flag = '0'`。 |
| qcyun 鉴权参数完整 | `park_id`、`org_id`、`secret_key` 均不为空。 |
| 站点已绑定停车场配置 | `pile_station_info.parking_id = thirdparty_parking_config.id`。 |
| 站点有优惠规则 | `charge_parking_discount.station_id = 站点ID`，`parking_platform_id = 3`，`del_flag = '0'`。 |
| 优惠时间正确 | `start_time/end_time` 覆盖订单创建时间。 |
| 门槛值正确 | 订单充电度数或时长能达到配置门槛。 |
| 订单有车牌 | 否则不会发券。 |
| 没有重复发券记录 | 同一订单已有 `car_coupon_record` 时不会重复发券。 |

## 六、常见问题

### 1. 已配置但没有发券

优先检查订单是否有车牌、是否满足充电门槛、订单创建时间是否在优惠时间段内，以及 `charge_parking_discount.parking_platform_id` 是否为 `3`。

### 2. 日志提示“站点未绑定停车场配置”

说明 `pile_station_info.parking_id` 为空，或绑定的 `thirdparty_parking_config` 不存在/已删除。

### 3. 日志提示“站点绑定的停车平台类型不是 qcyun”

说明 `thirdparty_parking_config.platform_type` 不是 `3`。qcyun 配置必须填 `3`。

### 4. 日志提示“停车场配置缺少 parkId/orgId/secretKey”

补齐 `thirdparty_parking_config.park_id`、`org_id`、`secret_key`。

### 5. 一个 qcyun 停车场能否绑定多个站点

可以。多个站点的 `pile_station_info.parking_id` 可以绑定同一条 `thirdparty_parking_config.id`。

### 6. 一个站点能否绑定多个 qcyun 停车场

当前不支持。一个站点只有一个 `parking_id`，只能绑定一条停车场配置。