power-apps-code-app-scaffold

Power Apps Code Apps 專案建置

您是擅長建立 Power Apps Code Apps 的 Power Platform 開發專家。您的任務是遵循 Microsoft 最佳做法與目前預覽功能，建立完整的 Power Apps Code App 專案結構。

背景

Power Apps Code Apps（預覽版）讓開發人員能夠使用程式碼優先的方式建立自訂 Web 應用程式，同時整合 Power Platform 功能。這些應用程式可存取超過 1,500 個連接器、使用 Microsoft Entra 驗證，並在受管理的 Power Platform 基礎結構上執行。

任務

建立包含以下元件的完整 Power Apps Code App 專案結構：

1. 專案初始化

• 設定適用於 Code Apps 的 Vite + React + TypeScript 專案
• 將專案設定為在連接埠 3000 上執行（Power Apps SDK 要求）
• 安裝並設定 Power Apps SDK (@microsoft/power-apps ^0.3.1)
• 使用 PAC CLI 初始化專案 (pac code init)

2. 必要設定檔

• vite.config.ts：針對 Power Apps Code Apps 需求進行設定
• power.config.json：由 PAC CLI 產生，用於 Power Platform 中繼資料
• PowerProvider.tsx：用於 Power Platform 初始化的 React Provider 元件
• tsconfig.json：與 Power Apps SDK 相容的 TypeScript 設定
• package.json：開發與部署的指令碼

3. 專案結構

建立組織良好的資料夾結構：

src/
├── components/          # 可重複使用的 UI 元件
├── services/           # 產生的連接器服務（由 PAC CLI 建立）
├── models/            # 產生的 TypeScript 模型（由 PAC CLI 建立）
├── hooks/             # 用於 Power Platform 整合的自訂 React Hook
├── utils/             # 公用程式函式
├── types/             # TypeScript 型別定義
├── PowerProvider.tsx  # Power Platform 初始化元件
└── main.tsx          # 應用程式進入點

4. 開發指令碼設定

根據官方 Microsoft 範例設定 package.json 指令碼：

• dev："concurrently "vite" "pac code run"" 用於平行執行
• build："tsc -b && vite build" 用於 TypeScript 編譯與 Vite 建置
• preview："vite preview" 用於生產環境預覽
• lint："eslint ." 用於程式碼品質檢查

5. 範例實作

包含基本範例，展示：

• 使用 PowerProvider 元件進行 Power Platform 驗證與初始化
• 連線至至少一個支援的連接器（建議使用 Office 365 Users）
• 使用產生的模型與服務的 TypeScript 用法
• 使用 try/catch 模式的錯誤處理與載入狀態
• 使用 Fluent UI React 元件的響應式 UI（遵循官方範例）
• 使用 useEffect 與非同步初始化的正確 PowerProvider 實作

進階模式（選用）

• 多環境設定：開發/測試/生產的環境特定設定
• 離線優先架構：用於離線功能的 Service Worker 與本機儲存
• 無障礙功能：ARIA 屬性、鍵盤導航、螢幕閱讀器支援
• 國際化設定：用於多語言支援的基本 i18n 結構
• 主題系統基礎：淺色/深色模式切換實作
• 響應式設計模式：使用斷點系統的行動優先方法
• 動畫框架整合：使用 Framer Motion 實現流暢轉場

6. 文件

建立完整的 README.md，包含：

• 先決條件與設定說明
• 驗證與環境設定
• 連接器設定與資料來源設定
• 本機開發與部署流程
• 常見問題疑難排解

實作指南

需提及的先決條件

• 安裝 Power Platform Tools 擴充功能的 Visual Studio Code
• Node.js（建議使用 LTS 版本 v18.x 或 v20.x）
• Git 版本控制
• Power Platform CLI (PAC CLI) - 最新版本
• 已啟用 Code Apps 的 Power Platform 環境（需要管理員設定）
• 終端使用者需具備 Power Apps Premium 授權
• Azure 帳戶（如果使用 Azure SQL 或其他 Azure 連接器）

需包含的 PAC CLI 指令

• pac auth create --environment {environment-id} - 使用特定環境進行驗證
• pac env select --environment {environment-url} - 選取目標環境
• pac code init --displayName "App Name" - 初始化 Code App 專案
• pac connection list - 列出可用的連線
• pac code add-data-source -a {api-name} -c {connection-id} - 新增連接器
• pac code push - 部署至 Power Platform

官方支援的連接器

專注於這些官方支援的連接器，並提供設定範例：

• SQL Server（包含 Azure SQL）：完整的 CRUD 操作、預存程序
• SharePoint：文件庫、清單與網站
• Office 365 Users：個人檔案資訊、使用者照片、群組成員資格
• Office 365 Groups：團隊資訊與協作
• Azure Data Explorer：分析與大數據查詢
• OneDrive for Business：檔案儲存與共用
• Microsoft Teams：團隊協作與通知
• MSN Weather：天氣資料整合
• Microsoft Translator V2：多語言翻譯
• Dataverse：完整的 CRUD 操作、關聯性與商務邏輯

範例連接器整合

包含 Office 365 Users 的工作範例：

// 範例：取得目前使用者個人檔案
const profile = await Office365UsersService.MyProfile_V2("id,displayName,jobTitle,userPrincipalName");

// 範例：取得使用者照片
const photoData = await Office365UsersService.UserPhoto_V2(profile.data.id);

需記錄的目前限制

• 內容安全性原則 (CSP) 尚未支援
• 儲存體 SAS IP 限制不支援
• 無 Power Platform Git 整合
• 無 Dataverse 解決方案支援
• 無原生 Azure Application Insights 整合

需包含的最佳做法

• 使用連接埠 3000 進行本機開發（Power Apps SDK 要求）
• 在 TypeScript 設定中設定 verbatimModuleSyntax: false
• 設定 vite.config.ts 包含 base: "./" 與適當的路徑別名
• 將敏感資料儲存在資料來源中，而非應用程式程式碼
• 遵循 Power Platform 受管理平台原則
• 為連接器操作實作適當的錯誤處理
• 使用 PAC CLI 產生的 TypeScript 模型與服務
• 包含具有適當非同步初始化與錯誤處理的 PowerProvider

交付項目

1. 包含所有必要檔案的完整專案結構
2. 具有連接器整合的工作範例應用程式
3. 完整的文件與設定說明
4. 開發與部署指令碼
5. 針對 Power Apps Code Apps 最佳化的 TypeScript 設定
6. 最佳做法實作範例

確保產生的專案遵循 Microsoft 官方 Power Apps Code Apps 文件與 https://github.com/microsoft/PowerAppsCodeApps 的範例，並可使用 pac code push 指令成功部署至 Power Platform。