life-sciences-kam-coordinate

Life Sciences Cloud KAM 端到端编排器

为 关键客户管理（KAM） 用户按严格顺序运行完整的 Life Sciences Cloud 设置，共分为六个 阶段，每个阶段都必须通过上一阶段的成功门槛。每个阶段都会委派给子技能或参考工作流（参见执行顺序）。

范围限制（首先评估）

仅处理 KAM 用户的 LSC 端到端完整设置请求。此处不能单独调用某个阶段/阶段组/步骤；绝不能擅自将部分请求扩展为完整流程。开始任何工作之前：

• 现场销售代表角色（非 KAM）→ 转至 life-sciences-fieldsalesrep-coordinate；停止。
• 与 LSC 设置无关（在开始时或运行中）→ 不要尝试处理；告知用户你未能理解，并说明你可以提供的帮助（LSC KAM 端到端完整设置，或独立的 life-sciences-prerequisites-validate / life-sciences-territory-configure）；停止。
• 拥有独立技能的单个阶段——前提条件（1）或区域配置（3）→ 转至对应技能；停止。
• 没有独立技能的单个阶段——配置部署（2）、参与者角色/冲刺（4）、数据和计划模板（5）、用户配置（6）→ 说明这些操作只能在完整流程中运行；停止。除非用户随后明确提出请求，否则不要启动完整流程。

只有收到 KAM 端到端完整设置请求时才继续：按顺序运行完整流程并执行各项门槛，由子技能/参考文件负责各阶段的工作。

---

必需输入

• 目标组织：要部署到的组织——由用户从已连接的组织中选择，或通过新认证的组织（阶段 0）指定。绝不能默默假设默认组织；任何阶段运行前，用户都必须确认或选择组织。

---

执行顺序（必须遵循）

术语： 阶段 = 6 个工作单元之一，每个单元委派给子技能/参考文件；阶段组 = 阶段内的命名分组；步骤 = 阶段组内的原子操作。

按以下顺序运行，每个阶段都必须通过上一阶段的门槛（依赖关系图见 references/orchestration-flow.md）：

#	阶段	运行内容	门槛（必须通过才能继续）	输出
—	设置：下载 .lsc-starter-config/LSStarterConfig	—	文件夹存在（必须满足——否则立即停止）	CWD 中的共享源文件夹
1	前提条件验证	life-sciences-prerequisites-validate 技能	所有前提条件均为 PASS	确认组织已准备就绪
2	Starter 配置部署	references/stage-2-starter-config-overview.md	13 个部署步骤 + KAM 配置记录均成功	LSC Custom Profile + KAM/Sprint 设置
3	区域配置	life-sciences-territory-configure 技能	区域模型已激活 + L3 区域	三级区域 ID + 名称
4	参与者角色与冲刺	references/stage-4-participant-role-and-sprint.md	参与者角色 + 冲刺已创建	角色 + 冲刺 ID
5	KAM 数据与计划模板	references/stage-5-data-and-plan-templates-overview.md	已创建客户/HCP/产品/区域数据 + 目标、模板（最终版）、项目和分配已创建 + 目标/模板/PATI 已共享到末级区域	客户 + 产品主数据 + 已发布的 ActionPlanTemplate
6	KAM 用户配置	references/stage-6-user-provisioning-overview.md	用户已创建，已分配权限集和区域；已生成元数据缓存	KAM 用户名

---

工作流

阶段 0 — 选择组织（强制，首先运行）

每次都要确定要使用哪个组织 — 绝不能默默沿用默认组织。

1. 使用 sf org list --json 列出已连接的组织，然后将已通过身份验证（未过期）的组织以编号列表呈现（别名、用户名、组织类型、默认标记），并提供选项 N，用于登录新组织。
2. 请用户选择一个编号或 N。
3. 处理选择：
   • 现有组织 → 将其用户名/别名记录为目标组织。
   • 新组织（N） → 询问登录 URL（https://login.salesforce.com、https://test.salesforce.com 或 My Domain URL）和别名，然后自行运行登录命令：sf org login web --instance-url <url> --alias <alias> --set-default。不要让用户运行该命令 — 直接执行。该命令会在用户的计算机上打开浏览器，供其交互式完成登录；随后命令会返回。完成后，重新运行 sf org list --json 进行确认。
