life-sciences-fieldsalesrep-coordinate

Life Sciences Cloud 端到端编排器

按严格顺序运行完整的 Life Sciences Cloud 设置工作流，共分为五个阶段，每个阶段都必须以前一阶段成功为前提。每个阶段都会委派给子技能或参考工作流，内部按阶段组和步骤组织（定义见下文的执行顺序）。

范围限制（首先评估）

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

• 如果请求与 LSC 设置无关（无论是在开始时还是运行过程中）→ 不要尝试处理。告诉用户你没有理解该请求，并说明你可以提供哪些帮助（完整的端到端 LSC 设置，或独立的 life-sciences-prerequisites-validate / life-sciences-territory-configure）；然后停止。
• 如果请求涉及有独立技能的阶段——前提条件（阶段 1）或区域配置（阶段 3）→ 引导用户使用 life-sciences-prerequisites-validate / life-sciences-territory-configure；然后停止。
• 如果请求涉及没有独立技能的阶段——配置部署（2）、用户配置（4）、拜访创建（5）→ 说明这些阶段只能作为完整流程的一部分运行，不能单独运行；然后停止。除非用户随后要求运行完整流程，否则不要启动完整流程。

仅当用户要求完整的端到端设置时才继续：按顺序编排完整流程（前提条件 → 配置部署 → 区域 → 用户配置 → 拜访创建），并设置关卡。每个阶段的实际工作都委派给子技能／参考文件。

---

必需输入

继续之前收集以下信息：

• 目标组织：要部署到的组织——由用户从已连接组织列表中选择，或使用新完成身份验证的组织（见阶段组 0）。绝不能默认使用某个组织；运行任何阶段前，都必须让用户确认或选择目标组织。

---

执行顺序（必须遵循）

术语： 阶段 = 5 个工作单元之一（1–5），每个都委派给子技能或参考工作流；阶段组 = 阶段内部的一组命名工作；步骤 = 阶段组内部的原子操作。因此，“阶段 2 › 阶段组 1 › 步骤 3”按从上到下的顺序执行。

按以下顺序运行，并且每个阶段都必须以前一阶段通过为前提（完整依赖关系图见 references/orchestration-flow.md）：

#	阶段	运行项	关卡（通过后才能继续）	输出
—	设置：下载 .lsc-starter-config/LSStarterConfig	—	文件夹已存在（必须满足——否则立即停止）	CWD 中的共享源文件夹
1	前提条件验证	life-sciences-prerequisites-validate 技能	所有前提条件均通过	已确认组织已就绪
2	Starter Config 部署	references/stage-2-starter-config-overview.md	13 个部署步骤全部成功	LSC Custom Profile 已创建
3	区域配置	life-sciences-territory-configure 技能	区域模型为 Active，且存在 L3 区域	Level-3 区域 ID + 名称
4	用户配置	references/stage-4-user-provisioning-overview.md	用户已创建，且已分配权限集 + 区域	代表用户名
5	示例拜访创建	references/stage-5-visit-creation-overview.md	拜访 + 支持记录已创建；元数据缓存已生成	—

---

工作流

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

在展示工作流之前，先确定要使用哪个组织。每次用户请求设置 Life Sciences Cloud 时都要执行此步骤，不要默默沿用当前默认组织。

1. 列出已连接的组织：

   sf org list --json
   

   解析结果，并以编号列表向用户展示已通过身份验证且未过期的组织——包括别名、用户名、组织类型（Dev Hub / Sandbox / Scratch / Production），以及默认标记（如有）：

   Connected Orgs — select the target for Life Sciences Cloud setup
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     1. ls-dev        [email protected]          (Dev Hub)   [default]
     2. ls-sandbox    [email protected]  (Sandbox)
     3. partial-scr   [email protected]       (Scratch)
   
     N. Log in to a fresh org (opens a browser to authenticate a new org)
   

2. 请用户选择：“您想使用哪个组织？请输入编号，或选择 N 登录新的组织。”

3. 处理选择：

   • 选择现有组织 → 将其用户名/别名设为后续所有步骤的目标组织。

   • 选择新组织（选项 N） → 以交互方式验证新组织：询问登录 URL（My Domain / 实例 URL，例如 https://mydomain.my.salesforce.com；生产环境使用 https://login.salesforce.com，沙盒使用 https://test.salesforce.com）和别名（例如 ls-setup），然后自行运行登录命令：

     sf org login web --instance-url <user-supplied-url> --alias <user-supplied-alias> --set-default
     

     不要让用户运行该命令——直接执行。命令会在用户的机器上打开浏览器，让用户以交互方式完成网页登录；完成后命令会返回。命令结束后，重新运行 sf org list --json 确认新组织，然后将其设为目标组织。

