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 默认接口地址：

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

测试 qcyun 默认接口地址：

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

示例：

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。

后台接口：

POST /pile/station/bindParkingPlatform

请求体：

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

等价 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 分钟停车费。

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 元停车费。

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，只能绑定一条停车场配置。