openydt-list

openydt-list — ナンバーリスト管理ドメイン（blacklist / redlist / visitor）

重要：開始前に必ず Read ツールで ../openydt-shared/SKILL.md を読み込んでください（認証／profile／署名／ステータスコード／レート制限／セキュリティルール）。共有基盤を読まずにコマンドを実行しないでください。

このスキルを使うタイミング

駐車場のナンバーリストを管理する場合に使います。対象となる業務は次の3種類です。

• ブラックリスト（blacklist）：車両の入場を禁止する／高額料金を徴収する。「この車をブラックリストに入れて」「ブラックリストに追加」「ブラックリスト一覧を確認」「ブラックリストを解除」など。
• ホワイトリスト（redlist）：通行許可のルールで、無料／優先通行が可能です。「ホワイトリストに追加」「パトカーを通行可能に」「ホワイトリストのルール」「通行許可ルールを削除」など。
• 訪問者（visitor）：一時的な訪問を登録し、時間制限付きで通行を許可します。「訪問車両を登録」「訪問者の通行を許可」「訪問予約をキャンセル」など。

意図のルーティング：

• 「ブラックリストに追加／ブラックリストに入れる／ブラックリストを確認／ブラックリストを解除」→ openydt blacklist ...
• 「ホワイトリストに追加／ホワイトリストのルール／ホワイトリストを削除」→ openydt redlist ...
• 「訪問者を登録／訪問者をキャンセル」→ openydt visitor ...
• 「特殊車両タイプを作成／VIP グループ」→ openydt ticket add-special-car-type（前提手順。「業務フロー」を参照。詳細は [[openydt-monthticket]]）

注意：このスキルのコマンドは blacklist / redlist / visitor の3つのサブコマンドドメインに分かれており、呼び出し時のプレフィックスもそれぞれ異なります。

使用可能なコマンド

日本語名	コマンド	読み取り／書き込み	主要パラメーター
ブラックリスト車両を追加	openydt blacklist add-black-list-car	書き込み	--park-code --special-car-type-id --car-code --car-owner --reason（すべて必須）
ブラックリスト車両一覧を照会	openydt blacklist get-park-black-list	読み取り	--body(parkCodeList 必須) / --car-code --owner --page-size --page-num
ブラックリスト車両を解除	openydt blacklist remove-black-list-car	書き込み	--park-code（必須） --blacklist-id / --car-no（いずれか一方）
ホワイトリストルールを追加	openydt redlist red-list-add	書き込み	--redlist-param --park-code-list（必須）--plate-color --operator --remark
ホワイトリストルールを照会	openydt redlist get-red-list	読み取り	--park-code-list（必須）
ホワイトリストルールを削除	openydt redlist del-red-list	書き込み	--rule-id（必須、照会結果から取得）
訪問車両を追加	openydt visitor add-visitor-car-new	書き込み	--park-code --car-no --owner --special-car-type-id --visit-from --visit-to（すべて必須）
訪問車両をキャンセル	openydt visitor cancel-visitor-car-new	書き込み	--park-code（必須） --visitor-id / --car-no（いずれか一方）

すべての書き込み操作（add/remove/del/cancel）には、確認のため --yes を追加してください。読み取り操作（get-*）には --yes は不要です。

業務フロー

ブラックリストへの登録／訪問者登録には、事前に「特殊車両タイプ」が必要です。その specialCarTypeId は後続コマンドの必須パラメーターです。以下が一連の手順です。必ず前のコマンドの応答に含まれるフィールドを、後続コマンドのパラメーターとして使用してください。

1. 特殊車両タイプを作成（前提手順。ticket ドメイン） openydt ticket add-special-car-type --yes

   • ブラックリストには vipGroupType=2、訪問者には vipGroupType=1 を使用します。
   • 応答から取得する specialCarTypeId は、ステップ2の必須パラメーターです（ブラックリスト --special-car-type-id／訪問者 --special-car-type-id）。

2. 車両を登録（ステップ1の specialCarTypeId ＋ナンバープレート＋parkCode を使用）

   • ブラックリスト：openydt blacklist add-black-list-car --yes
   • 訪問者：openydt visitor add-visitor-car-new --yes

3. 照会して確認

   • ブラックリスト：openydt blacklist get-park-black-list を実行し、返された一覧から blacklistId を取得します。これはステップ4で正確に解除するために使います。
   • ホワイトリスト：openydt redlist get-red-list を実行し、応答から ruleId を取得します。これは del-red-list で使用します。

