mirror of
https://codeup.aliyun.com/67c68d4e484ca2f0a13ac3c1/ydc/jsowell-charger-web.git
synced 2026-07-15 03:27:59 +08:00
添加qcyun停车优惠配置文档
This commit is contained in:
Guoqs
241
docs/qcyun停车优惠新站点配置指南.md
Normal file
241
docs/qcyun停车优惠新站点配置指南.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# 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`，只能绑定一条停车场配置。
|
||||
Reference in New Issue
Block a user