directory finding: 1クエリ1リポジトリ1DTO を基本方針として明文化する

[mk3008]

Summary

repository / DTO / SQL asset の関係について、read/write や tables/views のような分類軸を先に固定するのではなく、1クエリ1リポジトリ1DTO を基本方針として明文化する。

今回の判断基準は、ファイル数の少なさよりも、判断に迷わないこと / 規則性が強いこと / 将来の複雑化に耐えること を優先することにある。

実際には、障害の多くは SELECT query、または SELECT を含む複合処理で起きやすい。
一方で、単純なパラメータ指定の CUD は比較的単純であり、DTO の概念も強く出にくい。
しかし CUD でも、batch 化や INSERT ... SELECT ... のように選択クエリを含む処理へ発展すると複雑化し、read/write のような分類軸では判断に迷いやすい。

そのため本課題では、分類を先に細かく設計するよりも、以下の粒度原則を優先する。

• 1 SQL file
• 1 QuerySpec / contract
• 1 repository entrypoint
• 1 DTO / view model

この原則を採ることで、単純な query から複雑な query、batch 化された処理まで、同じ規則で扱えるようにする。

Problem

現在の整理では、repository の分類軸として read/write や tables/views のような方向が検討されていたが、以下の課題がある。

• INSERT ... SELECT ... や batch 系処理では read/write の境界が曖昧になる
• 単純な SELECT でも後から join / CTE / 集計 / DTO 専用化が発生しやすい
• 後から分類を変える運用は、移動コスト・import churn・AI の判断コストを増やす
• 障害分析の観点では、実際に問題が出やすいのは query 単位であり、分類単位ではない

つまり、分類の美しさよりも、query 単位で責務を固定すること のほうが保守・運用・AI 利用の実態に合っている。

Goal

以下を基本方針として明文化する。

• 原則として 1クエリ1リポジトリ1DTO
• SQL asset は query 単位で独立して存在する
• repository は query 単位の entrypoint として対応する
• DTO / spec / mapping もその query に対応する単位で持つ
• 複数 query を組み合わせる業務処理は、上位層でオーケストレーションする
• read/write や tables/views の taxonomy は、少なくとも本課題では固定しない

Why this matters

この方針の利点は以下。

1. 判断基準が迷わない

query が 1 つあるなら、それに対応する repository / DTO も 1 つ、というルールで済む。
read か write か、table か view か、といった分類判断を毎回しなくてよい。

2. 将来の複雑化に強い

単純な SELECT でも、後から join / 集計 / batch 化 / INSERT ... SELECT ... に発展しうる。
その場合でも「query 単位で責務を持つ」という原則は壊れない。

3. 障害分析と相性がよい

障害の多くは SELECT query や query を含む複合処理で起きるため、query 単位で責務を持たせるほうが追跡しやすい。

4. AI にとって規則性が強い

分類判断より、対応関係が明確なほうが AI は迷いにくい。
この SQL に対応する spec / repository / DTO はこれ という関係を固定しやすい。

Scope

本課題では以下を扱う。

• query-unit policy の明文化
• SQL asset / repository / DTO の対応原則の整理
• docs / policy / scaffold 説明の更新方針整理

Non-goals

本課題では以下は扱わない。

• read/write への全面移行
• tables/views の即時廃止
• directory 階層の全面再編
• 全 adapter / 全 DBMS 向けの個別最適化
• runtime / scaffold の大規模な構造変更

Expected direction

現時点の方向性としては、少なくとも次を明文化したい。

• SQL asset は human-maintainable source asset として独立させる
• 1 SQL file に対して 1 repository entrypoint を基本とする
• DTO / QuerySpec / mapping も query 単位で対応付ける
• 複数 query を使う処理は、repository の上位でまとめる
• taxonomy で迷うより、粒度原則で迷わないことを優先する

Acceptance Criteria

• 1クエリ1リポジトリ1DTO を基本方針として説明できる状態になる
• query 単位で責務を固定する理由が docs / policy 上で明文化される
• read/write のような分類判断をしなくても、置き場所と責務を説明できる
• 将来 query が複雑化しても、同じ原則で扱える設計方針になっている