life-sciences-territory-configure

Life Sciences 区域设置

使用 sf CLI 为 Life Sciences Cloud 创建并激活区域类型、区域模型，以及三级区域层级。

范围

• 范围内：创建区域类型、区域模型和区域；激活区域模型
• 范围外：将用户分配到区域、创建区域分配规则、验证前置条件

无关请求

如果用户提出与此技能无关的请求（无论是在开始时还是执行过程中），请勿尝试处理。告知用户你没有理解该请求，然后说明你可以提供的帮助：设置 Life Sciences Cloud 区域（此技能）；如果相关，还可以引导用户使用 life-sciences-prerequisites-validate 检查前置条件，或使用 life-sciences-fieldsalesrep-coordinate 完成端到端设置。然后停止并等待。

---

必需输入

继续之前收集：

• 目标组织：要部署到的组织别名或用户名（通过 sf config get target-org 获取，或由用户指定）

---

工作流

阶段 1 — 显示默认名称并获取确认

1. 向用户显示将用于区域组件的默认名称。阅读 references/territory-metadata.md，获取准确的 XML 模板和默认名称。

以表格形式显示名称：

| Component | Default Name |
|-----------|-------------|
| Territory Type | Geographical |
| Territory Model | LSC Territory Model |
| Territory (Level 1 - Region) | RD - West 20D |
| Territory (Level 2 - District) | DM - San Francisco 20D02 |
| Territory (Level 3 - Territory) | TM - SPC - San Francisco North 20D02T11 |

2. 询问用户是否接受这些名称，或希望更改其中任何名称。逐一询问各个组件：

   • “您接受区域类型名称 'Geographical' 吗？还是希望更改？”
   • “您接受区域模型名称 'LSC Territory Model' 吗？还是希望更改？”
   • “您接受区域名称 'RD - West 20D' 吗？还是希望更改？”
   • “您接受区域名称 'DM - San Francisco 20D02' 吗？还是希望更改？”
   • “您接受区域名称 'TM - SPC - San Francisco North 20D02T11' 吗？还是希望更改？”

3. 如果用户希望更改名称，询问他们想使用的新名称。记录更新后的名称。

阶段 2 — 预览并确认

4. 显示完整预览，展示将要创建的各个组件的最终 XML，并使用已确认的名称。使用 references/territory-metadata.md 中的模板，并替换为用户提供的名称。

按以下格式显示预览：

=== Territory Type ===
Name: <confirmed name>
Priority: 1

=== Territory Model ===
Name: <confirmed model name>

=== Territory Hierarchy ===
Level 1 (Region): <confirmed region name>
  └── Level 2 (District): <confirmed district name>
        └── Level 3 (Territory): <confirmed territory name>

Access Levels (all territories):
- Account: Read
- Contact: Edit
- Case: None
- Opportunity: None

5. 请求最终确认：“准备好创建并部署这些区域组件了吗？（yes/no）”

如果用户回答 no，请返回阶段 1。

阶段 3 — 创建并部署

6. 创建临时 SFDX 项目结构以供部署。请阅读 references/territory-metadata.md，了解确切的文件结构和 XML 内容。

目录结构必须如下：

territory-deploy/
├── sfdx-project.json
└── force-app/
    └── main/
        └── default/
            └── territory2Models/
                ├── <ModelApiName>.territory2Model-meta.xml
                └── <ModelApiName>/
                    ├── territory2Types/
                    │   └── <TypeApiName>.territory2Type-meta.xml
                    └── territories/
                        ├── <Level1ApiName>.territory2-meta.xml
                        ├── <Level2ApiName>.territory2-meta.xml
                        └── <Level3ApiName>.territory2-meta.xml

7. 根据用户确认的显示名称生成 API 名称：

   • 移除特殊字符、空格和连字符
   • API 名称使用 PascalCase
   • Territory 类型的 API 名称根据类型显示名称生成
   • Territory 模型的 API 名称根据模型显示名称生成（移除空格）
   • Territory 的 API 名称根据 Territory 显示名称生成（移除空格、连字符和特殊字符）

8. 使用 references/territory-metadata.md 中的模板和已确认的名称编写元数据文件。

9. 使用以下命令部署元数据：

   sf project deploy start --source-dir territory-deploy/force-app --target-org <org>
   

