Openydt Coupon

openydt-coupon — 电子券与商家域 (coupon)

CRITICAL：开始前 MUST 先用 Read 工具读取 ../openydt-shared/SKILL.md（认证 / profile / 签名 / 状态码 / 限速 / 安全规则）。未读共享基座不要执行任何命令。

何时用本技能

本技能覆盖电子券与商家域（coupon）：商家（trader）的创建与维护、电子券模板的创建、把券售卖给商家、给车辆发放电子券、查询券与商家信息、以及券的回收。车辆在停车场用电子券可抵扣部分或全部停车费。

意图路由：

• "新建一个商家 / 加个商户 / 录入商家账号" → openydt coupon create-trader（写，需 --yes）。
• "改商家信息 / 冻结商家 / 解冻 / 删除商家" → openydt coupon edit-trader / frozen-trader / delete-trader（写，需 --yes）。
• "查商家列表 / 看某个商家信息 / 校验商家账号密码" → openydt coupon get-trader-list / get-trader-info-by-trader-code / validate-trader-account-and-password。
• "建一个券模板 / 创建优惠券 / 建固定券" → openydt coupon create-coupon-template / create-coupon / create-fixed-coupon（写，需 --yes）。
• "把券卖给商家 / 售卖电子券" → openydt coupon sell-coupon（写，需 --yes）。
• "给这辆车发券 / 发放优惠券 / 按券编码发券 / 扫码发券" → openydt coupon send-coupon / send-coupon-by-coupon-code / sync-scan-coupon-qr-code（写，需 --yes）。
• "查这辆车有哪些券 / 已发放的券 / 可用券 / 券信息" → openydt coupon query-car-code-valid-coupon / query-usable-coupon / query-coupon。
• "回收这张券 / 退券 / 锁券 / 打印券" → openydt coupon cancel-coupon / lock-coupon / print-coupon（写，需 --yes）。

用券抵扣后的实际查费 / 缴费在 trade 域（openydt trade --help）；在场车确认在 parking 域（openydt parking --help）。

可用命令

所有写命令（create-trader / edit-trader / frozen-trader / delete-trader / create-coupon-template / create-coupon / create-fixed-coupon / sell-coupon / send-coupon / send-coupon-by-coupon-code / sync-scan-coupon-qr-code / print-coupon / lock-coupon / cancel-coupon）执行时必须加 --yes 确认，否则会被拦截。

本表未列、但属券域的可调用接口（如 couponFlow/thirdCoupon*/syncAutoCoupon、cityOperationCoupon 全族、getParkingPayCouponList/getUserCouponRecord），用 openydt api <cmd> --body '{...}' 调用（写操作 --yes、先 --dry-run）；详见 [[openydt-api-explorer]]。城市运营券模板创建示例见该技能。

业务流程

电子券闭环（建商家+建模板 → 售卖 → 发券 → 查询 → 回收）

逐步执行，务必把前序命令响应里的字段作为后续命令入参（商家编码 traderCode、券模板编码 traderCouponTemplateCode、销售账单 sellBillId、券唯一编号 couponSn），不要凭空构造：

1. 创建商家 + 创建券模板（写，均需 --yes）：

   openydt coupon create-trader --yes \
     --trader-name <商家名> --contact <联系人> --phone <手机号> \
     --park-code <车场编号> --login-account <账号> --password <密码>
   
   openydt coupon create-coupon-template --yes \
     --name <券名> --sell-from ... --sell-to ... --grant-from ... --grant-to ... \
     --valid-minute 60 --balance-type 0 --coupon-type 1 \
     --face-value 500 --original-price 600 --real-price 500 \
     --use-rule-from 0 --use-rule-to 1000
   

   • 从 create-trader 响应取商家编码 traderCode（也可用 get-trader-list 反查）→ 作为后续所有命令的 --trader-code；
   • 从 create-coupon-template 响应取券模板编码（商家券模板代码）→ 作为第 2 步 sell-coupon 的 --trader-coupon-template-code（也可用 query-coupon-template-by-coupon-code --code <模板代码> 核对）。

