FIELDPIN — 要件定義書 兼 Claude Code 実装指示書

版数 1.0（DBレス構成 / 記事埋め込み型デモ）／ 作成日 2026-08-17 ／ 発行 ソウゾウ合同会社 用途 SEO記事「【デモで試せる】Claude Codeで位置情報アプリ（GPS）を開発する方法と費用｜動画つき資料【2026年】」に組み込む実演デモ

このドキュメントの使い方（Claude Code へ）

これ1枚が、規約・仕様・タスクのすべて。リポジトリ直下に CLAUDE.md として置き、毎回読み込むこと。

• 実装は「13. 実装タスク」の順に進める。フェーズを飛ばさない。
• 各タスクの括弧内は要件ID。着手前に該当章を読むこと。
• 仕様がここに書かれていない場合は、推測で実装せず質問する。
• スコープ外（4章 Won't have）は、思いついても実装しない。
• 「デモだから」を理由に品質を落とす判断はしない。

姉妹プロジェクトとの関係 HIREBASE（求人）／ RELATE（顧客管理）／ CASTA（動画配信）に続く4本目。並べて「同じテンプレ」と思われた時点で失敗。 HIREBASE＝明朝・白・余白（読ませる）／ RELATE＝ゴシック・白・高密度（操作させる）／ CASTA＝ダーク・映像優先（見せる）／ FIELDPIN＝地図が全画面・UIは上に浮く・屋外向けの大型UI（現場で使わせる）。 9章は意図的に第4の方向に振っている。トークンを流用しないこと。

目次

1. プロジェクト概要
2. 記事への組み込み設計
3. アーキテクチャ方針
4. スコープ定義
5. ロールとデモ切替
6. 画面一覧とユーザーフロー
7. 機能要件
8. データ設計
9. デザイン要件
10. 技術要件・ディレクトリ構成
11. 非機能要件・プライバシー
12. 費用設計
13. 実装タスク
14. 受入基準

1. プロジェクト概要

背景と目的

「位置情報アプリを作りたい」という相談の実体は、ほぼ次のいずれかに収まる。

• 訪問介護・配送・警備・設備保守など、現場に出るスタッフの訪問記録を正確に残したい
• 紙とLINEで回している現場報告をアプリにしたい
• GPS打刻で、直行直帰の勤怠を管理したい

一方で、この領域は「作ってみたら使えなかった」が最も多い分野でもある。原因は3つ。

1. 位置情報の権限を取れない／拒否されたときの設計がない
2. 屋内・地下・山間部でGPSが飛ぶことを前提にしていない
3. Webではバックグラウンド追跡ができないことを知らずに設計している

記事とデモの役割は、この3つに正面から答えること。「作れます」ではなく「Webでどこまでできて、どこからネイティブが要るか」を示せることが、この記事の専門性になる。

プロダクト定義

プロダクトコンセプト

「現場の手を止めない。地図の上で終わらせる。」

現場のスタッフはアプリを見るために来ているのではない。訪問先に着き、記録し、次へ向かう——この3動作が地図から離れずに完結すること。画面遷移を減らし、タップを大きくし、片手の親指の届く範囲にすべてを置く。

デモとしての成功条件

1. 記事の読者が、自分の現在地で試せる — スマホなら実GPS、PCならシミュレーションで同じ体験ができる
2. 権限を拒否しても壊れない — 拒否した状態でも、シミュレーションで全機能を体験できる
3. ジオフェンスが体感できる — 訪問先に近づくと自動でチェックイン候補が出る
4. 管理側も見られる — スタッフの現在地・訪問実績・軌跡を地図上で確認できる
5. 記事に戻れる／問い合わせできる — デモが行き止まりにならない

2. 記事への組み込み設計

この章が本プロジェクト固有の最重要要件。 そして、動画（CASTA）よりも制約が厳しい。

決定的な技術制約：iframe内でGPSは取れない

クロスオリジンの iframe では、Geolocation API は既定で拒否される。 親ページが allow="geolocation" を明示し、かつ親自身が権限を持っている必要がある。さらにブラウザによっては、iframe 内からの権限プロンプト自体が抑制される。

したがって、記事内の埋め込みで実GPSを取ろうとしてはいけない。 取れないか、取れても読者ごとに挙動が変わり、「動かないデモ」として記憶される。

配置方針（2段構え）

記事内は「勝手に動いて見せるショーケース」、別タブは「自分で試す本番」。役割をはっきり分ける。

埋め込みモード（?embed=1）

同一アプリを、URLパラメータで動作を変える。別リポジトリに分けない。

<iframe
  src="https://fieldpin.souzoh-demo.com/?embed=1&sim=tokyo-route-a"
  width="100%" style="aspect-ratio:16/10; border:0"
  loading="lazy"
  title="FIELDPIN 位置情報デモ（シミュレーション）"></iframe>

記事本体のパフォーマンスを壊さない

「動画つき資料」との一体化

記事タイトルの「動画つき資料」を別途用意せず、デモの体験を撮ったものにする。

• 動画：シミュレーションでの走行 → ジオフェンス通過 → 自動チェックイン → 管理画面での軌跡確認、までを 3分程度で収録
• 資料：本要件定義から抜粋した「Webで足りる／ネイティブが要る の判断表」と「地図タイル費用の計算シート」をPDF化
• デモ内の「資料をダウンロード」からも同じPDFを取得できるようにし、そこを問い合わせ導線に接続する

導線と計測

SEO上の扱い

3. アーキテクチャ方針

基本方針

バックエンドとデータベースを持たない。ただし位置情報の取得だけは実在させる。

位置情報だけは実在させる理由

「現在地を取得しました（東京駅）」と表示されるデモには、何の説得力もない。自分の今いる場所が地図に出ることが、このデモの成否そのもの。