4. 向用户确认目标组织后再继续：“将 （）用作 Life Sciences Cloud 设置的目标组织。”将此信息存入 OrchestrationState.targetOrg。

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

阶段 1 — 介绍和确认

1. 向用户介绍工作流：

   Life Sciences Cloud — Full Setup Workflow
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   
   This will execute 5 stages in sequence. Each stage is internally
   organized into phases and steps.
   
   Stage 1: Validate Prerequisites
            Checks org settings, permissions, and features
   
   Stage 2: Deploy Starter Configuration
            Deploys objects, profiles, config records, layouts, flexipages
   
   Stage 3: Configure Territories
            Creates territory type, model, and 3-level hierarchy
   
   Stage 4: Provision Field Sales Rep User
            Creates user, assigns profile/permsets, assigns to territory
   
   Stage 5: Create Sample Visit
            Logs in as the rep, creates account/provider/visit records,
            generates the mobile metadata cache
   
   Target org: <org>
   

2. 征求确认："准备开始完整的 Life Sciences Cloud 设置吗？（yes/no）"

3. 重新下载共享源文件夹（强制 — 硬性关卡，必须在任何阶段开始前完成）。 阶段 2（Starter Config 部署 — 元数据 + 配置记录）和阶段 5（示例拜访创建 — 数据 CSV）都会从 .lsc-starter-config/LSStarterConfig/ 读取数据；这两个阶段都不会下载或删除该文件夹 — 编排器负责在此处全新下载一次，并在阶段 8 中删除一次。务必重新拉取 — 切勿复用现有文件夹（过期副本可能提供过时的 CSV，从而悄然破坏阶段 5“严格根据当前 CSV 创建”的规则，或跳过新添加的组件）。先删除任何已有的 .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）— 部署步骤（阶段 3）必须在该目录中运行。

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）。

   • 如果存在 → 在 OrchestrationState 中将 sourceFolderDownloaded: true，然后继续阶段 2。

   • 如果下载失败，或文件夹/内容缺失 → 停止。不要继续任何阶段 — 每个阶段都依赖此文件夹。报告失败并停止：

     STOP: Setup cannot start — source download failed
     
     Could not download .lsc-starter-config/LSStarterConfig from
     https://github.com/SalesforceLabs/LSStarterConfig.git
     Likely: no network / GitHub unreachable, git < 2.25 (no sparse-checkout),
     or insufficient disk space / write permission in the CWD.
     
     Mandatory prerequisite — no stage can run without it. Fix the cause and
     re-run, or download the folder manually into the CWD, then re-run.
     

     保持 sourceFolderDownloaded: false，不要推进工作流。

阶段 2 — 执行阶段 1：前提条件验证

5. 运行前提条件验证，并严格遵循 life-sciences-prerequisites-validate 技能工作流。

6. 关卡检查：查看结果。

   • 如果所有前提条件均通过 → 继续阶段 2
   • 如果任一前提条件未通过 → 停止并展示失败报告

   STOP: Stage 1 FAILED — Prerequisites not met
   
   <show the prerequisite failure table>
   
   Please resolve the failed prerequisites and re-run this workflow.
   

   询问用户："您想继续吗（跳过未通过的前提条件），还是先停止并修复问题？"

   • 如果用户选择停止 → 结束工作流
   • 如果用户选择继续 → 发出警告后继续，后续阶段可能会失败

阶段 3 — 执行阶段 2：Starter Config 部署

7. 运行 Starter Config 部署，并严格遵循 references/stage-2-starter-config-overview.md（按顺序完成全部 13 个步骤）；按指示阅读其参考文件。

8. 关卡检查：验证 LSC Custom Profile 是否存在：

   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，且三级区域是否存在：

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

• 如果找到三级区域且模型为 Active → 记录区域 ID 和名称，继续阶段 4
• 如果未找到 → 停止并报告问题

阶段 5 — 执行阶段 4：用户配置

11. 运行用户配置，严格按照 references/stage-4-user-provisioning-overview.md 执行；按其中的指示阅读其参考文件。传入阶段 3 中记录的区域信息。

