ファイル解析パイプライン

アップロードされたファイルに対する 非同期 AI 解析 パイプラインです。書類への一括添付時、または立替経費申請書の AI一括解析 からキューへ投入され、領収書・請求書などから日付・金額・取引先を file_uploads.ai_data に保存します。

解析のみモード: 立替経費申請書（claims）の証憑紐付けタブでは、OCR 結果をファイルに保存するだけで 経費行・仕訳は変更しません。ロック済み書類でも解析は可能です。

トリガー

イベント	コード / エンドポイント
書類への一括添付	`file-upload.controller.ts` → `FILE_ANALYZE`
AI一括解析（claims）	`POST /api/documents/:id/attachments/analyze-pending`
解析状態ポーリング	`GET /api/documents/:id/attachments/analysis-status`
サーバー起動時	`recoverAllStaleProcessingOnBoot()`

sequenceDiagram
  participant UI as 証憑パネル
  participant API as document API
  participant Q as キュー
  participant P as file-analyze.processor
  participant S as file-intelligence.service
  participant DB as file_uploads

  UI->>API: POST analyze-pending
  API->>Q: enqueue（直接＋リンク元カスケード）
  loop isActive の間 3秒ごと
    UI->>API: GET analysis-status
    API-->>UI: extracted / pending / processing
  end
  Q->>P: process job
  P->>S: analyzeFileUpload()
  S->>DB: ai_data + analysis_status

書類単位 REST API

エンドポイント GET `…/attachments/analysis-status`

フィールド	説明
`total`	解析対象ファイル数（直接添付＋カスケード、重複除外）
`extracted`	`ai_data` が保存済みの件数（完了の判定基準）
`pending` / `processing` / `failed`	キュー状態
`isActive`	`true` の間のみ FE が 3 秒ポーリング
`directCount` / `cascadedCount`	直接 / リンク元由来の内訳

エンドポイント POST `…/attachments/analyze-pending`

未解析・失敗・completed だが ai_data 空のファイルを一括 enqueue。CSRF 必須。

フィールド	説明
`enqueued`	キューに追加した件数
`alreadyCompleted`	既に OCR 済み
`cascadePending`	リンク元書類由来で待ちの件数

解析対象の範囲（カスケード）

証憑紐付けパネルに表示される添付ファイルと同じリストを使用します。

直接: 当該書類に紐づく file_document_links
カスケード: document_relationships 経由でリンクされた関連書類の添付（1 段）
同一ファイル ID は直接添付を優先して重複除外

例: 76 件表示 = 42 直接 + 34 カスケード。

ジョブ契約

フィールド	型	説明
`fileId`	UUID	`file_uploads.id`
`userId`	UUID	所有者
`purpose`	string	既定 `receipt`
`documentId`	UUID?	トレース用（任意）

プロセッサ: src/processors/file-analyze.processor.ts
サービス: src/services/file-intelligence.service.ts

冪等性

層	動作
POST 一括解析	処理中・OCR 済みは skip
プロセッサ	`ai_data` あり `completed` は skip
SHA-256 重複	同一ハッシュの既存行から `ai_data` をコピー（2026-06-19）
ポーリング	`isActive: false` で停止。ポール時に drain しない

analysis_status = completed でも ai_data が空の行は 未完了 として再解析対象です。

失敗とリトライ

最大 3 回 リトライ
404 / not found / unsupported は非リトライ（NonRetriableError）
processing が 5 分超 or キュー喪失 → 自動 pending 復帰（status ポール時）

観測性

保存先	内容
`file_uploads.analysis_status`	`pending` → `processing` → `completed` / `failed`
`file_uploads.ai_data`	抽出フィールド（vendor, amount, date 等）
`file_uploads.langfuse_trace_id`	LLM トレース
`parse_runs`	エンジン・品質スコア
Langfuse	`document-bulk-analyze`, `file-analyze-job`

フロントエンド連携

コンポーネント	役割
`useDocumentAttachmentAnalysis`	3 秒ポーリング・統計・一括解析
`EvidenceProvenanceStrip`	AI N/76 チップ・AI一括解析ボタン
`document-evidence-panel`	行ごとの解析中スピナー

詳細: リポジトリ内 docs/ATTACHMENT_ANALYZE_ONLY.md