nocobase-prototype-repro

目標

プロトタイプと一言の依頼から、忠実な NocoBase アプリを作成します。これはメタ／オーケストレーションスキルです。nocobase-data-modeling、nocobase-ui-builder、nocobase-app-discipline を順に実行し、忠実度を左右する2つの要素、領域からネイティブブロックへのマッピングと見た目の収束ループを加えます。CLI の使い方を再説明することはせず、仕組みについては関連するスキルに委ね、再現に特有の判断のみを担います。

使用する場合／対象外

必須条件（このスキルを選ぶ前に確認してください）： 照合対象となる実際のプロトタイプ（HTML ファイル、スクリーンショット、またはリンク）が必要です。プロトタイプがなく、忠実度の差もない場合、このスキルは対象外です。単に「アプリ／ページを作ってほしい」という依頼は、nocobase-app-discipline（システム全体）または nocobase-ui-builder（単一ページ／編集）の対象です。このスキルによって通常の構築フローを妨げないでください。

次の場合に使用します：

• ユーザーからプロトタイプ（HTML ファイル、リンク、スクリーンショット、または curl で取得する public/prototypes/... の URL）が提示され、NocoBase で再現するよう求められた場合。
• ページはすでに存在するものの、ユーザーが単調／見栄えが悪い／プロトタイプと一致しないと述べている場合、または領域をテーブルではなくリスト／カード／カンバンにすべきだと求めている場合。つまり、視覚的な目標と忠実度の差がある場合です。

対象外 — 引き継ぎ、このスキルでは対応しないでください：

• 純粋なデータモデリング（視覚的な目標を伴わないコレクション／フィールド／リレーション）→ nocobase-data-modeling。
• ワークフロー／自動化 → nocobase-workflow-manage。ACL／権限 → nocobase-acl-manage。プラグイン開発 → nocobase-plugin-development。
• 視覚的な目標も忠実度の差もない、UI の局所的な編集（フィールドの移動、アクション名の変更、リアクションの調整など）→ 直接 nocobase-ui-builder に引き継ぎます。このスキルのオーバーヘッドが有効なのは、プロトタイプの見た目や動作に合わせる場合のみです。機械的な表層の編集なら、ui-builder に直接進んでください。
• プロトタイプなしで業務上の一文からページ全体を作成する場合 → まず簡単なプロトタイプを作成し（prototype-authoring.md）、その後このスキルを使用します。または、ユーザーが一般的なページを求めているだけなら、nocobase-ui-builder の applyBlueprint が対象です。

ルーター — タスクの形に合わせて、まず読む

該当するルートを1つ選び、その「最初に読む」ドキュメントを確認してください。そのルートだけでは足りない場合に限り、「次に読む」ドキュメントを開いてください。兄弟スキルが仕組みを担当し、ここにあるリファレンスファイルが再現に特化した判断を担います。

タスクの形	最初に読む	必要に応じて次に読む
プロトタイプを受け取り、エンドツーエンドで再現する	spec-template.md（Phase 1 SPEC）	decomposition-grammar.md、block-recipes.md、gotchas.md、visual-loop.md
既存ページが単調／見栄えが悪い／ずれている	visual-loop.md	block-recipes.md、gotchas.md
「この領域にはどのブロックを使うべきか？」	以下の 領域 → ネイティブブロック の表	decomposition-grammar.md、block-recipes.md
ウィジェット（KPI カード、ドーナツグラフ、リーダーボード、期限間近のアラート、プログレスバー、トレンド、ファセットフィルター、カードグリッドなど）の JS 本体 が必要	template-library/_index.md — $p 入力コントラクト付きの、コピーして使えるウィジェット本体57個	block-recipes.md
JS、フローサーフェス、ポップアップ、チャートの 仕組み と実行可能な CLI を構築／編集する	nocobase-ui-builder（その js.md / popup.md / chart.md / runjs-* / page-archetypes.md）	—
コレクション／フィールド／リレーション	nocobase-data-modeling	—
スコープの規律、シードの基準、命名、最終レポート	nocobase-app-discipline	—
プロトタイプが与えられておらず、自分で作成する必要がある	prototype-authoring.md	—
1行のプロンプトから、ビルドを別のエージェントに引き継ぐ	handoff.md	—
リファレンス一覧全体	index.md	—

