ExplorationMaps

探査マップ

鉱物探査向けのブラウザベースのマップ作成ツールです。州の鉱区登録簿を検索し、掘削・地質データを取り込み、投資家向けのマップをスタイル設定して、PNG／SVG／PDF としてエクスポートできます。explorationmaps.com で公開中です。

技術スタック

• フロントエンド： React 18 + Vite 5 のシングルページアプリ（src/）、Leaflet マップエンジン
• バックエンド： Supabase（認証、Postgres、RLS）+ Vercel サーバーレス関数（api/）
• 静的マーケティングコンテンツ： public/ 配下に生成されるブログと会社ページ（scripts/generate-blog.js と scripts/pseo/ を参照）

要件

• Node 20+（Vite 5 の要件。開発／CI は Node 20／22 で検証済み）
• npm（package-lock.json がコミットされているため、再現性の高いインストールには npm ci を使用してください）

開発

npm ci                 # install exactly the locked dependencies
cp .env.example .env   # fill in the VITE_ variables (see below)
npm run dev            # Vite dev server on http://localhost:5173

api/ 配下のサーバーレス関数は Vercel 上で実行されます。フルスタックでローカル開発する場合は vercel dev を使用してください。npm run dev のみの場合、鉱区検索と分析のエンドポイントは利用できません（UI は適切に機能を縮退します）。

コマンド

コマンド	説明
npm run dev	Vite 開発サーバー
npm run build	ブログを生成し、dist/ にビルドして、管理シェルをコピーします
npm test	Vitest の実行（CI モード）
npm run test:watch	Vitest の監視モード
npm run pseo:fixture	フィクスチャデータを使って pSEO 会社ページのパイプラインを実行します

環境変数

.env.example に記載されています。概要：

公開用（VITE_ — クライアントバンドルにコンパイルされ、シークレットではありません）：

• VITE_SUPABASE_URL、VITE_SUPABASE_ANON_KEY — Supabase プロジェクトと匿名キー（本番環境で必須。設定されていない場合、認証／クラウド機能は無効になります）
• VITE_ADMIN_EMAIL — 管理ダッシュボードの表示のみを制御します。実際の認可はサーバー側で行われます（admin_users テーブル + is_admin()）

サーバー専用シークレット（Vercel に設定し、クライアントコードからは参照しません）：

• SUPABASE_SERVICE_ROLE_KEY — /api/track で分析データの取り込みに使用します。マイグレーション 20260710000004 の適用後は本番環境で必須です。
• ADMIN_API_SECRET — 任意。本番環境で x-admin-secret ヘッダーを使った鉱区 API の診断モードを有効にします。
• SUPABASE_URL / SUPABASE_ANON_KEY — 任意のサーバー側エイリアスです。api/claims.js（Quebec）と api/track.js は、フォールバックとして VITE_ 付きの値を使用します。
• STRIPE_SECRET_KEY、STRIPE_WEBHOOK_SECRET、STRIPE_PRICE_MONTHLY_ID、STRIPE_PRICE_YEARLY_ID — Pro サブスクリプションの課金に使用します（docs/billing.md を参照）。設定されるまでは、課金エンドポイントは 503 を返し、すべてのプランチェックはフェイルオープンになります。Stripe の設定前にコードを安全にデプロイできます。

アーキテクチャに関する注記

Tenure Monitor（/tenure-monitor）

保存済みの B.C. 鉱物権益ポートフォリオを監視します。各鉱区の good-to-date までの残日数、メール通知、変更検出、ワンクリックでのマップエディターへの引き継ぎに対応します。政府の取引に対しては読み取り専用で、ユーザーに代わって MTO にアクセスすることはありません。

• データ： DataBC の MTA_ACQUIRED_TENURE_SVW レイヤーのミラーです。GitHub Actions によって scripts/tenure-sync/ から読み込まれます（毎晩の全件同期と、1 日 2 回の対象指定同期）。政府からの応答が不完全または失敗した場合は書き込みを行わずに中止するため、州側で問題が起きた日でも保存済みのポートフォリオが損なわれることはありません。
• 通知： scripts/tenure-alerts/ で毎日実行されます。重複排除はアプリケーションロジックではなく、一意制約によって行われます。
• 期限は常に America/Vancouver で計算され（src/utils/tenureDates.js）、ブラウザーのタイムゾーンは使用されません。
• 開発者向けドキュメント：docs/tenure-monitor.md。ユーザー向けヘルプ：docs/tenure-monitor-help.md。

