building-ui-bundle-app

构建 UI Bundle 应用

概述

通过按正确的依赖顺序编排专门的 UI Bundle 技能，根据自然语言描述构建完整、可部署的 Salesforce React UI Bundle 应用。执行每个阶段之前，必须显式加载相应技能。

何时使用此技能

适用于：

• 用户在 Salesforce 上请求构建“React 应用”“UI Bundle”“Web 应用”或“全栈应用”
• 用户说“构建应用”或“创建应用程序”，且上下文表明要使用非 LWC 前端（例如 React）
• 工作目标是构建完整的 UI Bundle，包含脚手架、功能、数据访问和 UI，而非孤立的单个组件

以下示例应触发此技能：

• “构建一个使用 Salesforce 数据管理客户案例的 React 应用”
• “为员工目录创建一个带搜索和导航功能的 UI Bundle”
• “我需要一个支持身份验证、数据表格和文件上传的全栈 React 应用”
• “在 Salesforce 上构建一个咖啡店点单应用”

以下情况不要使用：

• 创建单个页面或组件（使用 building-ui-bundle-frontend）
• 只安装某项功能（使用 generating-ui-bundle-features）
• 只设置数据访问（使用 using-ui-bundle-salesforce-data）
• 只部署现有应用（使用 deploying-ui-bundle）
• 使用自定义对象和元数据构建 Lightning Experience 应用（使用 generating-lightning-app）
• 对现有 UI Bundle 进行故障排查或调试

---

依赖关系图和构建顺序

阶段 1：脚手架（基础）

UI Bundle scaffold (sf template generate ui-bundle)
    v
Install dependencies (npm install)
    v
Bundle metadata (uibundle-meta.xml, ui-bundle.json)
    v
CSP Trusted Sites (if external domains needed)

创建 UI Bundle 目录结构、元 XML，以及可选的路由／标头配置。后续所有阶段都要求脚手架已创建。

阶段 2：功能（可选）

Search project code (src/) for existing implementations
    v
Install dependencies (npm install)
    v
Search, describe, and install features (auth, shadcn, search, navigation, GraphQL)
    v
Resolve conflicts (two-pass: --on-conflict error, then --conflict-resolution)
    v
Integrate __example__ files into target files, then delete them

安装预构建且经过测试的功能包。如果应用不需要任何预构建功能，则跳过。始终先检查是否已有现成功能，再从头构建。功能为 UI 组件提供构建基础。

阶段 3：数据访问（后端连接）

Acquire schema (npm run graphql:schema)
    v
Look up entity schema (graphql-search.sh, max 2 runs)
    v
Generate queries/mutations (use verified field names, @optional on all record fields)
    v
Validate and test (npx eslint, ask user before testing mutations)

使用 @salesforce/sdk-data 设置数据层。记录操作优先使用 GraphQL；Connect、Apex 或 UI API 端点则使用 REST。

阶段 4：UI（前端）

Layout, navigation, header, and footer (appLayout.tsx)
    v
Pages (routed views)
    v
Components (widgets, forms, tables)

构建 React UI。引用阶段 3 中的数据层和阶段 2 中的功能。必须替换所有样板代码和占位内容。

阶段 5：集成（可选）

Agentforce chat widget (if requested)
File upload API (if requested)

这些集成彼此独立；如果两者都需要，可以并行执行。

阶段 6：部署

Org authentication
    v
Pre-deploy UI bundle build (npm install + npm run build)
    v
Deploy metadata
    v
Post-deploy configuration (permissions, profiles, named credentials, connected apps, custom settings, flow activation)
    v
Import data (if data plan exists)
    v
Fetch GraphQL schema and run codegen
*(Re-fetches schema from the deployed org -- required because the remote schema may differ from the local one used in Phase 3)*
    v
Final UI bundle build (rebuilds with the deployed schema)

按照规范的 7 步部署顺序执行。必须先部署元数据，再获取架构。必须先分配权限，再获取架构。

阶段 7：托管目标

根据应用的受众，从以下选项中选择一个：

阶段 7a：Experience Site（外部）

Resolve site properties (siteName, appDevName, etc.)
    v
Generate site metadata (Network, CustomSite, DigitalExperience)
    v
Deploy site infrastructure

