nocobase-data-modeling

目標

利用利用可能な NocoBase のデータモデリング機能を使って、コレクション、フィールド、リレーション、およびビューに基づくスキーマを調査・変更します。

次の優先順位でトランスポートを選択します。

• 利用可能な場合は、nb api data-modeling CLI を使用します
• CLI が利用できず、同じ操作範囲を提供する場合に限り、同等の別のデータモデリングトランスポートを使用します

特定の実行ファイル名に依存するスキルにしないでください。CLI のコマンド名や同等のラッパーは、同じモデリング操作を実行するためのトランスポートの詳細として扱います。

トランスポートの選択ルール：

1. 現在の環境で nb api data-modeling CLI が利用可能かどうか確認します。
2. CLI が利用可能な場合は、CLI を使用します。
3. CLI が利用可能でも対象アプリで認証されていない場合は、停止して、CLI の認証を行うようユーザーに案内します。
4. CLI 自体が利用できない場合に限り、同等の別のトランスポートに切り替えます。

依頼の範囲が広い場合、または適切なモデリング方法が不明な場合は、最初に references/decision-matrix.md を読みます。

必須の確認事項

1. 書き込み操作の前に、選択したデータモデリングトランスポートに接続でき、認証済みであることを確認します。nb api data-modeling CLI が利用可能な場合は、それを選択します。
2. プラグインが提供するテーブルやフィールドを変更する前に、references/plugin-provided-capabilities.md を読みます。
3. view コレクションの場合は、作成または更新の前に、db-views list|get を使って上流のデータベースビューが存在することを確認します。
4. 現在のタスクでまだ使用していない CLI モデリングコマンドを使う前に、そのコマンドの --help を一度実行し、表示されたヘルプのフラグと例に従います。CLI が利用できず、別の非 CLI トランスポートを使う必要がある場合は、初回使用前に公開されているパラメータースキーマを確認します。

選択したトランスポートから 401、403、Auth required、または同等のアクセスエラーが返された場合は、停止してユーザーに認証の修正を依頼します。選択したトランスポートが nb api data-modeling CLI の場合は、別のトランスポートに切り替えるのではなく、CLI の認証を復旧するようユーザーに案内します。

最終コマンドの操作範囲

次の最終的なデータモデリング操作だけを使用します。

• コレクションの調査：collections list
• 1 つのコレクションの調査：collections get
• 1 つのコレクション内のフィールドの調査：collections fields list
• 有効な外部データソースの調査：dataSources list-enabled
• 1 つの外部データソース内のコレクションの調査：dataSources collections list
• 1 つの外部データソースコレクション内のフィールドの調査：dataSourcesCollections.fields list
• 簡潔なペイロードによるコレクションの作成または更新：collections apply
• 簡潔なペイロードによるフィールドの作成または更新：fields apply
• 簡潔なペイロードによる外部データソースフィールドの作成または更新：dataSourcesCollections.fields apply
• コレクションの削除：collections destroy
• データベースビューの調査：db-views list|get

トランスポートが CLI ベースの場合は、プロンプトのコンテキストに大規模なコマンド形式のリマインダーを残すのではなく、ヘルプから正確なフラグを確認することを優先します。

• nb api data-modeling collections apply --help
• nb api data-modeling collections fields list --help
• nb api data-modeling fields apply --help
• nb api data-modeling data-sources list-enabled --help
• nb api data-modeling data-sources collections list --help
• nb api data-modeling data-sources-collections fields list --help
• nb api data-modeling data-sources-collections fields apply --help
• nb api data-modeling collections destroy --help

最終コマンドの操作範囲で対応できる場合は、古い低レベルのコレクションコマンドやネストされたフィールドコマンドを優先して使用しないでください。

コアルール