サーバーレス API（api/）

• api/claims.js — 複数州の鉱区申請検索プロキシ（BC WFS、ArcGIS の各州 ON/SK/MB/NL/YT、セルフホスト型 Supabase テーブル経由の Quebec）。正確な meta: { totalKnown, returned, truncated, pagesFetched, provider } を含む完全なページネーションに対応し、レート制限、CORS 制限、エラーのサニタイズを実施します。
• api/bc-claims.js — BC 専用の WFS プロキシ（近隣鉱区の bbox 検索と従来の検索）。
• api/tenure-search.js — B.C. の鉱業権登記簿をミラーリングした Exploration Maps を対象とする Tenure Monitor 検索（鉱業権番号、貼り付けたリスト、所有者名、クライアント番号、地図範囲、ジオメトリ）。匿名利用に安全で、レート制限を実施し、すべての応答でミラーの最終同期日時を示します。公開読み取りポリシーのもとで ANON キーを使って読み取り、サービスロールは決して使用しません。
• api/track.js — すべての分析データの取り込み（ページビュー、オンライン状況の ping、製品／検索イベント、ランディングページのクリック、リード）。イベント名の許可リスト、ペイロードのサイズ／深さ制限、セッション ID の形式を検証します。エッジヘッダーから位置情報を取得し（リクエスト本文からは取得しません）、検証済みの Supabase アクセストークンからユーザー ID を解決し、サービスロールで書き込み、IP ごとにレート制限を行います。SUPABASE_SERVICE_ROLE_KEY がない場合は受け付けて破棄し、分析機能によってアプリが停止することはありません。識別された自動ブラウザーは、書き込み前に破棄されます。管理者向けレポートでは管理者アカウントと内部用としてマークされたブラウザーも除外されます。管理ダッシュボードを開くとそのブラウザーがマークされ、?em_internal=1 と ?em_internal=0 で明示的に設定／解除できます。
• api/stripe-checkout.js / api/stripe-portal.js / api/stripe-webhook.js — Pro サブスクリプションの課金（Stripe Checkout、カスタマーポータル、public.user_plans を同期する署名検証済み Webhook）。ローンチ前からの既存アカウントのプランがダウングレードされることはありません。詳しくは docs/billing.md を参照してください。
• api/_lib/ — 共通ヘルパー（ページネーション、リクエストガード、esri→GeoJSON）。アンダースコア付きのパスは、Vercel がエンドポイントとして公開しないことを意味します。

共有マップ

共有リンクは /map/<id> 形式です。<id> はクライアントが生成する crypto.randomUUID()（122 ビットのランダムトークン）です。読み取りには get_shared_map(share_id) RPC を使用します。テーブルレベルの SELECT は取り消されているため、公開クライアントから shared_maps の内容を列挙することはできません。以前のリンクも引き続き機能します。ID は引き続き検索キーとして使われます。

認証と管理者

Supabase 認証（デフォルトはマジックリンク、パスワード認証も利用可能）。管理者権限は public.admin_users の行で管理され、SECURITY DEFINER のレポート関数内で is_admin() によって確認されます。すべての definer 関数では search_path が固定され、明示的な実行権限が付与されています。管理者を追加するには：

insert into public.admin_users (user_id, note)
select id, 'added by <you>' from auth.users where email = '<email>';

ローカルプロジェクトの保存

src/utils/projectStorage.js：プロジェクトと作業中の下書きは localStorage に保存され、deflate 圧縮（gz1: プレフィックス）、スキーマバージョン、決定論的なマイグレーションに対応しています。破損したレコードは .recovery キーに保持され（自動削除されません）、手動でエクスポート／破棄するヘルパーから確認できます。書き込みは構造化された結果を返すため、書き込みに失敗しても UI が成功を表示することはありません。サインイン時には、プロジェクトごとのステータスと再試行機能を使ってローカルプロジェクトをクラウドに移行します（src/utils/cloudMigration.js）。