ただし実在させるのは取得であって、送信ではない。取得した座標はブラウザから一切出ない。 これは技術方針であると同時に、デモとしての強い訴求点になる（11章）。

位置の供給元を抽象化する（最重要の設計判断）

実GPSとシミュレーションを、同じインターフェースの裏に隠す。

// lib/location/provider.ts
export interface LocationProvider {
  start(cb: (fix: Fix) => void, onError: (e: LocationError) => void): void
  stop(): void
  readonly kind: 'gps' | 'simulation' | 'manual'
}
// 実装は3つ
//  GpsProvider        … navigator.geolocation.watchPosition
//  SimulationProvider … ルートを一定速度で走行。誤差・精度低下も再現
//  ManualProvider     … 地図をタップした地点を現在地とする（PCでの検証用）

アプリのどこにも navigator.geolocation を直接呼ぶコードを書かない。 すべて LocationProvider 経由。これにより、

• 権限を拒否した読者も、シミュレーションで全機能を体験できる
• PCの読者も同じ体験ができる（記事の読者はPC比率も高い）
• E2Eテストが決定的に書ける（実GPSに依存しない）
• 埋め込みモードでは Provider を差し替えるだけで Geolocation を呼ばずに済む

この抽象化は記事の「方法」パートの中核コンテンツにもなる。

GPSの現実に対処する

永続化の範囲

擬似ディレイ は 150〜400ms。ただし位置取得・地図操作にはディレイを入れない。

4. スコープ定義

現場スタッフ向け機能

管理者向け機能

共通・基盤

対象外（Won't have）

スコープリスク： 位置情報は「追跡もしたい」「ナビも欲しい」「配車最適化も」と広がりやすい。特にバックグラウンド追跡は要望が出やすいが、Webでは技術的に不可能であり、ネイティブアプリ開発（別見積）になる。この線引きこそが記事の核心なので、曖昧にしない。

5. ロールとデモ切替

ロール定義

位置の供給元も切り替えられる（このデモ固有）

ロールとは別に、位置の供給元を切り替えるコントロールを持つ。

初回起動時、この3つを選ばせる。「今すぐ試す（位置情報を使う）／デモ走行を見る／地図をタップして試す」。いきなり権限プロンプトを出さない（FR-101）。

ロールとモードを跨ぐ体験（必ず動くようにする）

1. シミュレーションで走行 → 訪問先に近づく → ジオフェンス通知 → チェックイン → 管理者に切替 → 稼働マップにその記録が反映されている
2. 実GPSで自分の現在地を表示 → 地図タップで任意の訪問先を作成 → ジオフェンス半径を50mに → その場でチェックイン
3. オフライン（機内モード）でチェックイン → 未同期バッジが付く → オンラインに戻す → 自動同期される
4. 管理者で軌跡再生 → スタッフが今日たどった経路がタイムラインで再生される
5. 管理者が訪問先の位置を移動 → スタッフに切替 → ジオフェンスの判定位置が変わっている

デモ切替バー（F-S01）

画面上部に固定表示。埋め込みモードでは非表示。

• ロール切替（3ロール）
• 位置モード切替（GPS／シミュレーション／手動）と、現在の精度表示
• 「デモをリセット」（確認ダイアログ付き）
• 元記事へ戻るリンク
• 「これはデモです。位置情報は送信されません」の明示

デザイン上の扱い： アプリ本体が地図全画面なので、切替バーは地図に重ならない上端固定の濃色帯とし、地図UIと明確に区別する。

6. 画面一覧とユーザーフロー

全26画面。画面IDはディレクトリ構成と 1:1 で対応させる。

現場スタッフ画面（モバイル最適化）

管理者画面

主要フロー

フローA：記事の読者が位置情報に触れる（最重要）

SEO記事を読んでいる
   ↓
記事内の埋め込み（静止画の地図 + 「デモを再生」）
   ↓
再生 ── 仮想スタッフが地図上を走行、訪問先に接近
   ↓  ★ ジオフェンス円に入ると自動でチェックインが発生する様子が見える
「実際に自分の現在地で試す」→ 別タブ
   ↓
SC-001 モード選択 ──「今すぐ試す（位置情報を使う）」を選択
   ↓
SC-002 権限リクエスト ── ★ 何に使い、どこへも送らないことを先に説明
   ↓
ブラウザの権限プロンプト
   ├ 許可 → SC-010 メインマップ。自分の現在地が地図に出る
   └ 拒否 → SC-003 解除手順 + 「デモ走行で試す」導線 → シミュレーションで同じ体験
   ↓
SC-010 ── 近くに仮の訪問先が自動生成される（★ どこで開いても体験が成立する）
   ↓
訪問先に近づく or 地図タップで移動 → ジオフェンス通知 → チェックイン
   ↓
SC-014 訪問報告 → 写真添付 → 完了
   ↓
ロール切替「管理者」→ SC-100 稼働マップ
   ↓  ★ たった今の自分のチェックインが、管理側に反映されている
資料ダウンロード or 元記事に戻る

フローB：ジオフェンスとチェックイン

SC-010 メインマップ ── 訪問先ピンとジオフェンス円（半径100m）が見える
   ↓
移動して円の内側に入る
   ↓
★ ジオフェンス進入イベント
   ├ 画面上部にバナー「〇〇邸に到着しました」＋ チェックインボタン
   ├ バイブレーション（対応端末のみ）
   └ 通知センターに記録
   ↓
チェックインボタン
   ↓
SC-013 確認モーダル
   現在地と訪問先の距離（例：42m）
   位置の精度（例：±15m）
   ★ 距離が半径を超えている場合は「離れた場所での記録」として理由入力を必須化
   ↓
チェックイン完了 ── 滞在時間の計測開始、訪問先ピンが「訪問中」に変わる
   ↓
