experience-lds-data-requirements-generate

生成 LDS 数据需求

运行三阶段分析师工作流——需求澄清、API 名称验证、API 推荐——让下游开发者无需猜测即可实现 Lightning Data Service（LDS）解决方案。

使用时机

• PRD、Figma 评论或用户需求提到了 Salesforce 数据，但对象、字段或操作不明确（“显示客户信息”“更新记录”“列出即将举行的演出”）。
• 为新的数据需求编写任何 @wire/Apex 代码之前，或将推荐结果交给下游实现工作流之前。
• 你接手了类似 // TODO: fetch related records 的待办事项，需要将其转化为明确的规格。

以下情况请勿使用此技能：

• 数据需求已完整明确（对象 API 名称、字段 API 名称、操作类型、范围）。
• 组件完全不涉及 Salesforce 数据（仅 UI、外部 REST、本地状态）。

前提条件

• 自然语言形式的需求（PRD 片段、用户需求或 TODO 评论）。
• 有权访问目标 org 的 Setup → Object Manager，以确认自定义对象/字段的 API 名称。
• 了解当前 GraphQL / UI API / Apex 优先级顺序（能通过 GraphQL 读取时，应优先考虑）。

知识库

• references/requirements-analysis.md — 需求分析模式框架。
• references/api-name-validation.md — 对象/字段 API 名称的精确模式。
• references/api-recommendation.md — GraphQL → UI API → Apex 决策框架。
• references/lds-expert.md — LDS 整体模式与陷阱。
• references/lds-data-consistency.md — 缓存与一致性保证。
• references/lds-referential-integrity.md — 父子记录与相关记录规则。

工作流

严格按顺序运行这三个步骤。除非调用方已确认某一步的输出，否则不得跳过。

步骤 1 — 解析数据需求（需求分析模式）

目标： 提取所有已知信息，并在继续之前明确所有不确定之处。

每次对话开头都使用：

“我已分析你的数据需求：‘’。以下是我的理解，以及需要你澄清的内容……”

应用 references/requirements-analysis.md 中的四项操作：

1. 操作类型 — 是读取、创建、更新还是删除？动词含义不明确时，立即提出澄清问题。通过以下问题确认：“我已将其确定为 操作。这样是否正确？”
2. 数据实体识别 — 标准对象（置信度高，可继续）、疑似自定义对象（询问：“这是自定义对象 <Term>__c 吗？准确的 API 名称是什么？”），或未知（询问 Object Manager 中的 API 名称）。
3. 字段规格 — 将通用表述（phone、address、name、status）映射为具体的 API 名称。如果有多个候选项，逐一列出并询问。
4. 范围与上下文 — 一条记录还是多条；由用户触发还是自动触发；预期数据量；实时还是按需。

步骤结束关卡。 汇总为：

Clear Requirements: [confirmed facts]
Need Clarification: [numbered questions from 1.1–1.4]

仅当所有问题都已回答且置信度 ≥90% 时，方可继续。

步骤 2 — 验证 Salesforce API 名称（精确模式）

目标： 在编写代码之前，确保每个对象和字段的 API 名称都 100% 准确。

应用 references/api-name-validation.md 中的验证框架：

• 标准对象 — Account、Contact、Lead、Opportunity、Case、User、Task、Event、Product2、Pricebook2、Order、OrderItem、Asset、Contract、Campaign 可立即通过。其他任何对象都需要验证。
• 自定义对象 — 切勿假定后缀为 __c。请询问：“这是 <Term>__c，还是其他自定义对象 API 名称？” 指引用户前往 Setup → Object Manager → → Details → API Name。
• 标准字段 — 使用参考文件中的表格映射含义不明确的引用。
• 自定义字段 — 必须确认后缀为 __c；区分大小写。

确认模板：

Object API Name: <OBJECT>
Field API Names: <FIELD_LIST>
Confidence Level: 100% validated

如果仍有任何不确定之处，请停止。列出尚待验证的问题，并提供 Setup 导航说明。不要进入步骤 3，也不要生成代码。

仅当调用方明确表示 API 名称已在上游验证，或需求完全不涉及记录时，才跳过此步骤。在步骤 4 的输出中记录跳过原因。

步骤 3 — 推荐 API（解决方案架构模式）

目标： 使用 references/api-recommendation.md 中的决策框架，选择合适的数据访问 API。

