openydt-monthticket — 月票 / VIP 域 (ticket)

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

何时用本技能

当用户的诉求落在 月票 / VIP / 会员包月 / 特殊车辆(访客、黑名单)/ 车辆身份 业务时使用本技能,典型如:

• "给某车牌开通月票 / 续费 / 退费 / 取消月票"
• "新建一个月票类型 / 改月票类型 / 查月票类型详情"
• "查某车牌的月票记录 / 月票将过期 / 月票已售数量"
• "查车辆是不是 VIP / 查车主"、"月票冻结 / 解冻"
• "新增访客 VIP 组 / 黑名单 VIP 组的特殊车辆类型"

意图路由:

• 仅做查询(读) → 直接用对应 get-* 命令,无需 --yes。
• 涉及创建 / 修改 / 开通 / 续费 / 退费 / 取消 / 冻结(写) → 命令必须加 --yes(见下文每条标注)。
• 访客/黑名单的「名单成员」管理不在本域:访客用 openydt visitor,黑名单用 openydt blacklist,红名单用 openydt redlist（见 [[openydt-list]]）;但他们引用的「特殊车辆类型ID」由本域 add-special-car-type 创建并通过 get-special-car-type-list 查询。
• 临停实时算费不在本域，请用 [[openydt-billing]]（openydt trade get-park-fee）。

可用命令

命令格式:openydt ticket <use>。下表仅列 catalog 中 included 的命令(共 29 条)。

* 表示必填。写操作均通过 f.ConfirmWrite 拦截,执行时必须带 --yes,否则会被拒绝。
参数以 openydt ticket <cmd> --help 为准,有出入信 --help。

业务流程

月票闭环(创建类型 → 开通 → 续费/退费 → 查询)

务必把前序命令响应里的字段作为后续命令的入参,不要凭空编造 ID。

1. 创建月票类型 — openydt ticket add-online-month-ticket-type --yes(body 见下方示例)。

从响应取 data.monthTicketConfigId 作为「月票类型ID」。

1. 开通线上月票 — openydt ticket add-online-month-ticket --yes,用上一步的 monthTicketConfigId 填入 --month-ticket-config-id(或 body 的 monthTicketConfigId)。

从响应取 data.monthTicketId(月票订单id) 用于续费 / 退费 / 修改。

1. 续费 / 退费:

- 续费 — openydt ticket renew-online-vip-ticket --yes,用第 2 步的 monthTicketId 填 --month-ticket-id,并给新的 timePeriodList。 - 退费(取消)— openydt ticket cancel-online-vip-ticket --yes,用 monthTicketId + parkCode + refundPrice;或按类型批量取消 openydt ticket cancel-online-month-ticket-by-month-ticket-type --yes(用 monthTicketConfigId)。

1. 查询:

- 按类型/车场列表查 — openydt ticket get-online-month-ticket-list。 - 按车牌查 — openydt ticket get-online-month-ticket-by-car-card(用 carCode)。 - 单笔订单查 — openydt ticket get-online-vip-ticket(用 monthTicketId)。

💰 金额（originPrice/favorPrice/refundPrice/price）单位是元；开通/续费/扣减的 billCode/thirdpartyBillCode/thirdpartyIdentify 是幂等键——重试复用首次值、绝不新生成；收到 907 账单已同步 = 幂等命中、首次已开通，改查 get-online-vip-ticket 确认，不要再发。详见 [[openydt-shared]] 的 references/write-idempotency.md 与 references/result-reading-sop.md。

月票冻结 / 解冻

• 冻结需要月票订单id:先用 get-online-month-ticket-by-car-card 或 get-online-month-ticket-list 查到 monthTicketBillId(月票订单id)。
• 冻结 — openydt ticket apply-month-ticket-freeze --yes 或 openydt ticket freeze-month-ticket --yes(传 monthTicketBillId + frozenStartTime + frozenEndTime)。
• 解冻 — openydt ticket un-freeze-month-ticket --yes(传 monthTicketBillId)。

特殊车辆类型(供访客 / 黑名单复用)

• 用 openydt ticket add-special-car-type --yes 创建特殊车辆类型,vipGroupType=1 为访客VIP组、vipGroupType=2 为黑名单VIP组。
• 从响应取特殊车辆类型ID(也可用 openydt ticket get-special-car-type-list --vip-group-type 1 并传 --body '{"parkCodeList":["1ZS7H5PQH9"]}' 查询列表拿到ID;parkCodeList 和 vipGroupType 均为必填)。
• 该「特殊车辆类型ID」供 openydt visitor(访客)与 openydt blacklist(黑名单)在添加名单成员时作为入参复用,实现「类型在 ticket 域创建、名单成员在各自域管理」的闭环。

未一等化的 ticket 子特性（用 openydt api 兜底）

以下 ticket 域接口在 catalog 中可调用(callable)但未做成一等命令，无专属 openydt ticket 子命令；需要时用通用兜底 openydt api <cmd>（写操作必须 --yes，建议先 --dry-run 预览），body 照抄 catalog/catalog.json 的 sampleBody，详见 [[openydt-api-explorer]]：

