PostgreSQLの書き足すだけで消さない履歴（追記型履歴）で試行と受領を分ける——入力版・検査・採用理由を追跡する

翌月の問い合わせに答えられない

月次の取引先通知を作成し、配信する業務を考えます。担当者の記録には「完了」とありますが、取引先から前月の金額が載っていたと連絡が来ました。どの集計を使ったか、作成後に訂正したか、どの版を配信したかが分からなければ、通知を作り直す前に原因を探し直すことになります。業務の完了表示とは別に、完了した内容と当時の判断を後から説明できる記録が必要です。

実行履歴に求める問いは「何時に動いたか」だけではありません。「何を入力として受け取り、何を試し、何が返り、どの検査を通り、どの成果を採用したか」です。入力から採用までの関係があれば、誤った通知が集計、文章化、承認、配信のどこで生まれたかを絞れます。大量の処理記録を保存するより、後から答える必要のある問いを先に定める方が、使える履歴を作りやすくなります。

今回の例では、通知の文章作成と実際の配信を別の工程にします。配信の許可がない段階は作成までで止めます。履歴があることを外部送信の許可に読み替えないことが必要です。過去の記録を調べる場合にも、同じ通知を再送しません。原因を確認する読み取りと、新たな配信は別の操作です。この境界を保ったまま、通知の版と配信の結果をつなぐ設計を考えます。

試したことと受け取ったことを分ける

配信を依頼した記録は、相手側が受け付けた記録と同じではありません。依頼の直後に通信が切れた場合、相手側では処理されている可能性があります。履歴には送信の試行と、受け取った応答を別に残します。応答がない場合は結果不明と示し、失敗の一語で未実行と見なさないようにします。文章生成でも、依頼した、文章が返った、保存したという段階は区別できます。

受領記録には対象の版を結び付けます。通知の一版目を送った後に本文を修正しても、配信記録を最新の本文へ差し替えてはいけません。届いた通知と現在の編集内容は違うからです。以前の本文を保管し、修正版との関係を示します。後から誤りが分かった場合は、以前の配信がなかったことにするのではなく、訂正を追加の出来事として残します。歴史を上書きしない考え方です。

時刻も出来事に応じて分けます。依頼した時刻、応答を受けた時刻、担当者が結果を確認した時刻は一致しない場合があります。障害を後から発見した時刻を、障害が起きた時刻として埋めないようにします。分からない時刻は分からないと記録します。精密な数字の形式を使っていても、推測した時刻なら精密な履歴にはなりません。測れた事実と解釈を別に残す必要があります。

入力と成果の版を結び付ける

通知を作る入力は、対象月、取引先、集計資料、文面の規則、配信先です。同じ月の通知でも、集計が訂正されると結果が変わります。どの資料の版を使ったかを記録し、成果の内容と対応させます。通知の名前だけでは版を識別できないことがあります。保存済みの内容が提出時と一致するかを確認する方法も使い、履歴が参照する成果が後から別の文章へ変わらないようにします。

全ての入力を記録へ複製する必要はありませんが、保存場所と参照先が変わっても版を確認できる情報が必要です。重要な資料は必要な保持期間を定めます。入力が削除された場合は、以前の通知を完全には再現できない限界を示します。履歴には参照先だけあるが中身はなくなっている、という状態を正常と見せないことが大切です。説明できる範囲は、残っている入力と成果によって決まります。

再現には処理の設定も関わります。同じ資料でも文面の規則が変われば、見出しや注意事項が変わります。ただし秘密の認証情報まで履歴へ残す必要はありません。結果に影響する設定と、実行に使う秘密を分けます。説明用の画面に秘密を載せずに、どの条件で処理したかは示せます。何でも保存する方針より、必要な説明と安全な取り扱いの両方を満たす項目を定めます。

検査と採用を一つの成功にしない

文章が返った後、金額、対象月、取引先の一致を検査し、文面の読みやすさをレビューします。検査に合格したことは、配信を承認したこととは違います。承認したことも、配信が成功したこととは違います。それぞれの結果を履歴へ残せば、「作成は済み、配信は未承認」と説明できます。全工程のどこかが成功しただけで、最終の仕事を完了と表示しないことが必要です。

警告があっても採用する場合は、何を許容したかを残します。例えば住所の表記ゆれは配信先が一致しているため許容したが、金額の相違は許容しない、といった判断です。「警告ありで成功」だけでは次回に同じ条件を判断できません。採用理由は短い文章で具体化します。許容の判断を後から自動的な正しさへ置き換えず、誰がどの基準で決めたかを示すことが重要です。

検査後に成果が変わった場合は、以前の合格を新しい成果へ引き継ぎません。本文の小さな修正でも対象月や金額が変わることがあります。変更した範囲に応じて検査をやり直し、新しい結果を追加します。全検査をいつも最初から繰り返す必要はありませんが、どの確認を維持できるかは根拠が必要です。提出、検査、採用の版を一致させることが、履歴の信頼性を支えます。

追記は訂正を隠さないために使う

履歴を追記で残す方法は、過去の出来事を黙って消さないために役立ちます。誤った配信先が記録されていたなら、元の記録を残したうえで訂正を追加します。担当者が一覧を読むときには最新の説明が見られ、詳細では訂正前も分かるようにします。全ての古い説明を初期画面へ並べる必要はありません。読みやすい現在の表示と、変更の経緯を追える履歴を分けます。

