openydt-flow-park-access — 车辆进出场作业流程 (SOP)

CRITICAL：开始前 MUST 先用 Read 工具读取 [../openydt-shared/SKILL.md](../openydt-shared/SKILL.md)，了解认证 / profile / 签名 / 状态码 / 限速 / 安全等通用约定。本技能只讲“怎么把一辆车按真实物理流程弄进 / 弄出车场”的编排，不复述各命令的参数表——具体入参出参见各域技能。

何时用本技能（与域技能的分工）

• 用本技能：要把一辆车端到端进场或出场、模拟真实进出场、跑通整条链路、不确定先调哪个命令、或某一步报错不知如何接续。
• 用域技能（不要走本流程）：只查一条记录 / 在场车 / 锁车 / 只想调用某个单命令 → [[openydt-record]]（停车记录域）、[[openydt-device]]（设备域）、[[openydt-billing]]（缴费域）。

安全前提：进出场涉及写操作（补录、抓拍、校正、缴费、盘点），仅在 test 环境演练；每个写命令先 --dry-run 预览签名请求，确认后再加 --yes。详见 openydt-shared 的安全约定。

两个必须先理解的概念

1. 进场的两条路本质不同：

2. 通道放行模式（最反直觉的一点）： 抓拍进场里 correct-car-on-channel 校正成功 ≠ 车一定进场。是否真正进场取决于该通道的放行模式——若通道设了「严禁临时车进场」，校正后车也不会进车场。这是设计如此：抓拍链路严格按真实物理放行逻辑模拟。所以校正后务必复核是否真的在场（见下），不要假定校正完就进场了。

进场流程

先判断用哪条路：只是要让记录里有这辆车（强制） → (a) 补录；要演练真实抓拍识别校正过程 → (b) 抓拍。

(a) 补录进场（强制，车必进）

1. （可选）openydt parking check-channel-exist-car 确认通道当前是否已有车，避免重复补录。
2. openydt parking supplement-parking-record-in --yes：传 parkCode、carCode、enterTime、channelCode、carCodeType、carCodeColor、parkOrArea。响应返回新生成的 parkingCode。

> recordType / enterCarType 未传时 CLI 会按平台文档默认值自动补 1，无需手填。

1. 完成。补录是强制进场，记录立即生效。参数细节见 [[openydt-record]]。

(b) 抓拍进场（模拟真实物理流程，不保证进场）

1. 抓拍：openydt device channel-snap --yes（传 parkCode、channelCode），在进场通道触发一次抓拍。

> 前提：该通道有抓拍设备；否则返回 resultCode=908 找不到设备，换有设备的通道。

1. 判断车牌：看抓拍出的车牌是否就是目标车牌。

- 是目标车牌 → 进入第 3 步前的放行判断。 - 不是 → 校正：openydt parking correct-car-on-channel --yes（传 parkCode、channelCode、newCarNo=目标车牌、correctTime）。 > 若报「会话已过期」，说明该通道当前没有可校正的抓拍会话，需先成功 channel-snap 再校正。

1. 复核是否真的进场（关键）：用 openydt parking get-park-on-site-car（传 parkCodeList + enterTimeFrom/enterTimeTo，时间范围必填）查在场车。

- 在场 → 进场成功。 - 不在场 → 多半是该通道放行模式禁止临时车进场所致，校正不会让它进场；改用 (a) 补录，或换放行模式允许的通道。

出场流程

关键前提（最易踩坑）：correct-car-on-channel 在出口 ≠ 放车出场。 它只是「模拟出口设备抓到车、触发出场处理流程」。车是否真离场取决于 放行模式 × 缴费状态：
- 自动放行 + 已缴清 → 系统自动放行，车出场（后端约数秒内闭环到 leaveType=1）。
- 人工放行（或仍欠费）→ 车被拦住，correct 仍回 status=1 但车不出场，需另外开闸（见第 4 步）。
所以先把费缴清，再抓拍校正；correct 返回 status=1 不代表车走了，务必用 get-car-out-list/get-park-on-site-car 复核。

1. 查费：openydt trade get-park-fee（传 carCode + parkCode）。

- 看 data.shouldPayValue（单位：元，1 即 1.00 元，不是 1 分）；取 parkingCode、chargeDate、otherAttr 供缴费回传。 > 查费后 10 分钟内须完成缴费，令牌/账单否则失效。

1. 缴清费（先问后做）：shouldPayValue>0 时必须先缴清，否则自动放行也不会放车。

- 先询问用户「是否需要缴费？用什么支付方式？」——缴费是真实写操作，不要默默执行。 - openydt trade pay-park-fee --yes，回传 parkingCode、chargeDate、actPayCharge（缴清则 = shouldPayValue，单位元）、payOrigin、paymentMode、唯一 billCode。带券 0 元结算（actPayCharge=0 + 原样回传 otherAttr）见 [[openydt-billing]]。 - 缴清后复核 get-park-fee 的 shouldPayValue=0。

1. 出口抓拍 + 校正：

- openydt device channel-snap --yes（parkCode、channelCode=出口通道）→ 抓出「未识别NNNNN」。 - openydt parking correct-car-on-channel --yes（newCarNo=目标车 + correctTime）。 > 前提：该出口有抓拍设备，且通常需是进场通道配对的出口；否则 channel-snap 报 908 找不到设备。 > ⚠️ correct 偶发 resultCode=908 会话已过期：这是间歇性服务端故障（同一出口同一命令时成时败，疑似网关/后端会话一过性），不是 TTL、与快慢无关。遇到就重试或换时机，别据此断言"出场走不通"。

1. 复核 + 按需开闸：

- openydt parking get-car-out-list（carNo + leaveStartTime/leaveEndTime）查到 leaveType=1 且 get-park-on-site-car count→0 → 自动放行场，已闭环，结束。 - 若 correct 成功但车仍在场 → 多半是人工放行：调 openydt device op-gate --yes（parkCode、channelCode、opType=0 开、operator、operateTime）或云车场 openydt device cloud-open-gate --yes（channelId 数字ID、opType=0）放车，再复核出场记录。

关于盘点离场 inventory-car：⚠️ 对开放平台抓拍/补录进场的车是 no-op（返回 status=1 但车不离场、getInventoryRecord 无记录），不是可靠的出场兜底。物理出场优先走上面的「缴清 → 出口 snap+correct →（人工放行则开闸）」。

跨命令硬约束与失败速查

命令归属（参数见各域技能）

• 进场补录 / 校正 / 在场复核 / 盘点 → [[openydt-record]]
• 抓拍 channel-snap → [[openydt-device]]
• 查费 get-park-fee / 缴费 pay-park-fee → [[openydt-billing]]

进出场是跨域流程；单条命令的入参、出参、枚举值一律以上述域技能为准，本技能只负责把它们按正确顺序和约束串起来。