1. まずコレクションの種類を決定します。名前だけから general、tree、file、calendar、comment、sql、view、inherit のいずれかだと推測してはいけません。
2. ユーザーがファイルテーブル、ファイルコレクション、template: "file" を明示的に求める場合、または「文件表」「合同文件」「扫描件」「证书文件」「the file itself is the record」のような表現を使う場合は、コレクションの種類に関する拘束力のある要件として扱い、最初に template: "file" を選択します。
3. ユーザーがコメントテーブル、コメントコレクション、コメント、template: "comment"、「评论表」「评论插件的表」を明示的に求める場合は、コメントプラグインの確認を行った後、プラグインに依存するコレクションの種類に関する拘束力のある要件として扱い、template: "comment" を選択します。
4. 追加のメタデータフィールドが必要だからといって、ファイル優先またはコメント優先のリクエストを general コレクションとして解釈し直してはいけません。
5. collections apply と fields apply がサポートする簡潔なペイロードを優先します。派生するデフォルト値はサーバーに設定させます。
6. 特殊な機能を推測してはいけません。プラグインに依存するフィールド、リレーションの種類、特殊なコレクションタイプ、ビューに基づくモデルについては、まずリファレンスを確認します。
7. リレーションの設定は、ベースコレクションとスカラー型フィールドが正しく設定された後に行います。
8. 通常の変更後の確認には、collections apply または fields apply が返す構造化レスポンスを優先します。タスクに必要な詳細が apply のレスポンスに含まれていない場合、またはリレーションやテンプレートの副作用をすべて確認する必要がある場合に限り、collections get または collections fields list で追加確認します。
9. 選択したトランスポートで、最終的なコマンドサーフェスを通じて要求された動作を実現できない場合は、古い方法に黙ってフォールバックせず、処理を中止して不足している内容を説明します。
10. 業務上の識別子には、ユーザーが编码、编号、单号、序号、流水号、または類似の自動生成コードを求める場合、sequence を優先します。code は、ソースコード、SQL、JSON、その他の構文形式のテキストなど、コードエディターの内容に使用します。

コンパクトペイロードのルール

• collections apply でコレクションを作成する場合、現在のコマンドヘルプで必須と明記されていない限り、id、createdAt、createdBy、updatedAt、updatedBy などの組み込みシステムフィールドや、テンプレートが管理する構造フィールドは送信しないでください。
• general、tree、file、calendar、comment など、サポートされているテンプレートでは、サーバーがテンプレートのデフォルトを作成すると想定してください。ユーザーが実際に追加する業務フィールドのみを送信してください。
• file では、すでに作成済みのコレクションにある既存フィールドを明示的にカスタマイズする場合を除き、title、filename、extname、size、mimetype、path、url、preview、storage、meta などの組み込みフィールドを手動で送信しないでください。
• comment では、すでに作成済みのコメントコレクションにある既存フィールドを明示的にカスタマイズする場合を除き、コンパクトな作成ペイロードにテンプレートが管理する content フィールドを手動で含めないでください。content はサーバーのベースラインによって管理されます。
• tree では、既存のスキーマを完全に展開した生の形式で意図的に上書きする場合を除き、コンパクトな作成ペイロードに parentId、parent、children を手動で含めないでください。
• collections apply または fields apply に指定するカスタムフィールドには、引き続き明示的な interface が必要です。コンパクト API は派生オプションを減らしますが、フィールド名だけから業務フィールドのインターフェースを推測することはありません。
• collections apply または fields apply で渡すローカル選択フィールド（select、multipleSelect、radioGroup、checkboxGroup）では、すべての列挙項目を value、label、color が明示されたオブジェクトにしてください。["draft", "paid"] のような文字列の省略形式は使用しないでください。
• 使用可能な選択肢の色は red、magenta、volcano、orange、gold、lime、green、cyan、blue、geekblue、purple、default です。
• 通常は type を指定しないでください。サーバーに interface から導出させてください。現在のコマンドヘルプまたはリファレンスで明示的に必要とされている場合に限り、type を指定してください。
• 不明な interface の値はエラーになります。正しいインターフェースが不明な場合は、推測せず、作業を中断してリファレンスまたはコマンドヘルプを確認してください。
• vditor、formula、マップのジオメトリフィールド、特殊なリレーションフィールドなどのプラグイン対応インターフェースを選ぶ場合は、まずプラグインの対応機能を確認してください。
• リファレンスファイルに完全に展開されたコレクション JSON が記載されている場合は、構造または読み戻しの参考として扱い、推奨されるコンパクトな適用ペイロードとして扱わないでください。