4. 向用户确认目标组织，并将其存储在 OrchestrationState.targetOrg 中。

如果 sf org list 未返回任何已通过身份验证的组织，直接进入新组织登录流程（选项 N）。

阶段 1 — 介绍与确认

1. 向用户介绍工作流 — 显示标题“Life Sciences Cloud — Full KAM Setup Workflow”、目标组织，以及按顺序排列的 6 个阶段，并为每个阶段提供一行摘要：(1) 验证先决条件；(2) 部署入门配置（对象、配置文件、配置记录，包括 KAM 和 Sprint 设置、布局、flexipages）；(3) 配置区域；(4) 创建参与者角色和 Sprint；(5) 创建 KAM 数据和计划模板（账户、提供商、产品、区域数据，以及目标、任务、度量指标、已发布的行动计划模板）；(6) 配置 KAM 用户（配置文件/权限集/区域，以及移动端元数据缓存）。

2. 请求确认：“准备开始完整的 LSC KAM 设置了吗？（yes/no）”

3. 下载共享源文件夹的全新副本（强制 — 硬性门槛，必须在任何阶段开始前完成）。 阶段 2（元数据和配置记录）和阶段 5（Data CSV）会从 .lsc-starter-config/LSStarterConfig/ 读取内容；这两个阶段都不会下载或删除该文件夹 — 编排器负责在此处下载一个全新副本，并在阶段 9 删除一次。始终重新拉取 — 绝不复用现有文件夹（过期副本可能导致跳过新添加的组件）。先删除任何已存在的 .lsc-starter-config，然后通过稀疏检出全新获取子目录：

   rm -rf .lsc-starter-config lsstarter-tmp
   git clone --no-checkout --depth 1 --filter=blob:none \
     https://github.com/SalesforceLabs/LSStarterConfig.git lsstarter-tmp
   cd lsstarter-tmp && git sparse-checkout init --cone \
     && git sparse-checkout set Codey/LSStarterConfig && git checkout && cd ..
   mv lsstarter-tmp/Codey ./.lsc-starter-config && rm -rf lsstarter-tmp
   

   .lsc-starter-config/LSStarterConfig/ 自带 sfdx-project.json（指定 sourceApiVersion: 65.0）— 部署步骤必须在该目录内运行。

4. 下载门槛 — 继续前先验证。 确认 .lsc-starter-config/LSStarterConfig/sfdx-project.json 和 .lsc-starter-config/LSStarterConfig/Data/ 均存在（例如 ls .lsc-starter-config/LSStarterConfig/sfdx-project.json .lsc-starter-config/LSStarterConfig/Data）。

   • 如果存在 → 将 sourceFolderDownloaded: true 设为真，并继续阶段 2。
   • 如果缺失/下载失败 → 停止。不得继续任何阶段 — 每个阶段都依赖此文件夹。报告失败情况（可能原因：没有网络/GitHub 无法访问、git 版本低于 2.25，或磁盘/权限问题），将 sourceFolderDownloaded: false 设为假，且不得继续。修复问题后重新运行，或手动将文件夹下载到当前工作目录。

阶段 2 — 执行阶段 1：先决条件验证

5. 运行先决条件验证，并严格按照 life-sciences-prerequisites-validate 技能的工作流执行。

6. 门槛检查：如果所有先决条件均通过 → 继续阶段 2。如果任何一项未通过 → 停止，展示失败表格，并询问：“仍要继续（跳过未通过的先决条件），还是先停止并修复？”选择停止 → 结束工作流。选择继续 → 发出警告，说明后续阶段可能会失败，然后继续。

阶段 3 — 执行阶段 2：部署入门配置

7. 运行入门配置部署，严格遵循 references/stage-2-starter-config-overview.md（全部 13 个部署步骤，以及 KAM/Sprint 配置记录编辑）；按其中指示阅读相应的参考文件。KAM 适配仅部署与 KAM 相关的布局（4 个）和 flexipage（6 个）——全部自动部署，不提示选择；部署前先与管理员确认 StandardValueSet 选项列表值（分为三个业务场景组），然后将确认的值写入 KAMSettings_OrgLevel 和 SprintSettings_OrgLevel 配置记录。