再現度に差が出る理由 — 重要な要素（必ず身につけてください）

多数の再現作業で観察された影響度の高い順です。

1. スクリーンショットを撮り、比較し、修正するループ。 これが最も大きな要因です。レンダリングし、自分のスクリーンショットをプロトタイプの横に並べて確認し、差分を列挙して反復するエージェントは、精度を高めていきます。作って完了を宣言するエージェントは、「エラーはないが見栄えが悪い」段階で頭打ちになります。テキストだけの検証で証明できるのは「レンダリングできる」ことです。「一致している」と証明するには、視覚的な確認が必要です。visual-loop.md を参照してください。
2. 落とし穴を事前に把握する。 実行がうまくいかないケースで停滞の原因となる10〜20％は、ほぼ常にアルファ版の JS サンドボックスとフローサーフェスの JSON コントラクトです。これらを事前に提示しておけば、失敗を約10〜20回減らせるうえ、エージェントが諦めてページ全体を1つの大きな JS ブロックにまとめてしまう失敗パターンも防げます。gotchas.md を参照してください。
3. 対象を厳密に指定する。 「ページ UID X、ブロック UID Y、この N 項目を実施し、完了前に検証する」は、「このページを修正する」より効果的です。対象が曖昧だとスコープがずれたり、CRUD だけで作業を終えたりします。
4. 領域ごとに適切なブロックを選ぶ。 どこにでもテーブルを使うのが、「単調」になる最大の原因です。プロトタイプで求められているのは、多くの場合、カードリスト、カンバン、カレンダー、グリッドです。領域の表と block-recipes.md を参照してください。
5. モデル。 高性能なモデルはコントラクトのエラーから復旧でき、視覚的なレビュアーとしても機能します。性能が低めのモデルでも、スコープを厳密に絞り、落とし穴を事前に示した機械的な作業ならうまくこなせます。上記の要素を活用すれば、中程度のモデルでも忠実に再現できます。

ワークフロー — 段階的に進め、各段階でユーザー確認を行います

順番に進めてください。▣ CONFIRM ゲートごとに作業を止め、次の段階に進む前にユーザーの承認を得てください。 小規模な単一リージョンの調整を超える作業は、ひと息に進めるのではなく、複数回のやり取りに分けて計画してください。ユーザーは大きなステップごとに方向性を決めたいと考えています。

Phase 0 — 対象を読み込む。 プロトタイプがすでにある場合は、それを読み込むところから始めてください。プロトタイプなしでユーザーから業務内容を説明する一文だけが提供されている場合に限り、プロトタイプを作成します（prototype-authoring.md）。プロトタイプ（視覚的な目標）を curl／読み込みます。これがないと、ビルドが一般的なテーブルや大きな JS ブロックひとつに劣化します。埋め込みの <script type="application/nb-spec+json"> があるか確認し、あればそれを正規の仕様（データモデル、リージョンごとのブロック、インタラクション、JS カーネル）として解析し、推測の代わりにその notes／jsKernels を尊重してください。block-recipes.md と gotchas.md を読み込みます。環境を特定し、すべての nb api に -e <env> -y を指定してください。実際のページ／ブロックの UID を取得し（flow-surfaces get／desktopRoutes）、ドキュメントに記載された UID を決して信用しないでください。

