openydt-data

openydt-data — データ分析ドメイン（data）

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

このスキルを使用する場面

ユーザーが駐車場の読み取り専用データ分析とレポート統計を必要とする場合に、このスキルを使用します。たとえば、特定の駐車場の決済請求明細／請求集計を調べる、車両流量やナンバープレートの上位分布を見る、駐車場のリアルタイム駐車データを読み取る、当日の出庫回数や取引回数を集計する、分単位の車両流量曲線を見る、駐車スペースの利用状況を分析する（echart ヒートマップを含む）、駐車時間の分布を分析する場合です。

意図のルーティング：

• 請求／決済明細が必要 → get-bill-summary。請求集計指標が必要 → get-park-bill。
• 車両流量曲線／傾向が必要 → 全区間を分単位で取得する場合は get-traffic-flow。ナンバープレートの上位分布には get-car-traffic-flow-analysis を使用します。
• リアルタイム／当日のデータが必要 → リアルタイム駐車データには get-real-time-park-info。当日の出庫回数と取引回数には get-realtime-leave-and-charge-num を使用します。
• 駐車スペースの利用状況が必要 → リストデータには parking-place-used。echart ヒートマップの描画には parking-place-used-for-echart を使用します。
• 駐車時間の分布が必要 → parking-time-analyse。
• 決済の実行や駐車場の設定確認が必要な場合は、[[openydt-billing]]（trade 決済）または [[openydt-park]]（駐車場情報）を使用してください。
• 車両ごとの明細／駐車中の車両／入出庫記録が必要な場合は、[[openydt-record]]（parking 記録／駐車中）を使用してください。
• 月極券／クーポン／デバイス／ブラックリスト・ホワイトリスト／来訪者などについては、[[openydt-monthticket]] ／ [[openydt-coupon]] ／ [[openydt-device]] ／ [[openydt-list]] を使用してください。

使用可能なコマンド

日本語名	コマンド	読み取り／書き込み	主なパラメーター
特定の駐車場の決済請求情報を取得	openydt data get-bill-summary	読み取り	parkCode, dimension(0日/1月/2年/3カスタム), startTime, endTime, pageNum, pageSize
車両流量のナンバープレート上位分布を取得	openydt data get-car-traffic-flow-analysis	読み取り	parkCodeList(駐車場コード一覧 JSONArray)
特定の駐車場の請求集計情報を照会	openydt data get-park-bill	読み取り	parkCode, dimension(0日/1月/2年), startTime, endTime, pageNum, pageSize
駐車場のリアルタイムデータを取得	openydt data get-real-time-park-info	読み取り	parkCode
駐車場の当日の出庫回数・取引回数を取得	openydt data get-realtime-leave-and-charge-num	読み取り	parkCode
単一駐車場の分単位の車両流量を取得	openydt data get-traffic-flow	読み取り	parkCode, startTime, endTime(間隔≤1日、形式 yyyy-MM-dd HH:mm)
駐車スペースの利用状況データを取得	openydt data parking-place-used	書き込み（--yes が必要）	parkCode, startDate, endDate(yyyyMMddHHmmss), minuteInterval(10 または 240)
駐車スペースの利用状況データを取得（echart ヒートマップ）	openydt data parking-place-used-for-echart	書き込み（--yes が必要）	parkCode, startDate, endDate(yyyyMMddHHmmss), minuteInterval(10 または 240)
駐車場の駐車時間分析データを取得	openydt data parking-time-analyse	書き込み（--yes が必要）	parkCode, startDate, endDate(yyyyMMddHHmmss), vipType(1臨時車/2月極車), hourArea

説明：parking-place-used、parking-place-used-for-echart、parking-time-analyse は、プラットフォームの契約上、書き込みとしてマークされています。呼び出し時は必ず --yes を付けて確認してください。付けない場合、書き込み操作の確認によって処理がブロックされます。それ以外のコマンドはすべて読み取り専用で、--yes は不要です。

業務フロー

データ分析ドメインでは、すべて駐車場単位の読み取り専用／統計クエリを行います。主要な入力パラメーターは parkCode（駐車場番号／コード）です。代表的な分析フローを以下に示します。先行コマンドのレスポンスに含まれるフィールドを、後続コマンドの入力パラメーターとして使うことが重要です。

1. 対象の駐車場 parkCode を特定する：parkCode は駐車場ドメインのコマンド（openydt park／openydt parking の一覧／検索インターフェースなど）のレスポンスフィールド、またはユーザー／上流システムから取得します。まず parkCode を取得し、それをこのドメインのすべてのコマンドの --park-code に指定してください。
2. 簡易チェック（リアルタイム状況）：get-real-time-park-info（リアルタイム駐車中／駐車スペース）と get-realtime-leave-and-charge-num（当日の出庫回数、取引回数）を使って当日の概要を取得し、駐車場にデータがあること、番号が正しいことを確認します。
3. 車両流量の分析：
   • 単一駐車場の分単位の曲線：get-traffic-flow を使用します。startTime／endTime の間隔は1日を超えてはいけません（形式は yyyy-MM-dd HH:mm）。
   • 複数駐車場のナンバープレート上位分布：get-car-traffic-flow-analysis を使用し、複数駐車場の parkCode を parkCodeList 配列にまとめて渡します。