SC-014 訪問報告 ── 報告を書く（下書きは自動保存）
   ↓
SC-015 チェックアウト ── 滞在時間を確定。報告未記入なら警告
   ↓
訪問先ピンが「完了」に。次の訪問先へのルート案内ボタンが出る

フローC：オフラインでの記録と同期

SC-010 メインマップ（オンライン）
   ↓
機内モードにする（または DevTools でオフラインに）
   ↓
★ 画面上部にオフラインバナー「オフラインです。記録は端末に保存されます」
   ↓
チェックイン → 訪問報告 → 写真添付
   ↓  すべて成功する。ただし各記録に「未同期」バッジが付く
SC-031 未同期キュー ── 3件の未同期記録が並ぶ
   ↓
オンラインに戻す
   ↓
★ 自動で同期開始。バナーが「同期中… 2/3」→「同期しました」
   ↓
未同期バッジが消える
   ↓
ロール切替「管理者」→ SC-140 訪問記録に反映されている

7. 機能要件

7.1 位置情報の取得と権限（このデモの心臓部）

7.2 シミュレーション・手動モード

7.3 地図表示

7.4 ジオフェンスとチェックイン

7.5 訪問報告・写真・オフライン

7.6 ルート・並び替え

7.7 管理者機能

7.8 デモ基盤

8. データ設計

型定義（lib/types/）

// ---- 位置の基本型 ----
type Coord = { lat: number; lng: number }

type Fix = {                      // 位置の1点
  coord: Coord
  accuracyM: number               // 精度（メートル）
  altitude?: number
  heading?: number                // 進行方向（度）
  speedMps?: number
  source: 'gps' | 'simulation' | 'manual'
  at: string                      // ISO8601
}

type LocationError =
  | { kind: 'permission_denied' }
  | { kind: 'position_unavailable' }
  | { kind: 'timeout' }
  | { kind: 'insecure_context' }   // HTTPSでない
  | { kind: 'unsupported' }

type PermissionState = 'prompt' | 'granted' | 'denied' | 'unsupported'

// ---- 訪問先 ----
type Place = {
  id: string
  name: string
  nameKana: string
  address: string
  coord: Coord
  geofenceRadiusM: number         // 既定100、20〜500
  categoryId: string
  assignedStaffIds: string[]
  contactName: string
  contactPhone: string
  note: string
  isTemporary: boolean            // ★ 現在地近くに自動生成した仮の訪問先（FR-705）
  createdAt: string
  updatedAt: string
}

// ---- スタッフ・予定 ----
type Staff = {
  id: string
  name: string
  avatarUrl: string
  role: 'staff' | 'manager' | 'admin'
  teamId: string
  isOnDuty: boolean
  lastFix?: Fix                   // 最終位置。管理者の稼働マップで使用
  isActive: boolean
}

type ScheduleItem = {
  id: string
  placeId: string
  staffId: string
  date: string                    // YYYY-MM-DD
  plannedStartAt?: string         // 予定時刻
  plannedDurationMin: number
  sortOrder: number
  recurrence?: { type: 'weekly' | 'biweekly'; weekdays: number[] }
  status: 'planned' | 'in_progress' | 'done' | 'skipped'
}

// ---- 訪問記録 ----
type Visit = {
  id: string
  scheduleItemId: string
  placeId: string
  staffId: string
  // --- チェックイン ---
  checkInAt: string
  checkInFix: Fix
  checkInDistanceM: number        // ★ 訪問先からの距離（FR-305）
  isRemoteCheckIn: boolean        // 半径外だったか
  remoteReason?: string           // 半径外の場合の理由（FR-306）
  // --- チェックアウト ---
  checkOutAt?: string
  checkOutFix?: Fix
  stayMinutes?: number
  // --- 報告 ---
  report?: VisitReport
  photos: VisitPhoto[]
  // --- 同期 ---
  syncState: 'synced' | 'pending'  // ★ オフライン記録（FR-403）
  createdAt: string
}

type VisitReport = {
  templateValues: Record<string, string | string[] | boolean>
  freeText: string
  handover: string                // 次回申し送り
  savedAt: string
}

type VisitPhoto = {
  id: string
  objectUrl: string               // セッション内のみ有効
  fileName: string
  sizeBytes: number
  takenFix: Fix                   // ★ 撮影時点の位置（FR-407）
  at: string
}

type ReportTemplate = {
  id: string
  name: string
  fields: { id: string; label: string; type: 'select' | 'multiselect' | 'text' | 'checkbox'; options?: string[]; isRequired: boolean }[]
}

// ---- 軌跡 ----
type Track = {
  id: string
  staffId: string
  date: string
  fixes: Fix[]                    // 間引き済み（8章の方針参照）
  totalDistanceM: number
  startedAt: string
  endedAt?: string
}

// ---- ジオフェンスイベント ----
type GeofenceEvent = {
  id: string
  placeId: string
  staffId: string
  type: 'enter' | 'exit'
  fix: Fix
  distanceM: number
  at: string
}

// ---- シミュレーション ----
type SimRoute = {
  id: string                      // 'tokyo-route-a' 等
  name: string
  path: Coord[]                   // 通過点
  speedKmh: number
  placeIds: string[]              // このルート上に配置する訪問先
}

// ---- 設定 ----
type LocationSettings = {
  intervalSec: 5 | 15 | 60
  trackRecording: boolean
  retentionDays: number           // 保存期間
  purposeStatement: string        // ★ 取得目的の明示文（FR-613）
  accuracyThresholdM: number      // 既定100
  driftSpeedThresholdKmh: number  // 既定120
}

// ---- 同期キュー ----
type SyncQueueItem = {
  id: string
  targetType: 'visit' | 'report' | 'photo'
  targetId: string
  createdAt: string
  attempts: number
  lastError?: string
}