优先级顺序（不可更改）：

1. GraphQL wire adapter（lightning/graphql）——对于其能够处理的读取操作，这是首选。
2. UI API / LDS — CRUD 写入、元数据、布局、选项列表和简单读取。
3. Apex — 仅作为后备方案。

依次完成以下六个决策子步骤：

1. 操作类型（读取 / 写入 / 混合）。
2. UI API 对对象和字段的支持情况。
3. 关系复杂度（单对象或多对象、父级 / 子级）。
4. 查询复杂度（筛选、排序、分页、聚合）。
5. 性能与可扩展性（往返次数、负载大小）。
6. 特殊需求（元数据、原子事务、业务逻辑、更高权限）。

推荐规则：

• GraphQL：只读且对象受支持；多对象联接；分页 / 排序 / 筛选；聚合；减少往返次数。
• UI API：CRUD 写入、元数据（选项列表、布局、对象信息）、getRecordCreateDefaults + createRecord、列表视图。
• Apex：UI API 不支持相关对象 / 字段；多记录原子事务；自定义业务逻辑；系统上下文权限。

使用“展示推理过程”模板呈现结果——明确解释为什么不选 GraphQL / 为什么不选 UI API / 为什么不选 Apex。

交接：

• 推荐 GraphQL → 在步骤 4 的输出中记录查询结构（根对象、请求的字段、筛选条件）；后续由调用方编写实际的 lightning/graphql wire adapter。
• 推荐 UI API → 记录具体的 UI API adapter（getRecord、getRelatedListRecords、createRecord、updateRecord、getRecordCreateDefaults 等）以及任何布局 / 选项列表前置要求。
• 推荐 Apex → 在步骤 4 的输出中记录原因，并移交给项目既定的 Apex 工作流。

步骤 4 — 输出可用于 PRD 的规格说明

生成一个独立文本块，供调用方粘贴到 PRD 或组件文件头部：

## Data Requirement: <CLEAR_TITLE>

### Technical Specification
- Primary Object: <OBJECT_API_NAME>
- Required Fields: <FIELD_API_NAMES>
- Relationships: <RELATED_OBJECTS_OR_LOOKUPS_OR_NONE>
- Data Scope: <SINGLE_RECORD | MULTIPLE_RECORDS | QUERY_BASED>
- Access Pattern: <READ_ONLY | READ_WRITE | WRITE_ONLY>
- Trigger: <USER_ACTION | AUTO_ON_LOAD | REACTIVE>

### Implementation Details
- Recommended LDS API: <GRAPHQL | UI_API | APEX>
- Implementation Pattern: <WIRE | IMPERATIVE>
- Rationale: <WHY THIS API, NOT THE OTHERS>
- Next step: <author the GraphQL wire adapter | author the UI API adapter call | project's Apex workflow>

Few-Shot 示例

模糊需求	澄清问题
“获取联系人信息”	“具体需要哪些 Contact 字段？（Email、Phone、MailingAddress、Department，等等）”
“显示账户数据”	“需要哪些 Account 字段？是显示一条记录还是一个列表？”
“自定义健身房记录”	“这是自定义对象 Gym__c 吗？你要查找哪些具体字段？”
“更新记录”	“是哪个对象？哪些字段？哪条记录（运行时的 ID）？”
“所有客户信息”	“是 Account 还是 Contact？需要哪些字段？单条记录还是查询？”

验证清单

• 已将原始需求中的每个歧义术语解析为已确认的 API 名称。
• 已确认操作类型（R / C / U / D）。
• 已记录范围（单个还是多个）和触发方式（用户触发还是自动触发）。
• 已针对三个选项（GraphQL / UI API / Apex）说明 API 推荐理由。
• 已明确具体的后续操作——指定要接入的下游适配器（lightning/graphql、getRecord、createRecord 等），或项目中采用的 Apex 工作流。
• 如果跳过了步骤 2，已在输出中记录原因。
• 规范块可直接复制粘贴到 PRD 中。

交叉引用

• 技能：
  • 输出由 experience-lwc-generate 使用，用于将 @wire 适配器接入组件。
• 下游编写步骤（目前未绑定到技能）：
  • GraphQL 路径——调用方根据从目标组织中提取的架构编写 lightning/graphql wire 适配器。
  • UI API 路径——调用方接入推荐的 UI API 适配器（getRecord、createRecord 等）。