experience-lds-graphql-generate

构建 LDS GraphQL

生成经过架构验证的 Salesforce LDS GraphQL 查询（读取或变更），既可以作为独立查询，也可以通过 lightning/graphql 适配器接入 Lightning Web Component。此技能完整实现了以架构为事实来源的工作流。随附的两个 bash 脚本负责处理与组织相关的步骤——scripts/fetch-lds-graphql-schema.sh 用于架构内省，scripts/test-lds-graphql-query.sh 用于在实时组织中验证。

适用场景

• 用户希望创建、修改或集成 Salesforce GraphQL 查询（标准对象、自定义对象或设置对象）。
• 构建或更新通过 GraphQL 使用或变更 LDS 数据的 LWC。
• 在编写查询前内省组织的架构。
• 针对已连接的组织端到端验证生成的查询。

以下情况不要使用此技能：

• 基于 REST 的 UI API（请使用 LDS wire adapters；参见 experience-lds-best-practices-apply）。
• Apex callout 或自定义 GraphQL 端点——此技能仅适用于 LDS。
• 数据需求探索——请使用 experience-lds-data-requirements-generate。

前置条件

• 已连接的 Salesforce 组织（用户名或别名）。获取架构前，用户必须确认组织；绝不可自行假定。
• Shell 中可用的 Salesforce CLI / sf，用于获取架构。
• 以下选项的决定：
  • Namespace — uiapi（默认：标准对象 + 自定义对象）或 setup（权限集、配置文件等设置对象）。
  • 查询类型 — read（默认）或 mutation。
  • 输出格式 — standalone（原始 GraphQL + 变量）或 LWC integration（完整组件接线）。

核心规则

以下规则适用于每个步骤，是此技能强制执行的规则：

1. 按顺序执行 — 依次运行步骤 1→6。除非不满足触发条件，否则每个步骤都必须执行。
2. 失败时立即停止 — 步骤失败后，必须先完成修复，才能继续后续步骤。
3. 架构是唯一事实来源 — 每个实体名称、字段名称、字段类型和关系都必须来自 schema.graphql 内省结果。绝不可依赖常见的 Salesforce 知识（例如，不要假设 Owner 是 User——它可能是多态类型）。
4. 报告每个步骤 — 进入下一步前，使用提供的模板。
5. 错误报告 — 对错误进行分类；绝不可将工具的原始输出照搬到聊天中。

工作流

完整的规范工作流见 references/generation-guide.md。开始前请先阅读。读取查询的具体说明见 references/generation-query.md；变更的具体说明见 references/generation-mutation.md。

步骤 1 — 查询基本信息

收集并复述：

Query type:       [read | mutation]
Namespace:        [uiapi | setup]
Output format:    [standalone | LWC integration]

如有任何信息不明确，只询问一次并等待回复。

步骤 2 — 获取架构

1. 询问 usernameOrAlias。如果根据上下文推断出默认值，先告知用户并等待明确确认。
2. 使用已确认的别名运行 scripts/fetch-lds-graphql-schema.sh USERNAME_OR_ALIAS [OUTPUT_PATH] [API_VERSION]。脚本会将 SDL 写入 schema.graphql（或你指定的路径），确保架构不会进入聊天上下文。如果 OUTPUT_PATH 下已存在非空的 schema.graphql，脚本会提前退出（设置 LDS_FETCH_FORCE=1 可重新获取）。
3. 如果失败：立即停止，报告错误类别，请用户解决组织访问问题，然后重试。

使用架构文件

架构文件有 265,000 多行。绝不可读取整个文件——只能使用有针对性的 grep 调用。

• 对象类型：使用 -A 100 搜索 ^type <ObjectName> implements Record。
• 筛选器：使用 -A 50 搜索 ^input <ObjectName>_Filter。
• OrderBy：使用 -A 30 搜索 ^input <ObjectName>_OrderBy。
• 变更输入：使用 -A 50 搜索 ^input <ObjectName>(Create|Update)Input。

搜索预算：每个实体最多调用 4–5 次 grep。执行前先规划。

第 3 步 — 实体识别

1. 实体名称采用 PascalCase。
2. 如果未提供名称，从符合 ^type <Name> implements Record 的匹配项中提取候选名称。
3. 如果仍有未确定的实体，请询问用户并等待。
4. 报告：

   Identified entities:
   - EntityName (Field1, Field2, ...)
   Unknown entities:
   - <textual name>
   Step 3 status: SUCCESS | FAILED
   

5. 如果 Unknown entities 不为空 → 状态为 FAILED → 请求澄清 → 重新开始第 3 步。

第 4 步 — 迭代式实体内省

迭代限制：3 个周期（主实体 → 引用 → 子关系）。达到 3 个周期后强制停止。

每个周期：