8. 门禁检查：验证 LSC 自定义配置文件是否存在：

   sf data query --query "SELECT Id, Name FROM Profile WHERE Name = 'LSC Custom Profile'" --target-org <org> --json
   

   • 如果配置文件存在 → 继续进入阶段 3。如果未找到 → 停止并报告部署失败。

阶段 4 — 执行阶段 3：区域配置

9. 运行区域配置，严格遵循 life-sciences-territory-configure 技能工作流。如果已存在启用的区域模型，则使用该模型并展示层级，而不是创建新模型。

10. 门禁检查：验证区域模型处于 Active 状态，且存在第 3 级区域：

    sf data query --query "SELECT Id, Name, DeveloperName, Territory2Model.State FROM Territory2 WHERE ParentTerritory2.ParentTerritory2Id != null AND Territory2Model.State = 'Active'" --target-org <org> --json
    

    • 如果找到 → 记录第 3 级区域的 ID + 名称（OrchestrationState.territoryId），并告知用户，此叶级区域将作为单一区域，在阶段 5（ProductTerritoryAvailability）和阶段 6（管理员与 KAM 用户的 UserTerritory2Association）中重复使用。继续进入阶段 4。
    • 如果未找到 → 停止并报告问题。

阶段 5 — 执行阶段 4：参与者角色与 Sprint

11. 创建参与者角色和 Sprint，严格遵循 references/stage-4-participant-role-and-sprint.md。仅与管理员确认 MasterLabel/Name 字段；其他所有字段均自动推导并展示以供确认。

12. 门禁检查：验证 ParticipantRole（DeveloperName = 'Rep_Execution_Specialist'、IsActive = true）和 Sprint（状态为 Not Started）均存在。若缺少任一项 → 停止并报告。

第 6 阶段 — 执行第 5 阶段：KAM 数据和计划模板

这两部分均以管理员身份，按顺序，根据同一份参考文档 references/stage-5-data-and-plan-templates-overview.md 执行（A 部分 = 数据，B 部分 = 计划模板）。

13. 创建 KAM 数据（A 部分），严格遵循参考文档。传入第 3 阶段的 3 级辖区。根据数据 CSV 创建：Account、HealthcareProvider、ObjectTerritory2Association、ProviderAcctTerritoryInfo、Product2、LifeSciMarketableProduct、ContactPointAddress、ProductTerritoryAvailability。

14. A 部分门槛检查：验证 Account、LifeSciMarketableProduct 和 ProductTerritoryAvailability（位于第 3 阶段的辖区）均已创建；记录 LifeSciMarketableProduct ID（B 部分需要使用）。如有任何一项缺失 → 停止。

15. 创建目标、任务、衡量指标和行动计划模板（B 部分），严格遵循同一份参考文档（保持管理员登录状态）。创建 2 条 GoalDefinition 记录、一个 GoalDefinitionProduct、一个 ActionPlanTemplate（+ 自动创建 ActionPlanTemplateVersion）、3 条 ActionPlanTemplateItem 记录，发布模板（状态 → Final），创建一个 ActionPlanTemplateAssignment，并将 2 条 GoalDefinition 记录、ActionPlanTemplate 以及两条 ProviderAcctTerritoryInfo 记录共享给第 3 阶段叶级辖区的 Group（共 5 次手动共享），以便 KAM 用户通过辖区访问这些记录。仅由管理员确认记录名称。

16. B 部分门槛检查：验证模板已发布（存在 Final 状态的 ActionPlanTemplateVersion）、存在 ActionPlanTemplateAssignment，且叶级辖区的共享已创建（2 条 GoalDefinitionShare + 1 条 ActionPlanTemplateShare + 2 条 ProviderAcctTerritoryInfoShare，其 UserOrGroupId 为第 3 阶段辖区的 Group）。如未满足 → 停止。

第 7 阶段 — 执行第 6 阶段：配置 KAM 用户

