geekfujiwara/codeappsdevelopmentstandard/code-apps

Code Apps 開発スキル

Power Apps Code Apps（コードファースト）を TypeScript + React + Tailwind CSS で開発する。 UI 設計・CSP 構成・メール送信パターンまで Code Apps 開発の全領域をカバーする統合スキル。

プラント・設備の JSON 駆動設計: モジュール設計パターン と

追加テンプレート を参照。敷地・ユニット・ポート接続、CSP 対応検証器、

Python 候補生成、Dataverse 改訂・提案レビューを再利用できる。既存アプリへのアドオンであり scaffold 元ではない。

型・形状・共有保存の単独テストを先に通し、導入後のブラウザー/Teams/一般利用者権限は別ゲートで実測する。

設計と保守を統合する場合: Plant Design & Maintenance サンプル を参照。

既存画面・合成3Dモデル・部位別の故障／修理・ヒートマップ・AI候補の変更前後比較を同梱。

npm ci → Python依存導入 → npm run generate → npm run predeploy で単体検証できる。

AI候補は確定まで下書きに適用せず、共有保存と分離する。外部接続は既定無効。Code App は Dataverse と Copilot Studio の生成サービスだけへ接続し、MCP Server は Copilot Studio のツールとして構成する。

3D モデル（建物・家具・設備）を扱う場合: 3D 資産の共通利用 を参照。

既定 CSP で読める資産の持ち方（画像は img-src 'self'、JSON は import、GLB の扱い）、素材ライブラリの色合わせ・ライセンス、

契約検証（scripts/validate_3d_assets.py）とヘッドレス描画確認（scripts/capture_3d.mjs。ソフトウェア描画で黒くなる問題を含む）、

実在の GLB（テクスチャ埋め込み）を既定 CSP の中で表示する方法（?inline + createImageBitmap のプラグイン）を再利用できる。

工事・設備の進捗を 3D で見せる場合（完成形を破線、施工中をクリッピングで立ち上げる、部位と工程の対応、GLB の書き出し）は

3D 施工進捗モデル を参照。drei の <Environment preset> は CSP で失敗するとアプリ全体が落ちるので使わない（チェック 13 が検出）。

図面レビューを非同期会話で回す場合: 図面コミュニケーション アドオン と

PoC サンプル を参照。版付き図面 JSON と検証器、A3 の SVG 描画、

注釈／タスク、候補の差分・採用・Undo、会話の相関コントラクト（会話 ID・ターン ID・編集バージョン・基準ハッシュ、重複ターン拒否）、

A3 PDF を生成する Python スキルを再利用できる。Dataverse 未接続時は DEMO ワーカーであることを UI に明示し、実エージェント応答と偽らない。

[!NOTE]

本スキルは React + Vite の Web Code Apps 用。Expo／React Native、camera／barcode／location 等の

端末ネイティブ機能、Power Apps Developer app、Wrap が要件なら

`mobile-apps` へ切り替える。Native は Private Preview で本番利用できない。

[!NOTE]

Microsoft Learn の現行概要では、Code Apps は React / Vue などの SPA を Power Apps 上でホストする仕組み とされている。

この開発標準はその中でも React ベース実装に標準化したガイドであり、他フレームワーク一般論ではなく、このリポジトリのテンプレートと運用実績に基づく推奨事項をまとめている。

1. 概要

Code Apps 開発は 設計 → 初回デプロイ → データソース接続 → 改善デプロイ の順に進む。

既定は Dataverse。SharePoint URL を渡されても、直接接続・継続利用を明示されない限り 仕様・移行元の参照情報として扱い、SharePoint コネクタを追加しない。 dataverse と data-migration で移行し、 Code Apps は Dataverse の接続参照を使用する。移行元の読み取り権限・移行承認は別途必要。

環境チェックを明示的に依頼されない限り、すぐに開発を開始する。 DLP / ACP・Code Apps 許可・マネージド環境・MCP の診断を開始条件にしない。 対象環境とデプロイ承認を確認できたら、ローカル predeploy / build を通して初回 push を優先する。 初回 push はテーブル全件構築・データ移行・ローカライズの完了を待たず、未接続部分を UI に明示する。 障害時だけ admin の権限確認付き復旧 を使用する。

