備品予約の詳細設計書
利用者は数量を指定して10分間の予約を作成する。保存側で在庫と予約と受付結果を同時に確定し、取消と期限切れの返却を一度に制限する。本書は入力資料を具体化した未承認の設計案であり、実装・実DB・外部サービス接続・負荷試験は未実施である。文書と図の検査は採用承認や動作検証を意味しない。
README.md · evidence.md · design.json
責務と機能 境界 物理データ 画面 要件と確認条件 状態と遷移 並行制御 障害と回復 情報の区分と判断 未決と変更
責務と機能
備品予約の作成・取消・期限処理・切断後の結果照会と、それを支える画面・保存・確認条件を設計する。
terms
名前 受付用識別子 意味 request_idである。利用者が明示した作成または取消の一回をUUIDで識別し、owner_idと組で生存期間中ずっと再使用しない。通信再送は同じ識別子と内容を使う。
名前 同じ内容 意味 作成はoperation=create、item_id、quantity、取消はoperation=cancel、reservation_idの構造化値が等しいことである。owner_idは照合キーに含む。JSON空白と順序は無視し、UUIDは正規形に統一し、未知・重複キーを拒否する。数値は整数だけを許可する。
名前 確定結果 意味 受付結果表へ業務更新と同じコミットで記録した不変の応答である。作成時のactiveとavailable_at_resultは過去の値であり、後の期限切れで書き換えない。現在値はIF005で別に得る。
名前 未確認 意味 画面またはサーバーがコミットの有無を判断できないことである。予約の業務状態ではなく、ST002のunknownで示す。未確認を保存不成立や予約不存在と同一視しない。
名前 数量と残数 意味 quantityは1〜1000000、capacityとavailableは0〜1000000000の整数とする提案である。availableは確定済みactiveの引当を除いた残数であり、期限処理待ちも引当を保持する。
名前 共通応答 意味 IF001・IF002とIF004のresultで用いる同一形のJSONである。全9項目を常に返し、NULLの条件を各項目に定義する。durable=trueだけが保存済みの操作結果である。HTTP受信やタイムアウトだけでは確定を表さない。
modules
id M001 名前 ブラウザ画面・HTTP受付 責務 画面は入力と操作結果を表示し、受付は認証済みowner_id、サイズとJSON形を検査する。クライアントのowner_idを信用しない。 依存先
id M002 名前 予約サービス 責務 作成・取消・照会の規則と権利を検査し、IF001〜IF005の保存境界へ正規化済み項目を渡す。保存不成立と確定不明を分ける。 依存先
id M003 名前 期限監視 責務 起動時と1秒ごとの候補検索でactiveかつ期限到達の予約IDを最大100件取得し、各IDをIF003へ渡す。処理単位は1予約であり、候補検索の時点で返却を確定しない。間隔と件数はD002の未検証提案である。 依存先
id M004 名前 保存リポジトリ 責務 PostgreSQLの行ロック・条件付き更新・受付結果の衝突を一つのトランザクションに閉じ、コミット成立後にのみ確定結果を返す。スナップショット読取りは書込みを行わない。 依存先 —
features
id F001 名前 予約を作成する 目的 在庫を超えずに予約を一回だけ確定し、後から同じ結果を確認できるようにする。 根拠 担当する責務 開始条件 UI001のreadyで本人の予約権限があり、備品が事前登録されている。既存結果の再送照合は予約の全業務状態で行える。 入力の境界 処理順 受付がサイズ・認証・項目を検査する。サービスから保存リポジトリへはIF001の正規化したrequest_id・item_id・quantityと信頼済みowner_idだけを渡す。 既存のT003をowner_idとrequest_idで読む。同じ内容なら保存済み応答を返し、違う内容ならID_CONFLICTを返す。既存結果は予約がcancelled・expiredでも再利用する。 存在しなければREAD COMMITTEDのトランザクションで備品行をFOR UPDATEし、同じ受付結果を再読する。T001.available>=quantityかつversionが上限未満を確認する。備品なしと在庫不足も業務上の確定拒否として受付結果へ残す。 成功なら行ロック後の時刻を採り、available-=quantity、version+=1、予約UUID・active・created_at・expires_atを作る。数量を先に外部へ送信しない。 正規化内容と全応答をT003へ最後にINSERTし、在庫・予約と同時にCOMMITする。受付識別子の衝突なら試行全体をROLLBACKし、別トランザクションで勝者の結果を読み同内容かを照合する。 COMMIT成立を確認してから保存済み応答を返す。画面は操作時点の残数と予約IDを表示し、現在値はIF005で更新する。 結果 createdはactiveと期限・確定時残数を返す。再送は保存済みの同じHTTP状態と応答を返し、予約が後にexpiredになっても当初の結果を書き換えない。 異常・競合・中断 検査不正は更新前に拒否する。保存不成立をROLLBACKで確認できたときだけSAVE_FAILEDを返す。COMMIT結果不明と応答切断はunknownとし、実DB状態を断定せずIF004で照会する。在庫更新は自動再実行しない。 共通の状態 保存先 画面 回復設計 確認条件 C001 C002 C003 C008 C009 C010 C011 C013 関連する未決
id F002 名前 予約を取消する 目的 期限内の本人取消または期限到達の確定を一回の返却に制限する。 根拠 担当する責務 開始条件 UI001のreadyで予約IDと本人の取消権限がある。activeだけが取消成功の候補であり、終端でも受付結果の再送照合と結果取得を許可する。 入力の境界 処理順 IF002でrequest_id・reservation_idと信頼済みowner_idを渡す。既存結果を先に照合する。予約をロックせず一度読みitem_idを得る。この対応は作成後に変更しない。 本人の予約がなければNOT_FOUNDを確定拒否として保存する。存在すれば備品行、予約行の順でFOR UPDATEし、再度所有者・状態と既存受付結果を確認する。 activeの場合はロック後の判定時刻を一度採る。時刻<expires_atならTR002でcancelled、時刻>=expires_atならTR003でexpiredとする。後者は取消成功にせずEXPIREDを返す。 どちらの遷移でもavailable+=quantity、version+=1、ended_atを同じ単位で更新する。cancelledとexpiredは変更せずALREADY_CANCELLEDまたはEXPIREDを返す。 受付結果を最後に登録してCOMMITする。識別子衝突は全体を戻して勝者結果を再読し、競合敗者の返却を残さない。確定応答後にIF005で現在値を読む。 結果 cancelledは一回の返却成功を示す。expired_nowは期限到達による返却とEXPIREDを示し、terminalは既に返却済みの状態を示す。残数は操作時点の値である。 異常・競合・中断 同時取消・期限監視では備品→予約の同じロック順とactiveの条件で一方だけが返却する。検査拒否・確定ロールバックは状態を保つ。COMMIT不明は業務状態を断定せずunknownとしてIF004で結果を照会する。 共通の状態 保存先 画面 回復設計 確認条件 C004 C005 C006 C008 C009 C010 C011 C013 C014 関連する未決
id F003 名前 期限到達を処理する 目的 監視遅延や再起動があっても期限切れの引当を一回だけ解放する。 根拠 担当する責務 開始条件 期限監視の信頼済みworker権限で、候補検索から得たreservation_idだけをIF003へ渡す。候補のquantityや状態を呼出し引数にしない。 入力の境界 処理順 期限監視はactiveかつexpires_at<=保存側時刻の候補IDを期限・ID順に最大100件読む。候補検索はロックを保持せず、各IDを別トランザクションで処理する。 IF003で予約を再読しitem_idを得る。備品行→予約行の順でロックし、状態を再読して判定時刻を採る。activeかつ判定時刻>=expires_atのときだけTR003を適用する。 available+=quantityとversion+=1、予約expiredとended_atを同じCOMMITで確定する。終端・未到達・予約なしはno_opとして変更しない。 各COMMITの結果を観測ログへ記録する。ログは監査補助であり返却済みの根拠はT002の状態である。再起動時に同じ候補検索を再開する。 結果 appliedはexpiredの確定と返却後残数を返す。no_opは処理を要しなかった状態を返す。外部への通知や実行基盤の呼出しはない。 異常・競合・中断 ロールバック確認時はfailedとして次の走査に残す。COMMIT不明では在庫を逆補正せず、再読の後にactive条件付き処理だけを許可する。期限監視の再試行は保存済み状態に従う内部回復であり、利用者の作成・取消を再実行しない。 共通の状態 保存先 画面 — 回復設計 確認条件 関連する未決
id F004 名前 結果と現在値を照会する 目的 切断後の確定結果を識別子で読み、過去の操作と現在の在庫・予約を区別する。 根拠 担当する責務 開始条件 本人の読取権限があり、IF004には元のrequest_id、IF005にはitem_idと任意のreservation_idを渡す。終端の予約にも読取権限を認め、実行中の権利を要求しない。 入力の境界 処理順 IF004でowner_idとrequest_idを使い、プライマリDBのコミット済みT003を読む。レプリカ遅延による偽の未記録を避ける。結果があれば保存済みのHTTP状態と共通応答をresultとして返す。 受付結果がなければNOT_RECORDEDを返す。未着・実行中・ロールバックを区別できないので予約の不成立とは断定せず、unknownのまま結果照会を再度許可する。DB読取失敗はLOOKUP_FAILEDとする。 結果foundではunknownからknownへ進める。作成成功後に取消・期限処理が行われてもresult.state_at_resultはactiveのままとする。過去結果をcurrentに流用しない。 IF005は単一SQL文の同じ読取りスナップショットで備品と本人の任意の予約を結合し、一度だけ取得して束縛した保存側observed_atと、それを使うdueを返す。期限到達のactiveはactiveかつdue=trueとして返し、読取りでは返却しない。 画面は過去の操作結果と現在値を別に表示する。最大5秒ごとの自動更新はIF004・IF005の読取りだけとし、作成・取消を自動送信しない。 結果 foundは今回の確定結果を再取得できたことを示す。snapshotは現在の残数と予約状態を示す。終端の確定結果からpendingや未完了へ戻す応答はない。 異常・競合・中断 他人の受付結果は本人キーで見つからないためNOT_RECORDED、他人の予約の現在値はNOT_FOUNDとして内容を漏らさない。結果未記録や読取失敗ではunknownを保つ。IF005が新値を返しても、それだけで元操作を成功としない。 共通の状態 保存先 画面 回復設計 確認条件 関連する未決
境界
備品予約の作成・取消・期限処理・切断後の結果照会と、それを支える画面・保存・確認条件を設計する。
interfaces
id IF001 名前 予約作成 呼出し元 ブラウザ・受付 呼出し先 予約サービス・保存リポジトリ 通信経路 HTTP POST /api/v1/reservations、内部同期呼出しcreate(request_id,item_id,quantity,owner_id) 入力と制約 同じrequest_idと正規化内容を受付・サービス・保存で引き継ぐ。内部の数量を再生成しない。 要求の項目 項目パス 型 必須 NULL可否 制約 context.owner_id string(uuid) true false サーバー認証で確定した利用者。クライアントからの指定を許可しない。 body.request_id string(uuid) true false 小文字ハイフン付きUUID正規形36文字。異なる世代の操作に再利用しない。 body.item_id string(uuid) true false 登録済み備品ID。 body.quantity integer true false 1〜1000000の整数。
要求の欠落と未知項目 bodyはJSONオブジェクトとし、必須欠落・全項目のnull・未知キー・重複キー・配列・小数・真偽値の数量・JSON数値の文字列化を拒否する。UTF-8だけを受け付ける。paramsとcontextは本文ではなく受付が組み立て、owner_idはサーバー認証からだけ得る。 出力 応答候補の全項目を返す。確定した業務結果だけを保存し、コミット結果不明を保存済み拒否に変えない。 応答の種類と項目 名前 意味と条件 項目 created 201 CREATED。新しい予約と在庫・受付結果のCOMMITを確認した応答でありdurable=trueとする。 項目パス 型 必須 NULL可否 制約 request_id string(uuid) or null true true 妥当な識別子を受理済みならその値を返す。欠落・不正・識別前の拒否ではnullとする。 code string true false CREATEDだけを返す。 message string true false 1〜200 Unicode文字かつUTF-8で800バイト以下。利用者向け理由を返し内部例外は含めない。 reservation_id string(uuid) or null true true 予約に結び付く確定結果ではそのID、それ以外はnullとする。 state_at_result string or null true true 結果確定時のactive・cancelled・expired。予約がない拒否・保存不成立・確定不明はnullとする。 expires_at string(datetime) or null true true 予約に結び付く結果では共通UTC形式、それ以外はnullとする。 available_at_result integer or null true true 0〜1000000000。保存単位で取得した残数。備品がない場合、入力拒否、保存不成立、確定不明はnullとする。 result_at string(datetime) or null true true durable=trueの確定結果では共通UTC形式の確定判断時刻、durable=falseではnullとする。COMMIT完了時刻と同一とは限らない。 durable boolean true false T003へCOMMITした応答はtrue、入力拒否・ID_CONFLICT・SAVE_FAILED・COMMIT_UNKNOWN等の非保存応答はfalseとする。
replay 保存済み結果と同じHTTP状態・共通応答を返す。CREATED、NO_STOCK、NOT_FOUND、VERSION_LIMITの元コードを変更しない。 項目パス 型 必須 NULL可否 制約 request_id string(uuid) or null true true 妥当な識別子を受理済みならその値を返す。欠落・不正・識別前の拒否ではnullとする。 code string true false CREATED、NO_STOCK、NOT_FOUND、VERSION_LIMITだけを返す。 message string true false 1〜200 Unicode文字かつUTF-8で800バイト以下。利用者向け理由を返し内部例外は含めない。 reservation_id string(uuid) or null true true 予約に結び付く確定結果ではそのID、それ以外はnullとする。 state_at_result string or null true true 結果確定時のactive・cancelled・expired。予約がない拒否・保存不成立・確定不明はnullとする。 expires_at string(datetime) or null true true 予約に結び付く結果では共通UTC形式、それ以外はnullとする。 available_at_result integer or null true true 0〜1000000000。保存単位で取得した残数。備品がない場合、入力拒否、保存不成立、確定不明はnullとする。 result_at string(datetime) or null true true durable=trueの確定結果では共通UTC形式の確定判断時刻、durable=falseではnullとする。COMMIT完了時刻と同一とは限らない。 durable boolean true false T003へCOMMITした応答はtrue、入力拒否・ID_CONFLICT・SAVE_FAILED・COMMIT_UNKNOWN等の非保存応答はfalseとする。
rejected 400 INVALID_INPUT、413 TOO_LARGE、415 UNSUPPORTED_MEDIA、401 UNAUTHENTICATED、403 FORBIDDEN、404 NOT_FOUND、409 ID_CONFLICT、503 SAVE_FAILED、503 VERSION_LIMITとする。SAVE_FAILEDはROLLBACK確認済みに限る。NOT_FOUNDとVERSION_LIMITの有効要求はdurable=trueとして記録し、それ以外の事前拒否はfalseとする。 在庫不足は409 NO_STOCK、durable=trueとする。 項目パス 型 必須 NULL可否 制約 request_id string(uuid) or null true true 妥当な識別子を受理済みならその値を返す。欠落・不正・識別前の拒否ではnullとする。 code string true false INVALID_INPUT、TOO_LARGE、UNSUPPORTED_MEDIA、UNAUTHENTICATED、FORBIDDEN、NOT_FOUND、ID_CONFLICT、SAVE_FAILED、VERSION_LIMIT、NO_STOCKだけを返す。 message string true false 1〜200 Unicode文字かつUTF-8で800バイト以下。利用者向け理由を返し内部例外は含めない。 reservation_id string(uuid) or null true true 予約に結び付く確定結果ではそのID、それ以外はnullとする。 state_at_result string or null true true 結果確定時のactive・cancelled・expired。予約がない拒否・保存不成立・確定不明はnullとする。 expires_at string(datetime) or null true true 予約に結び付く結果では共通UTC形式、それ以外はnullとする。 available_at_result integer or null true true 0〜1000000000。保存単位で取得した残数。備品がない場合、入力拒否、保存不成立、確定不明はnullとする。 result_at string(datetime) or null true true durable=trueの確定結果では共通UTC形式の確定判断時刻、durable=falseではnullとする。COMMIT完了時刻と同一とは限らない。 durable boolean true false T003へCOMMITした応答はtrue、入力拒否・ID_CONFLICT・SAVE_FAILED・COMMIT_UNKNOWN等の非保存応答はfalseとする。
unconfirmed 503 COMMIT_UNKNOWN。結果が不明でありdurable=false、予約・状態・期限・残数・result_atはnullとする。応答不能ならHTTP応答はなく、画面が切断からunknownへ進む。 項目パス 型 必須 NULL可否 制約 request_id string(uuid) or null true true 妥当な識別子を受理済みならその値を返す。欠落・不正・識別前の拒否ではnullとする。 code string true false COMMIT_UNKNOWNだけを返す。 message string true false 1〜200 Unicode文字かつUTF-8で800バイト以下。利用者向け理由を返し内部例外は含めない。 reservation_id string(uuid) or null true true 予約に結び付く確定結果ではそのID、それ以外はnullとする。 state_at_result string or null true true 結果確定時のactive・cancelled・expired。予約がない拒否・保存不成立・確定不明はnullとする。 expires_at string(datetime) or null true true 予約に結び付く結果では共通UTC形式、それ以外はnullとする。 available_at_result integer or null true true 0〜1000000000。保存単位で取得した残数。備品がない場合、入力拒否、保存不成立、確定不明はnullとする。 result_at string(datetime) or null true true durable=trueの確定結果では共通UTC形式の確定判断時刻、durable=falseではnullとする。COMMIT完了時刻と同一とは限らない。 durable boolean true false T003へCOMMITした応答はtrue、入力拒否・ID_CONFLICT・SAVE_FAILED・COMMIT_UNKNOWN等の非保存応答はfalseとする。
エラーと終了値 CREATED、NO_STOCK、NOT_FOUND、VERSION_LIMIT、INVALID_INPUT、TOO_LARGE、UNSUPPORTED_MEDIA、UNAUTHENTICATED、FORBIDDEN、ID_CONFLICT、SAVE_FAILED、COMMIT_UNKNOWNを共通応答のcodeで判別する。 最大サイズ 要求本文4096バイト以下、応答8192バイト以下とする。HTTPパスとヘッダーは合計2048バイト以下とする提案である。 検査順 Content-Typeと生のUTF-8バイト上限→認証→JSON構文・重複/未知/欠落/null→型とUUID/整数範囲→権限→既存識別子内容照合→ロック後の業務条件→保存→COMMIT確認の順とする。 再送・重複 owner_id+request_idの保存結果が同内容なら再作成しない。相違はID_CONFLICT。並行INSERT衝突は全ROLLBACK後に元結果を読む。 切断後の扱い 自動でPOSTし直さずrequest_idを保持してIF004へ進む。 共通の状態 担当する責務 応答と状態の対応 状態定義 現在状態 応答名 次状態 遷移 理由 ST001 absent created active TR001 対応する遷移のガードを満たした場合だけ、同じ保存単位で次状態を確定する。 ST001 absent replay absent null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 absent rejected absent null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 active replay active null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 active rejected active null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 cancelled replay cancelled null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 cancelled rejected cancelled null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 expired replay expired null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 expired rejected expired null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST002 sending created known TR005 確定応答または保存不成立を受信し、操作結果を確認する。 ST002 sending replay known TR005 確定応答または保存不成立を受信し、操作結果を確認する。 ST002 sending rejected known TR005 確定応答または保存不成立を受信し、操作結果を確認する。 ST002 sending unconfirmed unknown TR006 COMMIT結果不明または応答切断であり、実DB状態は断定しない。
許可状態と権利と副作用 画面readyからTR004でsendingとして一回送信する。業務は新規ならabsent、再送照合ならabsent・active・cancelled・expiredで本人の予約/結果読取権限を許可する。unconfirmedにST001の遷移を定義しないのは実DB状態が不明だからである。作成成功だけTR001、replayとrejectedは業務状態を変えない。
id IF002 名前 予約取消 呼出し元 ブラウザ・受付 呼出し先 予約サービス・保存リポジトリ 通信経路 HTTP POST /api/v1/reservations/{reservation_id}/cancel、内部同期cancel(request_id,reservation_id,owner_id) 入力と制約 取消はreservation_idだけから保存済みitem_id・quantity・expires_atを読み、クライアントの数量を受け付けない。 要求の項目 項目パス 型 必須 NULL可否 制約 context.owner_id string(uuid) true false サーバー認証で確定した利用者。クライアントからの指定を許可しない。 body.request_id string(uuid) true false 小文字ハイフン付きUUID正規形36文字。異なる世代の操作に再利用しない。 params.reservation_id string(uuid) true false 本人の予約ID。
要求の欠落と未知項目 bodyはJSONオブジェクトとし、必須欠落・全項目のnull・未知キー・重複キー・配列・小数・真偽値の数量・JSON数値の文字列化を拒否する。UTF-8だけを受け付ける。paramsとcontextは本文ではなく受付が組み立て、owner_idはサーバー認証からだけ得る。 出力 応答候補の全項目を返す。確定した業務結果だけを保存し、コミット結果不明を保存済み拒否に変えない。 応答の種類と項目 名前 意味と条件 項目 cancelled 200 CANCELLED。activeかつ期限前の判定でcancelledと返却をCOMMITしdurable=trueとする。 項目パス 型 必須 NULL可否 制約 request_id string(uuid) or null true true 妥当な識別子を受理済みならその値を返す。欠落・不正・識別前の拒否ではnullとする。 code string true false CANCELLEDだけを返す。 message string true false 1〜200 Unicode文字かつUTF-8で800バイト以下。利用者向け理由を返し内部例外は含めない。 reservation_id string(uuid) or null true true 予約に結び付く確定結果ではそのID、それ以外はnullとする。 state_at_result string or null true true 結果確定時のactive・cancelled・expired。予約がない拒否・保存不成立・確定不明はnullとする。 expires_at string(datetime) or null true true 予約に結び付く結果では共通UTC形式、それ以外はnullとする。 available_at_result integer or null true true 0〜1000000000。保存単位で取得した残数。備品がない場合、入力拒否、保存不成立、確定不明はnullとする。 result_at string(datetime) or null true true durable=trueの確定結果では共通UTC形式の確定判断時刻、durable=falseではnullとする。COMMIT完了時刻と同一とは限らない。 durable boolean true false T003へCOMMITした応答はtrue、入力拒否・ID_CONFLICT・SAVE_FAILED・COMMIT_UNKNOWN等の非保存応答はfalseとする。
expired_now 409 EXPIRED。activeかつ期限到達の判定でexpiredと返却をCOMMITしdurable=trueとする。 項目パス 型 必須 NULL可否 制約 request_id string(uuid) or null true true 妥当な識別子を受理済みならその値を返す。欠落・不正・識別前の拒否ではnullとする。 code string true false EXPIREDだけを返す。 message string true false 1〜200 Unicode文字かつUTF-8で800バイト以下。利用者向け理由を返し内部例外は含めない。 reservation_id string(uuid) or null true true 予約に結び付く確定結果ではそのID、それ以外はnullとする。 state_at_result string or null true true 結果確定時のactive・cancelled・expired。予約がない拒否・保存不成立・確定不明はnullとする。 expires_at string(datetime) or null true true 予約に結び付く結果では共通UTC形式、それ以外はnullとする。 available_at_result integer or null true true 0〜1000000000。保存単位で取得した残数。備品がない場合、入力拒否、保存不成立、確定不明はnullとする。 result_at string(datetime) or null true true durable=trueの確定結果では共通UTC形式の確定判断時刻、durable=falseではnullとする。COMMIT完了時刻と同一とは限らない。 durable boolean true false T003へCOMMITした応答はtrue、入力拒否・ID_CONFLICT・SAVE_FAILED・COMMIT_UNKNOWN等の非保存応答はfalseとする。
terminal 既存cancelledは200 ALREADY_CANCELLED、既存expiredは409 EXPIRED。再返却せずその結果をdurable=trueとして記録する。 項目パス 型 必須 NULL可否 制約 request_id string(uuid) or null true true 妥当な識別子を受理済みならその値を返す。欠落・不正・識別前の拒否ではnullとする。 code string true false ALREADY_CANCELLED、EXPIREDだけを返す。 message string true false 1〜200 Unicode文字かつUTF-8で800バイト以下。利用者向け理由を返し内部例外は含めない。 reservation_id string(uuid) or null true true 予約に結び付く確定結果ではそのID、それ以外はnullとする。 state_at_result string or null true true 結果確定時のactive・cancelled・expired。予約がない拒否・保存不成立・確定不明はnullとする。 expires_at string(datetime) or null true true 予約に結び付く結果では共通UTC形式、それ以外はnullとする。 available_at_result integer or null true true 0〜1000000000。保存単位で取得した残数。備品がない場合、入力拒否、保存不成立、確定不明はnullとする。 result_at string(datetime) or null true true durable=trueの確定結果では共通UTC形式の確定判断時刻、durable=falseではnullとする。COMMIT完了時刻と同一とは限らない。 durable boolean true false T003へCOMMITした応答はtrue、入力拒否・ID_CONFLICT・SAVE_FAILED・COMMIT_UNKNOWN等の非保存応答はfalseとする。
replay 元の取消または拒否結果と同じHTTP状態・共通応答を返す。 項目パス 型 必須 NULL可否 制約 request_id string(uuid) or null true true 妥当な識別子を受理済みならその値を返す。欠落・不正・識別前の拒否ではnullとする。 code string true false CANCELLED、EXPIRED、ALREADY_CANCELLED、NOT_FOUND、VERSION_LIMITだけを返す。 message string true false 1〜200 Unicode文字かつUTF-8で800バイト以下。利用者向け理由を返し内部例外は含めない。 reservation_id string(uuid) or null true true 予約に結び付く確定結果ではそのID、それ以外はnullとする。 state_at_result string or null true true 結果確定時のactive・cancelled・expired。予約がない拒否・保存不成立・確定不明はnullとする。 expires_at string(datetime) or null true true 予約に結び付く結果では共通UTC形式、それ以外はnullとする。 available_at_result integer or null true true 0〜1000000000。保存単位で取得した残数。備品がない場合、入力拒否、保存不成立、確定不明はnullとする。 result_at string(datetime) or null true true durable=trueの確定結果では共通UTC形式の確定判断時刻、durable=falseではnullとする。COMMIT完了時刻と同一とは限らない。 durable boolean true false T003へCOMMITした応答はtrue、入力拒否・ID_CONFLICT・SAVE_FAILED・COMMIT_UNKNOWN等の非保存応答はfalseとする。
rejected 400 INVALID_INPUT、413 TOO_LARGE、415 UNSUPPORTED_MEDIA、401 UNAUTHENTICATED、403 FORBIDDEN、404 NOT_FOUND、409 ID_CONFLICT、503 SAVE_FAILED、503 VERSION_LIMITとする。SAVE_FAILEDはROLLBACK確認済みに限る。NOT_FOUNDとVERSION_LIMITの有効要求はdurable=trueとして記録し、それ以外の事前拒否はfalseとする。 項目パス 型 必須 NULL可否 制約 request_id string(uuid) or null true true 妥当な識別子を受理済みならその値を返す。欠落・不正・識別前の拒否ではnullとする。 code string true false INVALID_INPUT、TOO_LARGE、UNSUPPORTED_MEDIA、UNAUTHENTICATED、FORBIDDEN、NOT_FOUND、ID_CONFLICT、SAVE_FAILED、VERSION_LIMITだけを返す。 message string true false 1〜200 Unicode文字かつUTF-8で800バイト以下。利用者向け理由を返し内部例外は含めない。 reservation_id string(uuid) or null true true 予約に結び付く確定結果ではそのID、それ以外はnullとする。 state_at_result string or null true true 結果確定時のactive・cancelled・expired。予約がない拒否・保存不成立・確定不明はnullとする。 expires_at string(datetime) or null true true 予約に結び付く結果では共通UTC形式、それ以外はnullとする。 available_at_result integer or null true true 0〜1000000000。保存単位で取得した残数。備品がない場合、入力拒否、保存不成立、確定不明はnullとする。 result_at string(datetime) or null true true durable=trueの確定結果では共通UTC形式の確定判断時刻、durable=falseではnullとする。COMMIT完了時刻と同一とは限らない。 durable boolean true false T003へCOMMITした応答はtrue、入力拒否・ID_CONFLICT・SAVE_FAILED・COMMIT_UNKNOWN等の非保存応答はfalseとする。
unconfirmed 503 COMMIT_UNKNOWN。durable=falseとし予約・状態・期限・残数・result_atをnullとする。応答不能は画面でunknownとして扱う。 項目パス 型 必須 NULL可否 制約 request_id string(uuid) or null true true 妥当な識別子を受理済みならその値を返す。欠落・不正・識別前の拒否ではnullとする。 code string true false COMMIT_UNKNOWNだけを返す。 message string true false 1〜200 Unicode文字かつUTF-8で800バイト以下。利用者向け理由を返し内部例外は含めない。 reservation_id string(uuid) or null true true 予約に結び付く確定結果ではそのID、それ以外はnullとする。 state_at_result string or null true true 結果確定時のactive・cancelled・expired。予約がない拒否・保存不成立・確定不明はnullとする。 expires_at string(datetime) or null true true 予約に結び付く結果では共通UTC形式、それ以外はnullとする。 available_at_result integer or null true true 0〜1000000000。保存単位で取得した残数。備品がない場合、入力拒否、保存不成立、確定不明はnullとする。 result_at string(datetime) or null true true durable=trueの確定結果では共通UTC形式の確定判断時刻、durable=falseではnullとする。COMMIT完了時刻と同一とは限らない。 durable boolean true false T003へCOMMITした応答はtrue、入力拒否・ID_CONFLICT・SAVE_FAILED・COMMIT_UNKNOWN等の非保存応答はfalseとする。
エラーと終了値 CANCELLED、ALREADY_CANCELLED、EXPIRED、NOT_FOUND、VERSION_LIMIT、INVALID_INPUT、TOO_LARGE、UNSUPPORTED_MEDIA、UNAUTHENTICATED、FORBIDDEN、ID_CONFLICT、SAVE_FAILED、COMMIT_UNKNOWNをcodeに返す。 最大サイズ 要求本文4096バイト以下、応答8192バイト以下とする。HTTPパスとヘッダーは合計2048バイト以下とする提案である。 検査順 Content-Typeと生のUTF-8バイト上限→認証→JSON構文・重複/未知/欠落/null→型とUUID/整数範囲→権限→既存識別子内容照合→ロック後の業務条件→保存→COMMIT確認の順とする。 再送・重複 同じ識別子・内容は元結果、異なる内容はID_CONFLICTとする。別識別子で終端を取消してもterminalを記録するだけで返却しない。 切断後の扱い 自動再取消と在庫の逆補正をせず、IF004で取消request_idの結果を読む。 共通の状態 担当する責務 応答と状態の対応 状態定義 現在状態 応答名 次状態 遷移 理由 ST001 active cancelled cancelled TR002 対応する遷移のガードを満たした場合だけ、同じ保存単位で次状態を確定する。 ST001 active expired_now expired TR003 対応する遷移のガードを満たした場合だけ、同じ保存単位で次状態を確定する。 ST001 cancelled terminal cancelled null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 expired terminal expired null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 absent replay absent null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 absent rejected absent null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 active replay active null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 active rejected active null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 cancelled replay cancelled null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 cancelled rejected cancelled null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 expired replay expired null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 expired rejected expired null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST002 sending cancelled known TR005 取消成功・期限切れ・終端・拒否の応答を確認する。 ST002 sending expired_now known TR005 取消成功・期限切れ・終端・拒否の応答を確認する。 ST002 sending terminal known TR005 取消成功・期限切れ・終端・拒否の応答を確認する。 ST002 sending replay known TR005 取消成功・期限切れ・終端・拒否の応答を確認する。 ST002 sending rejected known TR005 取消成功・期限切れ・終端・拒否の応答を確認する。 ST002 sending unconfirmed unknown TR006 コミット成立は照会まで不明である。
許可状態と権利と副作用 画面readyからTR004でsendingへ進める。本人のactive・cancelled・expiredの取消受付と再送照合を許可する。absentと他人の予約はNOT_FOUNDとする。activeの期限到達はTR003、期限内はTR002とし、終端は変更しない。unconfirmedはST001を断定せずST002だけをunknownへ進める。
id IF003 名前 期限予約を一件処理 呼出し元 期限監視 呼出し先 予約サービス・保存リポジトリ 通信経路 プロセス内の同期expire(reservation_id,worker_role) 入力と制約 引数は候補の予約IDとworker権利だけとし、数量や時刻は保存側から再取得する。 要求の項目 項目パス 型 必須 NULL可否 制約 reservation_id string(uuid) true false 候補検索で取得したID。 context.worker_role string true false サーバーが付与するexpiry-worker固定値。
要求の欠落と未知項目 必須欠落・null・未知項目・重複項目を拒否する。入力なしの操作は設けない。contextの権利はサーバーが付与する。 出力 応答候補の全項目を返す。確定した業務結果だけを保存し、コミット結果不明を保存済み拒否に変えない。 応答の種類と項目 名前 意味と条件 項目 applied EXPIRED。activeからexpiredと返却をCOMMITした結果。 項目パス 型 必須 NULL可否 制約 reservation_id string(uuid) or null true true 有効な要求IDを返し、不正・欠落ならnull。 code string true false EXPIREDだけを返す。 state string or null true true 確認したactive・cancelled・expired。不存在、不正、確定不明ではnull。 available integer or null true true 0〜1000000000。確定したスナップショットがある場合だけ返し、それ以外はnull。 evaluated_at string(datetime) or null true true ロック後に判定できた共通UTC時刻。確定不明・入力拒否ではnull。
no_op activeで未到達はNOT_DUE、cancelled/expiredはALREADY_TERMINAL、予約なしはNOT_FOUND。DB変更なし。 項目パス 型 必須 NULL可否 制約 reservation_id string(uuid) or null true true 有効な要求IDを返し、不正・欠落ならnull。 code string true false NOT_DUE、ALREADY_TERMINAL、NOT_FOUNDだけを返す。 state string or null true true 確認したactive・cancelled・expired。不存在、不正、確定不明ではnull。 available integer or null true true 0〜1000000000。確定したスナップショットがある場合だけ返し、それ以外はnull。 evaluated_at string(datetime) or null true true ロック後に判定できた共通UTC時刻。確定不明・入力拒否ではnull。
failed INVALID_INPUT、FORBIDDEN、VERSION_LIMITまたはROLLBACK確認済みSAVE_FAILED。DB更新なし。 項目パス 型 必須 NULL可否 制約 reservation_id string(uuid) or null true true 有効な要求IDを返し、不正・欠落ならnull。 code string true false INVALID_INPUT、FORBIDDEN、SAVE_FAILED、VERSION_LIMITだけを返す。 state string or null true true 確認したactive・cancelled・expired。不存在、不正、確定不明ではnull。 available integer or null true true 0〜1000000000。確定したスナップショットがある場合だけ返し、それ以外はnull。 evaluated_at string(datetime) or null true true ロック後に判定できた共通UTC時刻。確定不明・入力拒否ではnull。
unconfirmed COMMIT_UNKNOWN。業務状態と返却回数を断定しない。 項目パス 型 必須 NULL可否 制約 reservation_id string(uuid) or null true true 有効な要求IDを返し、不正・欠落ならnull。 code string true false COMMIT_UNKNOWNだけを返す。 state string or null true true 確認したactive・cancelled・expired。不存在、不正、確定不明ではnull。 available integer or null true true 0〜1000000000。確定したスナップショットがある場合だけ返し、それ以外はnull。 evaluated_at string(datetime) or null true true ロック後に判定できた共通UTC時刻。確定不明・入力拒否ではnull。
エラーと終了値 EXPIRED、NOT_DUE、ALREADY_TERMINAL、NOT_FOUND、INVALID_INPUT、FORBIDDEN、SAVE_FAILED、VERSION_LIMIT、COMMIT_UNKNOWNをcodeに返す。 最大サイズ 内部要求256バイト相当以下、応答1024バイト以下とする提案である。 検査順 信頼済み権利→必須/欠落/null/未知項目→型とUUID→本人またはworkerの権利→保存済み情報の読取り→各業務条件の順とする。 再送・重複 同じIDを再度処理してもactive条件を満たさない終端は返却しない。 切断後の扱い タイムアウトは確定不明として再読し、activeかつ期限到達のときだけ次の走査で処理する。 共通の状態 担当する責務 応答と状態の対応 状態定義 現在状態 応答名 次状態 遷移 理由 ST001 active applied expired TR003 対応する遷移のガードを満たした場合だけ、同じ保存単位で次状態を確定する。 ST001 absent no_op absent null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 absent failed absent null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 active no_op active null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 active failed active null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 cancelled no_op cancelled null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 cancelled failed cancelled null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 expired no_op expired null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 expired failed expired null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。
許可状態と権利と副作用 expiry-worker権利からabsent・active・cancelled・expiredを再読できる。activeかつ期限到達だけTR003を行う。active未到達と終端・不存在のno_opは状態を保つ。failedはROLLBACK確認済みか更新前拒否だけである。unconfirmedは実DB状態を断定できないので状態効果を列挙せずRC003で再読する。
id IF004 名前 受付結果照会 呼出し元 ブラウザ・受付 呼出し先 予約サービス・保存リポジトリ 通信経路 HTTP GET /api/v1/requests/{request_id}、内部同期lookup(request_id,owner_id) 入力と制約 本人の受付用識別子で保存済みの元結果だけを取得する。 要求の項目 項目パス 型 必須 NULL可否 制約 context.owner_id string(uuid) true false サーバー認証で確定した利用者。クライアントからの指定を許可しない。 params.request_id string(uuid) true false 小文字ハイフン付きUUID正規形36文字。異なる世代の操作に再利用しない。
要求の欠落と未知項目 GET本文は許可せず0バイトとする。必須params/contextの欠落、null、未知・重複queryを拒否する。context.owner_idは受付が認証から付与する。 出力 応答候補の全項目を返す。確定した業務結果だけを保存し、コミット結果不明を保存済み拒否に変えない。 応答の種類と項目 名前 意味と条件 項目 found HTTP 200。コミット済みの元の応答をresultへ返す。元が拒否でもfoundであり、現在の予約状態を意味しない。 項目パス 型 必須 NULL可否 制約 request_id string(uuid) true false 照会対象の妥当なID。 result.request_id string(uuid) true false 照会対象request_idと同じ保存済みUUIDを必ず返す。NULLを許可しない。 result.code string true false CREATED、NO_STOCK、NOT_FOUND、VERSION_LIMIT、CANCELLED、ALREADY_CANCELLED、EXPIREDの保存済み元コードを返す。 result.message string true false 1〜200 Unicode文字かつUTF-8で800バイト以下。利用者向け理由を返し内部例外は含めない。 保存済み共通応答でありresult.durableはtrue固定、result.request_idとresult.result_atはnull不可である。 result.reservation_id string(uuid) or null true true 予約に結び付く確定結果ではそのID、それ以外はnullとする。 保存済み共通応答でありresult.durableはtrue固定、result.request_idとresult.result_atはnull不可である。 result.state_at_result string or null true true 結果確定時のactive・cancelled・expired。予約がない拒否・保存不成立・確定不明はnullとする。 保存済み共通応答でありresult.durableはtrue固定、result.request_idとresult.result_atはnull不可である。 result.expires_at string(datetime) or null true true 予約に結び付く結果では共通UTC形式、それ以外はnullとする。 保存済み共通応答でありresult.durableはtrue固定、result.request_idとresult.result_atはnull不可である。 result.available_at_result integer or null true true 0〜1000000000。保存単位で取得した残数。備品がない場合、入力拒否、保存不成立、確定不明はnullとする。 保存済み共通応答でありresult.durableはtrue固定、result.request_idとresult.result_atはnull不可である。 result.result_at string(datetime) true false 保存済みの確定判断時刻を共通UTC形式で必ず返す。NULLを許可しない。COMMIT完了時刻と同一とは限らない。 result.durable boolean true false 保存済み結果なのでtrue固定とする。 http_status integer true false 保存済み元応答の200・201・404・409・503のいずれか。 observed_at string(datetime) true false 照会時の保存側UTC時刻。
unrecorded HTTP 404 NOT_RECORDED。現時点で本人の受付結果が見えない。未着と処理中と保存不成立を区別しない。 項目パス 型 必須 NULL可否 制約 request_id string(uuid) or null true true 妥当なID受理済みなら値、欠落・不正ではnull。 code string true false NOT_RECORDEDだけを返す。 message string true false 1〜200文字かつUTF-8で800バイト以下。
failed HTTP 400 INVALID_INPUT、401 UNAUTHENTICATED、403 FORBIDDEN、413 TOO_LARGEまたは503 LOOKUP_FAILED。 項目パス 型 必須 NULL可否 制約 request_id string(uuid) or null true true 妥当なID受理済みなら値、欠落・不正ではnull。 code string true false INVALID_INPUT、UNAUTHENTICATED、FORBIDDEN、TOO_LARGE、LOOKUP_FAILEDだけを返す。 message string true false 1〜200文字かつUTF-8で800バイト以下。
エラーと終了値 NOT_RECORDED、INVALID_INPUT、UNAUTHENTICATED、FORBIDDEN、TOO_LARGE、LOOKUP_FAILEDはcodeに返す。foundのresult.codeはIF001・IF002の保存済みコードをそのまま返す。 最大サイズ GET本文0バイト、パス・ヘッダー2048バイト以下、応答12288バイト以下とする提案である。 検査順 信頼済み権利→必須/欠落/null/未知項目→型とUUID→本人またはworkerの権利→保存済み情報の読取り→各業務条件の順とする。 再送・重複 何度読んでも同じ確定結果を返し、終端結果をpendingにしない。識別子が別利用者のものでも本人キーで検索してNOT_RECORDEDとする。 切断後の扱い 読取りだけを再試行できる。未記録や失敗で作成・取消を自動送信しない。 共通の状態 担当する責務 応答と状態の対応 状態定義 現在状態 応答名 次状態 遷移 理由 ST002 ready found ready null foundだけが今回の保存済み結果を確定できる。未記録・読取失敗は元の確認状態を保つ。 ST002 ready unrecorded ready null foundだけが今回の保存済み結果を確定できる。未記録・読取失敗は元の確認状態を保つ。 ST002 ready failed ready null foundだけが今回の保存済み結果を確定できる。未記録・読取失敗は元の確認状態を保つ。 ST002 known found known null foundだけが今回の保存済み結果を確定できる。未記録・読取失敗は元の確認状態を保つ。 ST002 known unrecorded known null foundだけが今回の保存済み結果を確定できる。未記録・読取失敗は元の確認状態を保つ。 ST002 known failed known null foundだけが今回の保存済み結果を確定できる。未記録・読取失敗は元の確認状態を保つ。 ST002 unknown found known TR007 foundだけが今回の保存済み結果を確定できる。未記録・読取失敗は元の確認状態を保つ。 ST002 unknown unrecorded unknown null foundだけが今回の保存済み結果を確定できる。未記録・読取失敗は元の確認状態を保つ。 ST002 unknown failed unknown null foundだけが今回の保存済み結果を確定できる。未記録・読取失敗は元の確認状態を保つ。
許可状態と権利と副作用 ready・known・unknownから本人の結果読取権限で許可し、sending中の多重操作は画面で抑止する。予約の終端でも照会可能である。書込み・返却は行わない。入力方針:GET本文は許可せず0バイトとする。必須params/contextの欠落、null、未知・重複queryを拒否する。context.owner_idは受付が認証から付与する。
id IF005 名前 現在の在庫と予約照会 呼出し元 ブラウザ・受付 呼出し先 予約サービス・保存リポジトリ 通信経路 HTTP GET /api/v1/items/{item_id}?reservation_id={任意ID}、内部同期snapshot(item_id,reservation_id,owner_id) 入力と制約 現在値だけを取得し、過去の操作結果を推測しない。 要求の項目 項目パス 型 必須 NULL可否 制約 context.owner_id string(uuid) true false サーバー認証で確定した利用者。クライアントからの指定を許可しない。 params.item_id string(uuid) true false 登録済み備品ID。 query.reservation_id string(uuid) false false 欠落時は備品だけを取得する。指定時は本人かつ同じ備品の予約であることを検査する。
要求の欠落と未知項目 GET本文は0バイト、任意reservation_idだけ欠落を許し、指定されたnull・未知・重複query・必須params/context欠落を拒否する。contextは受付が付与する。 出力 応答候補の全項目を返す。確定した業務結果だけを保存し、コミット結果不明を保存済み拒否に変えない。 応答の種類と項目 名前 意味と条件 項目 snapshot HTTP 200。現在の在庫と任意の予約を同一読取りスナップショットで返す。 項目パス 型 必須 NULL可否 制約 item_id string(uuid) true false 対象備品ID。 available integer true false 0〜1000000000。observed_atの同一スナップショットの残数。 capacity integer true false 0〜1000000000の登録済み総数。 inventory_version string true false 0〜9223372036854775807の10進文字列。JavaScriptの丸めを避ける。 observed_at string(datetime) true false 保存側の共通UTC時刻。 reservation_id string(uuid) or null true true 任意の予約IDを指定し本人の予約を確認した場合だけ値、未指定ならnull。 state string or null true true 予約指定時active・cancelled・expired、未指定ならnull。 created_at string(datetime) or null true true 予約指定時の保存値、未指定ならnull。 expires_at string(datetime) or null true true 予約指定時の保存値、未指定ならnull。 due boolean or null true true 予約指定時はobserved_at>=expires_at。未指定ならnull。activeかつtrueは期限処理待ちであり、読取りは状態変更しない。
failed 400 INVALID_INPUT、401 UNAUTHENTICATED、403 FORBIDDEN、413 TOO_LARGE、404 NOT_FOUND、503 LOOKUP_FAILED。指定予約がない・他人・別備品の場合はNOT_FOUND。 項目パス 型 必須 NULL可否 制約 code string true false INVALID_INPUT、UNAUTHENTICATED、FORBIDDEN、TOO_LARGE、NOT_FOUND、LOOKUP_FAILEDだけを返す。 message string true false 1〜200文字かつUTF-8で800バイト以下。
エラーと終了値 INVALID_INPUT、UNAUTHENTICATED、FORBIDDEN、TOO_LARGE、NOT_FOUND、LOOKUP_FAILEDをcodeで返す。 最大サイズ GET本文0バイト、パス・ヘッダー2048バイト以下、応答4096バイト以下とする提案である。 検査順 信頼済み権利→必須/欠落/null/未知項目→型とUUID→本人またはworkerの権利→保存済み情報の読取り→各業務条件の順とする。 再送・重複 読取りの反復だけを許可し、期限到達を見つけてもこの境界では返却しない。 切断後の扱い 現在値の取得失敗は前の表示に取得時刻を付けて残し、操作結果のunknownを解消しない。 共通の状態 担当する責務 応答と状態の対応 状態定義 現在状態 応答名 次状態 遷移 理由 ST001 absent snapshot absent null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 absent failed absent null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 active snapshot active null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 active failed active null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 cancelled snapshot cancelled null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 cancelled failed cancelled null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 expired snapshot expired null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。 ST001 expired failed expired null 確定した業務状態を変更しない。再送照合と読取りは過去結果の取得である。
許可状態と権利と副作用 absent・active・cancelled・expiredで認証済みの在庫読取と本人予約読取権限を許可する。状態・在庫・受付結果への副作用はない。入力方針:GET本文は0バイト、任意reservation_idだけ欠落を許し、指定されたnull・未知・重複query・必須params/context欠落を拒否する。contextは受付が付与する。
物理データ
備品予約の作成・取消・期限処理・切断後の結果照会と、それを支える画面・保存・確認条件を設計する。
tables
id T001 名前 inventory 目的 備品一種類ごとの総数・残数と在庫更新版を保持する。 物理列 名前 型 NULL可否 既定値 制約 参照先 状態定義 キーへの所属 item_id UUID false 既定値なし。必須値を明示する。 登録済み備品の識別子。 参照先なし。 null PK 1 capacity INTEGER false 既定値なし。必須値を明示する。 CHECK 0<=capacity AND capacity<=1000000000。 参照先なし。 null — available INTEGER false 既定値なし。必須値を明示する。 CHECK 0<=available AND available<=capacity。 参照先なし。 null — version BIGINT false 0 CHECK 0<=version。更新時に上限未満を検査して1増やす。 参照先なし。 null — updated_at TIMESTAMPTZ(6) false 既定値なし。必須値を明示する。 在庫を更新した保存側UTC時刻。 参照先なし。 null —
主キーの列構成 一意キーの列構成 — キーの理由 item_idで一種類を識別する。追加の一意キーは設けない。 制約 予約作成・返却ではavailableとversionを同じ行更新で変更する。 capacity=available+同備品のactive予約quantity合計を全成功コミットの不変条件とする。期限到達後もactiveなら合計に含む。集約CHECKは設けずサービスの同一ロックと検査で守る。 索引 — 索引の採用理由 item_idによる行ロックと取得だけのため追加索引は置かない。 更新の単位 F001〜F003で予約・必要な受付結果と一つのトランザクションにする。 削除の単位と順序 この設計範囲で自動削除・補充・capacity変更は行わない。 移行手順 初回導入はサービス受付・期限監視を停止した状態で移行トランザクションに表・CHECK・参照制約・索引を作成し、全成功後だけ開始する。既存データの上書きはしない。失敗は全ROLLBACKして旧版を維持し受付を開始しない。将来変更は拡張→データ検査→切替の順とし、削除や型縮小は本案の対象外とする。実DB移行はU001で未実施である。
id T002 名前 reservations 目的 引当数量と期限、返却確定状態を保存する。 物理列 名前 型 NULL可否 既定値 制約 参照先 状態定義 キーへの所属 reservation_id UUID false 既定値なし。必須値を明示する。 サーバーが作成する予約ID。 参照先なし。 null PK 1 owner_id UUID false 既定値なし。必須値を明示する。 認証済み利用者ID。外部認証DBへの参照制約は置かない。 参照先なし。 null — item_id UUID false 既定値なし。必須値を明示する。 作成後変更しない。 T001.inventory.item_idへの参照制約。削除RESTRICT。 null — quantity INTEGER false 既定値なし。必須値を明示する。 CHECK 1<=quantity AND quantity<=1000000。作成後変更しない。 参照先なし。 null — state TEXT false 既定値なし。必須値を明示する。 CHECK state IN ('active','cancelled','expired')。absentを保存しない。 参照先なし。 ST001 — created_at TIMESTAMPTZ(6) false 既定値なし。必須値を明示する。 行ロック後の作成判定時刻。作成後変更しない。 参照先なし。 null — expires_at TIMESTAMPTZ(6) false 既定値なし。必須値を明示する。 CHECK expires_at=created_at+interval '10 minutes'。作成後変更しない。 参照先なし。 null — ended_at TIMESTAMPTZ(6) true NULL activeではNULL、cancelledとexpiredでは必須。cancelledはcreated_at<=ended_at<expires_at、expiredはended_at>=expires_at。 参照先なし。 null —
主キーの列構成 一意キーの列構成 — キーの理由 reservation_idで識別する。本人照合はowner_id条件で行い、追加の一意キーは設けない。 制約 CHECK (state=active AND ended_at IS NULL) OR (state=cancelled AND ended_at IS NOT NULL AND ended_at>=created_at AND ended_at<expires_at) OR (state=expired AND ended_at IS NOT NULL AND ended_at>=expires_at)を満たす。 activeからcancelledまたはexpiredだけを許す更新をサービスと状態条件で守る。owner_id・item_id・quantity・時刻は不変とする。 索引 idx_reservations_due(expires_at,reservation_id) WHERE state='active'。期限候補の先頭から走査する。 idx_reservations_item_state(item_id,state)。不変条件の照合と運用確認に用いる。 索引の採用理由 期限検索と整合確認の走査を抑える提案であり、負荷・実行計画はU001で未確認である。 更新の単位 activeからの状態更新と在庫返却は必ず同じトランザクションにする。 削除の単位と順序 終端を含め自動削除しない。参照先の備品を消さず、結果照会を継続する。 移行手順 初回導入はサービス受付・期限監視を停止した状態で移行トランザクションに表・CHECK・参照制約・索引を作成し、全成功後だけ開始する。既存データの上書きはしない。失敗は全ROLLBACKして旧版を維持し受付を開始しない。将来変更は拡張→データ検査→切替の順とし、削除や型縮小は本案の対象外とする。実DB移行はU001で未実施である。
id T003 名前 request_results 目的 本人の受付識別子と正規化内容、確定した共通応答を不変で保持する。 物理列 名前 型 NULL可否 既定値 制約 参照先 状態定義 キーへの所属 owner_id UUID false 既定値なし。必須値を明示する。 サーバー認証で得た利用者ID。 参照先なし。 null PK 1 request_id UUID false 既定値なし。必須値を明示する。 クライアントが一操作ごとに生成した受付用識別子。 参照先なし。 null PK 2 operation TEXT false 既定値なし。必須値を明示する。 CHECK operation IN ('create','cancel')。 参照先なし。 null — canonical_request JSONB false 既定値なし。必須値を明示する。 createではitem_idとquantity、cancelではreservation_idを正規型で持つ。operationと合わせて構造比較し、未知キーを持たない。 参照先なし。 null — reservation_id UUID true NULL 実在予約に結び付く結果ではそのID、備品なし・在庫不足等の予約なし拒否ではNULL。 T002.reservations.reservation_idへの参照制約。削除RESTRICT。 null — http_status SMALLINT false 既定値なし。必須値を明示する。 200・201・404・409・503の保存対象だけを許可する。 参照先なし。 null — response_body JSONB false 既定値なし。必須値を明示する。 IF001・IF002の共通9項目を欠落なく保存する。durable=true、request_idは列と同じ、result_atは非NULL。COMMIT_UNKNOWN、SAVE_FAILED、事前拒否とID_CONFLICTは保存しない。 参照先なし。 null — recorded_at TIMESTAMPTZ(6) false 既定値なし。必須値を明示する。 応答構築時の保存側UTC時刻。response_body.result_atと同じ値。 参照先なし。 null —
主キーの列構成 一意キーの列構成 — キーの理由 owner_idとrequest_idの複合主キーで、操作種別をまたいで一回の受付を識別する。request_id単独の一意性は要求しない。 制約 operationとcanonical_requestのキー・型、response_bodyのキー・型・NULL条件はアプリケーションで検査し、NOT NULLとコード集合・durable=trueはCHECKも設ける。 確定行は更新しない。作成/取消の成功と業務拒否を最後にINSERTし、衝突した試行は在庫・予約を含め全ROLLBACKして勝者を再読する。 索引 — 索引の採用理由 本人と受付識別子の完全一致取得だけのため追加索引は置かない。 更新の単位 成功時の在庫・予約の更新と受付結果INSERTは同じCOMMIT。NO_STOCK・NOT_FOUND・VERSION_LIMIT等の業務拒否は受付結果だけをCOMMITする。 削除の単位と順序 自動削除しない。識別子再利用と過去結果の喪失を防ぐ。保管期間と容量の承認はU003に残す。 移行手順 初回導入はサービス受付・期限監視を停止した状態で移行トランザクションに表・CHECK・参照制約・索引を作成し、全成功後だけ開始する。既存データの上書きはしない。失敗は全ROLLBACKして旧版を維持し受付を開始しない。将来変更は拡張→データ検査→切替の順とし、削除や型縮小は本案の対象外とする。実DB移行はU001で未実施である。
画面
備品予約の作成・取消・期限処理・切断後の結果照会と、それを支える画面・保存・確認条件を設計する。
screens
id UI001 名前 備品予約画面 項目 item_id、在庫available/capacityと取得時刻、数量入力、予約ID・状態・期限、今回の操作結果と識別子を表示する。状態表示はactive=予約中、cancelled=取消済み、expired=期限切れ、absent=予約なしとする。過去のstate_at_resultと現在のstateはラベルを分ける。 入力検査 quantityの整数1〜1000000と画面の残数以下を検査する。サーバーでも同じ型・上限を再検査し、在庫の権威は保存側に置く。画面の残数は同時更新で変わるため成功を先に表示しない。 表示状態 ST002のready=入力可能、sending=結果待ち、known=結果確認済み、unknown=成否未確認とする。初回読込・読取中は状態表示に読込中を添え、結果取得まで該当操作を無効にする。読取失敗は旧値に取得時刻と失敗を添える。activeかつdue=trueは期限到達・返却処理待ちを添え、expiredとは分ける。 操作と可否 readyで在庫1以上かつ有効数量なら予約できる。readyかつ本人activeで保存側スナップショットのdue=falseの場合だけ取消ボタンを許可し、サーバーでも期限を再検査する。画面の期限到達で取消を即無効化しIF005を読む。sendingは多重操作不可。unknownは結果照会と現在値読取りだけを許可し作成・取消の自動送信をしない。knownから新操作は最新IF005を取得してTR008でreadyへ進める。期限切れ・取消済みは取消不可である。 保存結果 CREATED、CANCELLED、期限切れ、在庫不足、識別子競合、保存不成立、成否未確認を文字で区別する。durable=trueの操作結果は確定時残数として示し、IF005の現在残数と混同しない。IF004のNOT_RECORDEDではunknownを保つ。 フォーカスとキーボード操作 TabとShift+Tabで数量→予約→取消→結果照会→現在値更新へ移動し、Enter/Spaceで各ボタンを操作できる。無効ボタンは実行しない。数量エラーは数量へ、他エラーと操作結果はライブ領域へ通知する。取消や期限切れで押下ボタンが無効になったら結果見出しへフォーカスを移し、結果照会後もそこへ移す。 更新通知 操作後と再表示時にIF005を読み、最大5秒間隔で読取りを更新する。古い応答には画面内の世代番号を付け、後から到着した旧世代を捨てる。request_id・内容・ST002をsessionStorageへ保持し、再読込み後のsendingはunknownとして復元する。明示的なログアウトでは本人の画面内記録を消去し、他人へ表示しない。ブラウザ保存を失った場合の履歴検索は対象外である。 共通の状態 使う境界
要件と確認条件
備品予約の作成・取消・期限処理・切断後の結果照会と、それを支える画面・保存・確認条件を設計する。
requirements
id R001 内容 数量指定の予約と残数表示、最後の1個の同時作成でも在庫を負にしない。 理由 共通仕様・対応する機能・確認条件へ具体化する。 根拠 対象機能 確認条件 関連する未決 — 設計の状態 designed
id R002 内容 作成から10分、取消または期限切れで一回だけ返却し、保存側時刻の等号は期限切れとする。 理由 共通仕様・対応する機能・確認条件へ具体化する。 根拠 対象機能 確認条件 関連する未決 — 設計の状態 designed
id R003 内容 同じ受付用識別子と同じ内容は再作成せず、違う内容は競合にする。 理由 共通仕様・対応する機能・確認条件へ具体化する。 根拠 対象機能 確認条件 関連する未決 — 設計の状態 designed
id R004 内容 保存後に応答し、切断と再起動後は識別子で確定結果を照会し更新を自動再実行しない。 理由 共通仕様・対応する機能・確認条件へ具体化する。 根拠 対象機能 確認条件 関連する未決 — 設計の状態 designed
id R005 内容 画面で残数・予約状態・操作結果を分け、期限切れ後の取消を受け付けずキーボード操作を可能にする。 理由 共通仕様・対応する機能・確認条件へ具体化する。 根拠 対象機能 確認条件 関連する未決 — 設計の状態 designed
checks
id C001 区分 normal 開始時の条件 在庫3、本人の新しい受付用識別子、quantity=2を用意する。 行う操作・発生する事象 IF001で作成し、IF004とIF005を読む。 観測する結果 CREATED、予約active、残数1、expires_at=created_at+10分、受付結果一件となる。保存済み共通応答と操作表示が一致する。 対象機能 関連する未決
id C002 区分 boundary 開始時の条件 数量0・1・1000000・1000001、小数・真偽値・文字列、UUID不正、必須欠落、null、未知/重複キー、4096/4097バイトの要求を用意する。 行う操作・発生する事象 IF001とIF002を呼ぶ。 観測する結果 整数と範囲・サイズ・形を全て満たす要求だけが業務処理へ進む。不正はINVALID_INPUTまたはTOO_LARGE等で在庫・予約・受付結果を更新しない。欠落IDの応答request_idはnullであり欠落値を必須UUIDとして返さない。 対象機能 関連する未決
id C003 区分 race 開始時の条件 同じ備品のavailable=1と異なる受付識別子二つを用意する。 行う操作・発生する事象 quantity=1の作成を同期して同時到着させる。 観測する結果 CREATEDは一件、他方NO_STOCK、available=0、active合計=1となる。二件の受付結果を記録し、負在庫と二重引当を生じない。 対象機能 関連する未決
id C004 区分 boundary 開始時の条件 active予約の期限をTとし、ロック後に採る判定時刻をT-1マイクロ秒に固定できる試験構成とする。 行う操作・発生する事象 本人がIF002で取消する。 観測する結果 TR002でcancelled、一回だけquantityを返却しCANCELLEDを記録する。ended_at<Tであり受付結果・在庫・状態が同時確定する。 対象機能 関連する未決
id C005 区分 boundary 開始時の条件 active予約の期限T、監視遅延、判定時刻TとT+1マイクロ秒の二条件を用意する。 行う操作・発生する事象 IF002またはIF003を呼び、後で同じ予約を再処理する。 観測する結果 どちらもTR003でexpiredと一回返却になる。取消の応答はEXPIRED、監視はappliedであり、次回はterminal/no_opで二回目の返却がない。 対象機能 関連する未決
id C006 区分 race 開始時の条件 active予約に本人取消二件と期限処理を用意し、期限直前・等号・直後を制御する。 行う操作・発生する事象 全処理を同時開始し備品ロック待機を注入する。 観測する結果 ロック取得後の時刻で勝敗が決まり、期限前に確定した取消だけcancelled、期限到達ならexpiredとなる。available増分はquantity一回、version増分一回で終端を覆さない。待機前時刻を使わない。 対象機能 関連する未決
id C007 区分 restart 開始時の条件 期限到達activeを含む複数予約と監視停止・再起動を用意する。 行う操作・発生する事象 監視を止め期限を越え、起動時に候補を最大100件ずつ処理する。 観測する結果 期限到達activeは返却まで処理待ち表示となり取消受付は期限再検査でEXPIREDとなる。各予約の返却一回と不変条件を保ち、候補が次の走査で消失しない。 対象機能 関連する未決
id C008 区分 race 開始時の条件 同一owner_id+request_idで同じ作成内容または同じ取消内容を二件用意する。 行う操作・発生する事象 同時に送信し、受付結果最終INSERTの前後で待機を注入する。 観測する結果 共通応答は一つの保存結果に一致し、作成予約は一件、取消返却は一回である。仮更新敗者は全ROLLBACKし、再送で期限を延ばさない。 対象機能 関連する未決
id C009 区分 race 開始時の条件 同一受付識別子で異なるquantity・item_id・操作種別を用意する。既存結果ありと未登録の同時到着を分ける。 行う操作・発生する事象 IF001/IF002を競合させる。 観測する結果 勝者の結果だけが固定され、相違側はID_CONFLICT、相違側の在庫・予約仮更新は全て戻る。別ownerの同じIDは独立し情報を漏らさない。 対象機能 関連する未決
id C010 区分 error 開始時の条件 作成・取消・期限処理で在庫更新後、予約更新後、受付結果INSERT後、COMMIT前に失敗を注入する。 行う操作・発生する事象 ROLLBACK成立を確認し、DBと応答を読む。 観測する結果 旧在庫・旧状態・旧受付結果を保ちSAVE_FAILEDを返す。新規予約や返却だけが残らない。version上限では更新しない。作成・取消はVERSION_LIMITの受付結果を記録し、期限処理はVERSION_LIMITのfailedを返して監視に残す。実行前検査拒否と保存不成立を区別する。 対象機能 関連する未決
id C011 区分 restart 開始時の条件 作成と取消のCOMMIT送信中、COMMIT後応答前、応答受信後の各切断位置とブラウザ再読込みを用意する。 行う操作・発生する事象 元request_idでIF004を繰り返し読み、IF005も読む。 観測する結果 確定済みならfoundの元結果が一致しunknown→known、未記録/照会失敗ならunknownを保つ。送信中切断を旧状態維持と断定しない。作成・取消の自動再実行が0回であり、現在値だけで元操作の成功を断定しない。 対象機能 関連する未決
id C012 区分 restart 開始時の条件 期限処理のCOMMIT直前と直後で停止し、結果不明も作る。 行う操作・発生する事象 保存済み予約を再読して監視を再起動する。 観測する結果 activeなら条件を再検査し一回返却、expired/cancelledならno_opである。結果照会/現在値読取りは副作用0回、availableの逆補正をしない。 対象機能 関連する未決
id C013 区分 normal 開始時の条件 UI001をキーボードだけで操作し、在庫変化と入力不正・成功・切断を用意する。 行う操作・発生する事象 予約・取消・結果照会・現在値更新と新しい操作への移行を行う。 観測する結果 フォーカス順・エラー復帰・結果ライブ通知が機能し、sending多重送信を防ぐ。unknownは照会だけ、knownからは最新取得後readyへ進む。旧世代の読取応答で現在値を巻き戻さない。 対象機能 関連する未決
id C014 区分 boundary 開始時の条件 作成成功の受付結果を残し、その予約を期限切れにする。他人のID・欠落ID・任意予約ID未指定の読取りも用意する。 行う操作・発生する事象 IF004とIF005を呼ぶ。 観測する結果 IF004は元CREATED・activeを固定して返し、IF005は現在expiredと返却後残数を返す。終端結果をpendingにしない。他人の結果はNOT_RECORDED、他人/別備品予約はNOT_FOUND、任意予約ID欠落は在庫だけで予約各項目null、指定nullはINVALID_INPUTとなる。 対象機能 関連する未決
状態と遷移
備品予約の作成・取消・期限処理・切断後の結果照会と、それを支える画面・保存・確認条件を設計する。
保存側のPostgreSQL時刻をUTC・マイクロ秒精度で扱う。作成時は備品行ロック取得後のclock_timestamp()を一度採りcreated_atとし、expires_at=created_at+interval '10 minutes'とする。取消・期限処理は必要な行ロックを全て取得した後に判定時刻を一度採る。判定時刻<expires_atだけ取消でき、等号と直後は期限切れとする。待機前のトランザクション開始時刻や画面時刻を判定に使わない。JSONはYYYY-MM-DDTHH:mm:ss.ffffffZとする。読取りのobserved_atも保存側から取得する。10分は引継ぎ条件、精度と取得関数はD002の提案である。
state_sets
id ST001 対象 予約の業務状態 状態と意味 名前 意味 absent 予約が存在しない仮想状態である。DBへabsent行は保存しない。 active 数量を在庫から引き当てた予約である。期限到達後も返却コミットまで引当は保持し、取消受付では時刻を再検査する。 cancelled 期限より前の利用者取消により一回の返却を確定した終端である。 expired 期限到達により一回の返却を確定した終端である。
id ST002 対象 画面の操作結果確認状態 状態と意味 名前 意味 ready 新しい操作を入力できる状態である。 sending 一つの作成または取消の応答を待つ状態である。 known 応答または照会により今回の確定結果、更新前拒否、保存不成立のいずれかを確認した状態である。 unknown 切断・コミット結果不明・受付結果未記録により成否を断定できない状態である。
transitions
id TR001 状態定義 ST001 現在状態 absent イベント 作成成功 遷移条件 在庫行ロック後に数量と上限を検査し受付結果の競合がない。 次状態 active 保存の内容と原子性 在庫減算・予約INSERT・受付結果INSERTを同じCOMMITで確定する。 通知 CREATEDをCOMMIT成立後に返す。 確認条件
id TR002 状態定義 ST001 現在状態 active イベント 期限内の取消 遷移条件 全行ロック後の判定時刻<expires_atである。 次状態 cancelled 保存の内容と原子性 状態条件activeで更新し在庫加算・version増加・取消受付結果を同時COMMITする。 通知 CANCELLEDと操作時点の残数を返す。 確認条件
id TR003 状態定義 ST001 現在状態 active イベント 期限到達 遷移条件 全行ロック後の判定時刻>=expires_atである。取消または期限監視が同じ条件を使う。 次状態 expired 保存の内容と原子性 状態条件activeで更新し在庫加算・version増加を同時COMMITする。取消起点ならEXPIREDの受付結果も含める。 通知 取消にはEXPIRED、監視にはappliedを返し、画面は次の読取りで更新する。 確認条件
id TR004 状態定義 ST002 現在状態 ready イベント 新しい操作の送信 遷移条件 画面入力検査を通り、操作識別子を保存し一回だけPOSTする。 次状態 sending 保存の内容と原子性 画面メモリとsessionStorageに操作種別・識別子・正規化内容を保存する。業務更新はF001/F002へ委ねる。 通知 作成・取消・結果照会の重複起動を抑止する。 確認条件
id TR005 状態定義 ST002 現在状態 sending イベント 確定応答または保存不成立を受信 遷移条件 IF001/IF002のunconfirmed以外を受信した。SAVE_FAILEDはROLLBACK確認済みである。 次状態 known 保存の内容と原子性 結果を画面とsessionStorageへ保持する。durable=falseの拒否は保存済み結果と表示を分ける。 通知 成功・期限切れ・拒否・保存不成立を文字で通知する。 確認条件
id TR006 状態定義 ST002 現在状態 sending イベント 応答切断または確定不明 遷移条件 応答未受信、通信切断、503 COMMIT_UNKNOWNである。 次状態 unknown 保存の内容と原子性 実DB状態を断定せず操作識別子を保持する。 通知 未確認と結果照会を表示する。 確認条件
id TR007 状態定義 ST002 現在状態 unknown イベント 識別子で確定結果を取得 遷移条件 IF004のfoundでdurable=trueの保存済み結果を得た。 次状態 known 保存の内容と原子性 元操作の共通応答を表示する。現在値はIF005で別に得る。 通知 結果照会で確認できた旨を通知する。 確認条件
id TR008 状態定義 ST002 現在状態 known イベント 利用者が新しい操作を開始 遷移条件 既存結果を確認し、最新のIF005スナップショットを取得した。 次状態 ready 保存の内容と原子性 過去の操作結果を履歴表示に残し、新操作には新しいrequest_idを発行する。 通知 新たな入力へフォーカスを移す。 確認条件
並行制御
備品予約の作成・取消・期限処理・切断後の結果照会と、それを支える画面・保存・確認条件を設計する。
保存側のPostgreSQL時刻をUTC・マイクロ秒精度で扱う。作成時は備品行ロック取得後のclock_timestamp()を一度採りcreated_atとし、expires_at=created_at+interval '10 minutes'とする。取消・期限処理は必要な行ロックを全て取得した後に判定時刻を一度採る。判定時刻<expires_atだけ取消でき、等号と直後は期限切れとする。待機前のトランザクション開始時刻や画面時刻を判定に使わない。JSONはYYYY-MM-DDTHH:mm:ss.ffffffZとする。読取りのobserved_atも保存側から取得する。10分は引継ぎ条件、精度と取得関数はD002の提案である。
concurrency
id P001 保護するデータ 同一備品のavailable・versionと予約quantity、予約状態、受付用識別子の確定結果を保護する。 排他の範囲 READ COMMITTEDでinventory行をFOR UPDATEし、取消/期限処理は対応するreservations行もロックする。request_resultsの複合主キー競合を最終判定とする。画面のボタン無効だけに依存しない。 取得順序 書込みは備品行→既存予約行→受付結果の最終INSERTの順である。作成は予約行INSERT、期限処理は受付結果なしである。予約IDからitem_idを先に非ロック読取りしても、その値は不変としロック後に再読する。1保存単位は1備品・1予約・1受付結果までとし、複数候補を一括ロックしない。 確保する時点 入力と認証後に行ロックを取得し、ロック後に状態・数量・期限・受付結果を再検査する。仮の在庫確保を別保存単位へ持ち出さない。 解放する時点 COMMITまたは全ROLLBACKで全ロックを解放する。HTTP応答・画面更新を待ちながらロックしない。 上限の更新 在庫の減算/加算とversion増加は同じCOMMITである。versionのBIGINT上限は更新前に検査し、作成・取消はVERSION_LIMITを受付結果として確定し、期限処理はfailedで返し監視に残す。capacity超過や負在庫は制約違反として全ROLLBACKしSAVE_FAILEDとし、運用調査する。プロセスの実行枠は在庫引当と別物であり本機能に枠数設定はない。 時刻と等号 数量の勝敗はロック後のavailable、期限の勝敗はロック後の一度の保存側時刻で決める。期限と等しい取消はexpiredへ進む。 競合の勝敗 最後の1個への別識別子の同時作成は先に確定した一件が成功し、他方はNO_STOCKとなる。取消と期限処理はactiveを最初に確定した一件だけが返却し、終端を覆さない。 確認条件
id P002 保護するデータ owner_id+request_idの同時再送と、異なる内容の衝突を保護する。 排他の範囲 受付結果は最終INSERTの複合主キーで勝者を決める。受付結果を読むだけの事前照合を排他の代用にしない。 取得順序 P001の順を守る。競合する受付結果INSERTが失敗したら在庫と予約を含め全ROLLBACKし、ロック解放後に新たな読取りトランザクションで勝者結果を取得する。 確保する時点 備品ロック後にも受付結果を再読する。異なる備品や操作の同じ識別子でも最終INSERTを省略しない。 解放する時点 勝者のCOMMIT/ROLLBACKで識別子競合が解消する。敗者はROLLBACK後にだけ結果を返す。 上限の更新 同内容の再送を新たな引当回数に数えない。衝突による仮更新も全ROLLBACKする。識別子数の上限と受付結果の削除はU003の保管設計で決め、ここでは削除しない。 時刻と等号 勝者の保存済み期限と結果を再利用する。再送の到着時刻から10分を延ばさない。 競合の勝敗 同内容は勝者の同じ応答、異内容はID_CONFLICTとなる。勝者が業務拒否ならその拒否も固定する。識別子衝突で負けた仮の在庫更新は残らない。 確認条件
障害と回復
備品予約の作成・取消・期限処理・切断後の結果照会と、それを支える画面・保存・確認条件を設計する。
保存側のPostgreSQL時刻をUTC・マイクロ秒精度で扱う。作成時は備品行ロック取得後のclock_timestamp()を一度採りcreated_atとし、expires_at=created_at+interval '10 minutes'とする。取消・期限処理は必要な行ロックを全て取得した後に判定時刻を一度採る。判定時刻<expires_atだけ取消でき、等号と直後は期限切れとする。待機前のトランザクション開始時刻や画面時刻を判定に使わない。JSONはYYYY-MM-DDTHH:mm:ss.ffffffZとする。読取りのobserved_atも保存側から取得する。10分は引継ぎ条件、精度と取得関数はD002の提案である。
recovery
id RC001 停止した場所 在庫の仮更新後・受付結果登録前またはCOMMIT前に停止し、ストレージ回復でROLLBACKを確認できた。 確定済みの内容 その保存単位の在庫・予約・受付結果は一件も確定していない。既存の確定値だけが有効である。 残る情報 旧在庫・旧予約状態と既存結果が残る。未コミットの予約と結果は読めない。 再起動と再開 DB回復後に受付結果と現在値を読む。保存不成立が確認できた応答だけSAVE_FAILEDとする。期限監視はactive候補を再検索できる。 再試行の条件 作成・取消は自動再送しない。利用者が明示的に同じ操作を再試行する場合だけ同じ識別子・同じ内容を使い、P002の照合を必ず通す。画面の標準操作は結果照会を提供する。 呼出し元と画面の結果 ROLLBACK確認済みのSAVE_FAILEDを受け取った画面はknownの保存不成立、未受信の画面はunknownである。IF004の未記録だけではROLLBACKを推論しない。 確認条件
id RC002 停止した場所 COMMIT送信中に接続が失われた、またはCOMMIT後・HTTP応答前に停止した。 確定済みの内容 COMMIT後停止では在庫・予約・受付結果が同時確定している。COMMIT送信中の障害では確定の有無が不明であり、状態維持も成功も断定しない。 残る情報 確定していれば不変の受付結果が残る。不明なら残るかどうかも照会まで断定しない。画面はsessionStorageの本人のrequest_idと正規化内容を保持する。 再起動と再開 IF004を本人権限で呼ぶ。foundなら保存済み結果を返しunknown→knownとする。unrecordedとfailedならunknownを保ち、IF005の現在値とは区別する。再読み込み時にsendingが残っていた画面はunknownとして復元する。 再試行の条件 結果照会の再試行は読取りだけである。作成・取消・返却の自動再実行も在庫の逆補正も行わない。 呼出し元と画面の結果 過去のCREATEDと現在expiredが同時に表示されても矛盾しない。前者は操作確定時点、後者は現在値である。terminalからpendingへ戻さない。 確認条件
id RC003 停止した場所 期限監視が停止する、または期限処理のCOMMIT前後で停止する。外部送信は存在しないためその前後停止は非該当である。 確定済みの内容 expiredのCOMMITがあれば在庫返却済み、activeなら未返却である。確定不明時は保存済み状態を再読するまで断定しない。 残る情報 予約のexpires_atとstate、在庫残数が残る。プロセスメモリの候補一覧は回復の根拠にしない。 再起動と再開 起動時に期限到達activeを検索し、IF003へ予約IDだけを渡す。expired/cancelledはno_op、activeはロック後の期限再検査でTR003を適用する。取消からも同じ期限条件で返却できる。 再試行の条件 1予約単位で同じ条件付き操作を再試行する。終端を戻したり先に在庫だけ補正したりしない。障害が続く候補はログと監視で検出し走査から消さない。 呼出し元と画面の結果 処理待ちactiveかつdue=trueは画面で期限到達・処理待ちと示し取消を無効にする。返却確定後はexpiredと最新在庫を表示する。 確認条件
情報の区分と判断
備品予約の作成・取消・期限処理・切断後の結果照会と、それを支える画面・保存・確認条件を設計する。
根拠 id 項目パス line end_line 区分 S001 docs/requirement.md 3 3 requirement S002 docs/requirement.md 4 4 requirement S003 docs/requirement.md 5 5 requirement S004 docs/requirement.md 6 6 requirement S005 docs/requirement.md 7 7 requirement S006 docs/basic-design.md 3 3 basic_design S007 docs/basic-design.md 5 5 basic_design S008 docs/basic-design.md 6 8 basic_design S009 docs/basic-design.md 9 9 basic_design
decisions
id D001 区分 inherited 内容 HTTP JSON、PostgreSQL、責務の分離、作成の同時確定、状態条件による一回返却、保存側UTCと確定後応答を引き継ぐ。基本設計自身が設計案と明記しており、採用済みや実装検証済みとは扱わない。 根拠 採用判断 proposed 判断の証拠 — 検証内容・状態 unverified 検証の証拠 — 外部検証への依存 false 関連する未決
id D002 区分 proposed 内容 API v1、UUID正規形、数量・在庫の上限、JSONの4096バイト上限、UTC精度、物理型、READ COMMITTEDと行ロック、受付結果最終登録、期限監視1秒・100件、索引・移行・エラーを提案する。PostgreSQLの対象版は未選定であり、ロック待機後の時刻と競合ロールバックを実DBで検証してから採用する。 根拠 採用判断 proposed 判断の証拠 — 検証内容・状態 unverified 検証の証拠 — 外部検証への依存 true 関連する未決
id D003 区分 proposed 内容 認証済みowner_idをサーバーの信頼済み文脈として渡し、本人の予約と受付結果だけを操作・照会する。画面の状態、最大5秒間隔の読取り更新とキーボード操作を提案する。認証方式とアダプターの写像は未検証である。 根拠 採用判断 proposed 判断の証拠 — 検証内容・状態 unverified 検証の証拠 — 外部検証への依存 true 関連する未決
id D004 区分 proposed 内容 取消にも受付用識別子を設け、作成と同じ結果台帳へ保存する。結果照会の保証を守るため備品・予約・受付結果をこの範囲では自動削除しない。容量・個人情報の保管期間と運用承認が必要である。識別子再利用を認める変更は互換性を別途設計する。 根拠 採用判断 proposed 判断の証拠 — 検証内容・状態 unverified 検証の証拠 — 外部検証への依存 false 関連する未決
未決と変更
備品予約の作成・取消・期限処理・切断後の結果照会と、それを支える画面・保存・確認条件を設計する。
根拠 id 項目パス line end_line 区分 S001 docs/requirement.md 3 3 requirement S002 docs/requirement.md 4 4 requirement S003 docs/requirement.md 5 5 requirement S004 docs/requirement.md 6 6 requirement S005 docs/requirement.md 7 7 requirement S006 docs/basic-design.md 3 3 basic_design S007 docs/basic-design.md 5 5 basic_design S008 docs/basic-design.md 6 8 basic_design S009 docs/basic-design.md 9 9 basic_design
issues
id U001 未決の内容 PostgreSQL対象版・実装・実DBの原子性、競合、停止注入、負荷と移行は未検証である。外部サービスへの接続試験も今回実施していない。 検証内容・状態 開発側が対象版を記録し、C001〜C014、READ COMMITTEDの待機後再読、受付結果衝突の全ROLLBACK、時刻精度、DB回復、索引実行計画と移行失敗を隔離環境で試験する。外部サービスは採用する場合に別途接続契約を検証する。 採用できる結果 全不変条件・返却一回・確定結果照会が観測値で一致し、期限監視の遅延と負荷の目標値を関係者が決定し実測が満たすことを採用条件とする。文書検査では代替しない。 確認する担当 実装・DB・試験担当 影響する設計 D001 D002 F001 F002 F003 F004 P001 P002 T001 T002 T003 独立して進める範囲 APIモック、画面、台帳の対応、試験データ・停止点の設計は独立して進められる。
id U002 未決の内容 認証方式・権限の供給とHTTP/画面実装は未確認である。 検証内容・状態 owner_idとworker_roleの信頼境界、本人以外の照会拒否、JSONとNULLの写像、キーボード・ライブ領域・sessionStorage復元とログアウトを実装で試験する。外部認証サービスへは接続していない。 採用できる結果 利用者が他人の予約・結果を読書きできず、期限・状態・操作結果とフォーカスがUI001と一致することを採用条件とする。 確認する担当 認証・画面・試験担当 影響する設計 D003 IF001 IF002 IF003 IF004 IF005 UI001 独立して進める範囲 認証スタブを用いるAPI契約・画面設計・試験条件は独立して進められる。
id U003 未決の内容 設計案の採用承認、取消識別子の拡張、保管期間・容量、数値上限と監視間隔の合意は未実施である。 検証内容・状態 設計責任者と運用担当がD001〜D004の提案、結果照会の保持保証、削除しない場合の容量見積りと個人情報保管をレビューし、判断記録を残す。 採用できる結果 選択条件と制約が明示され判断の出典が残った場合だけadoptionをacceptedへ変更する。現段階では全件proposedを維持する。 確認する担当 設計責任者・運用担当 影響する設計 D001 D002 D003 D004 T003 UI001 独立して進める範囲 本書とAPIモック・確認条件をレビュー可能な案として作成できる。承認済みや動作保証として公開しない。
changes
資料間の不一致と要件変更はない。詳細化した方式・上限・認証と保管はD002〜D004の未承認提案として扱う。