12. 关卡检查：验证用户存在、配置文件正确、拥有全部 4 个权限集，并已分配区域。记录代表用户名——阶段 5 将以此用户身份登录。

    停止关卡（阶段 4 完整性）。 不要将“用户已创建”视为通过此关卡——验证全部四个方面，任何一项不符合要求都必须停止：

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

    权限集数量必须为 4（{LifeSciencesCore, LifeSciencesFieldSalesRepresentative, HealthCloudStarter, LifeSciencesKeyAccountManager}）；用户必须处于 LSC Custom Profile 配置文件下，且 IsActive=true；并且必须存在与三级区域的 UserTerritory2Association。如果权限集数量 < 4，或任何一项不符合要求，说明阶段 4 未完整完成——在进入阶段 5 之前，重新运行 references/stage-4-user-provisioning-overview.md 中缺失的部分（其阶段 4/5 停止关卡会涵盖这些要求）。代表缺少权限集时，下游访问创建会静默失败，并产生令人困惑的权限错误。

阶段 6 — 执行阶段 5：创建示例访问

13. 运行访问创建，严格按照 references/stage-5-visit-creation-overview.md 执行；按其中的指示阅读其参考文件。传入阶段 4 中记录的代表用户名。此阶段将：

    • 以代表用户身份登录（sf org login web），并创建客户、医疗保健提供者和访问记录（归代表所有），以及区域关联和产品主数据（归管理员所有）。
    • 通过 Connect API 生成移动元数据缓存（归管理员所有）。

    此阶段使用两种身份——代表用户（来自阶段 4）用于访问记录，管理员用于产品主数据和元数据缓存生成。严格遵循子技能中代表/管理员的职责划分。

14. 关卡检查：验证至少创建了一条 Visit 记录：

    sf data query --query "SELECT Id, Name, AccountId FROM Visit ORDER BY CreatedDate DESC LIMIT 1" --target-org <org> --json
    

    • 如果存在 Visit → 继续查看最终摘要
    • 如果未找到 Visit → 停止并报告访问创建失败

阶段 7 — 最终摘要

15. 显示完整的工作流摘要——标题为“Life Sciences Cloud 设置完成”，后跟每个阶段的一个区块（替换为运行中的实际值）：

    • 阶段 1：确认所有组织前置条件。
    • 阶段 2：部署对象/配置文件/配置记录，部署 <N> 个布局 + <N> 个 flexipage，激活 28 个触发器处理程序。
    • 阶段 3：Territory Model <model name>（Active）；三级 Territory <territory name>。
    • 阶段 4：用户 <firstName> <lastName>（<username>）；配置文件 LSC Custom Profile；权限集 Life Sciences Core、Life Sciences Field Sales Representative、Health Cloud Starter、Life Sciences Key Account Management；Territory <territory name>；管理员也已分配到该区域。
    • 阶段 5：已创建 Account + Healthcare Provider；Visit <name>（Territory <territory name>）；产品详情/讨论记录；已生成移动元数据缓存（Connect API）。

    结尾写：“组织已准备就绪，可用于 Life Sciences Cloud 外勤销售工作流。”

阶段 8 — 清理（仅删除一次共享源文件夹）

16. 最终摘要完成后（全部 5 个阶段均已完成），删除在阶段 1 中下载的 .lsc-starter-config 文件夹，以保持工作目录整洁。从 CWD（.lsc-starter-config/ 的父目录）运行：

    rm -rf .lsc-starter-config
    

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

---

状态跟踪

维护整体编排状态：

OrchestrationState = {
  targetOrg: string,
  sourceFolderDownloaded: boolean,   // .lsc-starter-config/LSStarterConfig downloaded in Phase 1, deleted in Phase 8
  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: "UserProvisioning", status: "pending|running|passed|failed", userId?: string, username?: string },
    { name: "VisitCreation", status: "pending|running|passed|failed", visitId?: string }
  ]
}

---

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

阶段不可重入。执行任何阶段前，检查其在 OrchestrationState 中的 status：running → 回复“阶段 N 已在进行中”并不采取任何操作；passed → 请求用户明确确认后再重新运行；failed → 重新运行（有意恢复）；pending → 继续执行。执行开始时（而非用户输入时）将状态转换为 running，以免意外的重复确认导致阶段运行两次。

如果用户在后续阶段正在进行或尚未开始时，要求更改较早阶段的输入，则先进行影响评估：确认收到请求但暂不应用，指出受影响和不受影响的阶段，提供选项（重新运行受影响的阶段／仅在后续阶段应用／取消），并等待用户决定。说明破坏性变更警告（已激活的区域模型无法删除；现有用户和记录会保留）。

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