10. 检查部署状态——如果失败，请显示错误并建议解决方法。

    停止关卡（组件数量）。 单个部署包必须包含完整层级：1 个 Territory2Type + 1 个 Territory2Model + 3 条 Territory2 记录（分别为一个 Region、一个 District 和一个 Territory）。确认部署结果报告组件失败数为 0，并在激活前验证 Territory 是否存在：

    sf data query --query "SELECT COUNT(Id) c FROM Territory2 WHERE Territory2Model.DeveloperName = '<ModelApiName>'" --target-org <org> --json
    

    数量必须为 3。父级引用失败（例如，District 在其 Region 之前部署）可能导致层级不完整——没有通往其 Region 的路径的第 3 级 Territory 会悄然破坏下游用户／访问记录的 Territory 分配。所有 3 个 Territory 均已存在且部署失败数为 0 之前，不要激活模型（阶段 4）。

阶段 4 — 激活 Territory 模型

11. 告知用户模型已部署为 Planning 状态，并询问用户是否要激活。请包含以下警告：

    注意： Territory 模型一旦激活，可以停用，但无法删除。是否要继续激活？

12. 如果用户确认激活，请先查询模型记录 ID，然后将其 State 更新为 'Activating'（而非 'Active'——平台会异步地从 Activating 转换为 Active）：

    # 查询模型 ID 和当前状态
    sf data query --query "SELECT Id, State FROM Territory2Model WHERE DeveloperName = '<ModelApiName>' LIMIT 1" --target-org <org> --json
    

    如果模型处于 Planning 状态，请更新它：

    sf data update record --sobject Territory2Model --record-id <ModelId> --values "State='Activating'" --target-org <org>
    

    有关完整的激活逻辑（包括错误处理），请参阅 references/territory-metadata.md。

13. 验证激活状态——平台会异步地从 Activating 转换为 Active。请查询以确认：

    sf data query --query "SELECT Id, DeveloperName, State FROM Territory2Model WHERE DeveloperName='<ModelApiName>'" --target-org <org>
    

    如果仍处于 Activating，请稍等片刻并重新查询，直到状态变为 Active。

14. 如果用户拒绝激活，请告知用户模型处于 Planning 状态，之后可在 Setup 中激活。

15. 报告成功——确认所有组件均已创建，并报告模型的当前状态（Planning、Activating 或 Active）。

---

规则 / 约束

约束	原因
每个级别恰好创建一个区域——一个 Level-1 区域、一个 Level-2 区域、一个 Level-3 区域（共 3 个区域）	技能生成一个具有代表性的层级分支，而不是填充完整的多子级树
创建前始终确认名称	用户可能希望自定义适合其组织的区域名称
部署前显示预览	用户应准确了解将要创建的内容
一起部署所有组件	区域层级存在依赖关系（父级引用）
激活前警告用户：模型一旦激活便无法删除	这是不可逆操作——用户必须明确同意
更新记录时将 State 设为 'Activating'（而非 'Active'）	平台会处理从 Activating → Active 的异步转换
使用 --record-id <ModelId> 或 --where "DeveloperName='<ModelApiName>'" 指定更新目标	两种形式都适用于 sf data update record；可按需选用
部署后清理临时目录	不要留下部署产物

---

注意事项

问题	解决方案
已存在同名区域模型	先查询；询问用户是否要使用其他名称
已存在区域类型	先检查；如果匹配，则重复使用
因找不到父级区域而导致部署失败	确保所有区域都在同一个部署包中
直接将 State 设为 'Active' 时出现 INVALID_STATUS 错误	始终将 State 设为 'Activating'——平台会异步将状态转换为 Active
更新后模型状态显示为 Activating	这是正常情况——激活是异步的。等待并重新查询，直到状态变为 Active
API 名称冲突	确保生成的 API 名称与现有元数据不冲突

---

输出要求

交付内容：

• 使用已确认名称创建的区域类型
• 使用已确认名称创建的区域模型
• 使用已确认名称创建的 3 级区域层级
• 已激活的区域模型（如果以编程方式激活失败，则提供手动激活步骤）
• 显示所有已创建组件及其状态的确认消息

---

参考文件索引

文件	何时阅读
references/territory-metadata.md	所有阶段——包含区域组件的 XML 模板、文件结构和默认值