追記するだけで正確さが保証されるわけではありません。誤った記録を追記することもできます。出来事の種類、対象の仕事、対象版、確認者、根拠を定め、入力の不備を検査します。重要な記録では誰が書けるかも制限します。履歴が改変しにくいことと、記録内容が事実であることを分けます。前者は保存の仕組み、後者は実際の応答や成果との照合によって確かめます。

訂正の追加には理由を添えます。入力資料の改訂、処理の不具合、担当者の記入誤りでは対応が異なります。理由が分かれば、同じ種類の問題が別の通知にも影響するかを調べられます。履歴を一件ずつ眺めるだけではなく、共通の入力や条件を使った仕事をたどれるようにします。説明を残す目的は、責任を一人へ押し付けることではなく、影響範囲と必要な訂正を見つけることです。

履歴そのものを検証する

試験では、正常な実行のほか、応答前の停止、保存直後の停止、検査後の本文変更、訂正版の追加を確認します。停止したときに結果不明が残り、再起動後も対象の版を追えるかを見ます。履歴が表示できるだけでは足りません。保存した成果と記録が一致するか、二回の試行が一回の成功へ潰れていないかも検査します。記録の欠落がある場合は、その範囲を未確認と示します。

後日の問い合わせを模した確認も役立ちます。別の担当者へ「なぜこの金額になったか」と質問し、履歴だけで元資料と採用理由へ戻れるかを試します。作者の口頭説明がないと分からないなら、記録の構成を改善できます。表示が長すぎて重要な出来事を探せない場合も、目的に合っていません。出来事の網羅性と調査のしやすさを両方確かめ、詳細を隠す場所と残す場所を決めます。

一度の試験では長期の保持や全ての障害を保証できません。確認した停止点、保持期間、対象の種類を報告します。正常に動いた記録の件数を、障害から復旧した件数として数えることも避けます。説明できることを増やすための履歴が、報告の数字を誇張する材料になってはいけません。成功、失敗、結果不明、未検証を区別して残すことは、履歴の運用を評価する際にも必要です。

試行の履歴を工程の再開へ結び付ける

実行履歴は、送信の試行と相手側の受領を別の出来事として残す設計にします。実行履歴サービスのヤクモ提供の実装には、試行を追記で記録し結果を受領記録として保持する構成があります。月次通知では、対象月と取引先、本文の版をそれぞれの出来事へ結び付けます。試行だけ残って受領がない場合は、配信の成立が分かるまで結果不明として扱います。後から取得した応答は元の試行へ追加し、訂正した本文の配信と取り違えないように検査します。

状態保存、成果物の照合、別担当レビュー、差戻し、受入をつなぐ設計では、完了状態と成果物を別々に確認します。作業担当の提出と確認担当の判断が必要な工程を置き、完全無人の常駐処理を前提にしません。月次通知では、作成済みの本文と採用された本文の版を照合します。レビュー後に金額を直した場合は、以前の合格を流用せず関係する検査へ戻します。実装や実行の記録があっても、業務ごとの監査要件は別に確かめる必要があります。

試行の履歴と工程の保存状態は相互に役立ちますが、同じものではありません。履歴は何が起きたかを説明し、保存状態はどこから進めるかを支えます。現在の状態が完了でも、採用した成果の根拠が必要です。逆に履歴が充実していても、再開に必要な条件がなければ作業は進められません。目的ごとの情報を分けて持ち、必要な関係を結ぶ設計が考えられます。

履歴をTypeScriptとPostgreSQLで扱い、Vitestで追記や受領の挙動を検査する構成が考えられます。工程の進行はLangGraph、待機状態はSQLiteへ分担する方法もあります。履歴の保存と進行の管理は別の役割です。月次通知では、どの試行がどの版の受領と採用につながったかを対応付けます。検査合格後に本文が変わる例や、受領前に停止する例を用意し、履歴を読み直して再開先を選べるかを試します。同じ通知を再送して調査する経路にはしません。

説明できる完了条件を持つ

運用開始前に、問い合わせへ答えるための五つの問いを定めます。どの入力か、どの成果か、何を試したか、何を確認したか、どの結果を採用したかです。仕事の完了時には、この関係が残っていることも確かめます。履歴の量が多いことではなく、必要な問いへ戻れることを目標にします。日常の一覧では現在の進行を短く見せ、疑問が生じたときに詳しい経緯へ進める構成が使いやすくなります。

この設計は記事制作、データ集計、開発の受入にも応用できます。一方、履歴があっても法令や契約の監査要件を自動で満たすわけではありません。必要な保持期間、本人確認、変更の防止、閲覧の権限は用途ごとに確認します。技術の設計を決めた段階と、業務に必要な保持や閲覧の条件を満たした段階は区別します。業務が重いほど、必要な根拠の範囲を具体化することが重要です。

良い履歴は、失敗を隠さず次の仕事へつなげます。訂正を加えた理由や結果不明の範囲が分かれば、担当者は調査を最初からやり直さずに済みます。ただし工数削減を実測していない場合、その効果を数値で約束することはできません。何を説明できるようにするかを決め、実際の問い合わせで確認します。「終わりました」の後に根拠へ戻れることを、成果物の品質の一部として扱います。