basic-custom-app-build

Domo 基本アプリ構築プレイブック

使用するタイミング

• Domo の新しいカスタムアプリのプロジェクト開始時に使用します。
• 既存のアプリを引き継ぎ、プラットフォームのベストプラクティスに沿うように標準化する際に使用します。

進捗チェックリスト

このチェックリストをコピーして、作業に合わせて更新してください。

Build Progress:
- [ ] Phase 0: Rules loaded
- [ ] Phase 1: Manifest & contracts
- [ ] Phase 2: App shell (domo.js)
- [ ] Phase 3: Data access
- [ ] Phase 4: App storage (if needed)
- [ ] Phase 5: Toolkit clients (if needed)
- [ ] Phase 6: Feature skills (AI / Code Engine / Workflow — as needed)
- [ ] Phase 7: Performance review
- [ ] Phase 8: Build & publish
- [ ] Phase 9: Verification

フェーズ 0 — ルールの読み込み（常時）

コードを書く前に適用してください。

• rules/core-custom-apps-rule.md
• rules/custom-app-gotchas.md

フェーズ 1 — マニフェストと契約

manifest を使用します。

まず、データセット、コレクション、ワークフロー、Code Engine パッケージなど、すべての外部リソースのマッピングを定義します。ほかのすべての要素がこれに依存します。 エイリアスに使用できる名前のみを使ってください（^[A-Za-z][A-Za-z0-9]*$）。スペースや特殊文字は使用しないでください。

manifest.json の作成に加えて、ルートフォルダーに既存の thumbnail.png があるか確認し、新しいアプリの public フォルダーにコピーしてください。

既存アプリの引き継ぎですか？ 変更を加える前に、現在の manifest.json を実際のコードでの使用状況と照合して監査してください。

フェーズ 2 — アプリの基本構成

domo-js を使用します。

基本構成をセットアップします。ryuu.js のインポート、domo.navigate() によるナビゲーション、イベントリスナー、環境情報を設定してください。

DA CLI を使う上級ユーザーですか？ スキャフォールディングとマニフェストインスタンスのワークフローにも da-cli を使うよう、エージェントに依頼してください。ユーザーがエージェントに使用を明示的に依頼しない限り、使用しないでください。

フェーズ 3 — データアクセス（Domo データセットへのクエリが必要な場合）

dataset-query（主に使用）と data-api（ルーティングの概要）を使用します。

@domoinc/query でクエリを作成してください。すべてのデータセットの読み取りには Query API を使用します。ページフィルターが適用され、サーバー側で集計されます。

UI やデータマッピングのロジックを書く前に、manifest.json datasetsMapping 内のすべてのデータセットについて実際のスキーマを取得し、明示的なフィールドマップ（日付フィールド、主要な指標、ディメンションフィールド）を作成してください。スキーマで確認できていない限り、sales、category、order date のような名前を推測して使用しないでください。

必要なフィールドが要求された可視化に不足している場合は、ゼロを表示するのではなく、明確なマッピングエラーを出して速やかに失敗させてください。

生の SQL が必要ですか？ sql-query を使用してください。ただし、SQL ではページフィルターが無視されることに注意してください。

フェーズ 4 — アプリストレージ（appdb、またはユーザーデータの入力が必要な場合）

ストレージを作成する必要がある場合は、appdb と appdb-collection-create を使用します。

アプリがデータセットを読み取るだけの場合は、このフェーズをスキップしてください。アプリ固有の状態、ユーザー設定、またはドキュメント形式のデータを永続化する必要がある場合は、AppDB を使用します。

必要なコレクションがまだ存在しない場合は、ドキュメントの CRUD を接続する前に appdb-collection-create を実行して、データストアとコレクションをプロビジョニングしてください。

フェーズ 5 — ツールキットクライアント（appdb、Domo ワークフロー、または Domo SQL クエリが必要な場合）

toolkit を使用します。

利点がある場合は、型付きの @domoinc/toolkit クライアントに移行してください（構造化された応答、型安全性）。シンプルなアプリでは必須ではありません。

フェーズ 6 — 機能スキル（必要に応じて）

アプリに実際に必要なスキルのみを読み込んでください（ここでは 3 つの例を挙げていますが、ほかにも多くのスキルを利用できます）。

必要な機能	スキル
AI によるテキスト生成、またはテキストから SQL への変換	ai-service-layer
サーバー側関数（シークレット、外部 API）	code-engine + code-engine-create + code-engine-update
自動化ワークフローのトリガー	workflow

判断ガイド： ユーザーが AI、Code Engine、または Workflows に言及していない場合、このフェーズ全体をスキップしてください。アプリに不要な複雑さを加えないでください。

サーバー関数が必要となる必須条件： アプリの機能にサーバー側の動作（シークレット、外部 API 呼び出し、権限が必要な変換）が必要な場合は、まず Code Engine パッケージを作成または更新し、次に manifest.json packagesMapping を同期してから、アプリのコードで実行時の呼び出しを接続してください。

フェーズ 7 — パフォーマンスのレビュー

performance を使用します。

最終確定の前に、すべてのクエリを確認します。データセット全体の取得、集計の不足、不要な列がないかをチェックします。

フェーズ 8 — ビルドと公開

publish を使用します。

npm run build → cd dist → domo publish。初回の公開後、生成された id をコピーしてソースマニフェストに戻します。

フェーズ 9 — 検証

公開後、以下を確認します。

• Domo でアプリがコンソールエラーなしに読み込まれる
• すべてのデータセットエイリアスが解決される（データ呼び出しで 404 が発生しない）
• AppDB コレクションがカード UI に接続されている（使用している場合）
• ページフィルターが正しく反映される（アプリがダッシュボードに埋め込まれている場合）
• ナビゲーションで <a href> ではなく domo.navigate() を使用している
• サムネイルが public フォルダーにコピーされている

ビルド時のガードレール

• クライアントサイドのみ：SSR／サーバールート／サーバーコンポーネントは使用しません。
• Vite の base: './' を使用します。
• 書き換えを意図的に処理する場合を除き、HashRouter を優先します。
• domo.env.* は利便性のためだけのものとして扱い、信頼性に関する判断には検証済みの ID を使用します。