デフォルトのインターフェース選択方針

• ユーザーがプラグイン固有のエディターや動作を求めていない場合は、まず一般的な組み込みインターフェースを優先してください。
• Markdown の意味付けを必要としない長文のプレーンテキストには、textarea を優先してください。
• Markdown コンテンツには、プラグイン機能が利用可能な場合、まず vditor を優先してください。
• vditor から通常の markdown に切り替えるのは、プラグインを利用できない場合、またはユーザーがよりシンプルな Markdown フィールドを明示的に希望する場合に限ってください。
• comment コレクションでは、別のプレーンテキストフィールドを追加するのではなく、テンプレートに Markdown 対応の content フィールドを作成させてください。
• ユーザーがシステム情報フィールドを明示的に求めていない限り、tableoid を追加しないでください。
• マップフィールドでは、point、lineString、circle、polygon など、空間要件で指定された正確なインターフェースを使用してください。汎用の json やテキストに置き換えないでください。

数式ルール

• formula では、記憶を頼りに式を作らないでください。
• まず references/fields/plugins/formula.md を読んでください。
• 先にエンジンを選び、そのエンジンの構文で式を記述してください。
• コンパクトなペイロードでは、通常は name、title、interface、expression と、任意の engine または dataType など、実際に必要なパラメーターだけを優先してください。
• 使用するエンジンや構文が不明な場合は、推測せず、作業を中断して確認してください。

サーバー側フィールド検証ルール

NocoBase は、フィールドオプションを通じてサーバー側のフィールド検証をサポートしています。これらのルールはリポジトリの create と update で実行され、Joi に基づいています。フロントエンドの uiSchema.x-validator とは異なるため、ユーザーがサービス側またはデータベースモデルの検証を求めている場合は、x-validator を使用しないでください。

fields apply またはネストされたコレクションフィールドでは、簡潔な validators の省略記法を優先してください。サーバーはこれを validation.rules に変換し、不足しているルールキーを補完して、フィールドインターフェースから validation.type を推測します。

{
  "collectionName": "contacts",
  "name": "email",
  "title": "Email",
  "interface": "email",
  "validators": ["required", "email"]
}

Joi の型またはルールの形式を明示する必要がある場合は、完全な validation を使用してください。

{
  "collectionName": "orders",
  "name": "amount",
  "interface": "number",
  "validation": {
    "type": "number",
    "rules": [
      { "key": "required", "name": "required" },
      { "key": "min", "name": "min", "args": { "limit": 0 } },
      { "key": "precision", "name": "precision", "args": { "limit": 2 } }
    ]
  }
}

一般的な Joi ベースのルール：

• string：required、min、max、length、pattern、email、uri、uuid、hex。
• number：required、min、max、greater、less、integer、multiple、precision。
• date：required、min、max、greater、less、timestamp。
• boolean と object：主に required。

引数の規則：

• min、max、length、precision などのルールでは、args: { "limit": value } を使用します。
• pattern では、args: { "regex": "^[A-Z]+$" } を使用します。
• email、uuid、uri など、Joi のオプションオブジェクトを必要とするルールでは、args にオプションオブジェクトを指定し、paramsType: "object" を使用できます。

