experience-ui-bundle-app-coordinate

构建 UI Bundle 应用

概述

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

重要：在完成需求分析并继续后续步骤之前，请确认提示词中不存在相互冲突的要求（例如，“不需要身份验证”与“用户专属数据”、“公开访问”与“需要登录的功能”）。如果发现冲突，请停止并要求用户消除歧义——不要默默选择一种解释并继续。完整的冲突检查清单请参见步骤 1 操作项 #8。

先决条件

开始任何阶段之前，请确认以下先决条件均已满足：

1. 已通过身份验证的 Salesforce 组织：运行 sf org display，确认已设置默认组织且已通过身份验证。如果没有，请提示用户进行身份验证：sf org login web
2. 必需的 CLI 工具：确认 sf、npm 和 npx 均可用（在 metadata.cliTools 中声明）
3. Node.js 版本：运行 node scripts/check-prerequisites.mjs 并报告所有错误
4. 组织功能（如果要部署）：已启用 Experience Cloud，具备适当的许可证，并已启用 Sites

如果任何先决条件未满足，请停止并报告具体缺失项，然后再尝试执行任何阶段。

何时使用此技能

适用场景：

• 用户请求在 Salesforce 上构建“React 应用”“UI Bundle”“Web 应用”或“全栈应用”
• 用户表示“构建应用”或“创建应用程序”，且上下文表明前端不是基于 LWC 的（例如 React）
• 工作内容是构建完整的 UI Bundle，包含脚手架、功能、数据访问和 UI，而不是单独的组件

应触发此技能的示例：

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

不适用场景：

• 创建单个页面或组件（使用 experience-ui-bundle-frontend-generate）
• 仅安装某项功能（使用 experience-ui-bundle-features-generate）
• 仅设置数据访问（使用 experience-ui-bundle-salesforce-data-access）
• 仅部署现有应用（使用 experience-ui-bundle-deploy）
• 构建带有自定义对象和元数据的 Lightning Experience 应用（使用 platform-lightning-app-coordinate）
• 排查或调试现有 UI Bundle

---

提示词分类关键词

此技能会直接根据原始提示词文本做出两项判断。以下表格是这两项判断的唯一依据——不要在文件的其他位置重新陈述或推导这些列表。

1. 如果提示词提及以下任意关键词，则必须执行阶段 2（功能）：

类别	关键词	备注
数据功能	search, filter, sort, pagination, table, grid, list
导航	navigation, nav, menu, routing
身份验证	authentication, auth, login, logout, user session, user login
集成	upload, file
UI	shadcn, components, forms, buttons, cards
聊天（仅阶段 5）	chat	仅阶段 5——除非同时出现阶段 2 关键词（例如，“chat with authentication”），此时应先执行阶段 2，以满足身份验证前置条件

否定某个类别（例如，“without authentication”“no login required”“public access”）不会取消其他类别触发的条件——每项都会单独评估。例如，“no login required, with filtering”仍会触发阶段 2，因为“filtering”匹配数据功能。只有当提示词与上述关键词均不匹配时，才跳过阶段 2。

2. 托管目标——根据提示词中的关键词提取：

托管目标	关键词
Experience Site	"Experience Site", "Community", "external users", "public users", "guest users"
Custom Application	"Custom Application", "internal users", "Lightning app"

如果提示词与两组关键词都不匹配，或同时匹配两组关键词，请在继续之前询问用户以作确认——不要猜测。

---

依赖关系图与构建顺序

阶段 0：模板提议与引导（前置条件）

Offer prebuilt starter template (experience-ui-bundle-project-generate)
    v
If template chosen: scaffold via sf template generate project -- Phase 1 skipped
    v
If declined: run node scripts/check-sfdx-project.mjs
    v
If missing: create sfdx-project.json
    v
Verify project directory initialized

在从头构建之前，提供一个更快捷、更不易出错的起点。如果不使用模板，则需确保 SFDX 项目存在，再尝试生成 UI 包——否则，sf template generate ui-bundle 会因严重错误而失败。务必先检查——不要假定项目结构已存在。