创建用于托管 UI Bundle 的 Digital Experience 站点。用户需要面向公众的站点 URL，或需要供外部用户使用的身份验证站点 URL 时，使用此选项。

阶段 7b：自定义应用程序（内部）

Resolve app properties (appName, appNamespace, appLabel)
    v
Generate CustomApplication metadata (applications/*.app-meta.xml)
    v
Add <target>CustomApplication</target> to .uibundle-meta.xml
    v
Deploy custom application

在 Lightning App Launcher 中创建自定义应用程序入口。应用供内部用户在 Lightning Experience 中访问时，使用此选项。

---

执行工作流

步骤 1：需求分析与规划

操作：

1. 解析用户的自然语言请求
2. 确定应用名称和用途
3. 提取页面和导航结构
4. 确定所需的数据实体和 Salesforce 对象
5. 检测功能需求（身份验证、搜索、文件上传、聊天）
6. 判断是否需要 Experience Site
7. 确定需要注册到 CSP 的外部域名

输出：构建计划

UI Bundle App Build Plan: [App Name]

SCAFFOLDING:
- App name: [PascalCase name]
- Routing: [SPA rewrites, trailing slash config]
- External domains: [domains needing CSP registration]

FEATURES:
- [list of features to install: auth, shadcn, search, navigation, etc.]

DATA ACCESS:
- Objects: [Salesforce objects to query/mutate]
- Queries: [list of GraphQL queries needed]
- REST endpoints: [Apex REST or Connect API calls, if any]

UI:
- Layout: [description of app shell/navigation]
- Pages: [list of pages with routes]
- Components: [key components per page]
- Design direction: [aesthetic/style intent]

INTEGRATIONS (if applicable):
- Agentforce chat: [yes/no, agent ID if known]
- File upload: [yes/no, record linking pattern]

DEPLOYMENT:
- Target org: [org alias if known]
- Hosting target: [Experience Site / Custom Application / none]

SKILL LOAD ORDER:
1. generating-ui-bundle-metadata
2. generating-ui-bundle-features (if features needed)
3. using-ui-bundle-salesforce-data (if data access needed)
4. building-ui-bundle-frontend
5a. implementing-ui-bundle-agentforce-conversation-client (if chat requested)
5b. implementing-ui-bundle-file-upload (if file upload requested)
6. deploying-ui-bundle
7a. generating-ui-bundle-site (if Experience Site requested -- external users)
7b. generating-ui-bundle-custom-app (if Custom Application requested -- internal users)

步骤 2：分阶段执行

按顺序执行各阶段。完成一个阶段中的所有步骤后，再进入下一阶段。对于每个阶段：

步骤	操作	原因
1. 加载技能	调用本阶段所需的技能（例如，通过 Skill 工具）	获取当前规则、模式、约束和实现指南
2. 执行	按照已加载技能的工作流生成代码/配置	技能会说明如何正确完成工作
3. 验证	在 UI bundle 目录中运行 lint 和 build	在进入下一阶段前发现错误
4. 检查点	确认本阶段已完成，再继续	确保满足下一阶段的依赖条件

不要跳过步骤 1（加载技能）。 即使你记得技能的内容，技能也会不断更新。始终加载当前版本。

---

阶段 1 —— 搭建脚手架

• 1. 加载技能：调用 generating-ui-bundle-metadata
• 2. 执行：运行 sf template generate ui-bundle，安装依赖项（npm install），配置 meta XML、ui-bundle.json 和 CSP 可信站点
• 3. 验证：确认目录结构和元数据文件均已存在
• 4. 检查点：UI bundle 脚手架已就绪——进入阶段 2

阶段 2 —— 功能（如果不需要预构建功能，则跳过）

• 1. 加载技能：调用 generating-ui-bundle-features
• 2. 执行：安装依赖项、搜索并安装功能、集成示例文件
• 3. 验证：运行 npm run build，确认功能已顺利集成
• 4. 检查点：功能已安装——进入阶段 3

阶段 3 —— 数据访问（如果不需要 Salesforce 数据，则跳过）

• 1. 加载技能：调用 using-ui-bundle-salesforce-data
• 2. 执行：获取架构、查找实体、生成查询/变更，并将其接入组件
• 3. 验证：对包含 GraphQL 查询的文件运行 npx eslint
• 4. 检查点：数据层已就绪——进入阶段 4

阶段 4 —— UI

• 1. 加载技能：调用 building-ui-bundle-frontend
• 2. 执行：构建布局、页面、组件和导航。替换所有样板代码。
• 3. 验证：运行 lint 和 build——必须确保错误数为 0
• 4. 检查点：UI 已完成——进入阶段 5

阶段 5 —— 集成（如果未提出要求，则跳过）

• 1. 加载技能：调用 implementing-ui-bundle-agentforce-conversation-client（5a）和/或 implementing-ui-bundle-file-upload（5b）。如果两者都需要，它们彼此独立，可以并行执行。
• 2. 执行：按照各技能的工作流添加集成
• 3. 验证：运行 lint 和 build
• 4. 检查点：集成已完成——进入阶段 6

阶段 6 —— 部署

• 1. 加载技能：调用 deploying-ui-bundle
• 2. 执行：按照 7 步部署顺序操作（身份验证、构建、部署、权限、数据、架构、最终构建）
• 3. 验证：确认部署成功且应用可访问
• 4. 检查点：应用已部署——如有需要，进入阶段 7

阶段 7a —— Experience Site（如果未提出要求或选择了 Custom Application，则跳过）

• 1. 加载技能：调用 generating-ui-bundle-site
• 2. 执行：解析属性、生成站点元数据并部署
• 3. 验证：确认站点 URL 可访问
• 4. 检查点：站点已上线——构建完成

阶段 7b —— Custom Application（如果未提出要求或选择了 Experience Site，则跳过）

• 1. 加载技能：调用 generating-ui-bundle-custom-app
• 2. 执行：解析应用属性、生成 CustomApplication 元数据，并将 CustomApplication target 添加到 meta XML
• 3. 验证：确认应用显示在 App Launcher 中
• 4. 检查点：应用已注册——构建完成

步骤 3：最终摘要

所有阶段完成后，提供构建摘要：

UI Bundle App Build Complete: [App Name]

PHASES COMPLETED:
[x] Phase 1: Scaffolding -- [app name] UI bundle created
[x] Phase 2: Features -- [list of features installed, or "skipped"]
[x] Phase 3: Data Access -- [list of entities wired up]
[x] Phase 4: UI -- [count] pages, [count] components
[x] Phase 5: Integrations -- [list or "none"]
[x] Phase 6: Deployment -- deployed to [org]
[x] Phase 7: Hosting Target -- [Experience Site URL / Custom Application name / "skipped"]

FILES GENERATED:
[list key files and their paths]

NEXT STEPS:
[any manual steps the user should take]

---

验证

在宣布构建完成之前，请确认：

• 脚手架已就绪：UI bundle 目录包含有效的 meta XML 和 ui-bundle.json
• 依赖已安装：node_modules/ 存在，且 package.json 包含预期的软件包
• 构建通过：npm run build 生成 dist/，且没有错误
• Lint 通过：npx eslint src/ 报告 0 个错误
• 没有样板内容：所有占位文本、默认标题和模板内容均已替换
• 导航正常：appLayout.tsx 中的实际导航项与已创建的页面相匹配
• 数据层已接入：组件使用 @salesforce/sdk-data（如果已执行数据访问阶段）
• CSP 已注册：所有外部域名均有 CSP Trusted Site 元数据（如适用）

---

错误处理

类别 1：停止并询问用户

• 应用用途过于模糊，无法确定页面或数据需求
• 用户要求的功能彼此冲突（例如，“不需要身份验证” + “显示特定用户的数据”）
• 部署请求中未指定目标 org

类别 2：记录警告并继续

• 功能安装存在轻微冲突（解决冲突后继续）
• 可选集成设置遇到非阻塞问题
• 构建出现非错误警告

---

最佳实践

1. 始终遵循阶段顺序

安装功能之前绝不构建 UI。构建之前绝不部署。依赖关系必须严格遵循。

2. 替换所有样板内容

每个生成的应用都必须体现其专属用途。将“React App”标题、“Vite + React”占位内容以及所有默认内容替换为真实的、针对应用定制的文本和品牌元素。

3. 明确设计意图

遵循 building-ui-bundle-frontend 中的设计思路和前端美学指南。每个应用都应有清晰的视觉方向，而不是采用通用的默认设计。