軌跡データの間引き（重要）

位置を15秒間隔で8時間記録すると1,920点になる。そのまま保持すると localStorage が破綻する。

シードデータ（lib/seed/）

シード作成のルール（品質を左右する）

• 訪問先は実在住所を使わない。 実在の個人宅・企業を指すデータを作らない。地名は実在でよいが、名称は架空にする（「〇〇邸」は避け「A様邸」等）
• 座標は道路上・建物上に自然に配置する。 海の上や線路の真上にピンが立つと一瞬で嘘だと分かる
• 軌跡は道なりにする。 直線で結ばない。主要道路に沿った通過点を打つ
• 半径外チェックインを数件混ぜる。 異常検知と距離列が意味を持つようにする
• 遅延しているスタッフを1名作る。 全員順調だとアラート機能が動いて見えない
• 日付は現在日時からの相対で生成する。固定日付を埋め込まない
• 本日の予定に「訪問中」の1件を含める（起動直後の画面が空にならないように）

ストアとリポジトリ

lib/
├── types/  seed/
├── location/                # ★ 位置の抽象化（3章）
│   ├── provider.ts          # LocationProvider インターフェース
│   ├── gps-provider.ts      # navigator.geolocation を呼ぶ唯一の場所
│   ├── simulation-provider.ts
│   ├── manual-provider.ts
│   ├── permission.ts        # Permissions API のラッパー
│   └── filter.ts            # ドリフト棄却・精度フィルタ
├── geo/                     # 純粋な計算。副作用なし・テスト必須
│   ├── distance.ts          # Haversine
│   ├── geofence.ts          # 進入退出判定（ヒステリシス付き）
│   ├── simplify.ts          # Douglas-Peucker
│   ├── bounds.ts            # 表示範囲の算出
│   └── nearest.ts           # 最近傍法による並び替え
├── store/  { session, data, settings, sync, ui }
└── repo/                    # ★ コンポーネントが触るのはここだけ
    ├── _delay.ts _scope.ts
    ├── places.ts staff.ts schedule.ts visits.ts tracks.ts reports.ts sync.ts

リポジトリ層の規約（厳守）

• 全メソッドを async で定義。中身が同期でも例外なく
• 戻り値は { ok: true; data: T } | { ok: false; error: string } に統一
• コンポーネントから Zustand ストアを直接参照しない
• navigator.geolocation を lib/location/gps-provider.ts 以外で呼ばない（FR-111）
• lib/geo/ は純粋関数のみ。 ストア・DOM・地図ライブラリに依存させない。ここが最もテストしやすく、最もバグが出る場所
• 位置取得・地図操作に擬似ディレイを入れない

9. デザイン要件

アートディレクション

「地図の上に、必要なものだけ浮かせる」

FIELDPIN が使われるのは、屋外・立ったまま・片手・手袋・直射日光の下。オフィスのUIをそのまま持ち込むと、現場では使えない。

• 地図が全画面。 UIは地図の上に浮くカードとボトムシートだけ
• タップ領域を大きく。 最小56px。RELATE（業務PC向け高密度）とは正反対の方向
• 親指の届く範囲に主要操作を置く。 画面上部に重要ボタンを置かない
• 直射日光を想定する。 中間グレーを避け、コントラストを強く取る
• 色は状態のためにある。 訪問先の状態は色と形の両方で示す

姉妹プロジェクトとの差別化（重要） HIREBASE：明朝・白・広い余白（読ませる）／ RELATE：ゴシック・白・13px高密度（操作させる）／ CASTA：ダーク・映像優先（見せる）／ FIELDPIN：地図全画面・16px大型UI・56pxタップ領域（現場で使わせる） 4つ並べたとき、別の会社が作ったように見えることが理想。トークンをコピーしない。

カラートークン

:root {
  /* 地図の上に乗るので、UIは白と濃紺のカードで固める */
  --ink-900:   #101418;   /* 見出し・本文 */
  --ink-600:   #4B5563;   /* 補助テキスト。★中間グレーはここまで */
  --panel:     #FFFFFF;   /* カード・シート背景 */
  --panel-alt: #F1F3F5;   /* シート内の区切り */
  --bar:       #101822;   /* 上端の状態バー・デモ切替バー */

  --primary:   #0B5FA5;   /* 主要CTA・現在地マーカー */
  --primary-d: #084river; /* ※実装時は #08477C に置換 */

  /* 訪問先の状態。★色 + 形の両方で区別する */
  --st-todo:   #6B7280;   /* 未訪問  … 丸 */
  --st-active: #0B5FA5;   /* 訪問中  … 二重丸 */
  --st-done:   #1F7A4D;   /* 完了    … チェック */
  --st-skip:   #8A6D3B;   /* スキップ… 斜線 */
  --st-late:   #B4281E;   /* 遅延    … 三角 */

  --geofence:      rgba(11,95,165,.12);   /* 圏外時の塗り */
  --geofence-in:   rgba(11,95,165,.28);   /* ★圏内に入ると濃くなる */
  --accuracy:      rgba(11,95,165,.16);   /* 精度円 */
  --accuracy-bad:  rgba(180,40,30,.18);   /* 精度が悪いとき */

  --offline:  #B4281E;    /* オフラインバナー */
  --pending:  #8A6D3B;    /* 未同期バッジ */
}

配色ルール

• 地図と喧嘩する色を使わない。 彩度の高い緑・茶は地図の地物と混ざるため、UIでは使わない
• 中間グレーの文字を使わない。 屋外で読めなくなる。補助テキストも --ink-600 までとし、それより薄い色を作らない
• 訪問先の状態は必ず色と形の両方で区別する（A11Y-04）
• カードは影ではなく白背景 + 1pxの縁で地図から浮かせる。影だけでは日光下で境界が消える