**操作：**加载 experience-ui-bundle-project-generate，并提供两个入门模板供用户选择。如果用户拒绝，则运行 node scripts/check-sfdx-project.mjs；若出错，则先创建缺失的 sfdx-project.json，再继续。

第 1 阶段：脚手架搭建（基础）

Determine hosting target (Experience Site / Custom Application)
    v
UI Bundle scaffold (sf template generate ui-bundle --template reactbasic)
    v
Install dependencies (npm install)
    v
Bundle metadata (uibundle-meta.xml with <target>, ui-bundle.json)
    v
CSP Trusted Sites (if external domains needed)

创建 UI 资源包目录结构、元数据 XML（包括托管目标）以及可选的路由／标头配置。至关重要：必须先确定托管目标，因为元数据技能在第 1 阶段要求提供 <target>。后续所有阶段都要求脚手架已存在。

当提示词限制了范围时，移除未使用的脚手架内容。 reactbasic 模板默认包含完整的 shadcn 组件集、GraphQL 工具（codegen.yml、.graphqlrc.yml、src/api/graphqlClient.ts、graphql:* npm 脚本）和测试基础设施（playwright.config.ts、vitest.config.ts、vitest.setup.ts），无论提示词要求什么。如果提示词明确限制了范围（例如“跳过任何功能或集成”“只搭建脚手架并构建 X”“无需安装依赖项”），导致第 2 阶段和／或第 3 阶段被跳过，那么在运行第 4 阶段之前，删除原本由这些阶段负责的脚手架内容：

• 跳过第 2 阶段 → 删除 src/components/ui/ 下的 shadcn 组件，但保留第 4 阶段页面实际导入的组件；移除未使用的示例／演示组件。
• 跳过第 3 阶段 → 删除 codegen.yml、.graphqlrc.yml、src/api/graphqlClient.ts、package.json 中的 graphql:schema／graphql:codegen 脚本，以及模板预置的任何 hooks/ 数据获取占位文件（例如 useAsyncData.ts）。
• 既未要求测试，也未要求部署 → 只有当提示词暗示需要测试时才保留 playwright.config.ts／vitest.*；否则也将它们移除。
• 重写 README.md，使其介绍实际构建的应用，而不是通用模板样板内容；如果提示词要求只做最少工作，则删除该文件。

**删除文件只完成了一半——必须在同一轮中移除对该文件的所有引用，否则只是把过度生成变成了跨文件一致性问题（更糟的是，悬空导入会导致功能故障，而不只是范围蔓延）。**具体来说，删除上述任何文件后：