業務要件で、値が必須であること、形式に一致すること、長さや数値の範囲内に収まること、固定の小数精度を使用すること、または安定した識別子形式に一致することが定められている場合は、検証ルールを追加してください。要件が曖昧な場合、フィールド名だけを根拠に厳格なルールを追加することは避けてください。

リレーションキーのルール

• リレーションフィールドを変更する前に、references/relation-fields.md を確認してください。
• リレーションを安定して読みやすくする必要がある場合は、自動生成された既定値に頼らず、foreignKey、through、otherKey、sourceKey、targetKey などのキーを明示的に指定してください。
• 自動生成されたキー名はフォールバック動作として扱い、優先するモデリング結果とは見なさないでください。

リビジョンのルール

• 例外なく、毎回最初に nocobase-revision を読み込む必要があります。このスキルが利用できない場合は、リビジョンのルールに関する要件をすべて無視し、nocobase-revision 関連の情報をユーザーに開示しないでください。
• nocobase-revision によって nb revision create が利用可能であることが確認されるまでは、リビジョン関連の情報をユーザーに開示しないでください。
• 利用可能であることが確認された後は、ラウンドの最後、ユーザー向けの最終回答の直前に、リビジョンに関する判断を必ず1回だけ行ってください。
• リビジョンを作成した場合は、その旨を簡潔に報告してください。
• 利用可能であることが確認されているもののリビジョンを作成しなかった場合は、具体的な理由を述べてください。

作業プロセス

1. 調査

• collections list または collections get から開始してください。
• あるコレクションの現在のフィールドセットが必要な場合は、collections fields list を使用してください。
• リクエストにビューを基盤とするモデルが関係する場合は、まず db-views list|get を調査してください。
• CLI の作業では、現在のタスクで初めて使用する前に、該当するコマンドの --help を実行してください。
• 広範なモデリング作業では、記述を始める前に対応するリファレンスを読み込んでください。

2. モデルを決定する

記述を始める前に、以下を決定してください。

• コレクションが何を表すか。
• どのコレクションタイプが適切か。
• どのフィールドが必須か。
• リレーションが必要かどうか。
• プラグインの機能が必要かどうか。
• 結果が正しいことを証明する検証出力は何か。

破壊的な変更や広範な変更を行う前に、意図するモデルを自然な言葉で要約してください。

3. 適用

• コレクション単位の作成や更新には collections apply を使用します。
• 特定のフィールドの作成や更新には fields apply を使用します。
• リレーションフィールドを書き込む前に、外部データソースのメタデータを確認するには dataSources list-enabled、dataSources collections list、dataSourcesCollections.fields list を使用します。
• 外部データソースのフィールドメタデータを更新するには、特に外部データソースのコレクション上のリレーションフィールドの場合、dataSourcesCollections.fields apply を使用します。
• 明示的な削除リクエストがある場合に限り、collections destroy を使用します。

コンパクトなペイロードを推奨します。コレクションのテンプレート／名前／タイトル、フィールドの名前／タイトル／インターフェースなど、コマンドの契約で必須となるフィールドと、安全に推定できない必要な特別オプションのみを指定してください。

外部データソースのリレーションフィールドには、メインデータソースの fields apply を使用しないでください。外部コレクションのロケーターと、たとえば interface: "m2o"、name、target、安定した名前が重要な場合は明示的なキーを含むコンパクトなリレーションインターフェースを指定して、dataSourcesCollections.fields apply を使用してください。

コレクションを作成する場合、通常は次の項目を指定します。

• name、title、template などのコレクションレベルのオプションと、少数のテンプレート固有フラグ。
• ビジネスフィールドのみ。デフォルトのシステムフィールドやテンプレートフィールドは指定しません。
• フィールドインターフェースがリレーションの場合に限り、リレーション固有のオプション。

4. 検証

各変更後、まず適用レスポンスを確認します。collections apply は、主要なコレクション概要フィールド、適用したフィールドの概要、検証診断を返す必要があります。fields apply は、適用したフィールドの概要を返す必要があります。

