データの流れ

ブラウザからのリクエストが、どのミドルウェアを通って、どこで認証され、どこで snake_case に変換されて、どこでデータベースに届くか — の早見表です。

ひとつのリクエストがたどる道

sequenceDiagram
  participant FE as Frontend (axios)
  participant Helmet as helmet / cors / hpp
  participant RateLimit as レート制限<br/>(express-rate-limit)
  participant Auth as authMiddleware<br/>(JWT 検証)
  participant CSRF as CSRF / Origin チェック
  participant Case as ケース変換<br/>camelCase → snake_case
  participant Validate as zod / class-validator
  participant Controller as Controller
  participant Service as Service<br/>(ビジネスロジック)
  participant Prisma as Prisma Client
  participant DB as PostgreSQL<br/>(Supabase + RLS)

  FE->>Helmet: HTTPS 経由で受信
  Helmet->>RateLimit: セキュリティヘッダ付与
  RateLimit->>Auth: バケット内なら通す
  Auth->>CSRF: req.user 注入
  CSRF->>Case: Origin / Referer 検証
  Case->>Validate: body / query を snake_case 化
  Validate->>Controller: スキーマ検証成功
  Controller->>Service: 純粋なビジネス入力に変換
  Service->>Prisma: prisma.something.findMany(...)
  Prisma->>DB: SQL (RLS 付き)
  DB-->>Prisma: 行
  Prisma-->>Service: 値オブジェクト
  Service-->>Controller: 結果
  Controller-->>Case: snake_case のレスポンス
  Case-->>FE: camelCase の JSON

ヘッダの裏で requestId (req_xxx) を全リクエストに付与しています。エラーが出たときは、そのリクエスト ID を控えて問い合わせてください。

認証

認証は Supabase Auth が発行する JWT (Bearer) を使います
ログイン後にフロントが受け取った access_token を、Authorization: Bearer <token> ヘッダに乗せて送ります
Web では httpOnly Cookie として保存されているので、ブラウザの JavaScript からは中身を読めません
Capacitor (iOS / Android) は OS のセキュアストレージに保存し、起動時にヘッダへ注入します
バックエンドは JWT の署名検証をすべてのリクエストで行い、req.user に展開します

詳細は認証強化仕様を読んでください。

送信元チェックと CSRF

POST / PUT / PATCH / DELETE は、Origin または Referer ヘッダがホワイトリストの値であることを確認します。Capacitor からのリクエスト (capacitor://localhost など) はホワイトリストに含まれます。

CSRF トークン取得用のエンドポイントは GET /api/csrf で、フロント側ではアプリ起動時に一度取得し、変更系リクエストの X-CSRF-Token ヘッダに乗せます。

ケース変換 (camelCase ↔ snake_case)

solo-boss-cloud_backend は 三層命名コントラクト を厳守しています。

層	規約	例
データベース	`snake_case`	`journal_entries.entry_date`
API ワイヤ	`camelCase`	`{ "entryDate": "2026-01-31" }`
URL	`kebab-case`	`/api/journal-entries`
Zod 検証	`snake_case`	DB 形にそろえてから検証

クライアント側では 常に camelCase を使ってください。バックエンドのケース変換ミドルウェアが自動で snake_case に変換します。/api-docs、/public/*、multipart/form-data の 3 つは変換から除外されます (FormData は仕様上キーをそのまま渡すべきだから)。

詳細は命名規則を読んでください。

バリデーション

リクエストの検証には zod と class-validator を併用しています。

新規エンドポイントは zod を推奨 (型推論が強い、OpenAPI に沿わせやすい)
レガシー部分は class-validator が残っています
検証失敗は 400 ERR_3006 Validation Error で返り、detail にどのフィールドが何で落ちたかを含めます

エラーハンドリング

すべての例外は最後段の エラーハンドラミドルウェア がキャッチして、RFC 9457 形式に整形します。

既知のエラー (AppError 系) は code をそのまま使います
未知のエラーは ERR_6001 Internal Server Error に丸めて、Sentry に送ります
スタックトレースは本番では返しません

オフライン挙動・指数バックオフのリトライ規則は API エラーハンドリングと冪等性レシピを読んでください。

キャッシュ

ベース層は Express の 応答キャッシュミドルウェア が、認証済み GET の一部 (頻繁に変わらないリファレンスデータ) を 60 秒〜数分でメモリに保持します
Cloudflare ワーカーや CDN は通していません (会計データは個別企業に紐づくため)
フロントエンドは TanStack Query で再取得を制御しています (API ベストプラクティス)

ストレージ (Supabase Storage)

書類本体 (PDF / 画像) は Supabase Storage のバケットに置き、メタデータだけ Prisma 経由で PostgreSQL に保存します。署名付き URL の発行は API 経由で、TTL は短めに設定しています。

申告スナップショットと修正申告

提出済み申告データは 不変スナップショット として保存されます。比較・修正理由ビューは閲覧専用で、帳簿を自動変更しません。

flowchart TD
  Import[外部 XTX/XML 取込] --> Snap[external_filing スナップショット]
  Snap --> Compare[帳簿との比較]
  Compare --> Amend[修正申告セッション]
  Amend --> NewSnap[amended_filing スナップショット追加]
  Snap -.->|元は不変| Snap

操作	エンドポイント（例）	帳簿への影響
取込プレビュー	`POST /compliance/etax/import-preview`	なし
基準保存	`POST /compliance/etax/import-xtx/apply`	なし（スナップショットのみ）
比較	`POST /compliance/etax/compare`	なし
修正申告開始	`POST /filing-amendment/start`	期間ステータスのみ
修正申告完了	`POST /filing-amendment/complete`	新スナップショット追加

詳細: 外部提出ファイルの取込 · データの出どころ

観測性

Sentry に全エラー + 一定確率のパフォーマンストレースを送信
Langfuse は AI 呼び出し (プロンプト・レイテンシ・トークン数) を記録 — BYOK 時はメタデータ中心
リクエストログは Winston で構造化 (本番では info 以上、開発では debug)
X-Request-Id レスポンスヘッダで Sentry のトレースと突き合わせられます

ユーザー向けの AI 利用説明: AI の透明性