タイポグラフィ

モバイルの方が文字が大きい。 これは意図的。現場はスマホ、管理はPCという使い分けを前提にしている。

レイアウトとスペーシング

主要コンポーネント仕様

モーション

prefers-reduced-motion: reduce 時は、脈動と補間を停止し、位置は瞬時に更新する。

アクセシビリティ（WCAG 2.1 AA）

ライティング規約

10. 技術要件・ディレクトリ構成

技術スタック（固定・勝手に変更しない）

上記以外のライブラリを入れる前に必ず提案し、承認を得ること。特に Turf.js と Google Maps JS API の導入は禁止。

ディレクトリ構成

/
├── CLAUDE.md
├── app/
│   ├── layout.tsx
│   ├── page.tsx                  # SC-001 モード選択 / SC-090（?embed=1）
│   ├── permission/               # SC-002, 003
│   ├── map/                      # SC-010〜016（★ 地図インスタンスはここで1つだけ保持）
│   ├── visits/[id]/report/       # SC-014
│   ├── history/                  # SC-020, 021
│   ├── settings/                 # SC-030, 031
│   ├── admin/                    # SC-100〜160
│   └── dev/components/
├── components/
│   ├── map/                      # ★ 最重要
│   │   ├── MapCanvas.tsx         # MapLibre のライフサイクル管理（生成は1回だけ）
│   │   ├── CurrentLocationMarker.tsx
│   │   ├── PlaceMarker.tsx
│   │   ├── GeofenceCircle.tsx
│   │   ├── TrackLine.tsx
│   │   ├── TrackPlayer.tsx
│   │   └── useMapInstance.ts / useFitBounds.ts
│   ├── sheet/                    # BottomSheet, PlaceCard, ScheduleList
│   ├── domain/                   # CheckInButton, DistanceLabel, AccuracyBadge, OfflineBanner, SyncBanner, PermissionGuide
│   ├── demo/                     # RoleSwitcher, LocationModeSwitcher, ResetButton, GuideTour
│   └── layout/
├── lib/
│   ├── types/ seed/ store/ repo/
│   ├── location/                 # 8章参照。★ navigator.geolocation を呼ぶ唯一の場所
│   ├── geo/                      # ★ 純粋関数のみ。テスト必須
│   ├── query/ validation/ utils/
├── e2e/
└── public/

コーディング規約

• TypeScript strict。any 禁止
• navigator.geolocation を lib/location/gps-provider.ts 以外で呼ばない（FR-111）
• lib/geo/ は純粋関数のみ。 ストア・DOM・MapLibre に依存させない
• MapLibre のインスタンスは1つだけ生成し、画面遷移で破棄・再生成しない（FR-210・費用要件）
• watchPosition の ID を必ず clearWatch すること。 アンマウント時・モード切替時・visibilitychange 時
• MapLibre のマーカー・ソース・レイヤーも必ず破棄する。このアプリで最も起きやすい不具合はリスナーとマーカーのリーク
• 高さは 100dvh を使う。100vh を使わない
• コミットは1タスクごと。メッセージに要件IDを含める 例：feat(geofence): 進入退出判定にヒステリシスを追加 (FR-303)

11. 非機能要件・プライバシー

性能要件

プライバシー（この領域固有の最重要要件）

位置情報は、日本の個人情報保護法において個人関連情報にあたり、他の情報と結びつくことで個人データとなる。扱いを間違えると事故になる領域であり、その配慮を見せることがデモの信頼性を作る。

実案件への転用時の注意（デモ本体の要件ではない。商談で聞かれた際に説明できるよう記録）

• 従業員の位置情報を取得する場合、利用目的の特定と本人への明示が必要。就業規則や労使間の合意も論点になる
• 勤務時間外の位置取得は行わないことが原則。取得時間帯の制限を仕様に入れるべき
• 位置情報の保存期間を定め、期間経過後に削除する仕組みが必要
• 委託先（クラウド事業者）の管理、越境移転の確認が必要になる場合がある
• 本デモは位置情報をサーバーに送信しないため、これらの義務は発生しない。 ただし「デモである」旨は画面上に常時明示する

12. 費用設計

記事の主題の半分は「費用」。この章は実装要件であると同時に、記事本文の原稿素材でもある。

位置情報アプリの費用は「3つの分岐」で決まる

金額の前に、どの分岐を選ぶかで桁が変わることを説明する。ここが記事の核心。

分岐①：Webで足りるか、ネイティブが必要か（最大の分岐）

ここを誤解したまま進めると、作った後に「使えない」となる。 逆に、「スタッフが訪問先で開く」運用が成立するなら、Webで十分であり費用は大きく下がる。

判断の目安： 記録のタイミングを人が能動的に行う業務ならWeb。気づかないうちに記録したい業務ならネイティブ。

分岐②：地図タイルの課金モデル

地図は無料ではない。そして課金の単位がサービスごとに違う。

地図読み込み課金の月額 = 月間の地図初期化回数 × 単価

月間の地図初期化回数 = MAU × 月間セッション数 × セッションあたりの初期化回数
例：スタッフ20名 × 月20日稼働 × 1日3セッション × 1回 = 1,200回/月
   ↑ ただし「画面遷移のたびに地図を作り直す」実装だと 1回→8回 になり、9,600回/月

FR-210（地図インスタンスを1つだけ保持する）は、UI要件ではなく費用要件。 この1点で費用が数倍変わることを、記事で具体的に示す。

分岐③：位置データの保存と分析

軌跡を1日中記録すると、1人あたり1日 数千点になる。これをサーバーに保存し、後から検索・集計するなら、PostGIS等の空間データベースと、それを扱える設計が必要になる。開発費と運用費の両方が上がる。

