field-service-mobile-branding-configure

Field Service 移动端品牌定制

此技能会读取品牌来源，并生成一个包含 14 个字段的配色方案，将其应用到组织默认的 FieldServiceMobileSettings 记录（DeveloperName='Field_Service_Mobile_Settings'，IsDefault=true）。推导完成后、应用之前，必须先向用户确认 — 未经批准，绝不应用。

来源： 此技能由 Chad Barbour 编写，并从上游 Field Service 资源仓库镜像而来。 方法、颜色表和对比度检查均与上游版本一致 — 上游内容变更时，请从上游更新。

运行时约定： 此技能中的每次组织交互都是通过 Codey 运行时派发的单次 REST 调用（本地通过 dispatch 派发／在共享界面中通过托管的 Headless 360 MCP 派发）。此技能不依赖执行环境 — 不使用 sf CLI、Shell 脚本、本地 Python 或临时文件。颜色由 Agent 在运行过程中推导并验证，然后通过一次 sObject PATCH 写入。不要调用 Shell。

输入约定

以下任一种：

• 网站 URL — 使用 WebFetch 抓取并提取主要品牌颜色。
• 粘贴的品牌指南或文档 — 解析其中的十六进制代码和命名颜色。
• 直接提供的十六进制代码 — 按原样接受。
• 颜色描述（例如“我们是一家红白配色的公司”）— 继续操作前，请要求用户至少提供一个具体的十六进制代码或 URL。

四种输入情况（A–D）的详细说明，请参阅 reference/derivation-methodology.md。

输出

通过单次 sObject PATCH（PATCH /services/data/vXX.0/sobjects/FieldServiceMobileSettings/{id}），将包含 14 个字段的配色方案写入组织默认的 FieldServiceMobileSettings 记录。元数据缓存刷新后，设备上会显示颜色变更（默认：7 天；可在应用设置中强制刷新）。

工作流

1. 确认目标组织

抓取品牌来源之前，先通过轻量级身份验证探测，确认组织可访问 — 派发 SELECT Id FROM Organization LIMIT 1（GET /services/data/vXX.0/query）：

• 2xx，且 totalSize=1 → 会话令牌有效；继续。
• 401/403 → 组织需要重新进行身份验证。告知用户并停止；不要继续应用。

然后询问：“要将此方案应用到哪个组织？”并等待用户明确确认后再继续。不要假定使用默认组织 — 即使用户在请求中提到了组织名称，也要明确确认，以免造成意外。（Codey 运行时会解析已连接的组织；此技能不管理组织别名。）

2. 读取品牌来源

按照 reference/derivation-methodology.md 中的情况（A–D）进行处理。完成此步骤后，应得到两个基准颜色：

• 主要品牌颜色 — 用于非交互界面和导航栏。
• 次要／交互颜色 — 用于按钮、链接和 FAB。

3. 推导完整的 14 字段配色方案

按照 reference/derivation-methodology.md 中的推导规则，以及 reference/color-fields.md 中的字段语义进行推导。

在内存中将配色方案保存为一个扁平对象，其键与 14 个 FieldServiceMobileSettings 颜色字段相符。使用 examples/salesforce-default-scheme.json 作为模板。继续之前，请自行检查 14 个字段是否齐全，且每个值都符合 ^#[0-9A-Fa-f]{6}$（6 位十六进制数，以 # 开头 — 3 位简写和缺少 # 均无效）；不符合的值必须先修正，再提交给用户确认。

4. 验证对比度（浅色 + 深色模式）

对 reference/contrast-validation.md 中的每一组颜色对直接计算 WCAG AA 对比度——这是对你已掌握的十六进制值进行的确定性算术运算，无需使用外部工具。对于每组 #RRGGBB 颜色：

1. 规范化每个通道：r = R/255, g = G/255, b = B/255。
2. 线性化每个通道：c ≤ 0.03928 → c/12.92，否则为 ((c+0.055)/1.055)^2.4。
3. 相对亮度：L = 0.2126·r + 0.7152·g + 0.0722·b。
4. 对比度：(L_lighter + 0.05) / (L_darker + 0.05)。

评估 reference/contrast-validation.md 中全部 5 组浅色模式颜色对和全部 5 组深色模式颜色对；比值 ≥ 4.5:1 即为通过（WCAG AA，普通文本）。在第 5 步中，向用户指出所有未通过的颜色对，并提供建议的修复方案。请注意，品牌颜色在两种模式下固定不变，因此浅色模式方案通过，并不代表深色模式颜色对也会通过。