インポート形式

CSV（Papa Parse による RFC 4180 対応。緯度／経度列を自動検出し、ボーリング孔の軌跡では方位角、傾斜角、長さにも対応）、GeoJSON（検証済み）、ZIP 圧縮されたシェープファイル、個別の .shp/.dbf/.prj/.shx セット（.prj を適用し、投影座標系のファイルは proj4 を使って WGS84 に再投影）、KML、KMZ（エントリー数、展開後のサイズ、パストラバーサルに上限を設定）、ジオリファレンス画像（ワールドファイルまたは手入力の境界座標を指定した .png/.jpg/.gif/.webp。緯度／経度または UTM に対応し、2048 px にリサンプリングしてプロジェクトに保存）。公開されているタイル（{z}/{x}/{y}）と WMS サービスは、Reference Overlays のレイヤーとして追加できます。

権利登録簿

カナダ：BC（WFS）、オンタリオ／サスカチュワン／マニトバ／ニューファンドランド・アンド・ラブラドール／ユーコン（公式 ArcGIS サービス）、ケベック（毎週同期される Supabase ミラー）。米国：西部 11 州の連邦 BLM MLRS 権利情報。VITE_ENABLE_US_CLAIMS の背後で提供されます。連邦の権利情報のみで、州が管理する権益は含まれません（アラスカ州の権利情報は含まれません）。境界は一般化された BLM の表現であり、法的な測量図ではありません。データソース、フィールドのマッピング、デプロイ後の検証チェックリストについては、docs/us-claims.md を参照してください。

データベースのマイグレーション

タイムスタンプ付きの追加型マイグレーションは supabase/migrations/ にあります。リポジトリのルートにある従来の supabase-*.sql ファイルは、手動で実行していた過去のセットアップスクリプトです。既存の本番環境の状態を記録したものであり、新しい変更は supabase/migrations/ のみに追加してください。

適用順序が重要です。2 つのマイグレーションはデプロイと連動しています。

手順	操作	タイミング
1	20260710000001_shared_map_lookup_rpc.sql	いつでも（追加型）
2	20260710000003_live_pings_read_lockdown.sql	いつでも（デプロイ済みアプリは live_pings を読み取りません）
3	20260710000005_admin_authorization.sql	いつでも（追加型。現在の管理者を登録します）
4	フロントエンドをデプロイし（get_shared_map と /api/track を使用）、Vercel に SUPABASE_SERVICE_ROLE_KEY を設定します	—
5	20260710000002_shared_maps_lockdown.sql	手順 4 の後のみ
6	20260710000004_analytics_ingest_lockdown.sql	手順 4 の後のみ

各マイグレーションのヘッダーには、ロールバック手順が記載されています。適用後、匿名クライアント、通常の認証済みユーザー、管理者として RLS を検証してください。検証クエリは ...000005 に含まれています。

20260901000001_shared_rate_limit.sql は追加型で、いつでも適用できます。ただし、適用されるまでは api/_lib/guard.js のインスタンス間レートリミッターに呼び出し先がないため、フェイルオープンとなり、インスタンスごとのレートリミッターのみが適用されます。また、リード行のチェックを反映するために、send-welcome エッジ関数も再デプロイする必要があります（supabase functions deploy send-welcome）。

デプロイとロールバック

main へのプッシュは Vercel 経由でデプロイされます（npm run build → dist/ と api/ 関数）。ロールバックするには、以前の Vercel デプロイを再デプロイします（即時に反映）。ロールバック対象のデプロイ後にデプロイ連動型のマイグレーションを適用していた場合は、そのマイグレーションのヘッダーにあるロールバック用 SQL も実行してください。

テスト

Vitest と React Testing Library を使用します（tests/、設定は vitest.config.js）。テスト範囲は、リグレッション防止を重視しています。保存／自動保存の競合状態、権利情報リクエストの順序制御／キャンセル、プロバイダーのページネーション、シェープファイルの投影と CSV／GeoJSON の解析、ストレージの障害／破損への対応、ローカルからクラウドへの移行の再試行、API の堅牢化、ArcGIS ジオメトリの変換、共有マップへのアクセスを検証します。