整骨院管理SaaS

整骨院・治療院向けのマルチテナント業務管理 SaaS です。Next.js 15 (App Router) と Supabase をベースに、予約、患者、日報、収益、スタッフ、管理設定、セキュリティ監視を 1 つのアプリで扱います。

テナント境界は clinic_id。患者情報を扱う医療系システムのため、認可・RLS・テナント分離を最優先しています。現行バージョンは 0.1.0-pilot です。変更完了、パイロット出荷、一般商用出荷、顧客価値検証は、それぞれ独立した現行ゲートで判断します。

現在の実装範囲

ルーティング（ルートグループ構成）

App Router のルートグループでアクセス境界を分離しています。

• (public) — 未認証導線
  • / ランディング
  • /login スタッフログイン / /admin/login 管理者ログイン / /admin/callback
  • /register, /register/verify, /invite, /forgot-password, /reset-password/[source]
  • /booking/[clinic_id] 公開予約
  • /terms, /privacy, /unauthorized
• (app) — 認証必須の業務画面（AppShell レイアウト）
  • /dashboard
  • /reservations, /reservations/new, /reservations/list, /reservations/register, /reservations/[id]
  • /reservations/settings/menus, /reservations/settings/resources
  • /patients, /patients/list, /patients/[id]
  • /daily-reports, /daily-reports/input, /daily-reports/edit/[id]
  • /revenue, /staff, /staff/shift-requests, /staff/shift-requests/admin
  • /multi-store, /onboarding, /chat, /ai-insights, /blocks, /master-data
• (app)/manager — manager（多店舗統括）向け画面
  • /manager/clinic-comparison, /manager/shift-requests, /manager/staff, /manager/staff-analysis
• (app)/admin/(protected) — 管理者機能
  • /admin/users, /admin/tenants, /admin/settings, /admin/managers, /admin/master
  • /admin/security-dashboard, /admin/security-monitor, /admin/session-management
  • /admin/mfa-setup, /admin/chat, /admin/beta-monitoring, /admin/shift-requests

API / バックエンド

API は src/app/api/**/route.ts。網羅一覧ではなく主要なドメイン単位で記載します（正本はソースを参照）。

• 業務 API: reservations, customers, patients, daily-reports（および daily-reports/items の pricing / tags / care-episode）, revenue, revenue-estimates, dashboard（dashboard/bootstrap）, menus, menu-templates（billing-profiles 含む）, resources, blocks, clinics, care-episodes, customers/[id]/insurance-coverages
• スタッフ / シフト: staff, staff/shifts, staff/preferences, staff/demand-forecast, staff/shift-requests（convert 含む）, staff/shift-request-periods
• manager 集計 API: manager/dashboard, manager/assigned-clinics, manager/clinic-comparison, manager/revenue/analysis, manager/patients/analysis, manager/daily-reports/overview, manager/staff, manager/staff-analysis
• 公開 API: public/menus, public/reservations, public/resources
• オンボーディング / 認証補助: onboarding/*（clinic / profile / invites / status / seed）, auth/profile, mfa/*（setup / verify / status / disable / backup-codes）
• 管理 API: admin/settings, admin/users（accounts / candidates / [permission_id]）, admin/tenants/[clinic_id], admin/managers/[managerUserId]/clinics, admin/master-data（export / import / rollback）, admin/security/*, admin/rate-limit/*, admin/staff/invites, admin/dashboard, admin/chat, admin/ai-insights, admin/notifications, admin/monitoring/sentry-test, admin/tables
• AI: ai-insights, ai-comments, chat, clinic/analysis, customers/analysis
• ベータ運用: beta/feedback, beta/backlog, beta/metrics
• 通知 / 外部連携 / 監視: internal/process-email-outbox（outbox → Resend）, webhooks/resend, security/csp-report, notifications, ,

技術スタック

• フロントエンド: Next.js 15 (App Router), React 19, TypeScript, Tailwind CSS, shadcn/Radix UI, lucide-react, Recharts
• データ / 認証: Supabase, PostgreSQL, Row Level Security
• 状態管理 / フォーム: TanStack Query, React Hook Form, Zod, Zustand
• 監視 / セキュリティ: Sentry, Upstash Redis（rate limiting）, CSP, MFA（speakeasy / QR）
• メール: Resend（email_outbox 経由の outbox パターン）
• テスト: Jest, React Testing Library, Playwright

主要依存とスクリプトは package.json を正本としてください。

アーキテクチャの要点

• Supabase クライアントは必ず @/lib/supabase から import（@/lib/supabase/server の直 import は ESLint エラー）。
  • createClient() / getServerClient(): リクエスト毎の SSR クライアント（RLS 適用、通常はこれ）
  • createAdminClient(): service role で RLS バイパス（サーバー専用・最小限）
  • createScopedAdminContext(): clinic scope 検証付き admin クライアント（管理系・多店舗操作）
• API ルートの定型: Zod 検証（src/lib/schemas/）→ processApiRequest()（src/lib/api-helpers.ts、管理 API は verifyAdminAuth()）→ clinic scope 強制（ensureClinicAccess() / processClinicScopedBody()）→ 統一エンベロープ { success, data | error } → handleRouteError() + AppError。
• 認可モデル: user_permissions の role + clinic_id（単店舗）/ clinic_scope_ids（複数店舗）。manager スコープは resolveEffectiveClinicScope()、role 正規化は normalizeRole()（clinic_manager → clinic_admin）。RLS が最後の砦。
• データベース SSOT は supabase/migrations/ のみ。旧 src/database/ 等の参照SQLは docs/archive/sql-reference-assets/ に隔離済みで直接適用禁止。予約は reservations が SSOT（appointments はレガシー読み取り専用）。src/types/supabase.ts は npm run supabase:types の生成物（手書き編集禁止）。
• 日付・時刻は必ず src/lib/jst.ts の JST ユーティリティを使う（UTC/JST 混在で E2E が落ちた実績あり）。

セキュリティとアクセス制御

• 必須環境変数は src/lib/env.ts で起動時に検証します（NODE_ENV=test は除外）。
  • NEXT_PUBLIC_SUPABASE_URL
  • NEXT_PUBLIC_SUPABASE_ANON_KEY
  • SUPABASE_SERVICE_ROLE_KEY
  • NEXT_PUBLIC_APP_URL
• 保護対象ルート（PROTECTED_ROUTE_PREFIXES）とログイン分岐は middleware.ts で管理しています。
  • /admin/** は管理者ログイン（/admin/login）へ
  • それ以外の保護ルートはスタッフログイン（/login、redirectTo 付き）へ
• middleware パイプラインの順序: ①レート制限（Upstash Redis、429 + Retry-After）②CSP nonce 生成 + ヘッダー付与（CSP_ROLLOUT_PHASE: report-only | partial-enforce | full-enforce、失敗時 fail-open）③保護ルート判定 ④Pilot mode リダイレクト。
• Pilot mode（NEXT_PUBLIC_PILOT_MODE=true）時は /chat, /ai-insights, /admin/security-*, /admin/beta-monitoring, /admin/session-management, /admin/master, /admin/chat, /blocks, /master-data を /dashboard へリダイレクトします。
• ローカル Supabase は supabase/config.toml で管理し、auth.hook.custom_access_token により clinic scope を JWT claim に反映します。

セットアップ

前提

• Node.js 24.x
• npm >=10.0.0
• Docker Desktop
• Supabase CLI

インストール

npm install

npm 固定です。他パッケージマネージャのロックファイル導入は禁止しています。

This is the beginning of the README. Read the rest at the original. Read the full README ↗