component-scaffolder

コンポーネントスキャフォルダー

ドキュメント化されたスケルトンから、新しい Datex Studio コンポーネントをスキャフォールディングします。このスキルは、「新しい コンポーネントを作りたい」という要望に対応するルーティングレイヤーです。要求されたコンポーネントタイプを、次の項目に対応付けます。

1. ファイルのサフィックス（referenceName に付けます）。
2. configurationTypeId の数値 ID。
3. 正規の最小有効スケルトン（一致するクリエータースキルの references/<type>.md から取得します）。
4. 実際の本体作成を引き継ぐ、一致するクリエータースキル。

action-creator、function-creator、grid-creator などのクリエータースキルは、それぞれのコンポーネントタイプの作成を担当します。このスキルが担当するのは、どのサフィックス、どの cti、どのスケルトンドキュメント、どのクリエータースキルを選ぶかという振り分けの判断です。これにより、ルーティングロジックが各クリエータースキルに重複して記述されるのを防ぎます。ブランチが信頼できる唯一の情報源です。スキャフォルダーがローカルの src/ ツリーに書き込むことはありません。

参照資料

• ../datex-studio-conventions/file-format.md — 正規の configurationTypeId テーブル、ファイルサフィックスのルール、誤った cti による障害モード。
• 各クリエータースキルの references/<type>.md — そのコンポーネントタイプの正規の最小有効スケルトン。JSON 構造を記憶から作り上げないでください。必ず対応する参照ドキュメントを確認してください。

ワークフロー

1. 必要な3つの入力を収集します。

   • タイプ — 次のいずれかです。action、function、interface、enum、grid、hub、form、editor、embed、selector、storage、backendTest、datasource（OData または flow クエリタイプ、プラットフォーム版）、footprintDatasource（OData または flow クエリタイプ、Footprint 版）。呼び出し元がバリアントを指定せずに「datasource」と述べた場合は、どちらのバリアント（プラットフォームの -datasource か、Footprint の -footprintDatasource）を希望するか尋ねてください。これらは configurationTypeId もコンポーネントのバリアントも異なります。分類の全容については、datasource-creator/references/datasources.md を参照してください。
   • 名前 — コンポーネントの参照名（ファイルサフィックスを除く）。../datex-studio-conventions/naming-conventions.md に従い、タイプを示す識別子を名前自体に付けてください（_storage、_hub、_form、_editor、_embed、_grid、セレクターは _dd、アクションは _action、関数は _flow、インターフェースは i_ プレフィックス、列挙型は e_ プレフィックス）。
   • 説明 — null ではなく、空でなく、100文字以下にしてください。Footprint 側の SQL 列には厳格な上限があり、超過すると SQL の切り捨てエラーでインポートに失敗します。説明が指定されていない場合は、呼び出し元に確認してください。説明がなければ先に進まないでください。

2. 要求されたタイプに対応する行を、下のテーブルで確認します。そこからサフィックス、configurationTypeId、正規スケルトンを記載した参照ドキュメント、次に処理を委任するクリエータースキルが分かります。

3. 参照先のドキュメントから正規スケルトンを読み込みます。JSON 構造を推測しないでください。正規のスケルトン構造とタイプごとの細かな違い（たとえば、セレクターとデータソースのコンポーネントバリアント規則、バックエンドテストのフックフロー構成）は、参照ドキュメントを正とします。