Phase 1 — 分析と計画 → SPEC ▣ CONFIRM。 spec-template.md に沿って構造化された SPEC を作成します（パーサーではなく、レンダリングされたプロトタイプと照らし合わせて LLM が判断します）。データモデル、シグネチャーページを含むページ一覧、リージョン → ブロックの対応表（「すべてをテーブルにする」ことを防止）、およびインタラクションのチェックリストを記載します。リージョンごとに確認し、すべての操作要素（件数付きファセット／複数選択フィルター、ステータスピル、検索、ソート、幅いっぱいのグリッド、クリック → ポップアップ、インライン編集、ドラッグ、ライブ更新）を列挙してください。それぞれをレシピに対応付け、ネイティブでは実現できないものには JS カーネルの印を付けます。SPEC を提示し、明示的な確認を得てください。

Phase 2 — モデル＋ネイティブ CRUD＋初期データ ▣ CONFIRM。 コレクション／フィールド／リレーションを一度に構築します（nocobase-data-modeling）。構築中に編集してはいけません。プレーンなネイティブのバックエンドを用意します（Table＋Filter＋Add new＋View/Edit）。View は Details と associationName＋sourceId={{ctx.view.inputArgs.filterByTk}} を使った関連サブテーブルを含むドロワーを開きます。各列挙型の分岐に初期データを入れ、親ごとに子を 2 件以上作成し、公開デモではすべて英語にし、十分なデータ密度を確保してください（カレンダーは 1～2 か月分を埋めます。データが少ないと壊れているように見えます）。CRUD が動作することを確認してください。

Phase 3 — リージョンごとにプロトタイプへ近づける。 まずネイティブで実現します。シグネチャーリージョンごとにブロックを選んで構築し、ネイティブブロックで表現できないカーネルに限って JS を追加してください。ページ全体を JS ブロックひとつにまとめてはいけません。 検証可能な状態を保つため、一度にひとつのリージョンを進めます。実装方法と実行可能なスニペットは block-recipes.md を参照してください。

Phase 4 — 視覚的一致の反復 ▣ CONFIRM＋報告。 レンダリング → スクリーンショット → ビジョン対応の工程でプロトタイプと比較 → 具体的な差分一覧 → 修正 → 再撮影を、一致するまで繰り返します。レビュー担当は、同じエージェントによる自己チェックでも、別のビジョンモデルでも構いません。状況に応じてモデルに選ばせてください。手順の全容は visual-loop.md を参照してください。報告書（変更した UID、変更内容、差分／トレードオフ、スクリーンショット）を提出して確認を得てください。

リージョン → ネイティブブロック（単調なテーブルを避ける）

ネイティブ優先の段階表 — プロトタイプで必要なところまで進めてください。一致する最も低い段階を選びます。

1. ネイティブブロック＋ネイティブフィールド。 すべての領域で、まずこれを試してください。プレーンなネイティブフィールドを使ったネイティブの Table／List／GridCard／Details／Kanban／Calendar／Chart が、すでにプロトタイプにほぼ近い見た目（適切なデータ、適切な形状、十分に近いレイアウト）になっているなら、そのまま公開して次に進みます。 すでに十分近い領域に JS を追加しないでください。ネイティブフィールドならバインド／ソート／フィルタリング／書式設定を追加作業なしで利用でき、再現度を損なう JS のデータバインディングの不具合もありません。「十分なネイティブ表示」は「意欲的でも空表示になる JS」より優れています。
2. ネイティブブロック＋JS アイテム — ネイティブフィールドでは足りない場合に推奨される既定の選択肢です。フィールドでは見た目（スタイル付きカード、ステータスピル、進捗バー、KPI 数値、スパークライン、リング／ゲージ、リッチな先頭列）を再現できない場合は、ネイティブコンテナーを維持したまま（リソースバインド／CRUD／フィルタリング／ページネーション／ACL は引き続きコンテナーが担います）、カスタム表示をその中にJS アイテム／JS フィールド／JS カラム／JS アクションとして描画します。単独のブロックではなく、こちらを選んでください。本文をゼロから手書きしないでください。template-library/ には、これらの多くで動作する本文（KPI カード、ドーナツ、リーダーボード、期限間近／在庫僅少アラート、進捗バー、トレンド、ファセット、カードグリッド）が用意されています。$p を入力し、モデルの runJs.code に貼り付けて調整してください。
3. 独立した JS ブロック — 最終手段です。領域にデータコンテナーがまったくない場合（発光するマップ、キオスクスキャナー、単独のゲージ）に限ります。データに紐づく領域やページ全体を、ひとつの JS ブロックにまとめないでください。