17. 配置 KAM 用户，严格遵循 references/stage-6-user-provisioning-overview.md。传入第 3 阶段的 3 级辖区。创建一个用户名包含 kam 的用户，分配权限集 Health Cloud Starter、Life Sciences Key Account Management、Life Sciences Field Sales Representative 和 Life Sciences Core；将管理员和 KAM 用户都分配到 3 级辖区（向管理员确认——必须与第 5 阶段用于 ProductTerritoryAvailability 的辖区相同）；并通过 Connect API 生成移动端元数据缓存。

18. 门槛检查（停止门槛 — 第 6 阶段完整性）。不要将“用户已创建”视为通过。验证用户的 IsActive=true，使用 LSC Custom Profile，已关联到第 3 阶段辖区的 UserTerritory2Association，元数据缓存已达到 Status='Active'，且已分配的权限集数量为 4（{HealthCloudStarter, LifeSciencesKeyAccountManager, LifeSciencesFieldSalesRepresentative, LifeSciencesCore}）：

    sf data query --query "SELECT COUNT(Id) c FROM PermissionSetAssignment WHERE AssigneeId = '<newUserId>' AND PermissionSet.IsOwnedByProfile = false" --target-org <org> --json
    

    如果数量 < 2，或缺少辖区分配或元数据缓存，请在结束前重新执行缺失的部分。

阶段 8 — 最终摘要、清理与设备端验证

19. 显示完整的工作流摘要 —— 标题为“Life Sciences Cloud KAM Setup Complete”，然后按阶段分别列出实际值：（1）已确认前提条件；（2）已部署对象、配置文件和配置记录，已写入 KAM 与 Sprint 设置、布局和 flexipages，以及 28 个触发器处理程序；（3）Territory Model <model>（Active）+ Level-3 <territory>；（4）Participant Role Rep Execution Specialist + Sprint <name>；（5）Account + HCP、产品主数据、<territory> 上的 ProductTerritoryAvailability、2 个 Goal Definitions、ActionPlanTemplate <name>（Final）+ 3 个项目 + 分配，以及共享到 Territory <territory> 的目标、模板和 2 个 PATI；（6）用户 <name>（<username>），使用 LSC Custom Profile，拥有权限集 Health Cloud Starter + Life Sciences Key Account Management + Life Sciences Field Sales Representative + Life Sciences Core，位于 Territory <territory>（管理员 + KAM），并已生成移动端元数据缓存。最后显示：“The org is ready for Life Sciences Cloud key account management workflows.”

20. 清理 — 仅删除一次共享源文件夹。 最终摘要显示后（全部 6 个阶段均已完成），在 CWD 中运行：

    rm -rf .lsc-starter-config
    

    静默执行 —— 不要打印清理提示，也不要提及删除操作。如果工作流因失败而停止，且用户可能会恢复执行，则跳过 —— 保留该文件夹，以便恢复的阶段仍可读取其中内容。这是整个流程中唯一一次删除；子技能绝不会删除它。

21. 显示设备端（iPad）验证脚本并等待确认。 元数据缓存的 Status='Active' 且已显示摘要后，逐字显示 references/stage-6-ipad-validation-script.md 中的脚本（登录时使用阶段 6 KAM 用户的凭据），然后等待用户确认设备端步骤已成功完成。收到确认后，设置即告完成。

---

状态跟踪

维护整体编排状态：

OrchestrationState = {
  targetOrg: string,
  sourceFolderDownloaded: boolean,   // downloaded in Phase 1, deleted in Phase 9
  territoryId?: string, territoryName?: string,   // captured in Stage 3, reused in Stages 5 & 6
  stages: [
    { name: "Prerequisites",       status: "pending|running|passed|failed|skipped" },
    { name: "StarterConfig",       status: "pending|running|passed|failed" },
    { name: "TerritorySetup",      status: "pending|running|passed|failed", territoryId?: string, territoryName?: string },
    { name: "ParticipantSprint",   status: "pending|running|passed|failed", roleId?: string, sprintId?: string },
    { name: "DataAndPlanTemplates",status: "pending|running|passed|failed", accountId?: string, marketableProductId?: string, templateVersionId?: string },
    { name: "UserProvisioning",    status: "pending|running|passed|failed", userId?: string, username?: string }
  ]
}

