モデルと項目の名前を決める

1. このページで伝える機能

モデルと項目には、利用者に見せる表示名と、設計情報・コード・APIなどで使う英語識別名を付けます。データベースに保存するテーブル名・列名はDB物理名です。これらの役割を分けると、画面では分かりやすい名前を使いながら、内部の識別名を安定させられます。

業務の名前をAIに伝えれば、英語識別名を提案してもらえます。既存DBの名前に合わせたい場合は、テーブル名・列名の対応も指定できます。

名前だけでは伝わらない業務上の意味や設計意図は、モデルと項目の「開発者向け説明」として残せます。

2. Wagby11で実現できること

2.1 表示名・英語識別名・DB物理名を分ける

この表のDB物理名は、rdbnameを指定せず、例の英語識別名から自動変換した場合です。表示名をそのままDB名にする必要はありません。

2.2 英語識別名の付け方をそろえる

• モデルは単語の先頭を大文字にしてつなぎます。例：Customer、SalesOrder。この書き方をUpperCamelCaseと呼びます。
• 項目は最初の単語を小文字で始め、続く単語の先頭を大文字にします。例：customerName、orderDate。この書き方をlowerCamelCaseと呼びます。
• IDなどの略語も単語として扱い、customerIDではなくcustomerIdとします。
• モデルの定義ファイル名は英語識別名に合わせます。SalesOrderならSalesOrder.yamlです。

juser、jroleなどの予約済みシステムモデルとその項目は固定識別子です。この命名方針に合わせるために変更しません。

2.3 DB物理名を自動で決める・個別に指定する

上の命名方針で付けた英語識別名は、rdbnameを省略すると、小文字の単語をアンダースコアでつなぐsnake_caseへ変換されます。

既存DBでテーブル名がmst_customer、顧客コードの列名がcustomer_cdと決まっている場合は、rdbnameでそれぞれ明示します。英語識別名はCustomer、customerCodeのまま、DB物理名を別に指定できます。

rdbnameは保存先の名前を指定する設定です。既存DBを使う場合は、名前の対応に加えて、主キー、型、桁数、制約、既存データとの整合性もAIに確認してもらいます。

2.4 名前の重複と長さを確認する

• モデルの英語識別名だけでなく、そこから生成されるクラス名も大文字・小文字を区別せず一意にする必要があります。大文字小文字だけを変えた別モデルは作らず、業務上の違いが分かる名前を付けます。
• DB物理名の重複も、大文字・小文字を区別せずに検証されます。テーブル名はAppSchema全体で、永続化する列名は同じモデル内で一意にします。明示的にテーブルを共有する構成は別扱いです。
• 自動生成する主キー制約名・一意制約名・外部キー制約名・インデックス名は最大63文字です。自動生成するインデックス名が重複する場合は、8桁のハッシュ接尾辞を付け、全体を63文字以内に収めます。
• rdbnameで指定するテーブル名・列名は自動短縮されません。利用するDBの識別子長、使用できる文字、大文字・小文字の扱いを確認します。

項目のuniqueに明示する一意制約名は、英字またはアンダースコアで始め、英字・数字・アンダースコアだけを使い、63文字以内とします。設定方法は重複する値の登録を防ぐを参照してください。

生成クラス名の衝突はDB物理名を変えるだけでは解消しません。AIには検証エラーの対象と、他の定義への影響を確認してもらいます。既存の識別名を変更する場合の注意点は型や識別子を変えた時の影響も参照してください。

Javaコードからモデルや項目を参照する開発者向けの詳細は、英語識別名と生成Java名の対応を参照してください。

2.5 名前を変更しても、同じモデル・項目を追跡する

migration_idは、モデルと項目に付く変更しない内部IDです。名前や配置を変えても「以前からある同じモデル・項目」と判断するために使います。例えば「顧客名」の英語識別名を変更したとき、別の項目を追加したのか、同じ項目を改名したのかを、名前だけで判断するのは困難です。このIDが、その対応を保ちます。

DBの変更を準備する処理では、保存済みのSQL履歴に記録したID・物理名と、現在の定義を比較します。同じIDでテーブル名や列名が変わった場合は、既存データを保持するための名前変更SQLを追加生成する判断に使います。DB物理名が変わらなければ、当該テーブル・列の名前変更は不要です。

開発者が手動でAppSchemaを修正する場合

既存のIDを削除して補完し直すと、新しいIDが付いて履歴との対応が失われる場合があります。また、モデルと項目を通じてIDはAppSchema全体で一意にする必要があり、重複や不正な値、値を空にした指定は検証エラーになります。

このIDはUUID形式の文字列で、レコードの主キーやAPI名、DB物理名とは別の情報です。DBへmigration_idという列を追加するものではありません。モデルの参照、メニュー、式などは引き続き英語識別名を使うため、改名時はそれらも更新します。IDを保持するだけで関連参照やすべてのデータ移行が自動で解決するわけではありません。

2.6 名前だけでは伝わらない設計意図を説明として残す

モデルと項目には、開発者向け説明を日本語で記述できます。モデルには「何を管理するか」「どこまでをこのモデルの対象にするか」、項目には「値が業務上何を意味するか」「似た項目との違い」「保守時の注意点」などを残します。

この説明は、ビルドするアプリケーションの動作やDB定義に影響しません。設計書として出力する場合に、人間の開発者が業務上の意味や設計意図を理解するための補足情報になります。定義や業務上の扱いを変更したときは、説明も見直します。

3. AIへの指示例

最小限の指示例

受注日と顧客IDを持つ受注モデルを作り、表示名と英語識別名を分かりやすく付け、開発者向け説明も残してください。