4. スケルトンを適用します：

   • referenceName → コンポーネント名です。（例外：アクションの場合、referenceName は _action で終わり、ファイルのサフィックスは -footprintFlow.json です。作成者名とのこの組み合わせは意図的なものです。action-creator/references/actions.mdを参照してください。）
   • title → バックエンドタイプ（function、action、datasource、footprintDatasource、interface、enum、storage、backendTest）の場合、titleは画面に表示されないため、referenceName と同じ値にします。ユーザー向けタイプ（form、editor、hub、grid、embed、スタンドアロンセレクター）の場合、title はヘッダー／ダイアログのタイトル／タブのラベルとして表示されるため、文頭のみ大文字にした、referenceName とは異なる表示名にする必要があります。../datex-studio-conventions/naming-conventions.md → ユーザー向けコンポーネントの表示名に従い、referenceName とバイト単位で完全に同一の title は命名規則違反です。名前から表示名を導き出す（例：custom_example_map_embed → Example map）か、呼び出し元に確認してください。
   • description → 呼び出し元から指定された説明です（100文字以下）。
   • accessModifier → 呼び出し元に確認してください。希望がない場合は "public" を既定値にします。
   • configurationTypeId → ディスパッチテーブルの数値IDです。不明な点があれば、同じタイプの動作するコンポーネントからコピーしてください。誤ったctiは、Validateでは問題がないのにPreviewで失敗する原因になります（../datex-studio-conventions/file-format.mdを参照してください）。
   • その他のフィールド → スケルトンの既定値（空の配列、nullなど）にします。最小限の有効なスケルトンを超えて、プレースホルダーのプロパティ、フィルター、コードを事前に追加しないでください。

5. ブランチ上の競合を確認します。 存在するものの正とするのは、ローカルの作業ツリーではなくブランチです。dxs configuration get <type> <referenceName> -b <branchId>でブランチを調べてください。404（DXS-404-001）なら名前は空いています。該当するものが見つかった場合、コンポーネントはすでに存在するため、そこで停止して報告し、上書きしないでください。呼び出し元は別の名前を希望するか、既存のコンポーネントの変更を希望している可能性があります（それはscaffolderではなく、creatorスキルの役割です）。

6. スケルトンを一時ファイルbody.jsonに書き込みます。 このローカルファイルは一時的な作業用ストレージにすぎません。記録の正本はファイルではなくブランチです。呼び出し元が保持するローカルの作業コピーはあくまで便利なミラーであり、正本にはなりません。

7. 検証してから、dxsを使ってブランチ上に作成します — 2つのステップがあり、最初のステップの成功が2つ目の条件になります：

   dxs configuration validate <type> -b <branchId> -D body.json   # exit 1 = errors found
   dxs configuration upsert   <type> -b <branchId> -D body.json
   

   validateはエラーを検出すると終了コード1を返します。これは検証で問題が見つかったことを示すものであり、CLIの故障ではありません。validation_errorsの内容を読み、スケルトンを修正して再検証してください。ゲートを通過していない本文に対してupsertを実行してはいけません。../datex-studio-shared/configuration-roundtrip.mdを参照してください。

   upsertはreferenceNameに基づいて作成と更新を判断します。ブランチ上に何もないことは手順5で確認済みなので、作成処理に進みます。これで、最小限の有効なコンポーネントがブランチ上に作成されます。

8. 対応するcreatorスキルに引き継ぎます。 スケルトンはブランチ上にあるため、creatorは編集モード（取得 → 内部の.jsonを抽出 → 作成 → upsert）で作業します。今後このコンポーネントタイプを担当するcreatorスキルと、次に行うべき明確なステップを呼び出し元に伝えてください（例：「gridはブランチ上にスキャフォールディングされました。grid-creatorを呼び出して列を追加し、データソースを接続してください」「storageはスキャフォールディングされました。storage-creatorを呼び出してobjectTypeDefの列を定義してください」）。

ディスパッチテーブル

種類	サフィックス（referenceName）	configurationTypeId	スケルトンの参照先	作成スキル
action	-footprintFlow	18	action-creator/references/actions.md	action-creator
function	-flow	9	function-creator/references/functions.md	function-creator
interface	-customType	22	type-definition-creator/references/type-definitions.md	type-definition-creator
enum	-customType	22	type-definition-creator/references/type-definitions.md	type-definition-creator
grid	-grid	3	grid-creator/references/grids.md	grid-creator
hub	-hub	2	hub-creator/references/hubs.md	hub-creator
form	-form	5	form-creator/references/forms.md	form-creator
editor	-editor	4	editor-creator/references/editors.md	editor-creator
embed	-embed	20	embed-creator/references/embeds.md	embed-creator
selector	-selector	7	selector-creator/references/selectors.md	selector-creator
storage	-storage	17	storage-creator/references/storage.md	storage-creator
backendTest	-backendTest	24	backend-test-creator/references/backend-tests.md	backend-test-creator
datasource（プラットフォームバリアント）	-datasource	6	datasource-creator/references/datasources.md	datasource-creator
footprintDatasource（Footprint バリアント）	-footprintDatasource	19	datasource-creator/references/datasources.md	datasource-creator

