geekfujiwara/codeappsdevelopmentstandard/power-pages

Power Pages Code Site (SPA) 開発・デプロイスキル

公式リファレンス: Power Pages でシングルページ アプリケーションを作成して展開する | Microsoft Learn

新スキル参照: microsoft/power-platform-skills - power-pages

サブリファレンス（必要に応じて参照）

Dataverse 接続と認証の実装方法はこのファイルで概要を説明し、完全なサンプルコードは上記 References にまとめている。

刷新版の構成原則（upstream 優先）

このスキルは microsoft/power-platform-skills/plugins/power-pages の以下 4 スキルを優先参照して構成する。

標準実行順序（刷新後）

1. デプロイ基盤準備（.powerpages-site 作成）
2. Web ロール整備
3. 認証導線（SSO/ログイン/ログアウト）整備
4. Dataverse Web API CRUD 実装
5. 権限監査（ロール・テーブル権限整合）

⚠️ デプロイ後の必須ステップ: pac pages upload-code-site でテーブル権限 YAML をデプロイしても、

type=18 の content JSON 内 adx_entitypermission_webrole が空のまま残り、Web ロール紐付けが効かない。デプロイ直後に

python scripts/setup_permissions.py を実行して content の adx_entitypermission_webrole を書き込み、review_pre_deploy.py の

チェック 3.7 が ✅ になることを確認する（さもないと管理者を含む全ユーザーが 403）。詳細は教訓 14。

詳細な責務分離と判断基準は upstream 優先構成ガイド を正本として扱う。

microsoft/power-platform-skills 比較（認証・認可 vs Dataverse CRUD）

推奨適用順:

1. setup-auth で認証導線を整備
2. create-webroles でロールを確定
3. integrate-webapi で CRUD 実装
4. audit-permissions で権限妥当性を最終監査

核心原則

1. `pac pages upload-code-site` がサイト作成とデプロイの両方を行う — API でサイトを事前作成する必要はない
2. 初回は Inactive Sites に作成される → PP API (2022-03-01-preview) で activate_site.py を使ってアクティブ化
3. デプロイは upload-code-site → relink → restart の3ステップ — upload-code-site は既存テーブル権限の Web ロール紐付けを消すため、毎回 scripts/relink_table_permissions.py（または統合の scripts/deploy_site.py）で再付与する（教訓 15）。`npm run deploy`（build && upload-code-site だけ）で終わらせない
4. Post-Upload Fix は不要 — upload-code-site が header/footer/page を正しく構成する
5. `.powerpages-site/` は upload-code-site が自動管理する — ただし site-settings/ YAML は手動追加して永続化できる（下記参照）
6. `adx_website` レコードは絶対に削除しない — EDM 2.0 でもランタイムが起動時に参照する
7. 環境のクリーンアップ時は PP API のサイト一覧と照合してから削除する — 誤削除で 500 エラー
8. `credentials: "same-origin"` を使う — "include" ではない（same-site Cookie 認証）
9. powerpagecomponent type=18 には `powerpagesitelanguageid` が必須 — 未設定だと 404 になる
10. 報告者・作成者は Contact Lookup で追跡する — Power Pages では createdby はアプリケーションユーザーになるため使えない。ログインユーザーの Contact 情報を自動取得し入力不要にする（教訓 19）
11. デザイン系の変更は必ず `npm run dev`（localhost）で見た目を確認してから本番デプロイする — 本番デプロイ → ブラウザ確認 → 再デプロイのループは 1 サイクルあたり数十秒〜数分かかり非効率。レイアウト・配色・レスポンシブ崩れは localhost で先に潰し、本番デプロイは最終確認のみに留める（教訓 20）。ただし Power Pages 本体のテーマ CSS（Bootstrap 既定の見出し色など）はローカルには存在せず本番でのみ衝突しうるため、色指定は見出し要素に明示的な color を必ず設定し、デプロイ後の最終確認も省略しない（詳細は トラブルシューティング）
12. 取引先企業（`account`）配下の「業務テーブル」は Account スコープ（`756150002`）で権限を切る — 全件公開になるグローバルアクセスで逃げない。子テーブル権限（accountrelationship + create）を作り、POST 時に account Lookup を @odata.bind する。read は通るのに create だけ 403 になる典型パターンの原因（教訓 21）
13. `account` テーブル自身に Account スコープを設定してはいけない — Web API が 500（9004010A）を返し、会社名の参照も子レコードの bind も一切できなくなる。正解は Contact スコープ（`756150001`）＋ `contact_customer_accounts`。これで「自分の parentcustomerid が指す 1 件」だけが返る（実機検証済み）
14. Lookup バインドには参照する側・される側「両方」の 追加（Append）と 追加先（AppendTo）が要る — 片側だけでは 403。You don't have permission to associate or disassociate table X to Y が出たら、まず不足している側の権限を疑う（実機で 4 通りの真理値表を検証済み）
15. account Lookup を省いた POST は 403 ではなく 201 で通ってしまう — できるのは誰にも見えない孤立レコード。テーブル権限では防げないため、クライアント側で account 未取得なら作成 UI を出さない＋サーバー側（フロー等）で null を検知する二段構えにする（実機検証済み）

