生成ワークフローのアプリで、バックエンドとフロントエンドをOpenAPIでそろえる

## バックエンドのAPIを変えるたびに、OpenAPIの型とクライアントを作り直す バックエンドAPIを変更するたびに、リポジトリのOpenAPI更新コマンドを実行する。生成されたスキーマとフロントエンドの型は後回しの整理ではなく、同じ変更の一部として扱う。 フロントエンドコードは、生成されたOpenAPIクライアントを通じてバックエンドのエンドポイントを呼び出さなければならない。生成済みのリクエスト契約とレスポンス契約を重複させる手書きのserviceラッパーを追加しない。 バックエンドの責務を厳密に分ける。 - API層は入力の解析、認証と認可、レスポンスの構成を担う。 - service層はビジネスルール、状態遷移、データ編成を担う。 入力DTO、出力DTO、プロバイダー設定など、生成処理に関する層横断の契約は共有contractsモジュールに置く。taskモジュールにはタスクのラップ、ディスパッチ、実行の編成だけを置き、共有DTOを定義しない。 integrationモジュールは共有contractsに依存してよいが、task内部の型モジュールには依存してはならない。 API、型、状態モデルを変更した時は、バックエンド実装、OpenAPI文書、生成されたフロントエンド型、クライアント利用箇所、直接関係する文書をまとめて更新する。 ## 関数ごとにコメントを書き、今の事実と将来の計画を別の文書に分ける フロントエンドのスタイルが2回以上繰り返される場合は、さらに複製するより、再利用可能なコンポーネントまたは共有スタイル構造へ抽出する。 すべての関数、クラス、同等のコードブロックには、何をするものか、なぜ存在するかを説明するコメントが必要となる。複雑なロジックでは、関連する引数、戻り値の振る舞い、重要な内部判断も記述する。コメントは実装と同期させる。 文書は書く前に分類する。 - `guide`は、タスクの実行方法や機能の統合方法を説明する。 - `architecture`は、現在実装されているシステムを記録する。 - `plans`は、将来の作業、段階別タスク、変更案を記録する。 - `reference`は、参照するための安定した事実を収める。 - `blog`は、リリースノートを収める。 現在の境界、実装済みの状態遷移、実際の振る舞いはarchitecture文書に置く。まだ設計中または進行中の作業はplansに置く。運用手順と開発ワークフローはguideに置く。 現在の事実と将来の意図を一つのhow-to文書に混在させない。同じ主題を扱う場合でも、architectureとplansに分ける。 完成済みの過去のリリースノートは、タスクで明示的に求められない限り変更しない。 ## タスクセンターを軽く保ち、ワークフローの画面ごとに役割を分ける 主要なユーザーワークフローを、責務の明確な画面へ分ける。 - 準備ページはドメインデータを抽出し、候補を確認し、基本情報を修正して、対象を`ready`へ進める。 - 生成ワークスペースは成果物の準備度を確認し、主要アセットとパラメーターを管理し、生成を開始して結果を提示する。 - タスクセンターは、状態、進捗、成功、失敗、キャンセル、戻り先リンクなど、軽量で汎用的なタスク情報だけを表示する。 ドメイン固有の要約、プロンプトのデバッグ情報、アセット対応関係などの重い詳細を、汎用タスクセンターへ置かない。関連する準備、生成、実行、診断の各パネルに残す。 抽出ツールを生成ワークスペースに残す場合は、ショートカットまたは診断手段としてのみ提供する。主な確認画面である準備ページを置き換えてはならない。 責務の境界を変更する時は、関係するUIとarchitecture文書の両方を更新する。タスクセンターの再設計によって、タスクセンターを新たな業務詳細ページにしてはならない。 ## 対象の状態は情報の確認だけに使い、生成の進み具合には使わない ドメイン対象の主状態は、情報確認状態だけに使用する。 - `pending`は、抽出または確認作業が残っていることを表す。 - `ready`は、必要な情報の確認が完了し、後続の準備へ進めることを表す。 この状態を実行時の生成状態に使用しない。`generating`などの値は、タスクシステムとruntime summaryに属する。 成果物の準備度は別の状態軸として表す。対象が後続準備に対して`ready`であっても、生成に必要なすべての条件を満たしているとは限らない。 すべてのユーザーインターフェースで、次の3種類を区別しなければならない。 1. 情報確認状態。 2. 実行時タスク状態。 3. 成果物生成準備度。 状態の意味を変更する時は、バックエンドの振る舞い、OpenAPI、生成されたフロントエンド型、状態ラベル、ナビゲーション条件、開発文書を同期する。 ## 準備ページで確かめた後、生成ワークスペースへ案内する 標準フローは次のとおり。 1. ソースコンテンツから作業対象を抽出する。 2. 準備ページで、抽出されたアセット、台詞、その他の必須情報を確認して修正する。 3. 生成ワークスペースへ移り、主要アセット、参照資料、成果物パラメーター、準備度を確認する。 4. 生成ワークスペースから生成を開始する。 5. ドメインワークスペースで結果を確認し、タスクセンターは汎用的なタスク進捗の確認だけに使用する。 準備ページは抽出、確認、修正を担う。生成ワークスペースは生成準備、実行、結果確認を担う。 準備が成功した後は、ユーザーを生成ワークスペースへ明確に案内する。ワークスペースで対象が`ready`ではないと判明した場合は、理由を明確に示して準備ページへ戻す。 操作を変更する時は、このフローを優先する。利便性のためのショートカットによって、正規の次の手順を不明瞭にしたり、準備と生成を一つの曖昧な画面へ統合したりしてはならない。 ## 変更のたびにarchitecture文書を直し、リリースノートにそのまま使える移行手順を書く architecture文書には、現在実際に成立している振る舞いだけを記載する。plansには、進行中の作業、段階別タスク、優先順位、将来の実行経路を記載する。 コードの振る舞い、状態の意味、ページの責務を変更した時は、同じ作業でarchitecture文書を更新する。計画の範囲、優先順位、順序を変更した時はplansを更新する。実装済みの計画はarchitectureへ移すか、リリースノートにする。 古くなったarchitecture文書またはplans文書が残る作業は未完了として扱う。 リリースノートには、`title`、`date`、`description`、`tags`、`authors`のfrontmatterが必要となる。該当しない節だけを省き、次の安定した順序を使用する。 1. ハイライト。 2. 追加、変更、修正。 3. 破壊的変更、非推奨化。 4. セキュリティ、既知の問題。 5. 移行ガイド、ロールバック手順。 6. 互換性表、検証コマンド、アップグレード用チェックリスト。 7. 参考資料、コントリビューター向け注記、謝辞。 リリースノートはメンテナーの発表文として書く。結論と実行可能な情報を先に示し、短い段落とリストを使い、用語を一貫させる。新機能、振る舞いの変更、互換性リスク、既知の問題を明確に分ける。 移行手順、ロールバック手順、検証コマンドは、曖昧にせずそのまま使用できる内容にする。 ## 生成された型と文書がコードと合ってから完了にする 該当するすべての条件を満たした時だけ作業を完了とする。 1. 実装が存在し、明らかな仮置きや不要になった互換コードが残っていない。 2. 新規または変更した関数とクラスに、正確で有用なコメントがある。 3. API変更に合わせてOpenAPI、生成されたフロントエンド型、生成クライアントの利用箇所が更新されている。 4. 現在の振る舞いがarchitecture文書に、将来の作業がplansに反映されている。 5. 準備、生成、タスクセンターの責務が分離されたままになっている。 6. フロントエンドの変更が、リポジトリのTypeScript no-output checkに合格している。 7. バックエンドの変更が、関係するテスト、または最低限として文書化された構文検査とimport検査に合格している。 8. 完了報告に、変更内容と合格した検証を記載している。 9. 残作業または追加の推奨事項を別に列挙している。 コード、契約、生成された型、文書、状態の意味、ワークフロー画面に不一致がある間は、完了を報告しない。