「訪問した／しなかった」だけを記録するなら、データ量は劇的に小さくなる。 何をどこまで記録するかを最初に決めることが、費用管理そのものになる。

3層のコスト構造

開発費の目安（スコープ別）

「位置情報アプリ」という言葉の幅が広いことが、費用が伝わらない最大の原因。 記事ではこの3段階を明示し、デモは「標準構成」の実物であることを示す。具体的な金額はLPの価格体系に接続する。

記事に載せる際の注意： 各地図サービスの単価は変動するため、この文書に金額を書き込まない。 記事執筆時点で公式の料金ページを確認し、確認日を明記して掲載すること。 無料枠の条件（クレジット付与か、完全無料か）も併記すること。

デモ自体の運用コストを実測して記事に載せる

「記事に地図を埋め込むと、読まれるたびに課金される。だから押されるまで読み込まない設計にした」——この一文が、費用を理解して設計できることの証明になる。

13. 実装タスク

この順に進める。フェーズを飛ばさない。 完了時は [x] に更新する。

Phase 0 — 基盤と位置の抽象化（3日）

0-1. 初期化

• Next.js 15 / TypeScript strict / App Router / Tailwind で初期化
• ESLint / Prettier / husky（pre-commit で lint + typecheck）
• 10章のディレクトリ構成を作成
• ローカル開発をHTTPSで行えるようにする（Geolocation の検証に必須）

0-2. lib/geo/（純粋関数。最初に書いてテストで固める）

• distance.ts Haversine 距離
• geofence.ts 進入・退出判定（ヒステリシス付き、FR-303）
• simplify.ts Douglas-Peucker（DATA-01）
• bounds.ts 表示範囲の算出（FR-206）
• nearest.ts 最近傍法による並び替え（FR-502）
• 上記すべての単体テストを書く。ここが最もバグが出る場所

0-3. lib/location/（位置の抽象化。3章の中核）

• provider.ts LocationProvider インターフェース定義
• gps-provider.ts — navigator.geolocation を呼ぶ唯一の場所（FR-111）
• 2段階取得（低精度→高精度）(FR-103)
• visibilitychange での停止・再開 (FR-112)
• clearWatch の確実な実行
• simulation-provider.ts — ルート走行、精度の揺らぎと誤差を再現（FR-152）
• manual-provider.ts — 地図タップで現在地を指定（FR-154）
• permission.ts — Permissions API のラッパー、状態判定（FR-106）
• filter.ts — ドリフト棄却（速度閾値）・精度フィルタ（FR-105）
• Provider の単体テスト（シミュレーションで決定的に検証）

0-4. 型とシード

• lib/types/ に8章の型定義をすべて実装
• lib/seed/ の全ファイル
• 座標を道路上・建物上に自然に配置する。海の上にピンを立てない
• 軌跡を道なりにする。直線で結ばない
• 半径外チェックインを数件、遅延スタッフを1名、訪問中の予定を1件含める
• 実在住所・実在個人を指すデータを作らない

0-5. ストアとリポジトリ

• lib/store/{session,data,settings,sync,ui}.ts を Zustand + persist で実装
• lib/repo/_scope.ts（FR-708）
• lib/repo/ の全モジュール。位置取得・地図操作にディレイを入れない
• 軌跡の間引きと保持上限（DATA-01〜04）

0-6. デザインシステム

• app/globals.css にカラートークンを CSS 変数で定義
• tailwind.config.ts を拡張。タップ領域56pxを既定にする
• フォント（Noto Sans JP 500/700 / Roboto Mono）。距離・時刻に tabular-nums
• 100dvh とセーフエリアの対応
• shadcn/ui を導入し、タップ領域を拡大して上書き
• 共通コンポーネント：BottomSheet（3段階スナップ）／DistanceLabel / AccuracyBadge / StatusPin / EmptyState / Skeleton
• prefers-reduced-motion の対応
• /dev/components にコンポーネントカタログを作成

0-7. デモ基盤

• RoleSwitcher（3ロール）／LocationModeSwitcher（3モード + 精度表示）(FR-701, FR-702)
• デモ切替バー（地図に重ならない上端固定の濃色帯）
• 「デモをリセット」(FR-703)
• 元記事リンク・資料ダウンロード (FR-706)

Phase 0 完了チェック

• lib/geo/ のテストが全パターン通る
• シミュレーションProviderで、位置が滑らかに更新される
• 実機（スマホ・HTTPS）で gps-provider が実際の座標を返す
• /dev/components で全コンポーネントがトークン通りに表示される

Phase 1 — 地図と権限フロー（5日・最重要フェーズ）

1-1. 地図基盤

• MapLibre GL JS の導入（動的import）
• タイルサービスの選定と設定（12章の判断を記事に書けるよう、選定理由を記録すること）
• MapCanvas.tsx：インスタンスを1つだけ生成し、画面遷移で破棄しない（FR-210）
• useMapInstance.ts：ライフサイクル管理。マーカー・ソース・レイヤーの確実な破棄
• CurrentLocationMarker.tsx：点 + 精度円 + 進行方向の扇形 (FR-104, FR-110)
• 位置更新時の補間移動（瞬間移動させない）
• 精度が悪いときの警告表示 (FR-207)
• PlaceMarker.tsx：状態別の色と形（FR-202）。訪問中は脈動
• GeofenceCircle.tsx：圏内で塗りが濃くなる（FR-204）
• クラスタリング (FR-203)
• 「現在地へ戻る」FAB (FR-205)
• 初期表示範囲の自動調整 (FR-206)
• 地図スタイル切替（標準／航空写真風／高コントラスト）(FR-209)

1-2. 権限フロー（ここの丁寧さがこのデモの価値）

