tax-assistant: 新規クライアント登録フロー設計

クライアント切替機能が動くようになった直後、次に必要なのは「UIからの新規クライアント登録」だった。Planエージェントで設計を組み、Codex（GPT-5.3）に4ラウンドのレビューを回した。

背景

これまでクライアントの追加はCLI経由でしかできなかった。add_client() でクライアント情報をUPSERTし、init_client_db() で専用DBを初期化する流れ。開発中はこれで十分だったが、切替UIができた以上、登録もUIからできないと片手落ちになる。

もう一つの問題として、既存の add_client() がUPSERTで実装されていた点がある。新規登録の文脈でUPSERTを使うと、IDの打ち間違いで既存クライアントのデータを上書きしてしまうリスクがある。ここは設計段階で切り分けておく必要があった。

既存のコードを確認したところ、以下の状態だった。

機能	実装状況	備考
`add_client()`	CLI用、UPSERTで実装	新規登録には不向き
`init_client_db()`	クライアント専用DB初期化	そのまま使える
POST /api/clients	未実装	API層が丸ごと不在
フロントエンドUI	未実装	ClientSelectorにモーダルを追加する想定

short_name仕様の統一: クライアントの短縮名の扱いがCLIとAPIで揺れていた。short_name を正式フィールドとして定義し、全箇所で統一
FK CASCADE: 子テーブル（仕訳、勘定科目など）にクライアントIDの外部キー制約がなかった。将来のクライアント削除に備えて ON DELETE CASCADE を仕込む
ID競合対策: client_NNN の自動採番で、欠番があった場合の挙動を明確化

fiscal_year_end型の統一: 決算月の型が箇所によって文字列だったり整数だったり。Optional[int]（1-12、NULL=12月デフォルト）に統一
補償処理の原子化: create_client() が成功して init_client_db() が失敗した場合のロールバック処理が不十分だった

単一トランザクション: create_client() と init_client_db() を単一トランザクション内で実行し、途中失敗時に不整合が残らないようにする
delete_client改善: 将来の削除機能に備えて、FK CASCADEが正しく機能する前提でのクリーンアップ手順を文書化

合計で20件以上の指摘が出た。1回のレビューでは拾いきれなかった論点が、ラウンドを重ねるごとに浮き上がってきた。

4ラウンドのレビューを経て固まった主な設計判断。

項目	決定内容
ID形式	`client_NNN` 自動採番を維持
新規登録	INSERT-only（UPSERTは使わない）
FK制約	子テーブルに `ON DELETE CASCADE` を追加
トランザクション	create_client + init_client_db を原子的に実行
fiscal_year_end	`Optional[int]`（1-12月、NULL時は12月デフォルト）