ワークフロー

初回:
  npm run build
  → pac pages upload-code-site          ← Inactive Sites に作成
  → py portal/scripts/activate_site.py  ← PP API でアクティブ化 (api-version=2022-03-01-preview)
  → py portal/scripts/setup_contact_webapi.py
  → py .github/skills/power-pages/scripts/setup_inquiry_reporter.py  ← 報告者 Contact Lookup (教訓 19)
  → py .github/skills/power-pages/scripts/relink_table_permissions.py  ← ★ロール再付与＋再起動
 
2回目以降（推奨: 統合スクリプトで一括実行）:
  py .github/skills/power-pages/scripts/deploy_site.py
  （ビルド → upload-code-site → ★relink → 検証 → 再起動 を 1 コマンドで実行）
 
2回目以降（手動の場合）:
  npm run build → pac pages upload-code-site
  → py .github/skills/power-pages/scripts/relink_table_permissions.py  ← ★必須（省くと 403）
 
Account アクセスを採用する場合（初回デプロイ後に 1 回だけ・実機検証済みの順序）:
  py .github/skills/power-pages/scripts/setup_access_scope.py --scope account
  → py .github/skills/power-pages/scripts/setup_account_link_request.py
  → py .github/skills/power-pages/scripts/deploy_flow_account_link_request.py
  → 管理者用 Code App をデプロイ（code-apps/templates/account-link-admin）
  → py .github/skills/power-pages/scripts/setup_access_scope.py --scope account --verify-only

⚠️ `PAGES_SITE_NAME` を `.env` に必ず設定する。未設定だと最終更新のサイトが暗黙で選ばれ、

別サイトに権限を書き込む事故が起きる。

⚠️ **npm run build && pac pages upload-code-site だけで終わらせると、既存テーブル権限の

Web ロール紐付けが消えて全件 403 になる**（教訓 15）。relink_table_permissions.py を

毎回実行するか、deploy_site.py で一括実行すること。両スクリプトともハードコードなし・

すべて .env 管理（DATAVERSE_URL / ENV_ID / PAGES_WEBSITE_ID / PP_SUBDOMAIN /

RELINK_WEBROLE_NAMES / PORTAL_DIR）。

アクティベーション詳細

参照: microsoft/power-platform-skills activate-site

初回の pac pages upload-code-site はサイトを Inactive Sites に作成する。 アクティブ化は Power Platform API (api-version=2022-03-01-preview) で行う。

POST https://api.powerplatform.com/powerpages/environments/{ENV_ID}/websites?api-version=2022-03-01-preview
 
Body:
{
  "name": "<PAGES_SITE_NAME>",
  "subdomain": "<PAGES_SUBDOMAIN>",
  "templateName": "DefaultPortalTemplate",
  "dataverseOrganizationId": "<org_id>",
  "selectedBaseLanguage": 1033,
  "websiteRecordId": "<powerpagesiteid>"     ← pac pages upload-code-site が作った ID
}
 
Response: 202 Accepted + Operation-Location ヘッダー
→ Operation-Location を 10 秒間隔でポーリング
→ OperationComplete = 成功、OperationFailed = 失敗

⚠️ API バージョン注意: 2022-03-01-preview を使用すること。2024-10-01 ではアクティベーションが正しく動作しない。

前提条件・事前確認（会話の最初に 1 回だけ）

作業開始前に、standard の共通契約に加え、 1 回の AskUserQuestion で次をまとめて確認する。

環境全体の System Administrator を既定にせず、サイト管理と対象 Dataverse 構成に必要な 権限を持つ担当者を使用する。認証、scope、Web role、table permission のいずれかが未確定なら 外部公開へ進まない。

pac CLI 注意: サブコマンドは pac pages （例: pac pages list, pac pages upload-code-site）。

pac power-pages は無効。pac pages help でコマンド一覧を確認できる。

.env パラメータ

DATAVERSE_URL=https://{org}.crm.dynamics.com/
ENV_ID=                               # Power Platform 環境 ID
PAGES_SITE_NAME=                      # サイト名 (powerpages.config.json の siteName と一致)
PAGES_SUBDOMAIN=                      # サブドメイン (例: myportal → myportal.powerappsportals.com)
 
# Account アクセススコープを使う場合（Step 4）
ACCESS_SCOPE=account                          # self | account
ACCOUNT_CHILD_TABLES=                         # 論理名:リレーションスキーマ名 のカンマ区切り
ACCOUNT_LINK_REQUEST_TABLE=                   # 紐づけ依頼テーブルの論理名
ACCOUNT_LINK_REQUEST_RELATIONSHIP=            # contact との 1:N スキーマ名
ACCOUNT_LINK_ADMIN_RECIPIENT=                 # 依頼通知メールの宛先（配布リスト推奨）

プロジェクト構造（公式準拠 / upstream 推奨）