• SC-001 モード選択（起動直後に権限プロンプトを出さない）(FR-101)
• SC-002 権限リクエスト（目的と非送信の説明を先に）(FR-102)
• SC-003 拒否・ブロック時の案内：ブラウザ別の解除手順（iOS Safari / Android Chrome / PC Chrome / Firefox）(FR-106)
• シミュレーションへの導線を必ず併記 (A11Y-11)
• 非対応・非HTTPS の検知と案内 (FR-107)
• タイムアウト処理 (FR-108)
• 権限の全パターン（prompt / granted / denied / unsupported / insecure）を手動で検証する

1-3. メインマップ

• SC-010 メインマップ（全画面地図 + ボトムシート + FAB）
• SC-011 今日の予定シート（3段階スナップ、地図と連動）
• シート引き上げ時に現在地が隠れないよう地図をオフセット
• SC-012 訪問先詳細シート（距離を大きく表示）
• 現在地近くに仮の訪問先を自動生成（FR-705。どの地域で開いても成立させる）
• 位置モードの常時表示 (FR-156)
• 取得間隔の設定 (FR-109)

1-4. 埋め込みモード

• SC-090 埋め込みモード：Geolocation を一切呼ばない（FR-151, EMB-02）
• 静止画プレビュー + 「デモを再生」→ 押下で地図ライブラリを動的import
• シミュレーション自動走行・ループ、タブ非表示で停止 (EMB-05)
• 初期バンドル 60KB以下を実測 (EMB-03, NFR-07)
• アプリ内遷移の禁止、「実際に試す」は target="_blank"

Phase 1 完了チェック

• 実機で自分の現在地が地図に表示される
• 権限を拒否しても、シミュレーションで全機能が使える
• 画面を遷移しても地図インスタンスが再生成されない（FR-210 を DevTools で確認）
• 埋め込みモードで権限プロンプトが一切出ない
• 初回の概位置取得が3秒以下（NFR-01）

Phase 2 — ジオフェンスと訪問記録（4日）

• 位置更新ごとのジオフェンス判定（Haversine + ヒステリシス）(FR-302, FR-303)
• 進入通知：バナー + 通知センター + バイブレーション (FR-304)
• aria-live="assertive" での通知 (A11Y-06)
• SC-013 チェックイン確認（距離・精度の表示）(FR-305)
• 半径外チェックインの理由入力必須化（ブロックはしない）(FR-306)
• 二重チェックインの防止 (FR-308)
• SC-015 チェックアウト（滞在時間、報告未記入の警告）(FR-307)
• 訪問のスキップと理由記録 (FR-309)
• SC-014 訪問報告（テンプレート + 自由記述 + 申し送り）(FR-401)
• 下書きの自動保存 (FR-402)
• 写真添付と撮影時点の位置紐付け (FR-407)
• 画像圧縮 (FR-408)、Exif を読まない (FR-409)
• SC-016 訪問順の最適化（適用前後の総距離比較、自動適用しない）(FR-502, FR-503)
• 外部地図アプリでのルート案内 (FR-504)
• 軌跡の記録と総移動距離の算出 (FR-208, FR-505)
• SC-020 / SC-021 活動履歴

Phase 2 完了チェック

• フローBが完走する（ジオフェンス進入 → チェックイン → 報告 → チェックアウト）
• 境界を行き来してもジオフェンスが連続発火しない
• 手動モードで地図をタップしながら、ジオフェンスの進入・退出を再現できる

Phase 3 — オフラインとPWA（3日）

• Service Worker / PWA マニフェスト（F-S06）
• オフライン検知とバナー (FR-406)
• オフライン時のチェックイン・報告・写真添付 (FR-403)
• 同期キューの実装と「未同期」バッジ
• オンライン復帰の自動同期と進捗バナー (FR-404)
• SC-031 未同期キュー（一覧・手動同期・個別削除）(FR-405)
• aria-live="polite" での状態通知 (A11Y-07)
• SC-030 設定（位置モード、取得間隔、通知、軌跡記録ON/OFF）
• 保存データの件数・容量の可視化と削除導線（PRV-05, PRV-06）
• localStorage 上限接近時の処理 (NFR-12)

Phase 3 完了チェック

• フローCが完走する（オフラインで記録 → 復帰 → 自動同期）
• 機内モードでアプリを起動でき、記録ができる

Phase 4 — 管理画面（4日）

• SC-100 稼働マップ（全スタッフの現在地、最終更新からの経過時間、5分以上前は半透明）(FR-601)
• 進捗バッジと遅延アラート (FR-602)
• SC-101 / SC-102 スタッフ一覧・詳細
• SC-110 軌跡再生（日付・スタッフ選択、タイムライン再生、速度変更、シーク）(FR-603)
• SC-120 訪問先マスタ（一覧 + 地図の2ペイン、ピンのドラッグで座標修正）(FR-604)
• SC-121 ジオフェンス半径を地図上で円をドラッグして設定 (FR-605)
• SC-130 訪問予定（割当、日付・時間帯、繰り返し）(FR-606)
• SC-140 訪問記録一覧（距離の列表示、離れているものの絞り込み）(FR-607)
• SC-141 訪問記録詳細（チェックイン地点と訪問先の位置関係を地図で可視化）(FR-608)
• SC-150 実績ダッシュボード (FR-609)
• SC-151 エリア分析ヒートマップ (FR-610)
• 異常検知 (FR-611)
• CSVエクスポート (FR-612)
• SC-160 位置情報の設定（取得間隔・保存期間・軌跡記録・取得目的の明示文）(FR-613, PRV-08)

Phase 4 完了チェック

• 5章「ロールとモードを跨ぐ体験」の5パターンがすべて動作する
• 軌跡再生が滑らかで、道なりに動いて見える

Phase 5 — 記事統合と仕上げ（3日）

