SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场commerce-react-storefront-create

commerce-react-storefront-create

前端与建站

查看项目

更新于 10-24 05:41

技能介绍

这是什么

该技能把 commerce-b2b-headless 参考版 React 店面部署到用户的 B2B Commerce 组织，并返回托管店面 URL。该仓库是参考实现，内置四个与组织相关的 <…_Placeholder> 字符串，未替换时运行期会抛错。技能的核心工作就是针对目标组织解析这四个值，然后驱动构建 → 部署 → 访客用户授权，使店面真正可渲染。

仓库自带的 scripts/org-setup.mjs（npm run setup）可自动完成登录 → 构建 → 部署 → 权限集 → 开发服务器，但它不会发现 WebStore、不会替换占位值，也不会为站点访客用户授权，这些正是需要手工完成的步骤。

前提要求：Node 22+、sf CLI 2.130+，目标组织需启用 B2B Commerce 与 Multi-framework React（API 版本 67.0+）。只应对用户拥有或获授权修改的组织操作，部署、Apex 编辑与权限集分配都是真实的写入操作。

固定的仓库事实

  • 仓库克隆地址：https://github.com/trailheadapps/commerce-b2b-headless.git（先询问是否已有克隆；新克隆落在当前工作目录下经用户确认的路径）
  • UI Bundle 目录：force-app/main/default/uiBundles/commerceb2bheadless
  • WebStore 配置文件：该目录下的 src/config/commerce.ts
  • 注册用 Apex：UIBundleRegistration.cls（仓库 Apex 类目录）
  • Vite 配置：该目录下的 vite.config.ts
  • 认证权限集：UIBundleApexAccess（授予 6 个认证 Apex 类）
  • 站点名：commerceb2bheadless，也是店面 URL 路径
  • Connect urlPathPrefix：commerceb2bheadlessvforcesite（内部匹配键，非 URL 路径）
  • 默认 API 版本：v67.0

必须设置的四个值

  1. WebStore Id：commerce.ts 中 WEBSTORE_ID（0ZE 前缀）
  2. 默认 BuyerGroup Id：UIBundleRegistration.cls 中 DEFAULT_BUYER_GROUP_ID（0ZI 前缀）
  3. 买家权限集组：UIBundleRegistration.cls 中 BUYER_PERMISSION_SET_GROUP（DeveloperName）
  4. Vite 组织别名（可选）：vite.config.ts 中 salesforce({ orgAlias: '…' })

工作流程

步骤 1：确定目标组织。用户给了别名就直接用，否则用 sf org list --json 列出已连接组织并询问。用 sf org display 确认可达；未连接则用 sf org login web --alias <alias> --instance-url https://<my-domain>.my.salesforce.com 登录。

步骤 2：查询组织的 WebStore 并让用户选择。店面仅支持 B2B，查询 SELECT Id, Name, Type FROM WebStore WHERE Type = 'B2B' ORDER BY Name 只列 B2B 商店。始终让用户按名称选择，即使只有一个；不要代为选择。记录所选商店 Id（0ZE…），它既是值 #1，也用于限定步骤 4b 的 BuyerGroup 查询。若无结果，说明组织未开通 B2B 商店，应停止并引导用户先通过 b2b-commerce-org-setup 插件创建。

步骤 3：询问仓库位置或克隆。先问用户是否已有 commerce-b2b-headless 克隆及路径，或是否需要从上述地址克隆。已有克隆时用 ls 校验 README.md 与 UI Bundle 目录存在；克隆时先检查当前目录结构，避免落入其他 git 仓库或覆盖已有文件夹，提出 $(pwd)/commerce-b2b-headless 作为路径并等待用户确认后再克隆并校验。克隆因仓库不存在或认证失败时，应请用户提供可访问的 URL（如 fork）或本地克隆，而不是中断。