• vite.config.ts — 如果删除了 codegen.yml，移除 vite-plugin-graphql-codegen 导入及其 codegen({ configFilePathOverride: ... }) 插件代码块；如果删除了 vitest.*，移除 test: 配置代码块（setupFiles、coverage 等）。
• package.json — 移除现在未使用的依赖（vite-plugin-graphql-codegen、@graphql-codegen/*、playwright、vitest 等）及其 npm 脚本，而不只是删除配置文件。
• 任何导入了已删除 Hook、客户端或 shadcn 组件的组件／页面（例如 useAsyncData、graphqlClient），都必须移除或替换相关导入及其用法，绝不能保留指向不存在文件的导入。
• 不要在同一轮的其他位置重新添加刚刚删除的文件（例如，删除 codegen.yml 的同时仍生成 .graphqlrc.yml）——针对每项关注点，只确定一次范围，并在所有涉及该项的文件中一致执行。
• 完成第 4 阶段之前，对每个已删除文件运行 node scripts/check-dangling-refs.mjs <deleted-basename>，并报告任何错误。

第 2 阶段：功能（如果提示词提及功能关键词则为必需——见上文“提示词分类关键词”）

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

加载功能技能以安装预构建软件包，或采用模板中已有的软件包——绝不要自行构建目录型功能。触发条件及对否定措辞的处理方式，参见“提示词分类关键词”。

仅当是没有交互功能的最简“hello world”时才跳过；预置功能仍需执行此阶段。

第 2.5 阶段：自定义对象（如果提示词要求创建组织中不存在的新 Salesforce 自定义对象，则为必需）

有关第 2.5 阶段（自定义对象）的详情，请参阅 references/phase-custom-objects.md。

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

Ground every entity/field against the org (per experience-ui-bundle-salesforce-data-access)
    v
Generate queries/mutations FROM the verified names (never from guessed fields)
    v
Generate types (npm run graphql:codegen) and wire into components
    v
Validate and test (npx eslint, ask user before testing mutations)

使用 @salesforce/platform-sdk Data SDK（createDataSDK().graphql）搭建数据层。 记录操作优先使用 GraphQL；Connect、Apex 或 UI API 端点则使用 REST。experience-ui-bundle-salesforce-data-access 技能负责数据依据核实和编写工作流——请加载并遵循该技能；不要用本地 schema 搜索或猜测字段名称来替代。 数据依据核实针对实时 org进行，因此不要求本地存在 schema.graphql。如果第 2.5 阶段创建了新对象，必须先部署，才能在本阶段的数据依据核实步骤中找到它。

第 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. Guard against an empty or stale result -- Salesforce Edge caching can briefly serve the pre-deploy schema; re-fetch/retry before trusting it as empty and before running codegen)*
    v
Final UI bundle build (rebuilds with the deployed schema)

遵循规范的 7 步部署顺序。必须先部署元数据，再获取 schema。必须先分配权限，再获取 schema。

第 7 阶段：托管目标基础设施

部署第 1 阶段确定的托管目标基础设施。根据应用的受众，选择以下一项：

第 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，供外部用户访问的场景。注意：<target>ExperienceSite</target> 已在第 1 阶段的 meta XML 中设置。

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

Resolve app properties (appName, appNamespace, appLabel)
    v
Generate CustomApplication metadata (applications/*.app-meta.xml)
    v
Deploy custom application

在 Lightning App Launcher 中创建自定义应用条目。适用于供内部用户在 Lightning Experience 中访问的应用。注意：<target>CustomApplication</target> 已在第 1 阶段的 meta XML 中设置。

---

执行工作流

步骤 0：提供预构建模板（从头开始搭建之前）

在分析需求或搭建项目之前，先检查是否有合适的预构建起始模板——相比从头构建，它更快且更不容易出错。

• 加载技能：调用 experience-ui-bundle-project-generate。 该技能提供两个精简的 React 起始项目（面向内部员工和面向外部客户）；如果用户选择其中一个，它会通过 sf template generate project 将其生成到项目目录中。
• 如果用户选择模板： 搭建阶段（第 1 阶段）实际上已完成。直接跳到填充或自定义项目，根据用户想要更改的内容继续相应阶段（通常是第 4 阶段 UI 或第 3 阶段数据访问），然后进行第 6 阶段部署。
• 如果用户拒绝（想从头开始，或没有合适的模板）：正常继续步骤 1。

从头开始构建应用时，不要默默跳过此步骤——一开始就要提供该选项。

步骤 1：需求分析与规划

操作：

1. 解析用户的自然语言请求
2. 确定应用名称和用途
3. 提取页面和导航结构
4. 确定所需的数据实体和 Salesforce 对象
5. 检测功能需求（身份验证、搜索、文件上传、聊天）
6. 确定托管目标（Experience Site 或 Custom Application）——请参阅上文的“Prompt Classification Keywords”；如果不明确，请先让用户澄清，再继续
7. 确定需要进行 CSP 注册的外部域名
8. 检查是否存在相互冲突的需求——如果检测到以下任一冲突，请停止并询问用户：
   • “No authentication”或“public/guest access”与“user-specific data”、“show current user's data”或“My [Entity]”视图同时出现
   • “External users”与“Custom Application”同时出现（Custom Apps 仅供内部使用）
   • “Public access”与需要登录的功能（文件上传、用户个人资料、个性化）同时出现

计划中必须包含一个明确的数据核验步骤，且要先于任何查询编写。不要将猜测的对象/字段名称列为已确认事实，再留待代码生成时核验。计划中的数据访问部分必须写为：“先通过 experience-ui-bundle-salesforce-data-access 对照组织核验这些实体/字段，然后使用核验过的名称编写查询。”先编写查询、之后再生成代码的计划会导致猜测字段并手动补写类型——请勿输出此类计划。

继续生成输出（构建计划）之前，请先验证：

• 未检测到相互冲突的需求——如果存在冲突（参见操作 #8），请停止并报告：

  ERROR: Conflicting requirements detected:
  - [describe the specific conflict, e.g., "The prompt requires 'no authentication' while also requiring a 'My Cases' view scoped to the current user's identity"]
  
  RESOLUTION NEEDED: Please clarify:
  - [specific question, e.g., "Should the app require login (removing the 'no authentication' requirement), or should all data be public (removing the user-scoped view)?"]
  

  在解决此冲突之前，请勿继续生成构建计划或执行任何阶段。

输出：构建计划

UI Bundle App Build Plan: [App Name]

SCAFFOLDING:
- App name: [PascalCase name]
- Hosting target: [Experience Site / Custom Application] **REQUIRED**
- Routing: [SPA rewrites, trailing slash config]
- External domains: [domains needing CSP registration]

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

CUSTOM OBJECTS (if applicable):
- New objects/fields: [list any object the org does not already have, with its fields -- delegate to platform-custom-object-generate, not authored here]

DATA ACCESS:
- Objects: [Salesforce objects to query/mutate]
- Grounding: [verify each object + its fields against the org via experience-ui-bundle-salesforce-data-access BEFORE authoring — list the objects/fields to confirm, not assumed-correct names]
- Queries: [GraphQL queries to author FROM the verified names]
- REST endpoints: [only where GraphQL/uiapi genuinely cannot cover it — not as a fallback for fields that were hard to verify]

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]

SKILL LOAD ORDER:
0. experience-ui-bundle-project-generate (offer a prebuilt template first; if chosen, Phase 1 scaffolding is skipped; if declined, run the Bootstrap check for an existing SFDX project -- no skill load required)
1. experience-ui-bundle-metadata-generate (determines hosting target FIRST)
2. experience-ui-bundle-features-generate (if features needed)
2.5. platform-custom-object-generate (if the prompt requires a new custom Salesforce object the org doesn't have -- MUST complete and deploy before step 3)
3. experience-ui-bundle-salesforce-data-access (if data access needed)
4. experience-ui-bundle-frontend-generate
5a. experience-ui-bundle-agentforce-client-generate (if chat requested)
5b. experience-ui-bundle-file-upload-generate (if file upload requested)
6. experience-ui-bundle-deploy
7a. experience-ui-bundle-site-generate (if Experience Site requested -- external users)
7b. experience-ui-bundle-custom-app-generate (if Custom Application requested -- internal users)

步骤 2：分阶段执行

按照 references/phase-execution-pattern.md 中的标准模式依次执行各阶段。重要：执行前务必加载技能。 跳过或调整阶段顺序会导致应用无法正常运行。

---

阶段 0 -- 模板提供与引导

• 加载 experience-ui-bundle-project-generate，提供模板供选择。如果用户选择模板：跳过阶段 1，从阶段 2 继续。如果用户拒绝：运行 node scripts/check-sfdx-project.mjs，如果项目不存在则创建项目。

阶段 1 -- 脚手架搭建（如果阶段 0 使用了模板，则跳过）

• 前置条件：node scripts/check-sfdx-project.mjs 通过
• 加载 experience-ui-bundle-metadata-generate。首先确定托管目标。运行 sf template generate ui-bundle --template reactbasic，使用 <target> 配置 meta XML。
• 后置验证：node scripts/check-phase-1-complete.mjs 通过

阶段 2 -- 功能（出现任何功能关键词时都要执行，即使功能已预装也不例外——请参阅“提示词分类关键词”）

• 加载 experience-ui-bundle-features-generate。安装功能并集成示例。使用 npm run build 验证。

阶段 2.5 -- 自定义对象（如果组织中已包含所需的全部对象，则跳过）

• 阅读 references/phase-custom-objects.md 并按执行步骤操作。

阶段 3 -- 数据访问（如果没有 Salesforce 数据，则跳过）

• 加载 experience-ui-bundle-salesforce-data-access。获取架构、以实体为依据，并生成查询和变更操作。使用 npx eslint 验证。

阶段 4 -- UI（始终必须执行）

• 前置条件：node scripts/check-phase-1-complete.mjs 通过
• 加载 experience-ui-bundle-frontend-generate。构建布局、页面和组件。替换所有样板内容。
• 后置验证：node scripts/check-phase-4-complete.mjs 通过
• 重要：阶段 4 会生成实际的 React UI。切勿跳过。

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

• 根据需要加载 experience-ui-bundle-agentforce-client-generate（5a）和/或 experience-ui-bundle-file-upload-generate（5b）。

阶段 6 -- 部署

• 前置条件：node scripts/check-phase-6-ready.mjs 通过
• 加载 experience-ui-bundle-deploy。按 7 步顺序操作。如果 scripts/org-setup.mjs 可用，优先使用。
• 重要：防止架构为空——在代码生成前，最多重试获取 3 次。

阶段 7a -- Experience Site（外部用户）

• 触发条件：node scripts/check-hosting-target.mjs 的输出为 "ExperienceSite"
• 加载 experience-ui-bundle-site-generate。部署站点基础架构。

阶段 7b -- 自定义应用（内部用户）

• 触发条件：node scripts/check-hosting-target.mjs 的输出为 "CustomApplication"
• 加载 experience-ui-bundle-custom-app-generate。部署应用元数据。

步骤 2.5：阶段完成情况验证

继续执行步骤 3（最终摘要）之前，验证所有必需阶段均已执行。完整的重要事项/警告检查清单以及需要报告的确切错误/警告文本，请参阅 references/phase-completion-validation.md。

步骤 3：最终摘要

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

UI Bundle App Build Complete: [App Name]

PHASES COMPLETED:
[x] Phase 0: Template Offer & Bootstrap -- [template used: <name> / declined; SFDX project verified/created]
[x] Phase 1: Scaffolding -- [app name] UI bundle created with hosting target [Experience Site / Custom Application]
[x] Phase 2: Features -- [list of features installed, or "skipped"]
[x] Phase 2.5: Custom Objects -- [list of objects/fields created and deployed, or "skipped -- no new schema needed"]
[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] **(never "skipped" -- Phase 1 requires a target, so exactly one of 7a/7b always runs)**

FILES GENERATED:
[list key files and their paths]

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

---

验证

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

• 脚手架已就绪：UI bundle 目录中包含有效的 meta XML 和 ui-bundle.json
• 托管目标已确定并部署：Meta XML 包含 <target>ExperienceSite</target> 或 <target>CustomApplication</target>（不得留空），并且已生成并部署匹配的 Phase 7a 或 7b 基础设施，不能跳过
• 依赖项已安装：node_modules/ 存在，且 package.json 包含预期的软件包
• 构建通过：npm run build 成功生成 dist/，且无错误
• Dist 内容存在：dist/ 包含 index.html、JS/CSS bundle 和资源（不能只是空目录）
• Lint 通过：npx eslint src/ 报告 0 个错误
• 无样板内容：所有占位文本、默认标题和模板内容均已替换
• 导航正常：appLayout.tsx 中的真实导航项与已创建的页面相匹配
• 数据层已接通：组件使用 @salesforce/platform-sdk Data SDK（createDataSDK().graphql），并且所有实体和字段均已根据 org 核实，而非猜测（如果已执行数据访问阶段）
• 已注册 CSP：所有外部域名均已配置 CSP Trusted Site 元数据（如适用）

---

错误处理

类别 1：停止并询问用户

• 应用用途过于模糊，无法确定页面或数据需求
• 用户要求的功能存在冲突（例如，“无需身份验证”+“显示特定用户的数据”）
• 无法确定托管目标（请询问：“这是供内部用户使用（Custom Application），还是供外部用户使用（Experience Site）？”）
• 目标 org 未知，但用户要求部署

类别 2：记录警告并继续

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

---

最佳实践

1. 始终遵循阶段顺序

安装功能之前，绝不构建 UI。构建之前，绝不部署。依赖顺序不可更改。

2. 替换所有样板内容

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

3. 有目的地进行设计

遵循 experience-ui-bundle-frontend-generate 中的设计思维和前端美学指导。每个应用都应有明确的视觉方向，而不是使用通用默认样式。