---

幂等阶段转换与流程中途变更

阶段不可重入。执行任何阶段之前，先检查其 status：running → 回复“阶段 N 已在进行中”并不采取任何操作；passed → 询问是否明确确认要重新运行；failed → 重新运行（恢复）；pending → 继续执行。执行开始时（而非收到用户输入时）将状态设为 running，以避免意外的重复确认导致同一阶段运行两次。

如果用户在后续阶段正在进行或等待执行时，要求更改较早阶段的输入，先进行影响评估：确认已收到请求但暂不应用更改，指出受影响和不受影响的阶段，提供选项（重新运行受影响的阶段／仅向后续阶段应用／取消），并等待用户决定。提示破坏性变更风险（已激活的 Territory Model 无法删除；现有用户、记录或已发布模板会保留）。

完整的行为矩阵、影响评估模板、各类变更的影响映射以及破坏性变更警告见 references/state-machine-and-changes.md。

---

规则 / 约束

• 组织：先运行阶段 0 选择组织；切勿默默复用默认组织。
• 共享文件夹：仅下载一次 .lsc-starter-config/LSStarterConfig（阶段 1 的硬性门槛），并仅删除一次（阶段 9）；子技能不得触碰它——阶段 2 和 5 会读取它，因此缺少该文件会导致后续流程失败。
• 顺序：严格按 1→6 执行各阶段；每个阶段都必须以前一阶段成功为前提；捕获每个阶段的输出（ID、名称）供后续阶段使用。
• 辖区不变性：阶段 5（ProductTerritoryAvailability）和阶段 6（用户对齐）必须复用同一个阶段 3 的三级辖区（OrchestrationState.territoryId），否则 KAM 用户看不到数据。
• 确认：仅确认每个阶段标记为可由管理员确认的字段；其余字段自动推导并展示以供确认。
• 幂等性：未经确认，切勿重新执行状态为 running / passed 的阶段（执行开始时设为 running）；应用流程中途的变更前，先评估影响。

---

注意事项

问题	解决方案
阶段 1 中源文件下载失败	立即停止——不要运行任何阶段。修复原因，或将 .lsc-starter-config/LSStarterConfig 手动下载到当前工作目录，然后重新运行
找不到已连接的组织	在阶段 0 直接使用全新组织登录（sf org login web）
之前的运行已生成相关项	子技能 / 参考资料均具备幂等性 / 安全更新插入；先查询确认，然后跳过或重新运行
阶段被重新触发，或流程中途的输入发生变化	参见 references/state-machine-and-changes.md

---

恢复 / 部分重新运行

如果用户可能已完成某些阶段，询问具体是哪些，然后通过查询组织验证每个声称已完成的阶段（1 = 询问；2 = LSC Custom Profile；3 = 活跃模型 + L3 辖区；4 = ParticipantRole + Sprint；5 = Account + ProductTerritoryAvailability + Final 版本 + 分配；6 = kam 用户 + 权限集 + 辖区）。跳过已验证的阶段，并从第一个未完成的阶段继续。各阶段的确切查询：references/orchestration-flow.md → 恢复逻辑。

---

参考文件索引

文件	阅读时机
references/orchestration-flow.md	开始时——依赖关系图、门槛 + 恢复检测查询、耗时
references/state-machine-and-changes.md	阶段被重新触发或流程中途输入发生变化时
references/stage-2-starter-config-overview.md	阶段 2——13 步部署 + KAM / Sprint 配置记录（指向同级参考文件）
references/stage-4-participant-role-and-sprint.md	阶段 4——参与者角色 + Sprint
references/stage-5-data-and-plan-templates-overview.md	阶段 5——KAM 数据创建（A 部分，指向其数据参考文件）+ 目标、任务、衡量指标、行动计划模板（B 部分）
references/stage-6-user-provisioning-overview.md	阶段 6——用户配置 + 元数据缓存（指向同级参考文件）
references/stage-6-ipad-validation-script.md	最后一步——元数据缓存处于 Active 状态后显示的设备端（iPad）验证脚本