[!NOTE]

サブエージェント並行実行パターン: architecture スキルで Code Apps が確定し、dataverse スキルで

スキーマが承認されたタイミングで、このスキルがサブエージェントとして起動される。

Dataverse 構築（--skip-localize フェーズ）と Code Apps 開発（scaffold → deploy → add-data-source）は

並行して進める。Dataverse 構築が先に終わったら --localize-only でローカライズ＆デモデータ投入。

標準ワークフロー全体像

[設計]  ① デザインテンプレートを選ばせる（6種・プレビュー付き）
        ② 画面設計（design-pattern）→ ユーザー承認
          │
[§2 初回デプロイ]
        ③ テンプレート scaffold + npm install（業務テンプレートがあれば templates/sales-crm 等から生成。Dataverse 構築 Phase 2 と並行して即着手／VS Code では Code Apps サブエージェントとして起動）
        ④ ソリューションの ID を確定（初回 push で使用）
        ⑤ npx pa app init（power.config.json 生成）
        ⑥ vite.config.ts 必須設定の確認 / .env 設定
        ⑦ npm run deploy -- --solution-id {GUID}（build + pa app push）★初回 push でソリューション所属が確定
          │
[§3 データソース接続]
        ⑧ 専用接続 + 接続参照を用意 → add_data_source.py（初期化したアプリのルートで実行）
        ⑨ MicrosoftDataverseService + *WithOrganization ラッパーを実装
          │
[§4 改善デプロイ]
  ⑩ src/ 実装 → npm run deploy（pa app push を反復）
  ⑪ 最終 push 後に pa app share（利用者は play、共同開発者だけ edit）

この後の章構成

[!NOTE]

本スキル内のコード例は {prefix}_tablename 等のプレースホルダーで汎用化されています。

実際のテーブル名・型名は、あなたのプロジェクトのエンティティに読み替えてください。

パターン（Lookup 名前解決、SDK ラッパー、useMemo マップ等）はそのまま適用できます。

設計フェーズ（実装前に必須）

コードを書く前に、デザインテンプレートの選択と UI 設計を行い、ユーザーの承認を得ること。 手順:

1. デザインテンプレート集 の 6 種を一覧＋プレビューで提示し、ユーザーに 1 つ選んでもらう（デプロイされるアプリは常に 1 テンプレート。dark/light は ThemeProvider + ModeToggle）。
2. デザインシステム を読み込み、画面構成・コンポーネント選定・Lookup 名前解決パターンを設計する。
3. 設計（選択テンプレート＋画面設計）を提示し、「この設計で進めてよいですか？」と承認を得る。承認の証跡を残す場合は、設計承認 Issue テンプレート を対象プロジェクトの .github/ISSUE_TEMPLATE/ にコピーして Issue を作成する。
4. 承認後、選択テンプレートの CSS Variables を styles/index.pcss に適用してから実装する（変数一式・適用手順は デザインテンプレート集）。

CRUD 画面は [CRUD UI 標準パターン](references/crud-ui-pattern.md) に必ず従う: 一覧は行／カード全体をクリックして詳細を開く（目アイコン等の小さなクリック領域は使わない）、詳細の編集はモーダルではなくインライン編集モード、行内の削除・クイック操作は e.stopPropagation()、削除確認はブラウザの confirm() ではなくモーダル（useConfirm() / AlertDialog）。指示がなくても、テーブルごとに「一覧・詳細（インライン編集）・作成・削除」を標準実装すること。

