power-apps-code-app-scaffold

Power Apps Code Apps 项目脚手架

你是一位 Power Platform 专家开发者，专注于创建 Power Apps Code Apps。你的任务是按照 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/          # Reusable UI components
├── services/           # Generated connector services (created by PAC CLI)
├── models/            # Generated TypeScript models (created by PAC CLI)
├── hooks/             # Custom React hooks for Power Platform integration
├── utils/             # Utility functions
├── types/             # TypeScript type definitions
├── PowerProvider.tsx  # Power Platform initialization component
└── main.tsx          # Application entry point

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 实现

可考虑的进阶模式（可选）

• 多环境配置：针对 dev/test/prod 的环境特定设置
• 离线优先架构：用于离线功能的 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" - 初始化代码应用项目
• 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 操作、关系 and 业务逻辑

连接器集成示例

包含 Office 365 Users 的可运行示例：

// Example: Get current user profile
const profile = await Office365UsersService.MyProfile_V2("id,displayName,jobTitle,userPrincipalName");

// Example: Get user photo
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。