Payment systemに関わると、状態管理の重要性を強く感じます。

多くの人は、支払いをsuccessかfailedの二択で考えがちです。ユーザーが支払いボタンを押して、成功したら完了、失敗したらエラー。UIだけを見ると、そのように見えることもあります。

しかし実際のpayment flowは、もっと多くの状態を持ちます。

initiated、pending、processing、authorized、captured、settled、failed、reversed、refunded、canceled。システムやビジネスによって名前は違いますが、重要なのは「支払いには途中状態がある」ということです。

この途中状態を曖昧にすると、あとで多くの問題が起きます。

たとえば、ユーザーには失敗と表示されたのに、内部ではprocessingのまま残っている。partner側では成功しているのに、自社DBではfailedになっている。refundは完了しているのに、UIではまだ返金待ちに見える。support teamが問い合わせを受けても、どの状態を信じればよいのか分からない。

こうした問題の多くは、状態定義が曖昧なことから始まります。

Payment systemでは、UIに表示する状態と、内部で保持する状態が同じとは限りません。ユーザーには「処理中」と見せるだけでも、内部ではauthorization待ち、settlement待ち、external confirmation待ちなど、より細かい状態を持つことがあります。

この差を理解していないと、UIの都合で内部状態を雑に扱ってしまいます。

AIにコードを書かせる時も、状態管理は特に注意が必要です。AIは、if文やenumをすぐに作ってくれます。しかし、どの状態がどの意味を持ち、どのイベントで遷移し、どの状態から再実行できるのかは、人間が設計する必要があります。

状態管理で大事なのは、まずsource of truthを決めることです。

今の正しい状態はどこにあるのか。自社DBなのか、partner APIなのか、ledgerなのか、event logなのか。複数の場所に似た状態がある場合、どれを信じるのかを明確にしないと、システムはすぐに不整合になります。

次に、状態遷移を明示することです。

pendingからcompletedに進む条件は何か。failedからretryできるのか。processingのまま長時間残った場合はどうするのか。manual reviewが必要な状態はあるのか。refundされた時、元のtransaction stateはどう扱うのか。

こうしたルールは、コードを書く前に整理するべきです。

Paymentでは、単に状態を更新するだけでなく、「なぜその状態になったのか」を残すことも重要です。status reason、external code、timestamp、actor、request IDなどがあると、後から調査できます。

状態管理がしっかりしていると、supportやopsも強くなります。ユーザーから問い合わせが来た時に、今どの状態で、次に何が起きる予定で、手動対応が必要なのかを説明できます。

逆に、状態管理が曖昧だと、エンジニアが毎回databaseを直接見て調べることになります。これはスケールしません。

Payment systemで学んだ一番大きなことは、状態は単なる実装詳細ではないということです。

状態は、プロダクトの約束です。ユーザーに何を見せるか、supportが何を説明するか、opsがどう対応するか、システムがどう回復するかに直結します。

AI時代には、コードを書く速度は上がります。しかし、状態を設計する力はますます重要になります。

AIに実装を頼む前に、まず状態を整理する。状態の意味を言語化する。状態遷移を図にする。失敗時にどこへ戻るかを決める。

これができるエンジニアは、AIを使っても強いと思います。