データ資産化 — Provenance / Source Weight / Owner 承認フロー Data asset — Provenance / Source weight / Owner approval flow

Parky は駐車場データを 11 種類のソース（owner / admin / field / ugc / akippa / navitime / google / osm / kokudo / jichitai / import）から取り込みます。Phase 0 (2026-05-04 dev DB apply 済) で field 単位の provenance モデルを導入し、駐車場の各属性ごとに「誰が・いつ・どこから」入れた値かを記録できる構造に切り替えました。本ページは社内エンジニア向けに、provenance / source_weight / Owner 承認フロー / Raw landing zone / ハウスキーピング / バックアップを横断的にまとめます。

Parky ingests parking-lot data from 11 sources (owner / admin / field / ugc / akippa / navitime / google / osm / kokudo / jichitai / import). Phase 0 (applied to dev on 2026-05-04) introduced field-level provenance: every attribute is recorded with who supplied it, when, and from which source. This page is an internal engineering reference covering provenance, source_weight, the owner approval flow, the raw landing zone, housekeeping, and backups.

1. 全体構造1. Architecture overview

Phase 0 では parking_lots テーブルを VIEW にリネーム し、その背後に canonical identity テーブル parking_lots_master + provenance ログ parking_field_values を置きました。INSTEAD OF triggers で透過動作させているため、API 層の SQL (FROM public.parking_lots) は無改修で動きます。

Phase 0 turned parking_lots into a VIEW backed by a canonical identity table (parking_lots_master) and a provenance log (parking_field_values). INSTEAD OF triggers make this transparent — existing API SQL (FROM public.parking_lots) keeps working unchanged.

