docyrus-api-doctor

Docyrus API ドクター

Docyrus API コードの実装後チェックリストです。API ロジックを作成または変更した後、該当するチェックをすべて実施してください。タスクを完了とする前に、見つかった問題をすべて修正してください。

使い方： API ロジックを実装した後、変更したコードを以下の各チェックと照らし合わせて確認します。対象のコードに当てはまらないチェックはスキップしてください。詳しい説明と修正例については、references/checklist-details.md をお読みください。

---

バグ — エラーの原因になります

#	チェック	確認する内容
B1	columns パラメーターの指定漏れ	.list() または .get() の呼び出しで、columns プロパティが指定されていない箇所。指定しない場合、id のみが返されます。
B2	クエリペイロード内の limit: 0	limit を 0 に設定すると API エラーになります。limit を完全に削除するか、正の整数を設定してください。
B3	columns に含まれていない子クエリキー	childQueries で orders というキーを定義している場合、文字列 orders も columns に含める必要があります。
B4	columns に含まれていない数式キー	formulas で total というキーを定義している場合、文字列 total も columns に含める必要があります。
B5	@ 列構文による集計	columns で count@field または sum@field を使用している箇所。代わりに calculations パラメーターを使用してください。
B6	calculations との distinctColumns の併用	これらは相互に排他的です。集計には calculations を使用してください。
B7	数式 extract の入力数	extract ブロックの入力数は、必ず 1 つにしてください。
B8	数式 not のオペランド数	not ブロックのオペランド数は、必ず 1 つにしてください。
B9	数式 and／or のオペランド数	and／or ブロックには、2 つ以上のオペランドが必要です。
B10	数式の算術演算のオペランド数	算術演算（+、-、*、/、%）には、2 つ以上のオペランドが必要です。
B11	when のない数式 case	case 式には、1 つ以上の when 節が必要です。
B12	jsonb_build_object 内の型キャストされていないリテラル	jsonb_build_object 内の文字列リテラルには、明示的な "cast": "text" が必要です。自動キャストが機能するのは concat／concat_ws 内のみです。

パフォーマンス — 処理速度の低下やリソースの無駄につながります

#	チェック	確認する内容
P1	集計クエリでの不要な limit	生の行データが不要で calculations を使う場合は、limit を送信しないでください。集計結果は通常、グループ化された単一の結果として返されます。
P2	合計数を取得するだけの fullCount	必要なのが件数のみ（行データは不要）であれば、行を取得しながら fullCount: true を指定するのではなく、calculations: [{ func: 'count', field: 'id', name: 'total' }] を使用してください。
P3	計算結果のみを取得するクエリでの不要な columns	calculations を使用し、集計値のみを読み取る場合は、columns を送信しないでください。列を選択しなくても計算結果は返されます。
P4	列の過剰な取得	columns で選択されているものの、利用側のコードで読み取られていない列。表示または処理する列のみを選択してください。
P5	ページネーションなしでの大きな limit	offset／fullCount によるページネーションなしで limit > 200 を指定すると、応答が遅くなり、メモリ使用量が増加するおそれがあります。
P6	N+1 を引き起こす expand の指定漏れ	expand にフィールドを含めずに、リレーション／列挙型／ユーザーフィールドの .name を表示している箇所。expand がない場合、ID のみが取得されます。
P7	存在確認のための行データ取得	レコードを取得して、存在するものがあるかどうかだけを確認している箇所。代わりに calculations のカウントを使用してください。
P8	重複するクエリ	同じデータソースに対して、統合可能な重複列を取得している複数のクエリ。

コード品質 — 保守の負担を招く原因

#	チェック項目	確認する内容
Q1	レスポンスに対する as 型アサーションの多用	ランタイム検証を行わず、API レスポンスを as Array<...> でキャストしていないか確認します。型付きコレクションの戻り値を使用するか、検証を追加してください。
Q2	依存するクエリでの enabled の指定漏れ	recordId などのランタイム値に依存するにもかかわらず、enabled: !!recordId を指定していない useQuery を確認します。クエリが undefined で実行されます。
Q3	ミューテーションのエラーハンドリング漏れ	try/catch やユーザーへのエラー通知なしで .create()、.update()、.delete() を呼び出していないか確認します。
Q4	ミューテーション後のクエリ無効化漏れ	create/update/delete の後、リストを更新するために、関連するクエリキーを無効化する必要があります。
Q5	キャッシュを順番に無効化している	await queryClient.invalidateQueries(...) を複数回続けて実行していないか確認します。互いに独立した無効化には Promise.all() を使用してください。
Q6	非推奨の expandTypes の使用	expand パラメーターに置き換えてください。
Q7	データソースパスのハードコード	生成されたコレクションフックを使用せず、client.get('/v1/apps/base/data-sources/project/items') を直接呼び出していないか確認します。
Q8	orderBy なしでの distinctColumns の使用	distinctColumns では、グループごとにどの行を採用するかを定義するために orderBy が必要です。

---

実行方法

1. このタスクで変更されたファイルのうち、Docyrus API 呼び出しを含むファイルをすべて特定します
2. 各ファイルで .list(、.get(、.create(、.update(、.delete(、client.get(、client.post(、client.patch(、client.delete( を検索します
3. 各呼び出し箇所を BUG チェック（B1-B12）に照らして確認します
4. クエリのペイロードを PERFORMANCE チェック（P1-P8）に照らして確認します
5. 周辺のコード（フック、エラーハンドリング、無効化）を CODE QUALITY チェック（Q1-Q8）に照らして確認します
6. BUG カテゴリーから順に、見つかった問題をすべて修正します

参照資料

• references/checklist-details.md — 各チェック項目の詳しい説明、検出パターン、修正前後の例