步骤 4：填写四个组织相关值。用编辑方式就地替换，任何占位字符串残留都不可部署。

  • 4a：用步骤 2 的 0ZE… 替换 commerce.ts 中 WEBSTORE_ID。
  • 4b：优先查询绑定到该商店的 BuyerGroup（SELECT BuyerGroupId, BuyerGroup.Name FROM WebStoreBuyerGroup WHERE WebStoreId = '<0ZE…>'），回退为列出全部 BuyerGroup；多个时让用户选择，替换 DEFAULT_BUYER_GROUP_ID。新自助注册买家会加入此处。
  • 4c：查询 PermissionSetGroup 的 Id、DeveloperName、MasterLabel，需与商店在 Commerce App → Buyer Access → Self-Registration 中下发的 PSG 一致，让用户确认后替换占位值。错误或缺失会导致注册成功但下单报 INSUFFICIENT_ACCESS。
  • 4d：若机器上有多个组织，建议在 vite.config.ts 中固定 orgAlias，否则 SDK 回退 65.0，与较新组织不匹配，所有认证请求返回 401。

步骤 5：构建 UI Bundle 后转交部署。dist/ 是部署产物，WebStore Id 在构建时写入。先在 $REPO 执行 npm install，再在 $BUNDLE 执行 npm install、rm -rf dist、npm run build，并用 grep 确认 0ZE… 已写入 dist。部署前提醒 guest Chatter 设置：仓库网络元数据默认 enableGuestChatter 为 true，会向未认证访客暴露 Chatter，建议改为 false（需用户同意）；生产组织应确认已复查 README 中相关配置项再部署。部署交给 experience-sites-ui-framework/experience-ui-bundle-deploy 技能，只需运行其“Deploy metadata”步骤，并告知用户其构建、权限集、角色、自助注册、社交登录、数据导入和 GraphQL 步骤未运行及原因。若该技能不可用，报告部署转交受阻，不要自创部署方式。

步骤 6：为站点访客用户授权。应用所有店面路由都在登录之后，匿名访客只会看到登录/注册/找回密码/重置密码页，因此访客用户唯一需要的是 UIBundleApexAccess。查询 Site 的 GuestUserId 与权限集 Id，用 sf data create record 创建 PermissionSetAssignment；DUPLICATE_VALUE 视为已完成。随后查询确认分配存在。不要给访客用户额外的商务权限集。若用户日后移除登录限制以允许访客浏览，需在商店层配置 WebStore.OptionsGuestBrowsingEnabled、访客买家档案与访客买家组，并可能需将 WebStore 绑定到 headless 站点的 Network；该路径未经验证，应提示而非尝试。

步骤 7：解析并返回托管店面 URL。通过 connect/communities 接口按 urlPathPrefix 匹配 commerceb2bheadlessvforcesite，取 siteUrl 报告给用户。若 status 非 Live，需在 Setup → Digital Experiences → All Sites → commerceb2bheadless → Publish 发布后重新获取。接口无结果时回退为 https://<my-domain>.my.site.com/commerceb2bheadless，路径是站点名而非 vforcesite 前缀；非生产实例站点域名后缀不同，应提示用户在 All Sites 中核实。

一条命令替代方案

若四个值已设置，可用仓库自带编排器：cd $REPO && npm run setup -- --target-org <alias> --skip-dev --skip-data。注意它不替换占位值，且把 UIBundleApexAccess 分配给当前用户而非访客用户，所以仍需先做步骤 4、后做步骤 6。仅当用户需要本地 Vite 开发服务器时才去掉 --skip-dev；若未接入 GraphQL codegen，加 --skip-graphql。

故障排查

  • /login 返回 403“no access to UIBundleLogin”：访客用户缺少 UIBundleApexAccess，重做步骤 6。
  • 匿名访客落到 /login：属设计如此，所有店面路由需登录。
  • /commerce/... 返回 404：组织低于 API 67.0，不支持 Site Container，需升级。
  • 店面无商品：买家账户不在拥有有效价目表条目的 BuyerGroup 中。
  • 所有认证请求 401：Vite 回退到 API 65.0，设置组织别名后重新构建。
  • 下单报 INSUFFICIENT_ACCESS：买家 PSG 错误或缺失（步骤 4c）。
  • 重新部署后仍显示旧值或占位值：旧的 dist/ 被发布，删除后重新构建。

注意事项

双 Network：headless 店面运行在自己的 Network 上，与旧 LWR 商店的 Network 共存。不要重命名 Apex 类、UIBundleApexAccess 或站点 URL 前缀，它们被 React 应用、权限集和查询交叉引用。这是活组织工作流：在执行任何写入前说明组织、商店和操作，绝不对未获授权的组织部署。