1. 从列表中移除已完成内省的实体。
2. 使用上述架构模式搜索其余实体的字段。
3. 提取标准字段类型。
4. 识别引用字段（Owner: User）。不同实体上的同名字段可能具有不同类型 — 请分别检查每个实体。如果某字段对应多个实体类型，将其标记为多态，并计划使用内联片段（... on TypeA、... on TypeB）。
5. 识别子关系（Connection 类型，例如 Contacts: ContactConnection）。将新实体添加到未知列表。
6. 如果未知列表不为空且迭代次数 < 3，则循环。
7. 报告：

   [PASS|FAIL] EntityName
     - Standard fields: FieldName (type), ...
     - Reference fields: FieldName → TargetType, ...
     - Polymorphic fields: FieldName → [TypeA, TypeB], ...
     - Child relationships: RelationshipName → ChildType, ...
     - Unknown fields: FieldName, ...
   Introspection cycles used: N/3
   Step 4 status: SUCCESS | FAILED
   

8. 如果任何实体为 [FAIL] → 全局状态为 FAILED → 修复 → 从周期开始处继续。

第 5 步 — 读取查询生成（仅当查询类型为 read 时）

根据 references/generation-query.md 编写读取查询，并使用内省数据、实体列表、字段类型、输出格式和 usernameOrAlias。

应用 references/generation-query.md 中的规则 — 涵盖：

• 查询根节点 / 命名空间选择（uiapi.query 与 setup.query）。
• 字段选择规范（仅请求实际需要的字段 — 每个字段都会产生计费扫描）。
• 筛选运算符（eq、ne、in、nin、gt、gte、lt、lte、like、contains）。
• OrderBy（按字段指定方向）。
• 分页（first、after、last、before；edges.node、pageInfo）。
• 多态内联片段。
• 别名和变量占位符。
• 独立输出与 LWC 输出（来自 lightning/graphql 的 wire adapter、gql 标记模板，以及用于命令式刷新的 refreshGraphQL）。

如果工具返回错误，请对错误分类，并询问用户如何继续。

第 6 步 — Mutation 查询生成（仅当查询类型为 mutation 时）

根据 references/generation-mutation.md 编写 mutation — 涵盖：

• create、update、delete 操作结构。
• 输入类型（通过 input grep 模式发现的 <Entity>CreateInput、<Entity>UpdateInput）。
• 必填字段与可选字段（依据架构中的 ! 注解）。
• 仅使用 Id 更新引用字段。
• 返回选择 — mutation 后读取哪些内容以确保缓存一致性。
• 错误处理（record.errors[]）。
• LWC 集成：通过 lightning/graphql 中的 graphqlMutate 执行命令式 mutation。

第 7 步 — 测试查询

针对已确认的 usernameOrAlias 运行 scripts/test-lds-graphql-query.sh USERNAME_OR_ALIAS 'QUERY' '<VARIABLES_JSON>'，并向用户展示响应结构 / 示例。对错误进行分类，不逐字回显。

交叉引用

• 附带脚本：
  • scripts/fetch-lds-graphql-schema.sh — 通过针对组织 /services/data/vX/graphql 端点的 GraphQL 内省查询获取架构（LDS 不提供 /graphql/sdl 路由）；编写查询前，每个组织 / 会话调用一次。
  • scripts/test-lds-graphql-query.sh — 针对 /services/data/vX/graphql 对生成的查询进行基于组织的验证。
• 相关技能：
  • experience-lds-best-practices-apply — LDS 通用原则、缓存语义，以及 wire 与命令式方式的选择。
  • experience-lds-data-requirements-generate — 在本技能决定如何查询之前，先完成决定查询什么的准备工作。
  • experience-lwc-generate — 清晰地托管生成的 wire adapter。

示例

独立读取 — 最简示例

query Accounts($limit: Int = 10) {
  uiapi {
    query {
      Account(first: $limit) {
        edges {
          node {
            Id
            Name { value }
          }
        }
      }
    }
  }
}

LWC 集成 — 使用 wire 读取

import { LightningElement, wire } from 'lwc';
import { gql, graphql } from 'lightning/graphql';

export default class AccountList extends LightningElement {
    @wire(graphql, {
        query: gql`
            query Accounts($limit: Int = 10) {
                uiapi {
                    query {
                        Account(first: $limit) {
                            edges { node { Id Name { value } } }
                        }
                    }
                }
            }
        `,
        variables: '$variables'
    })
    accounts;

    variables = { limit: 10 };

    get records() {
        return this.accounts?.data?.uiapi?.query?.Account?.edges ?? [];
    }
}

验证

• 第 4 步之前，Step 3 status: SUCCESS；第 5/6 步之前，Step 4 status: SUCCESS。
• 生成的查询中的每个字段都出现在自省报告中（没有臆造字段）。
• 多态字段使用内联片段；非多态字段不使用。
• 对于变更操作，所有必需的输入字段（架构中的 !）都必须存在。
• scripts/test-lds-graphql-query.sh 执行后没有错误；或者在出现错误时，提供分类后的补救方案。
• 如果输出格式为 LWC integration，组件从 lightning/graphql 导入，使用 gql 标记模板，并通过 getter 暴露数据（而非直接在 HTML 中暴露）。