consumer-goods-sync-management-configure

**设置 CG Cloud Mobile Sync 需要按顺序完成全部三个阶段——阶段 1（设置同步）、阶段 2（分配用户）、阶段 3（规划并验证）——而不只是安装同步构件。**安装基线只是阶段 1 的一个步骤；完成安装不代表设置完成。

指导管理员／实施人员为客户组织设置 Consumer Goods（CG）Cloud Mobile Sync，以便销售代表安装 CG Cloud Mobile App，并能离线查看当天计划的拜访。相关组件位于托管包 Sync Management App 中（其命名空间会在运行时解析——参见 Session state 中的 ns_prefix），以及 CG Cloud 核心／Retail Execution 设置中。

此技能会尽可能自动执行真实传输可触发的操作——Headless-360／generic-core 调用（SOQL、sObject REST、Connect、Tooling）、sf 部署，或包中的 global @RestResource /v1/* 端点。仅有 public 包方法不够：在托管包中，public 仅限命名空间内部使用（订阅方组织无法访问），因此只有 global／webservice／@RestResource 成员可被触发。如果通用核心功能和可调用的包操作都无法完成某个步骤，此技能会报告所需内容以及由谁提供，并停止该步骤；绝不会伪造功能。

范围与完成定义 — 请先阅读

如果没有限定条件，“设置 CG Cloud 移动同步”／“为 Retail Execution 设置同步”／“配置 Consumer Goods 移动同步”意味着按顺序运行全部三个阶段：阶段 1 → 阶段 2 → 阶段 3。这不是指“安装构件”。如果你准备在未限定的请求中只执行安装，这正是本节要避免的问题——请从阶段 1 的第 1 步（就绪检查）开始。

安装构件后并未完成。只有达到阶段 3 的最终状态（已列出已激活的配置、已对照四个对象完成验证，并已与基线文件核对），设置才算完成。若运行在安装后结束，请明确说明这是一次部分运行。

阶段 1 不只是“仅安装”。安装前有严格的就绪检查关卡——命名空间关卡（A1.1）和 Retail Execution 启用状态（A1.2）；安装后还要验证（A1.4）。将基线安装到未启用 RE 的组织中，会生成永远无法同步的配置，因此必须先检查就绪状态；若未通过，就应报告并停止，而不是绕过检查。基线安装就是同步配置（根 Sync_Config__c 及其值来自基线 CSV 文件）——没有单独的“创建配置”步骤。

技能无法完成某个步骤，应视为仅停止该步骤，而不是停止整个运行。请报告限制，并说明缺少的部分由谁提供（CG Cloud 平台／Retail Execution 或组织管理员），然后继续执行所有未受阻的步骤。只有遇到严格就绪检查未通过时才停止整个流程：缺少同步元数据（既未安装包，组织命名空间也无法解析）、无法启用 RE 且当前未启用，或者在 Default_IOU 模式下，目标用户缺少默认 mobility IOU。

唯一合理的子集运行情况是管理员的请求本身范围较窄（例如“同步已安装，只需分配给 Chantelle”“只需验证哪些配置已激活”）——请参见路由表。若请求未限定范围，或你不确定，请运行完整的第 1 至第 3 阶段。

传输契约 — 每个可自动化步骤都属于 core 或 Sync Management App

这是诚信准则。执行步骤前，先确认其传输方式；对于没有任何传输方式能够完成的步骤，绝不伪造成功：

• core — 通用的 Salesforce / Headless-360 能力：通过 execute_api 直接执行 SOQL → GET /query?q=...；CG Cloud core RetailExecutionSettings 的获取→设置组织首选项三步操作；sObject-REST 写入（POST /services/data/vXX.0/sobjects/<Entity>）；Schema/Tooling describe 读取。
• Sync Management App — 在包内触发的操作。真正的无头接口是 global @RestResource /v1/* 端点，主要是以下三个 /v1/syncconfig/* 路由：/install（GET 发现 + POST 安装 — A1.3）、/configs（GET 已部署配置 + 策略 — A3.1 列表）、/assignment（GET/POST/DELETE 用户→配置绑定 — A2.3）。public Apex 方法（命名空间私有）和 Visualforce 操作不属于 Sync Management App。

如果两种传输方式都无法完成某一步，请说明缺少什么、由谁提供，然后停止该步骤 — 不要猜测 API 名称，也不要绕过接口直接写入。真正无法自动化的情况很少：advanced-RE 试点 GA 门槛（A1.2，由平台负责，无 API）以及创建 IOU 成员关系（A2.2，这是一项 CG Cloud core / RE 任务，本技能只会读取）。传输方式的详细规则见：references/transports-and-namespace.md。

强制性的写入前计划 — 在首次写入前说明

执行任何写入（启用 RE、安装基线、创建映射行）之前，先发布一份简短计划，明确说明你的范围决策，确保其清晰可审查：

1. 完整流程分为三个阶段 — 阶段 1（设置同步）、阶段 2（分配用户）、阶段 3（计划与验证）。
2. 说明你将执行哪些阶段/子阶段，跳过哪些阶段/子阶段 — 每项跳过都必须引用管理员请求中的确切措辞，以说明如何缩小范围（“请求说‘设置同步’”不属于缩小范围的限定语）；对于无法完成的步骤，说明缺失部分由谁提供。
3. 明确确认目标 org（绝不能默认沿用），并说明将用于包对象的已解析 ns_prefix。
4. 说明从哪里开始。 对于未限定范围的请求，从阶段 1 的步骤 1 开始（就绪情况：命名空间 + RE）— 绝不从安装开始。
5. 将此计划保存到工作目录中的 report.md — 这是你采取的第一个操作，必须在任何 org 写入之前完成。完成每个阶段后，追加该阶段的结果（已执行步骤、传输标签、回读结果、受阻步骤），并在末尾写下最终结论。这份文件 — 而不是聊天记录 — 是本次运行的交付物；即使运行提前停止，也必须存在。相关约定见 references/verify-and-smoke.md 中的“将运行报告写入磁盘”。

入口点 — 根据管理员的实际需求确定流程

默认规则：除非需求明确缩小范围，否则将其视为完整设置，并按顺序执行 Act 1→2→3。不确定时，执行完整流程。

信号	从哪里开始
“设置 CG Cloud 移动同步”／“为 Retail Execution 设置同步”／未限定范围／没有先前状态	执行完整流程：确认组织 + 确定命名空间，然后执行 Act 1 步骤 1（就绪检查：命名空间 + RE），再执行 Act 1→2→3。不是“只安装”。直到达到 Act 3 的最终状态才算完成。
“同步已安装，我只需要分配用户”	范围缩小 → Act 2。先读回已安装配置（Act 3 的列出步骤），确认配置已部署，然后再绑定用户。
“只安装 Retail Execution 基线”	范围缩小 → 仅执行 Act 1 A1.3，**但须先确认 A1.1/A1.2 已就绪，**并明确确认要使用哪个基线。先 GET /v1/syncconfig/install 进行发现，再 POST 进行安装。切勿通过原始 sObject 插入手动创建。报告跳过的步骤（A1.4、Acts 2–3）为未完成。
“只验证／列出已激活的内容”	Act 3。只读；不执行写入。
“启用 Retail Execution”	仅执行 A1.2。CG Cloud 核心功能，可通过 core 写入；只有高级 RE 会受平台管理的试点门槛限制（无 API）。

会话状态（在整个对话中跟踪）

• target_org_alias — 正在配置的组织；任何写入操作前都必须明确确认。
• ns_prefix — 命名空间前缀（带尾随 __），在运行时通过 A1.1 发现（绝不硬编码），确定一次后用于每个包对象路径。来源有两个：已安装的托管包（InstalledSubscriberPackage.NamespacePrefix）或组织自身注册的命名空间（Organization.NamespacePrefix，源代码部署的 DE／打包组织）。
• api_version — 原始 HTTP URL 使用的 Salesforce REST API 版本。**绝不硬编码。**通过 GET /services/data 确定一次，取最高的 version。execute_api 调用不带版本。
• org_ready — 布尔值；当 A1.1 的命名空间门槛通过且 A1.2（RE 已启用）通过时为 true。任一项未通过都必须停止运行。
• installed_config_id / installed_version — 来自基线安装（A1.3）。安装本身就是配置——无需单独设置“已创建配置”标志。
• act1_complete、act2_complete、act3_complete — 各 Act 的布尔值；严格按 1→2→3 执行。对于未限定范围的请求，在报告完成前，三者都必须为 true（已报告的不可自动化步骤除外）。
• resolution_strategy — 配置根目录的 Business_Area_Resolution_Strategy__c（Default_IOU 与 Custom_User_Field）；决定 A2.3 是通过 A2.2 隐式使用 IOU，还是显式写入映射。
• blocked_steps — 持续更新的步骤列表，记录技能无法完成的步骤、受限环节以及由谁提供缺失内容。
• report_path — 本次运行的磁盘交付物：工作目录中的 report.md。必须在首次组织写入前创建（从写入前计划开始），并在每个 Act 的边界处追加内容，以便部分完成或中断的运行仍留有准确记录。只在聊天中报告并不满足要求——记录必须作为文件存在。

每个子操作的传输方式速查表

各步骤使用哪种传输方式的唯一事实来源。完整详情（API 名称、回退方案、负责人）：references/transports-and-namespace.md、references/readiness-and-enablement.md、references/sync-management-app-install-backbone.md、references/verify-and-smoke.md。

子操作	要求	传输方式	说明
A1.1	验证同步元数据已存在 + 解析命名空间（硬性前置条件）	core	此处唯一的硬性阻止条件是命名空间门槛（Tooling InstalledSubscriberPackage → 否则 Organization.NamespacePrefix）。不读取许可证（安装不受许可证限制），也不检查权限集是否存在（权限集名称可能被重命名/合并）。
A1.2	启用 Retail Execution	core	通过 RetailExecutionSettings 读写（dispatcher、5 个偏好设置），或通过 MDAPI Settings:RetailExecution（3 个布尔值）。只有 advanced-RE 会触及试点 GA 门槛（无 API）；基本开关不受影响。
A1.3	安装同步配置（基线根配置 + 子配置），并获取确认	Sync Management App	SyncConfigInstallEndpoint /v1/syncconfig/install：GET discoverConfigs，POST installConfig。基线在运行时发现——绝不硬编码。**安装本身就是配置。**绝不要通过原始插入手动创建。
A1.4	验证每个受跟踪对象引用的字段集定义是否存在	core（只读 describe）	名称由 CSV 安装；定义（例如 RetailMobilityRelevant）由 RE 而非软件包提供。字段集缺失 → 报告并停止，负责人 = RE 配置提供方。
A2.1	验证目标用户存在	core	通过 execute_api 执行 User SOQL。
A2.2	确认用户属于 Mobility IOU（只读前置条件，仅限 Default_IOU）	core	读取 InternalOrgUnitUser（IsDfltMobIntrOrgUnit = true）；绝不写入 IOU 成员关系。Default_IOU 下无记录 → 报告并停止。使用 Custom_User_Field 时跳过。
A2.3	将用户分配到已安装的配置	Sync Management App / IOU 隐式关联 → A2.2	SyncConfigAssignmentEndpoint /v1/syncconfig/assignment（GET/POST/DELETE）。不能使用 core：原始写入会破坏被复用的 Business_Area_Name__c。
A3.1	列出并验证 4 个对象中已激活的配置	Sync Management App（列表）+ core（计数）	SyncConfigListEndpoint /v1/syncconfig/configs；在一次批处理 anon-Apex 调用中执行全部四个 COUNT()（而不是针对每个对象循环执行 sf data query）。没有 /v1/syncconfig/verify——记录数就是验证结果。
A3.2	对照基线静态资源文件进行验证	core	将每个对象已安装的记录数与已安装基线自身声明的记录数进行比较；这些数量在运行时推导——绝不硬编码。

第 1 幕，共 3 幕——同步设置

安装前执行就绪门控，安装后执行轻量落地检查——完整的逐对象验证属于第 3 幕，此处不重复。安装基线只是中间子步骤，并非整个幕的内容。

1. A1.1 — 确认同步元数据存在，解析命名空间。 core。确认同步对象存在并解析 ns_prefix（通过 Tooling 的 InstalledSubscriberPackage 获取包的命名空间，否则使用 Organization.NamespacePrefix）。只有两者都无法解析时才算硬性缺失（停止）。 安装包不受许可证限制，因此此处不读取许可证——并且不要按名称验证任何权限集（权限集名称可能被重命名或合并）。第 1 幕真正的就绪门控恰好有两项：元数据存在（此步骤）和 RE 已启用（A1.2）。
2. A1.2 — 启用 Retail Execution。 core 读写权限。通过 RetailExecutionSettings（dispatcher）或 MDAPI Settings:RetailExecution 读取；通过 dispatcher 的 PATCH setters 或 sf project deploy start --metadata "Settings:RetailExecution" 启用（false→true，并重新读取以确认）。重新启用 RE 即表示基础预配已完成。高级试点开关（orgHasAdvncdRetailExecutionPilot）没有 API，且仅控制高级 RE。
3. A1.3 — 将同步配置安装到四个对象中。 Sync Management App。GET discoverConfigs（运行时发现——不存在名为 "Standard" 的配置），然后只有在管理员明确同意后才 POST；此前须展示所选基线及其清单推导出的逐对象计数。子配置 = 子级基线；parentConfigId 来自清单，以确保先安装父级，再安装子级。切勿通过原始 sObject 插入手动构建。返回 SUCCESS 后，仅通过轻量聚合检查确认落地——对全部四个 core COUNT() 执行一次批量 anon-Apex 调用（绝不按对象逐个运行 sf data query 循环；冷启动会导致超时），总和 == InstallResponse.recordsInserted，不获取清单——这不是第 3 幕的逐对象比对。
4. A1.4 — 确认所引用的字段集定义存在。 仅执行 core 只读 describe——不是部署。同步查询字段路径遇到字段集缺失时会报错（首次同步时硬失败），因此需逐个跟踪对象进行验证；任何字段集缺失 → 报告并停止，负责人 = RE 预配。

第 1 幕结束状态： 包已存在（通过门控）且 RE 已启用（否则报告缺失并停止运行）；管理员明确确认后，基线已安装到四个对象中（已捕获 installed_config_id/installed_version），并通过 COUNT()==recordsInserted 聚合检查确认落地（逐对象基线验证属于第 3 幕）；已确认所引用的字段集定义均存在。完整详情：references/act1-setup-sync.md。

第 2 幕，共 3 幕 — 将用户分配到同步配置

在第 1 幕之后运行（将用户绑定到第 1 幕安装的配置）。选择 A2.3 的传输方式前，先检测配置根目录的解析策略。

1. A2.1 — 验证目标用户是否存在。 core。通过 execute_api 查询 User SOQL。
2. A2.2 — 确认用户所属的 Mobility IOU。 core 只读前置条件，仅限 Default_IOU。读取默认 Mobility IOU（IsDfltMobIntrOrgUnit = true）；将 iouId 带入 A2.3，若不存在则报告并停止（此技能不会创建 IOU 成员关系）。在 Custom_User_Field 下完全跳过——不要泛化为一律“没有 IOU ⇒ 停止”。
3. A2.3 — 将用户分配到配置。 Sync Management App（映射行）/ core（IOU 隐式）。分配可绑定 User（005）、Role（00E）或 Profile（00e）；Role/Profile 行会绑定整个群组。通过 GET /v1/syncconfig/configs 选择配置，将名称解析为 Id，并按策略确定范围（Default_IOU → iouId；Custom_User_Field → businessArea 选项列表）。向 /v1/syncconfig/assignment 发送 POST，然后执行 GET 回读——确认返回的短规范 clientAppId。重新分配属于插入或更新：先执行 GET；重复的 (configPath, businessArea, mappedRecordId) 三元组会被拒绝；要变更绑定，需先 DELETE 旧行，再 POST。切勿直接写入 Sync_Client_App_Profile_Mapping__c——必须由端点推导重载的 Business_Area_Name__c。

**第 2 幕结束状态：**已确认目标用户；在 Default_IOU 下，已确认默认 Mobility IOU（或已报告并停止）；用户已绑定到已安装的配置，并通过回读验证。完整详情：references/act2-assign-users.md。

第 3 幕，共 3 幕 — 规划并验证

最后一幕——进行权威验证（第 1 幕只执行了成本较低的汇总落地检查；每个对象的比较仅在此处执行一次）。对于未限定范围的设置，必须达到本幕的结束状态——不要在安装后就停止。

1. A3.1 — 列出并验证已激活配置涉及的四个对象。 Sync Management App（列表）+ core（计数）。通过 GET /v1/syncconfig/configs 列出已部署配置及策略（也可使用 core SOQL 列表作为等效备用方式）。通过一次批处理的匿名 Apex COUNT() 调用获取所有计数，涵盖四个同步对象及 Sync_Config_State__c（自定义设置）——不要逐个对象循环执行 sf data query（冷启动会导致超时）。不要调用 /v1/syncconfig/verify——记录计数本身就是验证。
2. A3.2 — 对照基线静态资源文件验证。 core。将已安装的每个对象的计数与已安装基线自身声明的计数进行比较；在运行时推导这些计数（根据 A1.3 中捕获的已激活配置/版本识别基线）——此项逐对象比较由 A3.2 负责（汇总总数是第 1 幕的落地检查）；这样可以发现总数正确但分布错误的安装。不要硬编码计数——计数会因基线而异。

**第 3 幕结束状态：**已通过 /v1/syncconfig/configs 列出已激活配置，并通过 core SOQL 记录计数验证了四个对象（及状态），每个对象的计数均与基线自身声明的计数相符。完整详情：references/act3-plan-verify.md。

完成定义（整个技能）

未限定范围的 CG Cloud 移动同步设置，只有在三幕都达到各自的结束状态后才算完成；对于技能无法完成的任何步骤，都必须明确报告，并说明缺失内容由谁提供：第 1 幕（组织已就绪；管理员确认基线已安装；字段集定义已验证——或报告缺失字段集并停止）→ 第 2 幕（用户存在；在 Default_IOU 下，默认 Mobility IOU 已确认——或报告并停止；配置已绑定）→ 第 3 幕（已列出已激活配置，并通过 core SOQL 计数对照基线文件完成验证）。**仅在安装后（A1.3）报告“已完成”属于缺陷。**结束时明确列出尚待完成的事项，以及每项缺失内容由谁提供。

范围之外／暂缓处理

报告这些事项是为了明确预期，并非停止 Act 序列的理由：

• 移除 orgHasAdvncdRetailExecutionPilot 准入开关／将其设为 GA 门槛——CG Cloud 核心（零售执行）；任何地方都没有 API（A1.2）。
• 编写已发布基线之外的新建／自定义基线（运行时发现）——手动编写 ZIP（manifest + CSV），不属于此技能范围。
• 创建 Mobility IOU 成员资格（A2.2）——这是 CG Cloud 核心／RE 任务；此技能只读取该成员资格。

配套参考资料

• references/act1-setup-sync.md、references/act2-assign-users.md、references/act3-plan-verify.md——各 Act 的独立拆解。
• references/transports-and-namespace.md——传输与命名空间规则，以及 sf CLI 使用指南。
• references/readiness-and-enablement.md——命名空间门槛与 RE 启用详情。
• references/sync-management-app-install-backbone.md——Sync Management App 安装骨干流程。
• references/verify-and-smoke.md——验证与冒烟测试模式。
• examples/scenarios.md——经过验证的场景示例（正确运行与反模式运行）。