flowchart LR
  subgraph CLIENT["Client / API"]
    A[FROM public.parking_lots]
  end
  subgraph VIEW["VIEW layer (透過)"]
    V["parking_lots (VIEW)
INSTEAD OF triggers"]
  end
  subgraph CORE["Core tables"]
    M["parking_lots_master
canonical identity
(id / code / status /
location / shape_type)"]
    F["parking_field_values
provenance log
(field_name / source /
captured_at / priority_score)"]
    C["parking_field_confirmations
UGC 補強"]
  end
  subgraph SEARCH["Search layer"]
    S["parking_search_v (MV)
field_values primary を pivot"]
  end
  subgraph INGEST["Raw landing zone"]
    R["parking_ingest_runs"]
    P["parking_ingest_payloads"]
  end

  A ==> V
  V -->|read| M
  V -->|read primary| F
  V -->|INSTEAD OF INSERT/UPDATE| M
  V -->|INSTEAD OF INSERT/UPDATE| F
  F --> C
  M --> S
  F --> S
  R --> P
  P -->|upsert_ingest_payload| F

2. parking_field_values テーブル2. The parking_field_values table

Phase 0 の中心。(parking_lot_id, field_name, source, captured_at) を 1 行として、駐車場 1 属性につき複数 source の値が時系列で蓄積されます。

The heart of Phase 0. One row per (parking_lot_id, field_name, source, captured_at) tuple — multiple values per attribute, accumulated chronologically.

UNIQUE INDEX idx_pfv_primary ON (parking_lot_id, field_name) WHERE is_primary AND deleted_at IS NULL で、同 (lot, field) で primary が 1 行のみであることを物理保証します。

A partial UNIQUE INDEX (idx_pfv_primary) physically enforces "one primary row per (lot, field) where not deleted."

3. data_source ENUM と source_weight3. data_source ENUM and source_weight

どのソース由来の値を信頼するかは source_weight で表現します。実装は public.calc_priority_score(source data_source, captured_at timestamptz, confirms_n int) RETURNS double precision 関数。

How much we trust each source is encoded in source_weight, materialized in public.calc_priority_score(source, captured_at, confirms_n) RETURNS double precision.

4. priority_score の計算4. priority_score calculation

calc_priority_score は 3 要素を線形合成します。係数は dev DB 側で調整可能 (将来 displacement batch でチューニング)。

calc_priority_score linearly combines three signals. Coefficients are tunable on dev DB (will be tuned via the displacement batch later).

priority_score
  = 1.00 * source_weight(source)             -- 0.25 .. 1.00
  + 0.30 * recency_factor(captured_at)       -- 0.0 .. 0.3 (90 日 half-life の指数減衰)
  + 0.15 * confirm_factor(confirms_n)        -- 0.0 .. 0.15 (log scale, cap 5)

同点処理: priority_score 同点は captured_at DESC で勝負。それでも引き分けなら最後に書き込んだ行が primary に。

Tie-breaks: ties on priority_score fall back to captured_at DESC; further ties go to the most recent insert.

5. is_primary の自動再計算5. is_primary auto-recompute

parking_field_values への INSERT / UPDATE で trg_pfv_recompute_primary が発火し、対象 (lot, field) の中から 承認済 (approved_at IS NOT NULL) かつ priority_score 最大の 1 行を is_primary=TRUE、それ以外を FALSE に書き換えます。未承認の owner / admin レコードは候補から除外されるため、Owner Portal で PATCH しても admin 承認まで公開値は変わりません。

Insert / update on parking_field_values triggers trg_pfv_recompute_primary, which picks the highest priority_score among approved rows and flips it to is_primary=TRUE (others to FALSE). Unapproved owner / admin rows are skipped — so an owner PATCH never moves the public value until admin approves.

6. Owner 承認フロー (parking_lots VIEW INSTEAD OF triggers)6. Owner approval flow (parking_lots VIEW INSTEAD OF triggers)

Owner 編集の挙動は 駐車場 status と caller の権限で分岐します。INSTEAD OF triggers (parking_lots_view_insert/update/delete) と provenance helper (parking_lots_view_provenance) で実装。

Owner edit behavior branches on lot status and caller role. Implemented in INSTEAD OF triggers (parking_lots_view_insert/update/delete) plus a provenance helper (parking_lots_view_provenance).

申請中の field を Owner Portal で表示するため、GET /v1/owner/parking-lots/mine/{lotId}/pending-fields endpoint が source='owner' AND approved_at IS NULL AND deleted_at IS NULL の行を返します。Portal 側は PublicationTab で「N 件の修正が運営審査中」と提示します。

For Owner Portal visibility, GET /v1/owner/parking-lots/mine/{lotId}/pending-fields returns rows with source='owner' AND approved_at IS NULL AND deleted_at IS NULL. The portal renders "N edits awaiting admin review" in PublicationTab.

7. Raw landing zone (Phase 0d)7. Raw landing zone (Phase 0d)

外部 API (akippa / navitime / google / osm 等) から取り込んだ生データを parking_field_values へ流し込む前段に parking_ingest_payloads として保管します。失敗時のリトライ、過去版の参照、新フィールド抽出のリプレイに使います。

External API ingests (akippa / navitime / google / osm / ...) land in parking_ingest_payloads before being projected into parking_field_values. Used for retry, historical lookup, and replay when extracting new fields.

• parking_ingest_runs — 1 batch 取り込みの metadata (source / started_at / finished_at / counts)
• parking_ingest_payloads — 1 件の raw payload (jsonb) + hash ベースの dedup + supersede chain
• bff_only.upsert_ingest_payload(...) — 取り込みの単位 RPC (run_id / external_id / hash で冪等)
• bff_only.start_ingest_run / finish_ingest_run — run lifecycle
• parking_ingest_payloads_active (VIEW) — superseded されていない最新版だけを返す

8. ハウスキーピング (Phase 0e)8. Housekeeping (Phase 0e)

Raw landing zone は何もしないと無限に肥大化するため、リテンション + プルーンを pg_cron で自動運用します。

The raw zone would grow unbounded — pg_cron handles retention + pruning.

全ハウスキーピング実行は infra.parking_ingest_housekeeping_log に行き先 (rows_examined / rows_deleted / parameters / triggered_by) と一緒に記録され、infra.parking_ingest_storage_v view でテーブルサイズと併せて監視できます。

Each housekeeping run is logged in infra.parking_ingest_housekeeping_log (rows_examined / rows_deleted / parameters / triggered_by). Combine with infra.parking_ingest_storage_v for table-size monitoring.

9. 検索層 (parking_search_v MV)9. Search layer (parking_search_v MV)

地図検索 / 一覧 API は parking_search_v (MATERIALIZED VIEW) を読みます。parking_lots_master + parking_field_values の primary を pivot した形で、ratings / hourly_rate も JOIN 済。setup_parking_search_v_refresh_cron() で pg_cron に REFRESH MATERIALIZED VIEW CONCURRENTLY が登録されます。

Map search and list APIs read parking_search_v (MATERIALIZED VIEW): a pivot of parking_lots_master + the primary parking_field_values, pre-joined with ratings and hourly_rate. setup_parking_search_v_refresh_cron() registers a pg_cron REFRESH MATERIALIZED VIEW CONCURRENTLY.

10. バックアップ (Phase 0g)10. Backups (Phase 0g)

Phase 0f (per-row R2 archive) は over-engineered として revert し、代わりに pg_dump → R2 → Wasabi の 3 拠点バックアップに統一しました。

Phase 0f (per-row R2 archive) was reverted as over-engineered, replaced with a unified pg_dump → R2 → Wasabi 3-vendor backup.

• Xserver cron 02:30 JST で scripts/ops/backup-supabase-to-r2.sh 実行 → db/parky-{prod|dev}/YYYY/MM/YYYY-MM-DD.dump として R2 (parky-archive bucket) に PUT
• 03:00 JST で scripts/ops/backup-r2-to-wasabi.sh が R2 → Wasabi (versioning ON / noncurrent 90 日 expire) に rclone copy
• 復元は scripts/db/restore-supabase-from-r2.sh --env prod --date 2026-04-01 --dry-run で dump 取得、本番 restore は別 DB へ

詳細運用は ops/db-backup-runbook.html。

Operational details in ops/db-backup-runbook.html.

11. 表で覚える Phase 0 の構成物11. Phase 0 inventory at a glance

12. 参考: 主要 RPC 一覧12. Reference: key RPCs

13. Phase 1 以降 (スコープ外 / 参考)13. Future phases (out of scope, for reference)

• Phase 1: OSM Overpass 取り込み / UGC submit/confirm API / displacement batch の recency 改良
• Phase 1: OSM Overpass ingest / UGC submit/confirm API / recency tuning in displacement batch
• Phase 2: NAVITIME / akippa 連携 / ownership_rate ダッシュボード / 実地調査ファイル取り込み
• Phase 2: NAVITIME / akippa partnerships / ownership_rate dashboard / field survey ingest
• Phase 3: B2B データ提供 (OSM 派生は除外、Parky 所有データのみ)
• Phase 3: B2B data delivery (OSM-derived data excluded, only Parky-owned)

Phase 0 で provenance / source_weight / Owner 承認フロー / Raw landing zone / ハウスキーピング / バックアップが揃ったため、Phase 1 以降は 新ソースの追加と新 ingestion script の実装 だけで済むはず、という設計判断になっています。

With Phase 0 in place — provenance, source_weight, owner approval flow, raw landing zone, housekeeping, backups — later phases should reduce to adding new sources and new ingestion scripts only.