テーブルに関する注記：

• データソースには2つのコンポーネントバリアント（-datasource と -footprintDatasource）があり、それぞれ異なる configurationTypeId を持ちます。各バリアントでは、どちらのクエリタイプ（OData または flow）も使用できます。バリアントはランタイム層を、クエリタイプはデータの取得方法を示します。選択可能性のマトリックス（セレクターが -datasource.json のみに戻るなど）は datasource-creator/references/datasources.md が管理しています。ここで再導出せず、そちらのリファレンスに従ってください。
• interface と enum は -customType.json コンポーネントタイプ（cti=22）を共有します。内部の本体構造は大きく異なります。2つの形式については type-definition-creator/references/type-definitions.md を参照してください。
• テーラードバリアント（たとえば、baseConfiguration オーバーレイで既存の core-library グリッドをテーラリングする場合）では、これらのスケルトンから作成しないでください。テーラードオーバーレイの形式は異なり、tailoring-overlay スキルが管理しています。このスキャフォールダーを経由せず、そのスキルを直接呼び出してください。
• 既存のコンポーネントを変更する場合は、新しいファイルをスキャフォールドしないでください。対応する作成スキルを直接呼び出してください。このスキルは新しいコンポーネントのみをスキャフォールドします。

ルール

• スケルトンはリファレンスドキュメントから取得します。 本体を作成する前に、必ず該当する references/<type>.md を読みます。記憶を頼りに JSON 構造を作らないでください。スケルトンの形状とデフォルト値については、リファレンスドキュメントが正となります。
• ブランチを正とします。 dxs configuration upsert によってスケルトンはブランチに反映されます。ローカルの body.json は一時的な作業用ファイルであり、正式な記録ではありません。ローカルのファイルパスを確認するのではなく、dxs configuration get で存在を確認してください。
• referenceName はファイル名の拡張子を除いた部分と完全に一致させる必要があります。 例外は actions のみで、その referenceName は _action で終わりますが、ファイルのサフィックスは -footprintFlow.json です。これは文書化された規約であり、誤記ではありません。バックエンドタイプでは title は referenceName と同じになりますが、ユーザー向けタイプ（form、editor、hub、grid、embed、standalone selector）では、表示用の title を別途、文頭のみ大文字の文体で指定する必要があります。手順 4 と ../datex-studio-conventions/naming-conventions.md を参照してください。
• Description は必須で、100 文字以下でなければなりません。 SQL の列上限によるものです。指定されるまでは先に進まないでください。黙って切り詰めず、依頼者に確認してください。
• configurationTypeId は、Studio の Validate では検証されませんが、コード生成時に重要です。 cti が誤っていると、壊れたコンポーネントに触れていないファイルを起点として、Preview のカスケード障害が発生します。同じタイプの動作するコンポーネント、または上記のディスパッチテーブルから必ずコピーしてください。障害モードについては ../datex-studio-conventions/file-format.md を参照してください。
• 有効性を満たす最小限の構成にしてください。 Validate に合格するためにスケルトンが要求するものを超えて、プレースホルダープロパティ、フィルター、列、コードを追加しないでください。本体の作成はクリエータースキルの担当です。このスキルではブランチ上に空の有効なコンポーネントを作成し、引き継ぎます。
• 競合があれば停止してください。 dxs configuration get でブランチ上に同じ referenceName が見つかった場合、上書きしないでください。依頼者に報告し、名前を変更するか、（クリエータースキルを使用して）既存のものを変更するか、削除するかを判断してもらいます。
• 1 回の実行につきスキャフォールドは 1 つです。 依頼者が複数のコンポーネント（例：hub とそのタブグリッド、フィルターデータソース）を作成したい場合は、1 つずつ作成し、適切な順序で引き継いでください。通常は、まずデータソースを作成し、次にそれを利用する UI コンポーネントを作成します。