| name | code-apps |
| description | Power Apps Code Apps（コードファースト）の初期化・Dataverse 接続・UI 設計・開発・デプロイ。TypeScript + React + Tailwind CSS で開発する。CSP 構成・メール送信パターンも含む。 |
| category | ui |
| triggers | ["Code Apps","power-apps init","power-apps push","add-data-source","DataverseService","Tailwind","shadcn","React","TypeScript","Vite","Code Apps デプロイ","nameUtils パッチ","日本語サニタイズ","Code Apps デザイン","UI 設計","コンポーネント選定","画面レイアウト","ギャラリー","テーブル","カンバン","ガントチャート","ダッシュボード","フォーム","デザイン例","iframe","embed","埋め込み","CSP","Content Security Policy","frame-src","connect-src","メール送信","PDF添付","PDF生成","htmlToPdfBase64","ContentBytes","base64","html2canvas","jsPDF","日本地図","地図","マップ","JapanMap","add-flow","list-flows","フロー呼び出し","フロー連携","AI Builder","詳細画面","詳細ページ","detail page","RecordListPanel","レコード一覧パネル","インライン編集","executeAsync","dataSourcesInfo","Copilot Studio コネクタ","Copilot Studio 直接","ExecuteCopilotAsyncV2","shared_microsoftcopilotstudio","エージェント呼び出し","会話継続","conversationId","デプロイして","プッシュして","ディープリンク","deep link","queryParams","パラメータ渡し","URL パラメータ"] |
Code Apps 開発スキル
Power Apps Code Apps（コードファースト）を TypeScript + React + Tailwind CSS で開発する。
UI 設計・CSP 構成・メール送信パターンまで Code Apps 開発の全領域をカバーする統合スキル。
[!NOTE]
Microsoft Learn の現行概要では、Code Apps は React / Vue などの SPA を Power Apps 上でホストする仕組み とされている。
この開発標準はその中でも React ベース実装に標準化したガイドであり、他フレームワーク一般論ではなく、このリポジトリのテンプレートと運用実績に基づく推奨事項をまとめている。
1. 概要
Code Apps 開発は 設計 → 初回デプロイ → データソース接続 → 改善デプロイ の順に進む。
[!NOTE]
サブエージェント並行実行パターン: architecture スキルで Code Apps が確定し、dataverse スキルで
スキーマが承認されたタイミングで、このスキルがサブエージェントとして起動される。
Dataverse 構築（--skip-localize フェーズ）と Code Apps 開発（scaffold → deploy → add-data-source）は
並行して進める。Dataverse 構築が先に終わったら --localize-only でローカライズ＆デモデータ投入。
標準ワークフロー全体像
[設計] ① デザインテンプレートを選ばせる（6種・プレビュー付き）
② 画面設計（design-pattern）→ ユーザー承認
│
[§2 初回デプロイ]
<<<<<<< HEAD
③ テンプレート scaffold + npm install
=======
③ テンプレート scaffold + npm install（Dataverse 構築 Phase 2 と並行して即着手／VS Code では Code Apps サブエージェントとして起動）
>>>>>>> origin/main
④ pac code init（power.config.json 生成）
⑤ vite.config.ts 必須設定の確認 / .env 設定
⑥ npm run deploy（build + pac code push）→ Dataverse 接続確立
│
[§3 データソース接続]
⑦ pac code add-data-source（toggle_table_lang.py で日本語回避）
⑧ dataSourcesInfo は re-export / getClient(dataSourcesInfo)
│
[§4 改善デプロイ]
⑨ src/ 実装 → npm run build → pac code push（反復）
この後の章構成
| 章 | 内容 |
|---|
| §1 概要（本章） | 標準ワークフロー全体像・大前提・設計フェーズ（デザインテンプレート選択） |
| §2 初回デプロイ | 環境前提・scaffold・init・初回 build & push |
| §3 データソース接続 | add-data-source・dataSourcesInfo・Lookup 名前解決 |
| §4 改善デプロイ | 開発時の必須ルール・再デプロイ・プレデプロイレビュー |
| §5 リファレンス | 全リファレンス索引・技術スタック・.env |
[!NOTE]
本スキル内のコード例は {prefix}_tablename 等のプレースホルダーで汎用化されています。
実際のテーブル名・型名は、あなたのプロジェクトのエンティティに読み替えてください。
パターン（Lookup 名前解決、SDK ラッパー、useMemo マップ等）はそのまま適用できます。
設計フェーズ（実装前に必須）
コードを書く前に、デザインテンプレートの選択と UI 設計を行い、ユーザーの承認を得ること。 手順:
- デザインテンプレート集 の 6 種を一覧＋プレビューで提示し、ユーザーに 1 つ選んでもらう（デプロイされるアプリは常に 1 テンプレート。dark/light は
ThemeProvider + ModeToggle）。
- デザインシステム を読み込み、画面構成・コンポーネント選定・Lookup 名前解決パターンを設計する。
- 設計（選択テンプレート＋画面設計）を提示し、「この設計で進めてよいですか？」と承認を得る。承認の証跡を残す場合は、設計承認 Issue テンプレート を対象プロジェクトの
.github/ISSUE_TEMPLATE/ にコピーして Issue を作成する。
- 承認後、選択テンプレートの CSS Variables を
styles/index.pcss に適用してから実装する（変数一式・適用手順は デザインテンプレート集）。
CRUD 画面は CRUD UI 標準パターン に必ず従う: 一覧は行／カード全体をクリックして詳細を開く（目アイコン等の小さなクリック領域は使わない）、詳細の編集はモーダルではなくインライン編集モード、行内の削除・クイック操作は e.stopPropagation()、削除確認はブラウザの confirm() ではなくモーダル（useConfirm() / AlertDialog）。指示がなくても、テーブルごとに「一覧・詳細（インライン編集）・作成・削除」を標準実装すること。
設計で提示する内容: 選択テンプレート、画面一覧（ページ名・ルート）、各画面のコンポーネント構成、カラム定義、Lookup 名前解決方法（_xxx_value + useMemo Map）、ナビゲーション構造。
大前提（ソリューション運用）: Dataverse テーブル・Code Apps・Power Automate・Copilot Studio は同一ソリューション内に開発し、.env の SOLUTION_NAME / PUBLISHER_PREFIX を全フェーズで統一する。詳細は standard スキル。
2. 初回デプロイ
環境の前提条件（デプロイ前に必ず確認）
1. Power Platform 管理センターで「コード アプリを許可する」がオン
→ オフの場合: CodeAppOperationNotAllowedInEnvironment (403) エラー
2. PAC CLI 認証プロファイルが対象環境用に作成済み
pac auth create --name {profile-name} --environment {ENVIRONMENT_ID}
pac auth list # * が付いているのがアクティブ
3. power.config.json は pac code init で生成する
→ テンプレートから手動コピーしない
→ 別環境の appId が残っていると: AppLeaseMissing (409) エラー
→ 新規環境では必ず pac code init で新規生成
プロジェクトの 3 つの生成段階（生成物は手動作成・コピー禁止）
| 生成元 | 主な生成物 |
|---|
| ① テンプレート scaffold | vite.config.ts / plugins/ / styles/ / src/ / tsconfig* / package.json 一式 |
② pac code init | power.config.json（＋ .power/）。vite.config.ts や plugins/ は生成しない |
③ pac code add-data-source | .power/schemas/appschemas/dataSourcesInfo.ts / src/generated/ |
どのファイルを誰が生成し、何をカスタマイズしてよいかの一覧は ビルドリファレンス。SDK 管理ファイル（power.config.json / dataSourcesInfo.ts / src/generated/）は手動編集禁止。
テンプレートのプレースホルダー設計
テンプレートのデモメニューには template: true フラグが付いている。このフラグが残ったまま npm run predeploy を実行するとエラーになるため、削除忘れを防げる。
{ label: "顧客", path: "customers", iconKey: "customers", template: true },
{ label: "ダッシュボード", path: "dashboard", iconKey: "dashboard" },
デプロイ前は npm run predeploy（.env・power.config.json を自動検証）→ npm run deploy（predeploy + build + push を一括実行）。
標準ワークフロー
上から順に実行すれば動く正常系フロー。各 Step の詳細・必須設定・型定義は ビルドリファレンス を参照。
<<<<<<< HEAD
=======
# Code Apps 採用が決まった時点（設計承認後）で、Dataverse 構築（Phase 2）と並行して着手する
# （npm install はネットワーク待ちのみで Dataverse 構築をブロックしないため、待たずに並行実行する）。
# VS Code では本トラック全体を「Code Apps サブエージェント」として並行起動できる。
# 先行工程（scaffold / init / 初回 build & push）はテーブル不要。以下は Dataverse 構築の完了を待つ同期点:
# ★同期①: pac code add-data-source は Dataverse Phase 2（テーブル作成）完了後に実行
# ★同期②: pac code add-flow は Power Automate Phase 5（フロー実装）完了後に実行
# 詳細は standard §8「開発フロー全体図」を参照。
>>>>>>> origin/main
cp -n .github/skills/standard/references/gitignore-template .gitignore # .gitignore がなければコピー
npm install --no-audit --no-fund
# Step 1: 初期化 — power.config.json を生成（PAC CLI 認証でテナント不一致なし）
pac code init -env {ENVIRONMENT_ID} -n "AppName"
# Step 2: vite.config.ts 必須設定を確認（base: "./" / external に @microsoft/power-apps を含めない）
# → references/build-reference.md Step 2
# Step 3: .env.example を .env にコピーしてテーマ固有の値を設定
# Step 4: 初回ビルド＆デプロイ → Dataverse 接続が確立
npm run build
pac code push -env {ENVIRONMENT_ID} -s {SOLUTION_NAME}
# Step 5: データソース追加（日本語表示名は toggle_table_lang.py で英語に切替）
python scripts/toggle_table_lang.py en
pac code add-data-source -a dataverse -t ${PUBLISHER_PREFIX}_{table_basename} # 全テーブルに繰り返す
python scripts/toggle_table_lang.py jp
# Step 6: src/ を実装 → 再ビルド＆デプロイ（反復）
npm run build
pac code push -env {ENVIRONMENT_ID} -s {SOLUTION_NAME}
インポート／getClient の必須パターン: @microsoft/power-apps/data 等のサブパスからインポートし、getClient(dataSourcesInfo) のように dataSourcesInfo を必ず渡す。よくある失敗（base 未設定で 404・external 指定でモジュール解決エラー・getClient() 引数なし・vite-env.d.ts の手動型宣言等）は トラブルシューティング と ビルドリファレンス にまとめている。
デプロイコマンドの選択
| コマンド | 認証基盤 | テナント問題 | 推奨度 |
|---|
pac code init -env {ID} -n "Name" | PAC CLI プロファイル | なし | ✅ 標準 |
pac code push -env {ID} -s {SOL} | PAC CLI プロファイル | なし | ✅ 標準 |
pac code add-data-source -a dataverse -t {table} | PAC CLI プロファイル | なし | ✅ 標準 |
npm run deploy | PAC CLI プロファイル | なし | ✅ 推奨（predeploy チェック付き） |
3. データソース接続
正常系: pac code add-data-source
Dataverse テーブルの追加は 常に pac code add-data-source を使う（npx power-apps add-data-source は使わない）。npx power-apps は PAC CLI と独立した認証トークンキャッシュを持つため、正しいテナントで pac auth create 済みでも別テナント扱いとなり 403 エラーになる事故がある（トラブルシューティング #12）。systemuser 等のシステムテーブルも同じコマンドで追加できる。
テーブルごとに pac code add-data-source -a dataverse -t {table} を実行すると、.power/schemas/appschemas/dataSourcesInfo.ts が自動更新される（systemuser・bot 等のシステムテーブルも同じ）。src/lib/dataSourcesInfo.ts はこの生成ファイルを re-export するだけ（手書き追記はコネクタ等 add-data-source で追加できないものに限る）。
python scripts/toggle_table_lang.py en
pac code add-data-source -a dataverse -t ${PUBLISHER_PREFIX}_{table_basename}
python scripts/toggle_table_lang.py jp
日本語 DisplayName で Failed to sanitize string エラーが出る場合、および npx power-apps add-data-source をフォールバックで使う場合（patch-nameutils.cjs 適用）の判断フロー・詳細手順は 日本語サニタイズリファレンス を参照。
4. 改善デプロイ
CSP（Content Security Policy）違反の回避
Power Apps ランタイムはデフォルトで connect-src 'none'。外部 API への fetch はブロックされる。
Dataverse SDK（getClient(dataSourcesInfo)）経由のデータアクセスのみ CSP 安全。
→ 詳細: CSP 構成
ログインユーザーの systemuserid 取得
SDK getContext().user.objectId（Entra AAD Object ID）を取得し、systemuser テーブルの
azureactivedirectoryobjectid でマッピングして systemuserid を解決する。
Xrm・fetch・executeAsync は CSP でブロックされるため使用不可。
→ 詳細: ユーザー識別リファレンス
ディープリンク: 外部から Code Apps の特定ページに遷移
SDK の getContext().app.queryParams で親ウィンドウの URL パラメータを取得する（cross-origin iframe のため window.location.search は不可）。
→ 詳細: ディープリンクリファレンス
基本設計方針: モーダル操作 + z-index ルール
新規作成・編集・削除はすべてモーダル（Dialog / AlertDialog）で操作する。
サイドバー z-40 / Dialog z-[300]/z-[400] で重なり問題を回避。
SDK 生成サービスとデータソースパターン
フロー連携時は統合 dataSourcesInfo が必須（getClient(dataSourcesInfo) はシングルトンのため、最初の呼び出しで全データソースを含める必要がある）。
→ 詳細: データソースパターン
Lookup 名はクライアントサイド名前解決が必須
SDK 生成サービスは Lookup 名フィールド（createdbyname 等）を返さない。
_xxx_value（GUID）+ useMemo マップで名前解決する。
データソース未登録テーブルの場合は OData FormattedValue アノテーションを使う。
所有者（「誰のレコードか」）の表示は _owninguser_value + systemusers Map で解決する（取得 hook の $select に _owninguser_value を含めること）。
→ 詳細: Lookup 名前解決リファレンス
一覧の検索・フィルター・重要列（所有者・金額）
営業系の一覧は名称検索だけで終わらせず、所有者列・金額列などの重要項目を表示し、ステータス／所有者で絞り込み・横断検索できる構成を標準とする。所有者フィルターは実データに存在する所有者のみを列挙し、絞り込み結果の件数・合計をツールバーに表示する。
→ 詳細: CRUD UI 標準パターン の「一覧の検索・フィルター・重要列」
ステージ矢羽（Stage Path）— OptionSet の進捗を可視化＆クリックで変更
商談ステージ・リードステータス等、順序を持つ OptionSet を Salesforce 風の矢羽（シェブロン）で表示する。onSelect でその場ステージ変更（patch）も可能。失注・不認定など否定的終端は negativeValue で赤表示。
→ 詳細: ステージ矢羽パターン
scaffold 時に含めないファイル
外部 API 呼び出しを含むデモページ（design-examples.tsx / use-learn-catalog.ts / learn-client.ts 等）は CSP 違反になるため、業務テーマに不要なものは最初から生成しない。標準コンポーネント（form-modal.tsx / list-table.tsx / inline-edit-table.tsx / sidebar*.tsx / ui/ 等）は残す。
→ 含める／含めないファイルの完全な一覧は 新規テーマ開始チェックリスト。
構築手順の詳細
詳細な構築手順（初期化・Dataverse 接続・ビルド・デプロイ）は 構築リファレンス を参照。
TanStack React Query パターン
自前 DataverseService を React Query で包むパターン（useRecords / useCreateRecord 等）は データソースパターン を参照。
プレデプロイレビュー（「デプロイして」「プッシュして」時の必須チェック）
「デプロイして」「プッシュして」が指示されたとき、ビルド前に必ずレビューを実行する。
dataSourcesInfo 整合性・インポート元・ルーター種別（createHashRouter 必須）・サイドバー fixed レイアウト等を確認。
→ 詳細: プレデプロイレビューリファレンス
ビルド・デプロイの注意事項
noUnusedLocals: true のため未使用 import は即削除- PowerShell で
npm run build 2>&1 の後にテキストを付けない（Vite が入力パスと誤解）
→ 詳細: ビルドリファレンス
Power Automate フロー統合
フロー追加は npx power-apps add-flow --flow-id {id} を使う（add-data-source --api-id logicflows は旧方式）。
Copilot Studio 応答は JSON 配列文字列で返るため JSON.parse() → 配列の最初の要素を取得する。
502 タイムアウト対策としてローカル検索へのフォールバックを必ず実装する。
→ 詳細: フロー連携リファレンス
5. リファレンス
正常系の流れは本ファイル（§1〜§4）に集約し、異常系・詳細手順・トラブルシューティングは references/ に逃がしている。各トピックの詳細は以下を参照。
| リファレンス | 内容 |
|---|
| デザインテンプレート集 | 設計時に選択する配色テンプレート 6 種（プレビュー HTML・CSS Variables 一式・light/dark 対応） |
| デザインシステム | Tailwind CSS v4 のコンポーネント選定・画面設計パターン |
| コンポーネントカタログ | 全コンポーネントの詳細仕様・使用例 |
| ステージ矢羽パターン | OptionSet（ステージ／ステータス）を Salesforce 風の矢羽で可視化・クリックで変更 |
| 月間カレンダーパターン | 日付を持つレコードを月間グリッドで俯瞰（date-fns のみ・依存追加なし・イベントチップ・今日ハイライト） |
| ウィザードフォームパターン | 入力項目の多いフォームを複数ステップに分割（ステップインジケーター・ステップ別バリデーション・確認画面） |
| CSV エクスポートパターン | フィルター適用後の一覧を UTF-8 BOM 付き CSV でダウンロード（Excel 日本語対応・OptionSet ラベル変換） |
| パレート図パターン | 不良分析・ABC 分析などの分類別集計を降順棒 + 累積構成比折れ線 + 80% 基準線で可視化（重点対策対象の強調色） |
| チェックリスト採点パターン | 点検・監査系業務の判定トグル・スコア自動計算（対象外を分母から除外）・テンプレート一括生成・親レコードへのスコア同期 |
| クロス集計マトリクスパターン | 2 軸の組み合わせ件数をヒート色付きピボット表で俯瞰（行列自動生成・合計行/列・追加依存なし） |
| 縦タイムライン/ステッパーパターン | 順序を持つ項目の進行状態を縦に可視化（done/current/problem/pending・行ごとに操作ボタン差込可・追加依存なし） |
| 構築リファレンス | ビルド・デプロイの詳細手順・vite.config.ts 必須設定・TypeScript エラー対処 |
| データソースパターン | SDK 生成サービス・dataSourcesInfo・getClient(dataSourcesInfo)・TanStack React Query |
| Lookup 名前解決 | クライアントサイド名前解決・OData FormattedValue パターン・所有者（Owner）列の表示 |
| 日本語サニタイズ | 日本語 DisplayName エラーの回避（toggle_table_lang.py / patch-nameutils.cjs） |
| CSP 構成 | iframe 埋め込み・外部 API 接続時の CSP 設定・CSP 安全な SDK メソッド一覧 |
| ユーザー識別 | ログインユーザーの systemuserid 取得パターン（CSP 安全） |
| ディープリンク | MDA / Power Automate から特定ページへパラメータ付き遷移 |
| フロー連携 | Power Automate フロー呼び出し・Copilot Studio 応答パース・エラーハンドリング |
| Copilot Studio コネクタ | Copilot Studio エージェント直接呼び出し・会話継続・レスポンス解析 |
| コネクタリファレンス | Code Apps で利用する主要コネクタの追加方法・使用例 |
| メール・PDF 送信 | HTML→PDF 変換・Power Automate 経由メール添付送信パターン |
| 日本地図パターン | SVG 都道府県地図の実装パターン |
| 高度な実装パターン | マルチ環境・オフライン・i18n・パフォーマンス最適化パターン |
| プレデプロイレビュー | 「デプロイして」「プッシュして」時の自動チェック手順 |
| 新規テーマ開始チェックリスト | 前テーマの残骸がないクリーン開始の確認手順・scaffold 時に含めないファイル |
| トラブルシューティング | 頻出エラーと対処法（GUID フィルタ・.toLowerCase() 統一・テンプレート削除時の use-theme 巻き添え 等） |
| サンプル作成ガイド | 公開リポジトリ向けサンプルのセキュリティ要件・環境変数ルール・feature flag 命名規則 |