5-1. 記事統合

• 記事側の埋め込みコードを作成し、実際の記事ページで動作確認 (EMB-01〜05)
• 埋め込みが記事のCore Web Vitalsを悪化させないことを、埋め込み前後で比較検証
• 「実際に自分の現在地で試す」カードの設置
• 資料PDF（判断表・費用計算シート）の作成とダウンロード導線 (F-S03)
• 元記事リンク・問い合わせ導線 (EMB-10, EMB-11)
• GA4 イベント設定。geo_permission_result を必ず含める（EMB-12, EMB-14）
• GA4 に座標を送っていないことを確認 (PRV-03)
• ?embed=1 を noindex に (EMB-21)
• デモ本体の title / description / OGP (EMB-20)
• 記事側に VideoObject と HowTo の構造化データ (EMB-23)

5-2. 体験の総点検

• 5章の5パターンをすべて手動で確認
• 全26画面を開き、空の画面が1つもないことを確認
• 実機（iOS Safari / Android Chrome）での実地テスト。 実際に外を歩いて検証すること
• 屋内・地下での挙動を確認（精度低下時の表示）
• ガイドツアーを実装 (FR-709)

5-3. アクセシビリティ監査

• axe-core を全画面に実行し、Critical / Serious を0件に
• 地図を使わずに（リストだけで）全業務が完結することを確認 (A11Y-02)
• キーボードのみで全画面を操作完遂
• タップ領域56px以上を全画面で確認 (A11Y-03)
• フォントサイズ200%での操作確認 (A11Y-10)
• 屋外（直射日光下）での視認性を実機で確認

5-4. パフォーマンス

• MapLibre / Recharts を動的import に切り出し、初期バンドルを200KB以下に (NFR-08)
• 初回の概位置取得3秒以下を実測 (NFR-01)
• 地図操作の60fpsを実測 (NFR-05)
• 30分連続稼働でのメモリ推移を計測（watchPosition とマーカーのリーク検証）(NFR-09)
• Lighthouse で Performance 85 / Accessibility 95 (NFR-10)

5-5. 公開と記録

• Playwright で フローA・B・C の E2E（シミュレーションProviderを使って決定的に）
• Vitest：lib/geo lib/location _scope のカバレッジ80%以上
• /dev/components を本番で非公開に
• Vercel へデプロイ（HTTPS必須）、地図サービスの使用量アラートを設定 (COST-03)
• 地図初期化回数・タイル取得数・費用の記録を開始 (COST-01)
• 解説動画（3分）の収録：シミュレーション走行 → ジオフェンス → チェックイン → 管理画面での軌跡確認
• 各フェーズのキャプチャを整理し、記事の「方法」パートの素材にまとめる

合計 22営業日（約4.5週間）／1名専任 + レビュー体制。

工数配分の意図： Phase 0 の lib/geo/ と lib/location/ に丸1日以上を割き、テストで固めてから先に進む。位置情報アプリのバグは、実機を持って外を歩かないと再現しない。 純粋関数として切り出してテストできる部分を最大化しておくことが、後半の工数を決める。 Phase 1 に5日を割いているのは、権限フローの丁寧さがこのデモの価値そのものだから。「許可してください」の一言で済ませるアプリとの差が、ここに出る。

14. 受入基準

1. 7章の優先度 P1 の要件がすべて実装されていること
2. 6章の主要フローA・B・Cが、エンドツーエンドで完走すること
3. 5章「ロールとモードを跨ぐ体験」の5パターンがすべて動作すること
4. 実機で、自分の実際の現在地が地図に表示されること
5. 位置情報の権限を拒否しても、シミュレーションで全機能が体験できること
6. 権限の全状態（prompt / granted / denied / unsupported / insecure）で、適切な案内が表示され、白画面や無言の失敗が起きないこと
7. ジオフェンスの進入・退出が正しく判定され、境界で連続発火しないこと
8. 半径外のチェックインが、ブロックされずに理由付きで記録できること
9. オフラインで記録でき、復帰時に自動同期されること
10. 画面遷移で地図インスタンスが再生成されないこと（DevTools で確認。費用要件）
11. 埋め込みモードで Geolocation API が一度も呼ばれないこと、初期バンドルが60KB以下であること
12. 取得した座標が外部に一切送信されていないこと（DevTools の Network で確認。GA4 のイベントにも含まれないこと）
13. 30分連続稼働でメモリが単調増加しないこと
14. 全26画面のいずれにも空の状態がなく、リアルなデータが表示されていること
15. 地図を使わず、リストだけで全業務が完結できること
16. axe-core で Critical / Serious の指摘が0件であること
17. データアクセスがすべて lib/repo/ を経由し、navigator.geolocation が gps-provider.ts 以外で呼ばれていないこと
18. HIREBASE / RELATE / CASTA と並べたときに、明確に別のプロダクトとして見えること

判断に迷ったときのルール

1. 仕様がこの文書にない場合は、実装せずに質問する。 推測で作らない
2. 権限フローの丁寧さ、位置を使わない選択肢、空の画面を作らないことは削減対象外
3. navigator.geolocation を lib/location/gps-provider.ts 以外で呼ばない
4. lib/geo/ を純粋関数に保つ。 ここにストアやDOMを持ち込まない
5. 地図インスタンスを1つだけ保持する。 これはUI要件ではなく費用要件
6. watchPosition の clearWatch と、MapLibre のマーカー・リスナーの破棄を忘れない。このアプリで最も起きやすい不具合はリーク
7. スコープ外（4章 Won't have）は実装しない。特にバックグラウンド追跡は、Webでは不可能。 できないことを曖昧にしない
8. 「デモだから」を理由に品質を落とす判断はしない
9. HIREBASE / RELATE / CASTA のトークン・コンポーネントをコピーしない