2. 售卖给商家（写，需 --yes）— 用第 1 步拿到的商家编码 + 模板编码：

   openydt coupon sell-coupon --yes \
     --trader-coupon-template-code <来自 create-coupon-template> \
     --trader-code <来自 create-trader> \
     --sell-num 100 --sell-money 0.01 --sell-time "2026-06-01 09:00:00"
   

   • 从 sell-coupon 响应取销售账单 sellBillId → 作为第 3 步 send-coupon 的 --sell-bill-id（也可用 query-usable-coupon --trader-code <traderCode> --sell-bill-id <id> 核对该批次可发放余量）。

3. 发放给车辆（写，需 --yes）— 用第 2 步拿到的 sellBillId + 商家编码：

   openydt coupon send-coupon --yes \
     --trader-code <来自 create-trader> \
     --sell-bill-id <来自 sell-coupon> \
     --car-code <车牌> --car-code-color 1
   

   也可按券编码发券：send-coupon-by-coupon-code --yes --coupon-code <券编码> --car-no <车牌>（--car-no 与 --card-no 不能同时为空）。发券前可先 check-coupon-whether-send-available --coupon-code <券编码> 确认是否可发。

4. 查询券（读）— 确认券已落到车辆 / 商家：

   openydt coupon query-car-code-valid-coupon --park-code <车场> --car-code <车牌>
   openydt coupon query-coupon --trader-code <traderCode> --query-type 1 --page 1 --page-size 10
   

   • 从查询响应取券唯一编号 couponSn → 作为第 5 步 cancel-coupon 的 --coupon-sn（按券编码反查商家用 query-trader-info-by-coupon-code --coupon-sn <couponSn>）。

5. 回收（写，需 --yes）— 用第 4 步取到的 couponSn + 商家编码：

   openydt coupon cancel-coupon --yes --trader-code <traderCode> --coupon-sn <来自 query>
   

💰 金额量纲：faceValue 量纲由 couponType 定：0=免费券、1/2/3=金额券(faceValue→元)、4=时间券(faceValue→分钟)、5=不同计价券；balanceType 是结算类型（0销售/1发放/2使用），不判券种。sellMoney/originalPrice/realPrice 单位元。 🔑 幂等：sell-coupon 的 transationNum、create-fixed-coupon 的 uniqNo 是去重键——重试复用同值，绝不新生成，避免重复售券/建券组。详见 [[openydt-shared]] 的 references/write-idempotency.md。 查券 0 条 ≠ 该车无券（确认 parkCode/时间窗给全），见 [[openydt-shared]] 的 references/result-reading-sop.md。

错误自愈速查（券域）

通用码见 [[openydt-shared]]。

示例

示例 parkCode/时间为文档化测试值（仅 test）；照抄 catalog 历史 sampleBody 会撞无效车场/过期有效期。写操作建议先把 --yes 换成 --dry-run 预览，尤其 delete-trader / cancel-coupon 等不可逆操作，确认后再 --yes。

创建商家（写操作；先 --dry-run 预览，确认后 --yes）：

openydt coupon create-trader --dry-run \
  --trader-name 测试商家 --trader-type 5 \
  --contact 联系人 --phone 13800000000 \
  --park-code 1ZS7H5PQH9 --login-account trader001 --password 123456
# 确认无误后改 --yes 实发

售卖电子券给商家（写操作，必须加 --yes；模板编码 / 商家编码取自前序响应）：

openydt coupon sell-coupon --yes \
  --trader-coupon-template-code GCSH3FI1YNDN \
  --trader-code NWTSZY49BH67 \
  --sell-num 100 --sell-money 0.01 --sell-remark 测试 \
  --sell-time "2026-06-01 09:00:00"

GCSH3FI1YNDN/NWTSZY49BH67 为占位值，取自前序响应；transationNum 是幂等键，重试复用首次值。

按车牌查询已发放电子券（读操作）：

openydt coupon query-car-code-valid-coupon --park-code PTD2YBBZ --car-code 粤B88888