4. 請求の分析：まず get-park-bill を使って請求集計指標を確認します（dimension で日／月／年を選択）。明細を1件ずつ確認する必要がある場合は、その後 get-bill-summary を使用します（dimension はカスタム期間の 3 に対応）。どちらもページネーションに対応しています（pageNum／pageSize、pageSize は最大 1000 件）。
5. 駐車スペースと駐車時間の分析（書き込み確認が必要、--yes が必要）：
   • 駐車スペースの利用状況：parking-place-used（リスト）／parking-place-used-for-echart（ヒートマップの座標データ）。minuteInterval は 10 または 240 のみ指定できます。
   • 駐車時間の分布：parking-time-analyse を使用し、vipType（1 臨時車／2 月極車）と、駐車時間区間を表す hourArea（例：0-1,1-4,4-7,7-10,10-12,12-0）で区分します。
   • 上記コマンドの時間パラメーターは、yyyyMMddHHmmss のコンパクト形式です。手順 3／4 の yyyy-MM-dd 形式とは異なるため、区別してください。

フィールドの受け渡しの要点：上流の駐車場ドメインのレスポンスに含まれる parkCode → このドメインのすべてのコマンドの --park-code。ページネーション付きクエリですべてのデータを取得する場合は --all-pages --out <file>.ndjson を使用します。複数駐車場の分析では、各駐車場の parkCode を収集して、--body の parkCodeList 配列に渡します。

📖 結果の解釈：get-park-bill／get-bill-summary が返す金額フィールドの単位は「元」です。test 環境で多くの統計インターフェースが nodata を返すのは正常であり、駐車場にデータがないことを意味しません（prod に切り替えるか、対象の時間範囲に業務データがあることを確認してください）。3層での判定方法／空の結果については、[[openydt-shared]] の references/result-reading-sop.md を参照してください。

データ分析の必須ルール

• 請求などのページネーション付き明細が必要な場合は、--all-pages --out <file>.ndjson を使って一括エクスポートします。同一の駐車場、インターフェース、時間範囲の明細は一度だけ取得し、その後の指標計算ではローカルファイルを再利用します。
• 駐車時間、分位数、中央値、分布、複数テーブルの関連付け、重複排除、金額シナリオのシミュレーションなどに関わる計算では、必ずコードを作成して実際に実行してください。自然言語による暗算に頼ってはいけません。
• 計算成果物には、再実行と監査に備えて、少なくともスクリプト、入力ファイルまたは入力ファイルのハッシュ、入力件数、フィルター対象／異常件数、有効件数、主要指標の検証結果を残してください。

错误自愈速查（统计）

现象	含义	恢复动作
get-traffic-flow 报错/空	startTime/endTime 间隔 >1 天 或格式非 yyyy-MM-dd HH:mm	缩到 ≤1 天、改对格式
parking-place-used* 报错	minuteInterval 非 10/240	改为 10 或 240
返回 nodata	test 环境常态 / 时间窗无业务	换时间窗或 prod 核实，非接口故障

通用码/退出码/重试见 [[openydt-shared]]；金额单位=元、0 条≠无见其 references/result-reading-sop.md。

示例

示例 parkCode/时间为文档化测试值（仅 test）；照抄 catalog 历史 sampleBody 会撞无效车场/过期时间窗。

# 1) 查询某车场账单汇总（按年维度，只读，无需 --yes）
openydt data get-park-bill \
  --park-code 1ZS7H5PQH9 --dimension 2 \
  --start-time "2026-06-01 00:00:00" --end-time "2026-06-01 23:59:59" \
  --page-num 1 --page-size 10

# 2) 获取车流量车牌 top 分布（多场，用 --body 传 parkCodeList 数组，只读）
openydt data get-car-traffic-flow-analysis \
  --body '{"parkCodeList":["1ZS7H5PQH9","PTD2YBBZ"]}'

# 3) 获取车场停车时长分析数据（write 操作，先 --dry-run 预览再 --yes）
openydt data parking-time-analyse \
  --park-code PTD2YBBZ \
  --start-date 20260601000000 --end-date 20260601235959 \
  --vip-type 1 --hour-area "0-1,1-4,4-7,7-10,10-12,12-0" \
  --dry-run
# 确认无误后去掉 --dry-run 加 --yes 实发