requirements-gathering

需求收集

从任何来源收集并整理需求，生成标准化简报，供下游技能（schema-explorer、datasource-creator、report-creator）使用。

使用时机

• 创建报表之前（report-creator 会在第 1 阶段调用此技能）
• 创建数据源之前（当需求不明确时，datasource-creator 会调用此技能）
• 每当用户提供工作项 ID、模型图、规格说明或描述，并且你需要在开始构建之前提取结构化需求时

输出约定

无论来源是什么，都应生成包含以下章节的需求简报：

## Requirements Brief

**Title:** [name of the report/datasource/feature]
**Purpose:** [1-2 sentence summary]
**Source:** [work item #ID / user conversation / document / existing report]

### Data Requirements

#### Fields with Semantic Roles
For each field, identify WHAT it is and WHERE it belongs:

| Field | Semantic Role | Report Section / Usage |
|-------|--------------|----------------------|
| ownerName | Goods principal name | Shipper/Consignor header |
| accountName | Customer name | Consignee header |
| materialLookupCode | Product identifier | Line item grid |
| tareWeight | Packaging weight | Calculated: gross = raw + qty * tare |

#### Entity Keywords
[List of OData entity search terms derived from requirements]

### Layout Expectations
- **Report category:** [Label / Official Documentation / Work Detail / Inventory-Operations]
  - Labels: high visibility, scannable barcodes, tight margins
  - Official Documentation: branded, legally compliant, standard margins
  - Work Detail: key info only, minimal distractions
  - Inventory/Operations: data comparison tables (consider if an app component would serve better)
- **Page size:** [letter/legal/A4/custom]
- **Orientation:** [portrait/landscape]
- **Key sections:** [header, detail grid, footer, etc.]
- **Special elements:** [barcodes, logos, signatures, images]

### Business Rules
- [Calculated fields with formulas]
- [Conditional visibility rules]
- [Date null-guard requirements]
- [Filtering/exclusion rules]

### Parameters
- [Input parameters with types]

### Reference Materials
- [List of attachments, screenshots, documents consulted]

来源路由

DevOps 工作项

用户提供工作项 ID 或 URL 时：

1. 调用 devops-requirements 技能——它负责获取工作项、关联项、附件并提取信息
2. 增强输出，加入语义字段映射（见下文）
3. 将简报保存到制品目录

模型图或屏幕截图

用户提供图像（模型图、屏幕截图、PDF）时：

1. 读取所有可见元素——标签、列标题、数据值、区块边界、徽标、条形码
2. 将标签映射到数据字段——每个可见标签都隐含一个字段。“SHIPPER”不只是文本，它还是一个数据源（承运方实体是什么？）
3. 识别区块——页眉、地址区块、明细网格、页脚、签名
4. 在最终确定简报之前，就含义不明确的元素提出澄清问题

自然语言描述

用户在对话中描述所需内容时：

1. 将名词提取为候选实体——“客户送货地址” → Account、ShippingAddress
2. 将限定词提取为候选字段——“仓库电话号码” → Warehouse.Contact.Phone
3. 提出结构化问题以补全信息：
   • 这里要展示哪些数据？（实体 + 字段）
   • 谁会使用它？（决定布局：打印还是屏幕、页面尺寸）
   • 哪些筛选条件/参数会影响它？（输入参数）
   • 是否有计算或业务规则？（表达式）
   • 是否有类似的现有报表？（参考）
4. 提交简报草稿供确认，再继续后续工作

现有报表（.rdl 或 .rdlx-json）

用户提供现有报表文件时：

1. 对于 .rdlx-json：使用 dxs report inspect 提取结构、DataSets、字段名称和表达式
2. 对于 .rdl（SSRS）：扫描包含 SQL 的 <CommandText> 元素——SELECT 列以及 FROM/JOIN 表可映射到 OData 实体和字段
3. 根据元素名称及其在布局中的位置，将提取的字段映射到语义角色

文档或规格说明

用户提供文档（Word、PDF、Excel）时：

1. 提取字段列表——查找表格、SQL 查询、列定义
2. 提取布局草图——任何输出的可视化表示
3. 提取业务规则——公式、条件、筛选逻辑

语义字段映射

这是防止下游错误的关键步骤。从任何来源提取原始字段后，为每个字段分配一个语义角色——也就是它在领域语境中的含义。

如何分配角色：

1. 根据 SQL 字段名称：将前缀作为领域线索

   • owner* → 货物所有人 / 托运人（在 BOL 语境中）
   • account* → 客户 / 付款方
   • shipTo* → 交货目的地 / 收货人
   • warehouse* → 设施 / 3PL 位置
   • carrier* → 运输服务提供商
   • material* / lot* → 库存商品详情
   • order* → 订单级数据（参考编号、日期、备注）

2. 根据原型图标签：将视觉标签映射到数据实体

   • “发货人/托运人” → Owner 实体（不是 Account）
   • “收货方” → Account / Ship-To 实体
   • “承运人” → Carrier 实体
   • “运费账单编号” → 可能是 BOL，也可能是参考编号——请询问

3. 根据自然语言：将描述的概念映射到实体

   • “客户的地址” → Account.Address 或 ShipToContact.Address
   • “是谁发的货” → Owner（货物所有人，而不是承运人）

4. 存在歧义时：标记歧义并询问用户。不要猜测——错误的语义分配会导致数据源字段和报告布局都出错。

反模式

• 不带角色的扁平字段列表——列出字段却不进行语义映射，会导致下游技能猜测每个字段应放在哪里。始终分配角色。
• 跳过看似“显而易见”的字段——packUOM、tareWeight、vlDescription 可能不会出现在报告标题或主要列中，但它们仍是必需的。列出来源中的所有字段。
• 假设 SQL = OData——SQL 视图会预先扁平化联接数据。同样的数据在 OData 中可能需要多层 $expand 或关联数据源。在简报中注明复杂的联接路径。
• 使用通用法律文本——如果来源包含特定法律措辞（例如承运人责任条款），请逐字记录。不要用通用的标准条款替代。
• 忽略图像/签名——如果来源显示了徽标、签名或图像字段，请注明。这些内容需要特殊处理（嵌入式图像、数据库提供的图像或流程数据源）。