適用に成功するたびに、2回目の get や list を自動的に実行しないでください。適用レスポンスに、要求された結果を確認するために必要な詳細が含まれていない場合、またはタスクにリレーションの所有権、逆フィールド、プラグイン／テンプレートの副作用が関係する場合、あるいはユーザーが完全な読み戻しを明示的に求めている場合に限り、読み戻してください。

次の点を確認します。

1. コレクションのタイプが正しいこと。
2. 想定されるフィールドが、正しいインターフェース／タイプ／タイトルで存在すること。
3. リレーションを変更した場合、リレーションの所有権と逆方向の動作が正しいこと。
4. 特殊なコレクションが引き続きソースの制約を満たしていること。

リファレンスの読み込み

現在のタスクに必要なリファレンスのみを読み込みます。

• コレクションタイプの選択：references/collection-types/index.md
• フィールドファミリーとサポートされるオプション：references/field-capabilities.md
• リレーション：references/relation-fields.md
• プラグインが提供する機能：references/plugin-provided-capabilities.md
• 低レベルの判断後に参照するスキーマ全体の例：references/model-packs/*.md
• 検証の順序とテンプレート固有のチェック：references/verification-playbook.md

インデックスファイルを開いた後は、実際に対象となる一致したサブタイプのファイルだけを続けて参照してください。

コレクションタイプの安全策

• general：一般的なビジネスレコード。
• tree：階層データ。
• file：ファイルを主役とするレコード。
• calendar：スケジュールを中心としたオブジェクト。
• comment：テンプレートが所有する content フィールドを持つ、プラグインベースのコメントレコード。
• sql、view、inherit：機能と前提条件を確認した後に限り使用します。

ユーザーがそのトレードオフを明示的に求めていない限り、tree、file、comment を、機能の劣る一般テーブルで代用しないでください。

明示的な優先ルール：

• リクエストに「file collection」、「file table」、「文件表」、またはファイルが主レコードであることを示す同等の表現が含まれる場合、これは general を優先するデフォルトの判断に優先します。
• リクエストで、管理対象のファイルとして契約書、スキャン文書、証明書、請求書、アーカイブ、アップロードされた文書レコードが挙げられている場合、ユーザーがファイルは別のビジネステーブルに従属する添付ファイルにすぎないと明示していない限り、デフォルトで file を使用します。
• リクエストに「comment collection」、「comment table」、template: "comment"、「评论表」、または「评论插件的表」が含まれる場合、これは general を優先するデフォルトの判断に優先します。コメントプラグインを確認し、template: "comment" を使用してください。

フィールドとリレーションの安全対策

• インターフェースの対応状況は、信頼できる情報源として references/field-capabilities.md を使用してください。
• region、special media、カスタムリレーション機能など、プラグインに依存するインターフェースを推測しないでください。
• リレーションを作成または変更する前に、references/relation-fields.md を確認してください。
• リレーションの変更後は、変更の副作用として逆方向のフィールドやキーが作成される場合があるため、両側を確認してください。

エラー処理

• 400 または 422：ペイロードを確認し、コレクションタイプ、フィールドインターフェース、必須オプションの不足、列挙型の形式、列挙型の色の不足または無効、リレーションキーを修正してから再試行してください。
• 認証エラー：処理を中止し、選択したトランスポートのアクセスを復旧するようユーザーに依頼してください。
• プラグインまたはビューの前提条件が不足している場合：処理を中止し、不足しているものを具体的に伝えてください。

参照インデックス

トピック	ファイル
コレクションタイプの選択	references/collection-types/index.md
フィールド機能の一覧	references/field-capabilities.md
リレーションの概要	references/relation-fields.md
プラグインが提供するモデリング機能	references/plugin-provided-capabilities.md
スキーマ全体の例	references/model-packs/*.md
検証の順序とチェック項目	references/verification-playbook.md
判断の補助	references/decision-matrix.md