この表では、プロトタイプの各領域を対応する段階に割り当てています。「JS カーネル？」列はネイティブコンテナー内に描画されるコンテンツを示しており、コンテナーの代替ではありません。

プロトタイプの領域の見た目	使用するもの	JS カーネル？
フォーム — カスタムコントロールやライブプレビューを備えた、作成・新規作成・編集画面	ネイティブの Form ブロックに、内部にネストした JS アイテム／JS アクションを配置します（ピル、カウンター、フォーム値に連動するライブプレビュー）。単独の JSBlock フォームは使用しません。	はい — アイテム／プレビュー
スプレッドシート／項目が密に並ぶ行	Table	任意：リッチな先頭列として、レコード全体を表示するJS 列を1つ
カードのフィード／リスト、連絡先、アクティビティ、「現在 X」の表示	List + JS アイテム（各行でレコード全体を描画）。1列のカードフィード	はい — カードの本文
左側にファセットレール、ステータスピル、グリッドがあるカタログ	リッチカタログのアーキタイプ：JS ファセットレール（複数選択＋件数）+ ステータスピルバー + List + JS カード + CSS の自動配置グリッド。相互にフィルターを適用します。block-recipes.md §3b	はい — ファセット、ピル、カード
幅いっぱいに広がるレスポンシブなカードグリッド	List + JS カード + CSS の自動配置（repeat(auto-fill, minmax(280px,1fr))）。block-recipes.md §3	はい — カードの本文
固定ブレークポイントのシンプルなカードグリッド（ファセットなし、幅いっぱいに広げない）	GridCard + JS カード — GridCardItemModel で add-field --renderer js を実行し、兄弟の DetailsItemModel ノードを削除して、showLabel:false を設定します。block-recipes.md §3	はい — カードの本文
写真／アバターのギャラリー、人物ディレクトリ（ネイティブフィールドのみ）	GridCard（ネイティブフィールド、JS なし）	任意
ステータス列のあるボード、パイプライン	Kanban、groupField=<status>。カードのフィールド上限は2つです。JS カードフィールドを追加します	はい — カード
日ごとのカレンダー／スケジュール／部屋の予約	Calendar（startField/endField/titleField）	まれ
チャート、KPI、分析ダッシュボード	Chart（単一テーブルの集計にはビルダーを使用し、ゲージ／ヒートマップにはカスタムの生 ECharts を使用します）。大きな数値で示す KPI → 小さな JS ブロック	KPI のみ
ツリー／組織図／ネストされたカテゴリ	Tree ブロック	いいえ
別の領域を操作するフィルターバー	FilterForm + ブロック間フィルター	場合による
データブロック上のクイックフィルターピル／カスタムコントロール	ブロックの右上ツールバーにある JS アイテム（add-action --use JSItemActionModel を使用）	はい — ツールバーのウィジェット
クリック時に表示する詳細ドロワー／ポップアップ	実際の ViewActionModel を使ったネイティブポップアップ（ctx.openView(<viewActionUid>, {filterByTk})）	該当なし
データコンテナーのないカスタム表示：発光する地図、キオスク、ゲージ、独立したフィード	JS ブロック（単独で使用できる唯一の正当なケース）	はい