• 月票预约/排队：bookOrCancelReservation(写)、checkMonthTicketAppointment、getMonthTicketAppointmentByCarCode / getMonthTicketAppointmentDetail / getMonthTicketAppointmentLineUp。

> ⚠️ getMonthTicketAppointmentPark(查月票预约可开通的车场)属 park 域，请用 openydt api getMonthTicketAppointmentPark 调用，见 [[openydt-park]]。

• 月票授权访客：addMonthTicketAuthorizeVisitor(写)、allowBuyMonthlyTicket(写)、cancelMonthTicketAuthorizeVisitorByCarNo / cancelMonthTicketAuthorizeVisitorById(写)、getMonthTicketAuthorizeVisitor / getMonthTicketAuthorizeVisitorHis。
• 月票证件规则：monthTicketCertifiRuleSave(写)、saveOrUpdateMonthTicketCretifi(写)、delMonthTicketCertifiRule(写)、getMonthTicketCertifiRuleList / getMonthTicketCertificateInfoList / getCertificateByInfo。
• 线下月卡（整套未一等化）：getMonthCard / pauseMonthCard(写) / recoverMonthCard(写) / refundMonthCard(写) / renewMonthCard(写)——线下月卡的查询/暂停/恢复/退费/续费，均用 openydt api <cmd> 调，body 见 catalog。
• VIP 类型扩展：addCusVipType(写) / editCusVipType(写) / getVipType / addVipTicket(写) / setVipChargeRule(写) / querySupportMonthTicketParkList——自定义 VIP 类型与计费规则，同样用 api 兜底。

示例

示例 parkCode/时间为文档化测试值（仅 test 环境；照抄 catalog 历史 sampleBody 会撞无效车场/过期有效期）。写操作建议先用 --dry-run 预览签名请求，确认后再 --yes；ID 类参数（monthTicketConfigId 等）须取自上一步响应，不要照抄示例值。

1. 新增线上月票类型(写,需 --yes)— 成功后从响应 data.monthTicketConfigId 取类型ID:

# 先 dry-run 预览
openydt ticket add-online-month-ticket-type --dry-run --body '{
  "parkCodes": "1ZS7H5PQH9",
  "ticketName": "测试月票类型01",
  "price": 10,
  "timePeriod": { "startTime": "2026-06-01 00:00:00", "endTime": "2026-06-30 23:59:59" }
}'
# 确认后实发
openydt ticket add-online-month-ticket-type --yes --body '{
  "parkCodes": "1ZS7H5PQH9",
  "ticketName": "测试月票类型01",
  "price": 10,
  "timePeriod": { "startTime": "2026-06-01 00:00:00", "endTime": "2026-06-30 23:59:59" }
}'

1. 用上一步的 monthTicketConfigId 开通线上月票(写,需 --yes):

# 先 dry-run 预览
openydt ticket add-online-month-ticket --dry-run --body '{
  "carNo": "粤EJW962",
  "billCode": "<全局唯一订单号,如 your-app-20260601-0001>",
  "parkCodes": "1ZS7H5PQH9,PTD2YBBZ",
  "originPrice": 10,
  "favorPrice": 5,
  "payMode": 4,
  "payModeRemark": "微信支付",
  "payOrigin": 7,
  "payOriginRemark": "智慧停车",
  "userName": "王五",
  "userPhone": "18000000000",
  "thirdpartyIdentify": "<第三方唯一标识,预约开通必填>",
  "monthTicketConfigId": "<取自上一步响应的 data.monthTicketConfigId>",
  "timePeriodList": [
    { "startTime": "2026-06-01 00:00:00", "endTime": "2026-06-30 23:59:59" }
  ]
}'
# 确认后实发(--yes)
openydt ticket add-online-month-ticket --yes --body '{
  "carNo": "粤EJW962",
  "billCode": "<全局唯一订单号,如 your-app-20260601-0001>",
  "parkCodes": "1ZS7H5PQH9,PTD2YBBZ",
  "originPrice": 10,
  "favorPrice": 5,
  "payMode": 4,
  "payModeRemark": "微信支付",
  "payOrigin": 7,
  "payOriginRemark": "智慧停车",
  "userName": "王五",
  "userPhone": "18000000000",
  "thirdpartyIdentify": "<第三方唯一标识,预约开通必填>",
  "monthTicketConfigId": "<取自上一步响应的 data.monthTicketConfigId>",
  "timePeriodList": [
    { "startTime": "2026-06-01 00:00:00", "endTime": "2026-06-30 23:59:59" }
  ]
}'

1. 按车牌查询线上月票(读,无需 --yes):

openydt ticket get-online-month-ticket-by-car-card --body '{
  "carCode": "粤EJW962",
  "buyMethod": 2,
  "ticketType": 1,
  "validStatus": 0,
  "startTime": "20260601000000",
  "endTime": "20261231235959",
  "pageNum": 1,
  "pageSize": 10
}'