AIは受注の英訳、項目の英語識別名、主キー、型、顧客IDを参照項目にするかなどを、既存の定義と業務の説明から類推して補います。説明の内容も既存の定義や業務の説明から補うため、受注日と登録日の違いなど、業務固有の意味は具体的に伝えます。英語識別名やDB名に決まりがある場合も指定します。この短い指示だけで、次の詳細例と同じ仕様になるとは限りません。

より詳細な指示例

Wagby11のguideと必要なreferenceを確認し、新しい受注モデルの命名を次の方針にしてください。
・表示名は「受注」、英語識別名はSalesOrderとし、定義ファイル名をSalesOrder.yamlにしてください。
・項目「受注日」の英語識別名はorderDate、項目「顧客ID」はcustomerIdとしてください。
・DB物理名はrdbnameを指定せず、標準の自動変換を使ってください。
・既存のモデル・項目・生成クラス名・DB物理名と衝突しないか検証してください。
・主キー、項目の型、顧客の参照方法、権限、メニューは、既存定義と業務に合わせて提案してください。
・既存の英語識別名、migration_id、DB物理名、データは保持してください。
・受注モデルの開発者向け説明に「顧客から受け付けた注文を管理する。見積段階の情報は含めない」と記録してください。
・受注日の開発者向け説明に「顧客から注文を受け付けた日。データをシステムへ登録した日とは区別する」と記録してください。
・その他の項目にも業務上の意味や設計意図を残し、判断できない内容は確認事項として示してください。
・開発者向け説明は設計書を読む開発者への補足情報として扱い、説明の追加を理由に画面のヘルプや入力チェックを変更しないでください。
表示名・英語識別名・DB物理名の対応表と、追加した説明、検証結果を示してください。

DB物理名が決まっている場合は、次のように指定できます。

顧客モデルの英語識別名はCustomer、顧客コードの英語識別名はcustomerCodeにしてください。
DB物理名は、テーブルをmst_customer、顧客コードの列をcustomer_cdとして、rdbnameで明示してください。
既存DBの主キー・型・桁数・制約と整合するか確認し、必要な移行と既存データへの影響を説明してください。

既存のモデル・項目を改名するときの指示

最小限の指示例

顧客モデルの「顧客名」を「顧客名称」に表示変更してください。同じ項目として既存のmigration_idを保持してください。

AIは対象項目を既存の定義から判断します。英語識別名やDB物理名も変えたい場合は、対象と変更先を明示します。この短い指示で、以下の英語識別名の変更まで行うとは限りません。

より詳細な指示例

顧客モデルCustomerの項目customerNameを、同じ項目として改名してください。
・表示名は「顧客名称」、英語識別名はcustomerDisplayNameにしてください。
・モデルと項目の既存migration_idは保持し、削除・再発行しないでください。
・DB物理名の変更有無を確認し、SQL履歴との対応と必要な追加移行を説明してください。
・検索・一覧・参照・計算式・APIなど、英語識別名を使う箇所への影響も確認してください。
・既存データを保持し、変更した定義と自動生成したSQLの差分を確認してください。

4. 編集されるAppSchemaの例

以下は命名と開発者向け説明を示す抜粋です。利用者は構文を覚えなくても、表示したい名前と、英語識別名・DB名の方針をAIへ伝えられます。主キーや権限など、モデル全体の設定はモデルを定義する例を参照してください。

DB物理名を自動変換する例

designer/repository/appschema/SalesOrder.yamlの抜粋です。テーブル名はsales_order、受注日の列名はorder_dateになります。

entity:
  name: 受注
  name_en: SalesOrder
  description: |
    顧客から受け付けた注文を管理する。
    見積段階の情報は含めない。
  type: T
  attributes:
    - name: 受注日
      name_en: orderDate
      description: |
        顧客から注文を受け付けた日。
        データをシステムへ登録した日とは区別する。
      type: date

モデルの説明はentity.description、項目の説明はentity.attributes[].descriptionに記録します。複数行の説明も残せます。

DB物理名を明示する例

designer/repository/appschema/Customer.yamlの抜粋です。モデルのrdbnameがテーブル名、項目のrdbnameが列名を指定します。

entity:
  name: 顧客
  name_en: Customer
  rdbname: mst_customer
  type: M
  attributes:
    - name: 顧客コード
      name_en: customerCode
      rdbname: customer_cd
      type: string
      length: 20

モデルと項目の固定IDを保持する例

以下はIDを付与した後の定義の抜粋です。entity.migration_idがモデル、各項目のmigration_idが項目自身を識別します。名前を変えても、それぞれの値は保持します。

entity:
  name: 顧客
  name_en: Customer
  migration_id: "f208f466-a562-4fa3-8510-f994cfd4004d"
  attributes:
    - name: 顧客名
      name_en: customerName
      migration_id: "9de85129-85f7-4fa7-b0c8-af19c56b36e5"
      type: string
      length: 100
  # 主キーなど、その他の定義は省略

このUUIDは説明用の例です。実際の編集では、対象の定義に保存されている値を保持してください。新規モデルや項目へ、この例のIDをコピーして使いません。

5. 参考資料

guide：命名規約

designer/docs/appschema/html/guide/01-project/04-naming-conventions.html

guide：モデルを作成する

designer/docs/appschema/html/guide/03-model/01-create-model.html

guide：ファイル構成

designer/docs/appschema/html/guide/01-project/02-file-organization.html

reference：modules

designer/docs/appschema/html/reference/05-modules.html

reference：entity

designer/docs/appschema/html/reference/06-entity.html