#434

docs/counts-exports.md

@@ -0,0 +1,53 @@
+# Counts エクスポートワーカー
+
+Counts の画面からのエクスポートは永続ファイルキューへ登録する。
+Active Job の既定のプロセス内 async アダプターは使用しない。
+追加 gem、外部キュー、DB マイグレーションは不要。
+
+## 起動・配置
+
+backend で `bundle exec rake counts:export_worker` を、systemd 等の監視対象として
+別プロセスで起動する。Web プロセス内では起動しない。
+ワーカー未起動の間は待機状態となる。1 プロセスは同時に1ジョブを処理し、
+全体の実行枠は既存の2枠を共有する。ワーカーの起動・配備は実施していない。
+
+Web とワーカーは同一リリース、Rails secret、アプリケーション環境、DB 接続先を
+使用する。DB コネクションはワーカープロセスごとに必要。
+`COUNTS_EXPORT_DIRECTORY` を同じ永続 POSIX 共有ディレクトリに設定する。
+省略時は `backend/tmp/counts_exports`。
+全プロセスで同一の所有者とアクセス権を使用する。
+複数ホストでは、flock・同一ファイルシステム内の atomic rename・fsync が正しく
+機能する共有ボリュームが必須。オブジェクトストレージや各コンテナ独立の tmp は不可。
+ジョブ JSON と完成ファイルが格納されるため、このディレクトリを静的公開しない。
+
+## API と進捗
+
+- POST `/counts/export/jobs`：要求検証・実行時点の固定・署名付きジョブトークンの発行。
+- GET `/counts/export/jobs/:token`：状態、実際の処理済みレコード数、判明している総数。
+- DELETE `/counts/export/jobs/:token`：取消を永続記録。
+- GET `/counts/export/files/:token`：生成完了後の署名付きファイルトークンによる取得。
+
+ジョブ・ファイルのトークンは作成元のセッションに紐付く。
+既存の BAN・CSRF 制御を使用する。フロントは約800ms間隔で状態を取得する。
+明細の総数は同じ読み取りトランザクション内の SQL 件数を使用する。
+集計結果の出力セル総数は生成終了まで確定させず、不確定進捗として扱う。
+完成状態はファイルの生成完了であり、ブラウザの保存完了を意味しない。
+
+## 取消・障害・制限
+
+通常は約250ms間隔の生成チェックポイントで取消を検知する。
+DB 問い合わせ・ファイル I/O がブロックしている間は即時に中断できない。
+取消済みへの遷移は生成処理の終了と一時ファイル削除後に行う。
+既に始まった HTTP 転送やブラウザ側の保存は取り消せない。
+
+ワーカーが異常終了したジョブは、次のワーカーが実行ロックを取得した際に失敗状態にし、
+そのジョブの残存生成ファイルを削除する。別の読み取り状態で自動再実行しない。
+原子的に書き換える状態ファイルとプロセス間ロックにより、二重処理・取消との競合を防ぐ。
+
+既存の同時実行2、1ファイル128MiB、保存領域512MiB、生成120秒、期限10分を維持する。
+生成時間制限もチェックポイント方式であり、実行中 SQL の強制停止ではない。
+期限切れのジョブ・ファイル・残存状態書込ファイルは登録時またはワーカーの巡回時に削除する。
+ワーカーと Web の両方を停止した間は巡回削除も停止する。
+
+これらの処理は静的確認のみで、実環境のキュー処理・取消・転送・共有ボリュームでの
+排他動作は未確認。