5. 展示方案并确认

向用户展示：

• 包含全部 14 个字段、十六进制值及其用途的 Brand & Navigation / Contrast Scale / Feedback Colors 表格。
• 第 4 步的浅色模式和深色模式对比度结果，并标记未通过的颜色对。
• 目标组织别名。

应用前请用户确认。为未通过的颜色对提出替代方案时，请使用 reference/contrast-validation.md 中建议的修复方案。

6. 应用到组织

仅在用户已批准第 5 步中的方案后才进行应用。需要进行三次 REST 调用：

1. 确认 FLS（可选，但建议执行）。 GET /services/data/vXX.0/sobjects/FieldServiceMobileSettings/describe，并确认 14 个颜色字段的 updateable: true。如果字段的 updateable: false（或 describe 结果经过筛选），这是运行用户缺少编辑权限的最早信号——尝试 PATCH 前先告知用户。

2. 解析组织默认记录。 使用 SELECT Id FROM FieldServiceMobileSettings WHERE DeveloperName = 'Field_Service_Mobile_Settings' AND IsDefault = true LIMIT 1 调用 GET /services/data/vXX.0/query。totalSize = 0 表示 Field Service Mobile 尚未配置——告知用户错误并停止（参见第 7 步）。否则，使用 records[0].Id。

3. 写入配色方案。 调用 PATCH /services/data/vXX.0/sobjects/FieldServiceMobileSettings/{id}，请求正文为包含 14 个颜色字段的扁平 JSON。采用合并语义——只写入正文中的字段。不要发送 IsDefault（该字段不可更新）。返回 204（无正文）即表示成功；随后 GET 该记录，确认值已写入。

7. 汇报结果

成功后，打印：

• FieldServiceMobileSettings 记录 ID。
• 更新时间戳。
• 提醒用户：元数据缓存默认有效期为 7 天；缓存刷新或技术人员从应用设置中手动强制刷新之前，设备上不会显示新配色方案。

如果应用失败是因为不存在 Field_Service_Mobile_Settings 记录，请告知用户错误并停止——该组织可能尚未设置 Field Service Mobile。请引导用户前往 Setup → Field Service Mobile Settings，创建默认记录，然后重试。

范围

自动生成：

• 根据一个或两个品牌主色，以及可选的品牌中性色和语义色，生成完整的 14 字段配色方案。
• Agent 直接计算全部 5 组浅色模式和 5 组深色模式颜色对的 WCAG AA 对比度并进行验证。
• 通过对组织默认的 FieldServiceMobileSettings 记录执行一次 sObject PATCH 来应用配色方案。

不在范围内：

• 启动画面、个人资料选项卡背景图片、推送通知图标——仅可通过 Setup 上传。
• 每个配置文件对应的 FieldServiceMobileSettings 记录（多配置组织）——此技能只针对单个 IsDefault=true 记录。如果组织中有多条记录，请先查询，并确认要更新哪个 DeveloperName。
• 调度员控制台 / 甘特图颜色（FSLQA__GanttPalette__c）。
• BrandingSet 元数据（Experience Cloud / Lightning 应用品牌设置——不会为 FS 移动应用设置主题）。

此技能中的文件

• reference/color-fields.md — 14 个字段、说明、默认值和 JSON 架构。
• reference/contrast-validation.md — 浅色和深色模式的配对定义、公式和常见修复方法。
• reference/derivation-methodology.md — 将品牌来源转换为完整配色方案的方法，以及边缘情况。
• examples/salesforce-default-scheme.json — 开箱即用的 Salesforce 紫蓝配色方案。
• examples/dark-blue-scheme.json — Salesforce 主题的深蓝配色方案（也用作对比度警告示例）。

对比度验证和配色方案推导由 Agent 内联执行（见步骤 3–4）；此技能中没有可执行脚本。组织写入操作通过 Codey 运行时分派为单次 REST 调用。

相关技能

• configure-field-service-mobile — 页面布局、权限和 FieldServiceSettings 开关。此技能将品牌设置交由它处理，而它将移动端结构配置交由此技能处理。
• fs-data-capture-form-deployer — 生成并部署 Data Capture Flow 元数据。