業務のための文書を
もっと端的に

ファイル取込 Design Doc

1. 概要

ファイル取込処理を非同期化する。APIは受信したファイル本体をオブジェクトストレージへ保存し、保存先をキューへ登録する。ワーカーはキューから保存先を受け取り、オブジェクトストレージ上のファイルを読み込んで解析し、解析結果をDBへ保存する。

2. 背景と目的

• APIリクエスト中に解析処理を実行せず、APIの処理時間と負荷を抑える。

• ファイル本体をキューに載せず、キューのメッセージサイズ制限に収める。

• 解析処理をワーカーに分離し、再実行や水平スケールを可能にする。

非同期化により、利用者が解析結果を確認できるまでの時間は同期処理より遅くなる。この遅延は本方式の前提とする。

3. 確定事項

• APIはファイル本体をオブジェクトストレージへ保存する。

• 保存成功後、保存先をキューへ登録する。

• オブジェクトストレージへの保存に失敗した場合、APIはHTTP 503を返し、キューには登録しない。

• ワーカーは保存先からファイルを読み込み、解析結果をDBへ保存する。

• ファイル本体をキューへ載せる方式は採用しない。想定ファイルサイズ10MBに対し、キューのメッセージサイズ上限が1MBのため。

• キューへの登録失敗時の回復方法は未決定であり、本Design Docでは確定しない。

4. 処理フロー

利用者
  │ ファイル送信
  ▼
API
  │ 1. オブジェクトストレージへ保存
  ├─ 失敗 ──> HTTP 503（キュー登録なし）
  │
  │ 2. 保存先情報をキューへ登録
  ▼
キュー
  │ 保存先情報
  ▼
ワーカー
  │ 3. オブジェクトストレージから取得
  │ 4. ファイル解析
  │ 5. 解析結果をDBへ保存
  ▼
DB

5. API仕様（実装方針）

5.1 リクエスト

• APIはファイルをmultipart/form-data等で受け付ける。

• ファイルサイズ上限は、少なくとも想定上限10MBを考慮して設定する。比較のポイント資料の「10MBのファイル」を、入力サイズの上限として読み替えています。このままでは、10MBを超えるファイルを拒否する要件まで決まったように読めます。スキルありは、10MBを処理対象の例として保っています。

• 受信したファイルには一意な取込IDを付与する。比較のポイント資料にない取込IDを追加し、メッセージやDB設計もこのIDを前提にしています。実装者には、合意済みの仕様と書き手が補った仕様の区別がつきません。スキルありでは、このIDを導入せずに処理の流れを説明しています。

5.2 オブジェクトストレージへの保存

保存先キーには、他の取込と衝突しない値を使用する。例：

imports/{import_id}/source

保存時には、実体とあわせて以下のメタデータを管理できるようにする。

• 取込ID

• 元ファイル名

• Content-Type

• ファイルサイズ

• 保存日時

• ハッシュ値（必要に応じて）

保存に失敗した場合は以下を行う。

1. エラーをログへ出力する。

2. HTTP 503 Service Unavailableを返す。

3. キューへの登録処理を実行しない。

4. クライアントが再試行可能なレスポンスであることを明示する。

5.3 キューへのメッセージ

キューにはファイル本体ではなく、ワーカーが取得に必要な情報だけを登録する。例：

{
  "import_id": "01J...",
  "object_key": "imports/01J.../source",
  "content_type": "application/pdf",
  "created_at": "2026-09-22T00:00:00Z"
}

実際のキューサービスに応じて、バケット名、オブジェクトURI、バージョンIDなどを追加する。

5.4 APIレスポンス

キュー登録まで成功した場合は、解析完了を待たずに受付結果を返す。推奨例：

• HTTP 202 Accepted

• 取込ID

• 状態確認用のリソース情報（提供する場合）

{
  "import_id": "01J...",
  "status": "queued"
}

解析結果はAPIレスポンスには含めず、別途状態確認APIまたは既存の結果参照手段で取得する。

6. ワーカー処理

ワーカーはキューからメッセージを受け取ったら、次の順で処理する。

1. メッセージから取込IDとオブジェクトキーを取得する。

2. オブジェクトストレージからファイルを読み込む。

3. ファイル形式・サイズ等の入力検証を行う。

4. ファイルを解析する。

5. 解析結果をDBへ保存する。

6. 成功時にキューのメッセージを完了扱いにする。

6.1 DB保存

取込IDを一意キーとして扱い、同一メッセージが再配信された場合でも解析結果が重複しないようにする。DB保存は冪等に実装する。

推奨する状態例：

• queued: キュー登録済み

• processing: ワーカー処理中

• completed: 解析結果保存済み

• failed: 解析または保存に失敗