画面の骨格は [デザインシステム](references/design-pattern.md#ページの骨格新規画面はここから書き始める) からコピーして書き始める: マルチカラムは grid-cols-[minmax(0,1fr)_...]（素の 1fr は使わない）＋直接の子すべてに `min-w-0`、長文は break-words ではなく [overflow-wrap:anywhere]、コード・表・JSON は overflow-x-auto で閉じ込める。min-w-0 は後付けすると必ず抜けるため最初から書く。npm run predeploy のチェック 7 が抜けを警告する。

画面が 3 つ以上あるアプリには [使い方ガイド](references/onboarding-guide-pattern.md) を標準実装する: 初回起動でカルーセルを自動表示し、「使い方を見る」から実操作ツアーへ繋ぐ。設計提示の段階でスライド構成（4〜6 枚）とツアー手順を画面一覧と一緒に示す。

設計で提示する内容: 選択テンプレート、画面一覧（ページ名・ルート）、各画面のコンポーネント構成、カラム定義、Lookup 名前解決方法（_xxx_value + useMemo Map）、ナビゲーション構造、テレメトリの転送先と監視する SLI（転送しない場合も明記）。

大前提（ソリューション運用）: Dataverse テーブル・Code Apps・Power Automate・Copilot Studio は同一ソリューション内に開発し、.env の SOLUTION_NAME / PUBLISHER_PREFIX を全フェーズで統一する。詳細は `standard` スキル。

2. 初回デプロイ

デプロイ先とローカル構成（管理 API の事前確認は不要）

対象環境・アカウント・ソリューションとローカル構成を確認する。 Code Apps 許可は製品上の要件だが、通常フローでは管理センターや管理 API で事前診断せず push を試す。 既に無効と分かっている場合は無駄に push せず、復旧手順へ進む。

1. Power Platform 管理センターで「コード アプリを許可する」がオン
   → オフの場合: CodeAppOperationNotAllowedInEnvironment (403) エラー
 
2. npm CLI のアクティブアカウントが対象テナント用
  npx pa auth status
  npx pa auth switch --account user@contoso.com
 
3. power.config.json は npx pa app init で生成する
   → テンプレートから手動コピーしない
   → 別環境の appId が残っていると: AppLeaseMissing (409) エラー
  → 新規環境では必ず npx pa app init で新規生成

環境全体のチェックは明示依頼時のみ、障害時は原因に必要な項目だけを

admin スキル で診断する。委任権限がなければ管理操作を試さず管理者へ依頼する。

Code Apps の必須条件は環境で「コード アプリを許可する」が有効であること。

マネージド環境はガバナンス上の選択肢であり、Code Apps のデプロイ要件ではない。

CLI の実行ファイル名は `pa`。@microsoft/power-apps-cli は bin を power-apps から `pa` にリネームし、

コマンドも group 化した（init → app init、push → app push、auth-status → auth status）。

旧名を呼ぶと npm error could not determine executable to run だけが出て原因が見えない。

npm run predeploy（チェック 11）が package.json のデプロイコマンドとインストール済み bin 名の不一致を検出する。

全コマンドの対応表は npm CLI リファレンス。

プロジェクトの 3 つの生成段階（生成物は手動作成・コピー禁止）

どのファイルを誰が生成し、何をカスタマイズしてよいかの一覧は ビルドリファレンス。SDK 管理ファイル（power.config.json / dataSourcesInfo.ts / src/generated/）は手動編集禁止。

テンプレートのプレースホルダー設計

テンプレートのデモメニューには template: true フラグが付いている。このフラグが残ったまま npm run predeploy を実行するとエラーになるため、削除忘れを防げる。

// template: true が付いた行はデプロイ前に削除 or テーマ用に書き換える
{ label: "顧客", path: "customers", iconKey: "customers", template: true },
// テーマ固有のメニュー（template フラグなし）
{ label: "ダッシュボード", path: "dashboard", iconKey: "dashboard" },

デプロイ前は npm run predeploy（.env・power.config.json を自動検証）→ npm run deploy（predeploy + build + push を一括実行）。

認証はキャッシュ優先。pa auth status はアカウント表示で、push 時の更新成功を保証しない。 TTY が無いだけでは停止せず、CLI 自身の暗号化キャッシュからのサイレント取得・更新を使う。 接続セットアップは下記のラッパーを使い、本人の認証・Edge プロファイルを確認した場合だけ --allow-interactive を付ける。必要な実コマンドを対話コンソールで実行し、手動ターミナルへの移動を要求しない。 device-code は使わず、通常のキャッシュ再利用を先に試す。 Python/SDK は auth_helper の共有キャッシュを使うが、npm CLI は別 client ID・専用キャッシュである。 外部トークンを受け取る公開オプションが無いため、CLI へ直接共有できたとは報告しない。 詳細は 認証・キャッシュ境界。

テンプレートは src/lib/telemetry.ts を含み、起動時に initializeLogger を登録する。既定では外部送信せず、 クエリ文字列・フラグメント・GUID を除去したメトリクスだけを code-apps:telemetry イベントへ出力する。 Application Insights 等へ転送する場合は custom sink と CSP の connect-src を合わせて設計する （テレメトリ / 可観測性パターン）。

標準ワークフロー

チュートリアル・画面ツアーを追加するときは、最初から 標準チュートリアル構成 を使う。対象内は透明、枠外だけ暗幕、 フォーカス後のスクロール、固定ヘッダーと非同期レイアウトの再計測を実装し、 通常の npm run predeploy の既知不具合チェックと実プレイヤーの視覚検証を行う。

上から順に実行すれば動く正常系フロー。各 Step の詳細・必須設定・型定義は ビルドリファレンス を参照。

# Step 0: テンプレート scaffold（標準では @GeekPowerCode が scaffold）
# Code Apps 採用が決まった時点（設計承認後）で、Dataverse 構築（Phase 2）と並行して着手する
# （npm install はネットワーク待ちのみで Dataverse 構築をブロックしないため、待たずに並行実行する）。
# VS Code では本トラック全体を「Code Apps サブエージェント」として並行起動できる。
# 先行工程（scaffold / init / 初回 build & push）はテーブル不要。以下は Dataverse 接続情報の準備を待つ同期点:
#   ★同期①: shared_commondataserviceforapps の connectionId / orgUrl が揃ったら add data-source を 1 回実行
#   ★同期②: pa app add flow は Power Automate Phase 5（フロー実装）完了後に実行
# 詳細は standard §8「開発フロー全体図」を参照。
cp -n .github/skills/standard/references/gitignore-template .gitignore   # .gitignore がなければコピー
# 共通スキャフォールダーで生成計画を確認し、同じコマンドから --dry-run を外して生成する
python .github/skills/update-skills/scripts/scaffold_from_template.py \
  --template .github/skills/code-apps/templates/generic-base --target {TARGET_DIR} --dry-run
python .github/skills/update-skills/scripts/scaffold_from_template.py \
  --template .github/skills/code-apps/templates/generic-base --target {TARGET_DIR}
# 業務テンプレートから始める場合は --template を差し替える（generic-base を extends 済み。例: 営業支援 CRM）
#   --template .github/skills/code-apps/templates/sales-crm
#   --template .github/skills/code-apps/templates/field-service --var PUBLISHER_PREFIX=fsdemo  # フィールドサービス管理（右上の使い方ガイド・スケジューリング・デモ予定補充）
#   --template .github/skills/code-apps/templates/agm-qa-assist   # 株主総会 Q&A アシスト
#   --template .github/skills/code-apps/templates/store-ordering  # 店舗発注システム（業務端末風 UI ＋ Dataverse ＋ 合成デモデータ）
#   --template .github/skills/code-apps/templates/construction-cockpit   # 建設現場コックピット（--var PUBLISHER_PREFIX / COWORK_PLUGIN_ID / DATAVERSE_ORIGIN）
#   --template .github/skills/code-apps/templates/perse3d-studio   # パース3D内見スタジオ（--var PUBLISHER_PREFIX）
# scaffold.json に questions があるテンプレートは、値を AskUserQuestion で 1 問ずつ聞いてから生成する:
#   --questions --env <answers.env> で未回答の質問（JSON）を出す → 1 問ずつ聞いて answers.env に追記 → [] になるまで繰り返す
#   → --env <answers.env> --write-env {TARGET_DIR}/.env で生成（答えが .env にも入る）
# 対象ディレクトリは空（.git / .github / .vscode / .env だけなら空とみなす）であること
npm install --no-audit --no-fund
 
# 既存プロジェクトを更新するときは SDK / CLI とも latest を候補にし、build と CLI help を再検証する
npm install @microsoft/power-apps@latest
npm install -D @microsoft/power-apps-cli@latest
npx pa --help          # ★ bin 名は pa。コマンドは auth / app / connector / connection / solution の group 制
npm run build
# バージョン方針と検証項目: references/cli-reference.md#バージョン方針
 
# Step 1: ソリューションを用意し、SOLUTION_ID / SOLUTION_NAME / PUBLISHER_PREFIX を .env に保存
# standard / dataverse スキルで承認済みのものを使う。初回 push 前に GUID を確定する。