4. 削除／キャンセル

   • ブラックリスト：openydt blacklist remove-black-list-car --yes（ステップ3の --blacklist-id を使用するか、--car-no のみを指定してそのナンバープレートのブラックリスト登録をすべて解除します）
   • 訪問者：openydt visitor cancel-visitor-car-new --yes（--visitor-id を使用するか、--car-no のみを指定して最新の訪問登録をキャンセルします）
   • ホワイトリストルール：openydt redlist del-red-list --yes --rule-id <ステップ3のruleId>

ホワイトリストルールは比較的独立しており、特殊車両タイプは不要です。openydt redlist red-list-add で直接追加できます（単一ナンバープレート、または *警 のようなワイルドカードルールに対応）。

書き込みの冪等性と確認

• add-black-list-car／add-visitor-car-new で同じナンバープレートを繰り返し送信した場合、プラットフォームはナンバープレートで重複排除します（同じナンバープレートを繰り返しブラックリストに追加しても、新しい項目は作成されません）。初回の操作が反映されたか不明な場合は、先に get-park-black-list で確認してください。
• ⚠️ remove-black-list-car／cancel-visitor-car-new で --car-no のみを指定し（ID を指定せずに）実行すると、そのナンバープレートに該当する項目がすべてキャンセルされます。一括操作となるため、実行前に get-park-black-list で対象範囲を確認し、照会で取得した blacklistId／visitorId を使って正確にキャンセルすることを優先してください。

PII：--phone／--car-no は PII です。prod では実際の値を記録しないでください（[[openydt-shared]] を参照）。特殊車両タイプの作成については [[openydt-monthticket]] を参照してください。

エラー発生時のクイックリカバリー（ブラックリスト／ホワイトリスト／訪問者）

現象	意味	復旧操作
ブラックリストへの追加に失敗 status=7／resultCode=909	specialCarTypeId が指定されていない／この駐車場のものではない／タイプが一致しない	まず openydt ticket get-special-car-type-list でこの駐車場のタイプ ID を確認し、vipGroupType=2 であることを確認してからブラックリストに追加します
訪問者の登録に失敗 status=2	specialCarTypeId がブラックリストタイプ（vipGroupType=2）である、または認証されていない	訪問者タイプ（vipGroupType=1）の specialCarTypeId を使用していることを確認します
ブラックリスト／訪問者をキャンセルした後も反映されていないように見える	--car-no のみを指定したが、プラットフォーム側の照会に遅延がある	1～2秒待ってから get-park-black-list で再確認します。同じナンバープレートの項目が複数ある場合は、--blacklist-id を使って正確にキャンセルします
get-park-black-list の結果が0件	駐車場にブラックリストがない または parkCodeList がすべて指定されていない	parkCodeList が正しいことを確認してから、「ブラックリストなし」と判断します。[[openydt-shared]] の結果解釈 SOP を参照してください

共通のステータスコードと再試行ルールについては [[openydt-shared]] を参照してください。結果の三層判定については、同ドキュメントの ../openydt-shared/references/result-reading-sop.md を参照してください。

示例

下列 parkCode/时间为文档化测试值（仅 test；1ZS7H5PQH9/PTD2YBBZ 为测试车场，生产环境替换为授权车场）。写操作建议先 --dry-run 预览、确认后再 --yes。

1. 添加一条黑名单车辆（写，需 --yes；special-car-type-id 来自 add-special-car-type 的响应）：

openydt blacklist add-black-list-car --yes \
  --park-code 1ZS7H5PQH9 \
  --car-code 粤EJW962 \
  --car-owner 车主 \
  --reason 原因 \
  --special-car-type-id 253

2. 查询某停车场黑名单列表（读，免 --yes，用 --body 传 parkCodeList 数组）：

openydt blacklist get-park-black-list \
  --body '{"parkCodeList":["1ZS7H5PQH9"],"carCode":"粤EJW962","pageNum":1,"pageSize":10}'

3. 新增白名单放行规则（写，需 --yes，park-code-list 为数组用 --body）：

openydt redlist red-list-add --yes \
  --body '{"parkCodeList":["1ZS7H5PQH9","PTD2YBBZ"],"redlistParam":"粤EJW962"}'

4. 登记访客车辆（写，需 --yes；special-car-type-id 来自访客类型的 add-special-car-type 响应）：

openydt visitor add-visitor-car-new --yes \
  --park-code PTD2YBBZ \
  --car-no 粤EJW962 \
  --owner 李四 \
  --phone 13800000000 \
  --reason 访友 \
  --visit-from 20260601000000 \
  --visit-to 20260602000000 \
  --special-car-type-id 154