状態更新と解析結果保存の整合性を保つため、可能な範囲で同一トランザクションにまとめる。

6.2 エラー処理

• オブジェクトストレージからの読み込み失敗：一時障害か恒久障害かを判定し、キューサービスの再試行機構に従う。

• 解析失敗：取込状態をfailedにし、原因を記録する。

• DB保存失敗：結果が保存できるまでメッセージを再処理可能にする。

• 再処理時に既にcompletedの場合は、重複保存せず成功扱いにする。

リトライ回数、デッドレターキューへの移送条件、失敗ファイルの保持期間は実装時に決定する。

7. 重要な未決事項

キュー登録失敗時の回復方法

オブジェクトストレージへの保存後、キュー登録に失敗すると、ファイルは保存済みだがワーカーへ届かない状態になる。回復方法は未決定である。

候補として以下があるが、採用案は別途決定する。

• DBに取込状態と保存先を記録し、定期ジョブが未登録データを再送する。

• Outboxパターンでキュー登録要求を永続化する。

• キュー登録失敗時に同期リトライする。

• オブジェクトストレージのイベント通知を利用する。

この事項が決まるまで、キュー登録処理の失敗時にファイルを削除するか、保存済みファイルをどの期間保持するかも確定しない。

8. 非機能要件・実装上の注意

• 10MBのファイルを扱えるAPI、オブジェクトストレージ、ワーカーの設定にする。

• キューにはファイル本体を格納しない。メッセージサイズは1MB未満に収める。

• オブジェクトストレージのアクセス権はワーカーに必要最小限だけ付与する。

• ログには取込IDを必ず含め、API、キュー、ワーカー、DBの処理を追跡できるようにする。

• ファイル名やContent-Typeなどの外部入力をログやキーに利用する場合は、エスケープおよびバリデーションを行う。

• 一時ファイルは処理完了後に削除し、メモリにファイル全体を保持し続けない。

• APIのタイムアウトは、ファイル保存完了までを基準に設定する。解析完了は待機しない。

• 監視対象として、保存失敗数、キュー登録失敗数、キュー滞留時間、ワーカー失敗数、解析完了時間を計測する。

9. テスト観点

• ファイル保存成功後にキューへ正しい保存先が登録されること。

• ファイル保存失敗時にHTTP 503が返り、キュー登録されないこと。

• 10MBのファイルを処理できること。

• キューのメッセージにファイル本体が含まれないこと。

• ワーカーが保存先からファイルを取得し、解析結果をDBへ保存できること。

• 同一メッセージの再配信で結果が重複しないこと。

• オブジェクトストレージ読み込み失敗、解析失敗、DB保存失敗時に想定した再試行・状態遷移になること。

• APIが解析完了を待たず、受付完了を返すこと。

10. スコープと進行状況

• 今週の実装範囲：API実装比較のポイント今週の担当作業を設計のスコープと一緒に載せています。翌週には古くなる情報が、設計全体の対象と混ざります。スキルありは作業メモを本文から外し、APIからDB保存までの処理をスコープに挙げています。

• 担当：佐藤

• 関連チケット：DATA-64

• 関連PR：#203

今週は、ファイル保存、保存失敗時の503応答、キュー登録に必要なメッセージ生成、および受付レスポンスまでを実装対象とする。キュー登録失敗時の回復機構は未決定のため、実装範囲外として明示的に扱う。

ADR-001: 請求書PDF生成をキューによる非同期処理にする

• ステータス: 採用

• 決定日: 2026-08-20

• 関連: BILL-218、PR #106

コンテキスト

請求書のPDF生成には最大45秒かかることがある。同期的に生成すると、処理中にAPI接続が切断される可能性があるため、利用者への応答とPDF生成処理を同じリクエスト内で完了させる方式は安定しない。

決定

請求書のPDF生成はキューに投入して非同期で処理する。APIはPDFそのものではなく、受付IDを返す。利用者またはクライアントは受付IDを使って処理状況を確認し、生成完了後にPDFを取得する。比較のポイント資料で決まっているのは、APIが受付IDを返すことまでです。ここでは、そのIDによる状況確認とPDF取得もできると補っています。保守者がこの記述を読むと、確認方法まで採用済みだと受け取るおそれがあります。

選択しなかった案

同期生成

同期生成は採用しない。生成に最大45秒かかり、処理中に接続が切れる可能性があるためである。

影響

利点

• 長時間のPDF生成によるAPI接続切断の影響を抑えられる。

• APIは受付処理を短時間で完了できる。

• PDF生成処理をキューのワーカーで独立して処理できる。

欠点・利用者への影響

• API応答時点ではPDFは完成していない。

• 利用者はPDFの完成まで待つ必要がある。