---

规则／约束

约束	原因
始终先运行阶段 0 选择组织；列出已连接的组织，并让用户选择其中一个或登录到新组织	用户必须明确选择目标组织；绝不默默沿用默认组织
只下载一次 .lsc-starter-config/LSStarterConfig（阶段 1，强制硬性门槛），并只删除一次（阶段 8）；子技能绝不下载或删除它	两个子技能都从共享文件夹读取内容；不提供该文件夹就会导致后续步骤必然失败
严格按 1→5 的顺序执行各阶段，并以之前阶段成功作为门槛	每个阶段都依赖前面阶段的输出；这样可以避免故障连锁发生
绝不跳过阶段 2 或阶段 3，也绝不在阶段 5 之前跳过阶段 4	用户配置依赖个人资料和区域；访问创建会以阶段 4 的销售代表身份登录
严格遵循各子技能的工作流；记录输出（ID、名称）供后续阶段使用	子技能有各自的确认步骤；这样可以避免重复查询
未经明确确认，绝不重新执行状态为 running／passed 的阶段；在执行开始时（而非用户输入时）将状态转换为 running	避免重复的“继续”消息导致竞态，确保幂等性
应用流程中变更前先进行影响评估	用户必须在确认变更前了解可能失效或需要重做的内容

---

注意事项

问题	解决方案
第 1 阶段下载源文件失败（网络/git/磁盘问题）	立即停止——不要运行任何阶段。报告失败（参见第 1 阶段下载关卡）；解决问题，或手动将 .lsc-starter-config/LSStarterConfig 下载到 CWD，然后重新运行
未找到已连接的组织	sf org list 未返回任何结果——直接在第 0 阶段使用 sf org login web 登录新组织
登录新组织/销售代表账号需要浏览器	自行运行 sf org login web（第 0 阶段组织身份验证、第 5 阶段销售代表登录）——不要让用户来操作。该命令会在用户的计算机上打开浏览器；用户在那里完成网页登录后，命令便会返回
上次运行留下了产物（配置文件、区域、用户、配置）	子技能支持幂等操作/安全更新，并会检测现有记录——查询组织以确认，然后安全地跳过或重新运行
创建访问记录时使用两个身份（销售代表 + 管理员）	产品主数据和元数据缓存归管理员所有；遵循子技能的销售代表/管理员分工
阶段被重新触发，或用户在流程中更改了较早阶段的输入	参见 references/state-machine-and-changes.md 中的转换矩阵和影响评估

---

恢复 / 部分重新运行

如果用户可能已完成某些阶段（例如在之前的会话中），询问用户完成了哪些阶段，然后通过查询组织，逐一验证每个声称已完成的阶段（阶段 1 = 询问；阶段 2 = LSC Custom Profile；阶段 3 = 活跃模型 + L3 区域；阶段 4 = 配置了正确配置文件/权限集的用户；阶段 5 = 一条 Visit 记录）。跳过已验证的阶段，从第一个未完成的阶段继续。各阶段的具体检测查询见 references/orchestration-flow.md → 恢复逻辑。

---

输出要求

交付内容：

• 下载一次（第 1 阶段）并移除一次（第 8 阶段）.lsc-starter-config/LSStarterConfig 文件夹——这两项操作均静默完成；不在最终摘要中报告
• 成功执行全部 5 个阶段（或跳过的阶段已获用户确认）
• 完整总结创建/配置的内容
• 组织已准备好用于 Life Sciences Cloud 一线销售工作流

---

参考文件索引

文件	阅读时机
references/orchestration-flow.md	开始时——依赖关系图、各阶段关卡验证查询、恢复检测查询和时间预期
references/state-machine-and-changes.md	阶段被重新触发或用户在流程中更改了较早阶段的输入时——完整的转换行为矩阵、影响评估模板及映射，以及破坏性变更警告
references/stage-2-starter-config-overview.md	第 2 阶段（第 3 步）期间——完整的 13 步 Starter Config 部署工作流；其中会按需指向同级参考文件
references/stage-4-user-provisioning-overview.md	第 4 阶段（第 5 步）期间——完整的一线销售代表用户配置工作流；其中会按需指向同级参考文件
references/stage-5-visit-creation-overview.md	第 5 阶段（第 6 步）期间——完整的示例访问记录创建工作流；其中会按需指向同级参考文件