コンテナーとコンテンツの分離（基本ルール）。 データに紐づくすべての領域では、コンテナーは常にネイティブブロック（Form/Table/List/GridCard/Kanban/Calendar）を使用します。リソースのバインド、CRUD、フィルター、ページネーション、ACL をそのまま利用できます。JS が描画するのは、そのコンテナーの内部にあるコンテンツのみです。つまり、JS アイテム（フォームフィールド／リストカード）、JS 列（テーブルセル）、JS フィールド（レコード全体のカード）、JS アクション（ボタン）、または右上ツールバーの JS アイテム（ピル／カスタムコントロール）です。プロトタイプの見た目をネイティブコンテナーの内部にそのまま再現し、コンテナーを取り除いてはいけません。単独の JS ブロックは、データコンテナーのない領域（地図、キオスク、ゲージ）に限って使用します。ネイティブでない要素やインタラクティブな要素はすべて JS アイテム／ブロックにする必要があります。省略したり、静的なネイティブフィールドで代用したりしてはいけません（入力画面に表示するライブの電話プレビューは、静的なカードではなく、ctx.form.getFieldsValue() と formValuesChange にバインドされた JS アイテムです）。

厳守事項

• コンテナはネイティブ、コンテンツは JS。 すべてのデータ領域のコンテナはネイティブブロックにし、JS はその内部の描画にのみ使用します。ネイティブのデータコンテナを独立した JS ブロックに置き換えてはいけません（JS ブロックはデータを含まないビジュアル専用です）。1 ページを 1 つの JS ブロックだけで構成してはいけません。
• フィルター演算子はメタデータに基づいて選択します。 ネイティブまたは JS のフィルター条件をコピー、適応、作成する前に、トピック filter の nocobase-utils スキルを読み込み、フィルター条件の形式を確認します。終端フィールドの実際のフロントエンドインターフェース／型を特定し、そのフィールドグループの許可リストから演算子を選び直してください。テンプレートのフィールドを変更すると、元の演算子が引き続き適用できるという前提は無効になります。日付の比較には $lt、$lte、$gt、$gte を使用しません。
• デプロイ済みの JS は curl flowModels:save（全フィールドをフラットにアップサートし、parentId を保持）で編集します。flowModels:update は使用しないでください（parentId がクリアされ、ノードが消失します）。
• ブロックを追加または削除した後は、グリッドの v2 の props.layout、レガシーの props.rows、stepParams.gridSettings.grid を一貫して同期してください。同期しないと、クライアントで誤って「Collection may have been deleted」がスローされます。
• JS サンドボックス：JSFieldModel では ctx.libs.React/antd/antdIcons を使用します（ctx.antdIcons ではありません）。window、document、localStorage は使用できません。location という名前のローカル変数は使用できません。フォント文字列にスペースを含めることはできません（SFMono-Regular）。レコード全体は ctx.getVar('ctx.record') で読み取ります。全項目は gotchas.md を参照してください。
• select→Tag／色のすべてのマッピングでは、未知の列挙値に対して元の値にフォールバックさせてください（そうしないと描画時に「Tag not found」が発生します）。
• 完了 = 検証済み： キャッシュのない新しいブラウザーで、注入した localStorage NOCOBASE_TOKEN を使用して Playwright を実行し、/admin/<pageSchemaUid> を開きます。すべてのブロックが描画されること、コンソール／ページエラーがないこと、操作が機能することを確認し、さらにプロトタイプとの見た目の比較も行ってください。

参考資料インデックス

「先に読む／次に読む」の案内を含む全リストは index.md を参照してください。再現に特化したドキュメント：spec-template.md · decomposition-grammar.md · block-recipes.md · visual-loop.md · gotchas.md · prototype-authoring.md · handoff.md。すぐに使えるウィジェット本文：template-library/_index.md（57 個の JS ブロック／アイテム／列の本文と、それぞれの $p コントラクト）。すべてのフィルターパスでの演算子の選択は、フィルター条件の形式に従います。