• クライアントには、受付IDによる状況確認と、完了後のPDF取得処理が必要になる。

未決事項

• 生成失敗時の再試行回数の上限は未決定である。運用・障害影響を確認したうえで別途決定する。

• 完成通知、状態確認API、受付IDの有効期限などの詳細仕様は実装時に確定する。比較のポイント資料で未決定とされたのは再試行の上限だけです。通知や状態確認API、有効期限も並べると、これらの設計作業まで必要と決まったように読めます。スキルありでは、その追加項目を外しています。

進捗メモ

原資料の作業メモでは、本対応の進捗は70%と記録されている。比較のポイント進捗70%は実装時点の作業情報であり、採用した方式や理由は説明しません。本文には課題IDとPR番号もあり、長く参照する決定と短期間で変わる進捗が混ざっています。

月次請求CSV出力・経理受け渡し手順書（当番向け）

1. 実施条件

• 実施日：毎月第1営業日

• 対象：前月分

• 開始状態：社内端末で請求管理画面にログイン済み

• 事前条件：経理が締め処理を終え、当番へ対象月を連絡済み

• 必要な権限：

  • 請求管理画面の出力権限

  • 社内共有フォルダ『経理受け渡し』への書き込み権限

2. 請求CSVの生成とダウンロード

1. 請求管理画面の『月次請求』を開く。

2. 経理から連絡された対象月を選ぶ。

3. 次の2点を確認する。

   • 選んだ対象月が前月と一致している。

   • 画面の状態が『締め済み』である。

4. 対象月が前月と一致しない、または状態が『締め済み』でない場合は、その場で中止する。以降の操作は行わない。

5. 両方の確認を通過した場合だけ、画面に表示された請求件数を控える。

6. 『CSVを生成』を1回押す。

7. 状態が『生成完了』になったら、『ダウンロード』を押す。

8. 次の場合は中止する。再生成はしない。

   • 状態が『生成失敗』になった。

   • 『CSVを生成』を押してから5分経っても『生成完了』にならない。

3. ダウンロードしたCSVの検査

1. ダウンロードしたCSVを表計算ソフトで開く。

2. 列が次の3列であることを確認する。

   • 『対象月』

   • 『請求先ID』

   • 『金額』

3. ヘッダーを除く行数が、控えた請求件数と一致することを確認する。

4. 全行の『対象月』が、選んだ対象月と一致することを確認する。

5. 請求件数が0件の場合は、ヘッダーだけでよい。比較のポイント0件のときの確認基準に、操作と同じ手順番号を付けています。次に行う操作と、その結果をどう判定するかが並ぶため、手順の番号だけでは作業の順番を追いにくくなっています。

6. 次の場合は中止し、経理へ渡さない。

   • 列が違う。

   • 行数が違う。

   • 『対象月』が違う。

   • ダウンロードに失敗した。

   • ファイルを開く操作に失敗した。

4. 共有フォルダへの保存

1. 保存先を社内共有フォルダ『経理受け渡し』にする。

2. ファイル名を 請求-YYYY-MM.csv とする。YYYY-MM には対象月を入れる。

   • 例：対象月が2026年8月の場合は 請求-2026-08.csv

3. 保存する前に、共有フォルダ『経理受け渡し』に同名ファイルがあるか確認する。

4. 同名ファイルがある場合は、その場で中止して保存しない。上書きはしない。

5. 同名ファイルがないことを確認したら、検査済みのCSVを指定した名前で1回だけ保存する。

6. 保存に失敗した場合は、その場で中止する。

5. 保存後の確認

1. 保存できたファイルを共有フォルダ『経理受け渡し』から開き直す。

2. 次の内容を確認する。

   • 列が『対象月』『請求先ID』『金額』の3列である。

   • ヘッダーを除く行数が、控えた請求件数と一致する。

   • 全行の『対象月』が、選んだ対象月と一致する。

   • 請求件数が0件の場合は、ヘッダーだけである。

3. 開き直せない場合、または確認結果が違う場合は、その場で中止する。この場合、経理へ完了連絡をしない。

4. 確認を通過した場合だけ、社内チャット『#経理連携』に次の内容を投稿して完了とする。

   • 対象月

   • 請求件数

   • 保存先

6. 中止時の連絡

1. 中止した場合は、社内チャット『#請求運用』で運用担当へ連絡する。

2. 次の内容を伝える。

   • 対象月

   • 止まった操作

   • 画面の状態または表示されたエラー

3. 再実行せず、運用担当の指示を待つ。

4. 請求先IDや金額の明細はチャットに貼らない。比較のポイント連絡時に守る禁止事項を、最後の操作として番号付きの手順に入れています。実施する操作と、連絡の間ずっと守る条件の違いが見えにくくなっています。