weaver-work-cli 0.1.24 → 0.1.26

package/skills/weaver-e10-builder/references/report/datasource-metadata-guide.md

@@ -0,0 +1,365 @@
+# 数据源元数据获取指南（DataSetAction 接口）
+
+> **冷启动禁止通读**：找表优先 `app-datasource-lookup-guide.md` + `e10-cli report find`。本文仅需全接口手册时再读。
+> 对应 Java 文件：`DataSetAction.java`
+> 统一前缀：`/api/{module}/{submodule}/ds` 或 `/api/{module}/ds`
+> 认证方式：受 `@WeaPermission(publicPermission = true)` 保护，需携带 E10 标准登录态（`ebbusinessid`、`eteamsid`、`Cookie`）。
+
+## 1. 用户指令到接口的路由规则
+
+| 用户意图 / 指令 | 路由接口 | 前置依赖 |
+| ---------------------------------------- | -------------------------------------------------- | ------------------------------------------ |
+| "列出某个数据源下的所有数据集（不分页）" | `GET /ds/list` | 需已知 `sourceType` 与 `groupId` |
+| "分页查询数据集列表" | `GET /ds/listByPage` | 需已知 `sourceType`、`groupId` |
+| "获取数据源分组树" | `GET /ds/group` | 需已知 `sourceType` |
+| "查看某数据集的字段列表" | `GET /ds/fields` | 需已知 `sourceId`、`sourceType` |
+| "下拉选项/枚举值取数" | `GET /ds/options` | 需已知字段 `fieldName`、所属数据集 `objId` |
+| "批量取多个字段的选项" | `GET /ds/optionsList` | 需字段集合 JSON |
+| "校验 where 条件/函数公式是否可执行" | `POST /ds/conditionCheck`、`GET /ds/checkFunction` | 需完整 SQL/条件 JSON |
+| "执行接口数据源的调用" | `GET /ds/callApi`、`GET /ds/getApiInfo` | 需 `queryDto`（含 queryType） |
+| "根据 URL 解析数据源配置" | `GET /ds/pareDataSourceInfo` | 需目标页面/报表 URL |
+| "获取 ESB 字段类型" | `GET /ds/queryForField`、`POST /ds/saveFieldsType` | 用于 ESB 动作流字段映射 |
+
+## 2. 典型业务场景组合调用
+
+### 场景 A：搭建 EB 报表时选择数据源 → 取字段 → 取选项
+
+这是报表搭建（能力一）中最核心的数据源获取流程。
+
+**分支（强制）**：
+
+| 是否已指定 appId / appName | 流程 |
+|----------------------------|------|
+| **是** | 见 **`app-datasource-lookup-guide.md`** — 应用内 `form list` 或 scoped `listByPage`（1～2 次 API），**禁止**先调 `/ds/group` 全系统遍历 |
+| **否** | 下列全系统步骤 1～2 |
+
+全系统步骤（仅无 app 时）：
+
+1. `GET /ds/group?sourceType=LOGIC` 获取表单类数据源分组
+2. `GET /ds/listByPage?sourceType=LOGIC&groupId=weaver-ebuilder-form-service&name={关键字}&pageNo=1&pageSize=20` 分页选择数据集
+3. `GET /ds/fields?sourceType=LOGIC&groupId=weaver-ebuilder-form-service&sourceId=xxx` 拉取字段结构
+4. `GET /ds/options?sourceType=LOGIC&objId=xxx&fieldName=field_xx` 获取下拉选项
+5. 如需批量：`GET /ds/optionsList?fieldList={...}`
+
+应用内步骤（已指定 app，推荐）：
+
+1. `e10-cli report find {appId} {表单名}` 或 `GET /api/datasource/ds/listByPage?sourceType=logic&appid={appId}&condition={name}` → `sourceId`
+2. 报表内：`addDataset` → `fieldsAndOriginFields?isFront=true`（fieldKey 用 `data.fieldsKey`）
+3. 字段核对走 fieldsKey / DataSetAction（本包不用 e10-cli）
+
+### 场景 B：外部数据库数据源获取
+
+1. `GET /ds/group?sourceType=EXTERNAL` 获取外部数据库分组树
+2. `GET /ds/listByPage?sourceType=EXTERNAL&groupId={dbConnectionId}&pageNo=1&pageSize=20` 获取数据库下的表列表
+3. `GET /ds/fields?sourceType=EXTERNAL&sourceId={tableId}` 获取表的字段结构
+
+### 场景 C：内部接口数据源获取
+
+1. `GET /ds/group?sourceType=INNERAPI` 获取内部接口分组
+2. `GET /ds/listByPage?sourceType=INNERAPI&groupId={categoryId}&pageNo=1&pageSize=20` 获取分类下的接口列表
+3. `GET /ds/fields?sourceType=INNERAPI&sourceId={apiId}` 获取接口返回字段
+
+### 场景 D：报表搭建前预检数据源可用性
+
+在执行 `saveReportConfig` 保存报表配置前，先通过数据源接口校验：
+1. `GET /ds/fields` 确认所有 `sourceId` 对应的字段仍然存在
+2. `GET /ds/checkFunction` 校验公式/条件是否可执行
+3. `POST /ds/conditionCheck` 校验 where 条件语法
+
+## 3. 接口间前后置依赖
+
+```
+GET /ds/group (获取分组树)
+ │
+ ▼
+GET /ds/listByPage (选定数据集，拿到 sourceId)
+ │
+ ├──────────────────────────┐
+ ▼ ▼
+GET /ds/fields GET /ds/list (全量)
+ │
+ ├──────────────┐
+ ▼ ▼
+GET /ds/options GET /ds/optionsList (获取下拉选项)
+```
+
+- **所有查询接口** 必须先获取正确的 `sourceType`（枚举见下表）与 `groupId`。
+- **`/ds/fields`** 依赖 `/ds/listByPage` 拿到的 `sourceId`。
+- **`/ds/options`、`/ds/optionsList`** 依赖 `/ds/fields` 拿到的 `fieldName`。
+- **`/ds/checkFunction`、`/ds/conditionCheck`** 必须在执行 SQL 类接口（`/ds/callApi`、`/ds/getFinalSql`）前优先调用，用于预检。
+- **`/ds/permission`** 仅对数仓（ETEAMS）数据源有效，其他 `sourceType` 调用无意义。
+
+## 4. sourceType 枚举速查
+
+| sourceType | 含义 | 典型用途 |
+| ---------------- | ------------------ | -------------------------------- |
+| `ETEAMS` | E10 数仓 | 数仓报表，需 `permission` 校验 |
+| `FORM` | EB 表单 | 表单数据集，最常用 |
+| `BIZ` | 业务模块 | 业务数据集 |
+| `LOGIC` | 逻辑数据源 | 跨表单组合视图 |
+| `EXTERNAL` | 外部数据库 | MySQL/Oracle/PG/达梦等外部连接 |
+| `INNERAPI` | 内部接口 | 平台内部 REST API 数据源 |
+| `EXTERNALDATASET`| 外部数据集 | 外部系统自定义数据集 |
+| `LOCALDS` | 本地数据源 | 本地文件/CSV |
+| `BIDS` | 标书数据源 | 招投标场景 |
+| `INTEGRATION` | 集成数据源 | 集成平台数据 |
+
+## 5. 关键参数速查
+
+| 参数 | 含义 | 典型值 |
+| ---------------------- | --------------------------- | ------------------------------------------- |
+| `sourceType` | 数据源类型枚举 | `FORM` / `LOGIC` / `ETEAMS` / `EXTERNAL` 等 |
+| `groupId` | 数据源分组或连接 ID | 由 `/ds/group` 返回 |
+| `sourceId` / `tableId` | 数据集 ID | 由 `/ds/listByPage` 返回 |
+| `appId` | 所属应用 ID | eBuilder 应用 ID |
+| `pageNo` | 当前页码（**注意**：不是 `current`） | 默认 1，≥1 |
+| `pageSize` | 每页大小 | 默认 10，1~100 |
+| `name` | 模糊搜索关键字 | 可为空 |
+| `needPermission` | 是否开启权限校验 | 默认 false |
+| `isPublic` | 是否支持外发 | 默认 false |
+| `otherParams` | 扩展参数，JSON 字符串 | 含 `isPublic`、`dataUsage` 等 |
+| `queryDto` | 查询结构体（JSON 字符串） | 含 `queryType`，用于 SQL 拼接 |
+| `fieldInfo` | 字段映射入参（JSON 字符串） | 字段 ID + 选项集合 |
+
+## 6. 核心接口详情
+
+### 6.1 GET /ds/listByPage — 分页获取数据集列表
+
+**业务用途**：搭建 EB 表单、报表、卡片时选择数据集的分页加载。
+
+**请求参数**：
+
+| 字段 | 类型 | 必填 | 传递位置 | 约束 | 说明 |
+| -------------- | ------------ | ---- | -------- | ------------------------------------------------------------ | ----------------------------------- |
+| sourceType | enum | 是 | query | `ETEAMS`/`FORM`/`BIZ`/`LOGIC`/`EXTERNAL`/`INNERAPI`/`EXTERNALDATASET`/`LOCALDS`/`BIDS`/`INTEGRATION` | 数据源类型 |
+| groupId | string | 是 | query | 长度 ≤ 64 | 数据连接 ID 或分组 ID |
+| name | string | 否 | query | 默认空串 | 按名称模糊搜索 |
+| pageNo | int | 否 | query | 默认 1，≥1 | 当前页码 |
+| pageSize | int | 否 | query | 默认 10，1~100 | 每页大小 |
+| tableId | string | 否 | query | - | 指定表 ID |
+| dataUsage | array | 否 | query | - | 数据用途过滤，如列表/图表 |
+| needPermission | boolean | 否 | query | 默认 false | 是否开启权限校验 |
+| appId | string | 否 | query | - | 应用 ID |
+| comName | string | 否 | query | - | 组件名称 |
+| isPublic | boolean | 否 | query | 默认 false | 是否支持外发 |
+| otherParams | string(JSON) | 否 | query | 需 JSON 序列化 | 扩展参数，内部会自动追加 `isPublic` |
+| dynamicParams | string(JSON) | 否 | query | 需 JSON 序列化 | 动态参数，解析为 `DynamicParamDto` |
+
+**响应示例**：
+
+```json
+{
+ "code": 200,
+ "message": "success",
+ "data": {
+ "list": [
+ {
+ "id": "87123",
+ "name": "demo_form",
+ "label": "演示表单",
+ "groupId": "1001",
+ "sourceType": "FORM",
+ "appId": "2001"
+ }
+ ],
+ "total": 1,
+ "pageNo": 1,
+ "pageSize": 10
+ },
+ "success": true
+}
+```
+
+**错误码**：
+
+| code | 说明 |
+| ---- | ------------------------------------ |
+| 200 | 成功 |
+| 500 | 服务器异常，`message` 含具体异常信息 |
+
+**请求示例**：
+
+```
+GET /api/ebuilder/ds/listByPage?sourceType=FORM&groupId=1001&name=&pageNo=1&pageSize=10&needPermission=true
+```
+
+**调用参考**：
+- 前置：先调 `GET /ds/group?sourceType=xxx` 拿到 `groupId`。
+- 后置：拿到 `data.list[*].id` 后，调用 `GET /ds/fields?sourceType=xxx&sourceId=xxx` 获取字段。
+
+**安全要求**：
+- 必须校验用户登录态
+- 当 `needPermission=true` 时，需过滤用户无权访问的数据集
+- 风险等级：低（纯查询接口）
+
+**注意事项**：
+- `otherParams`/`dynamicParams` 为 JSON 字符串，务必进行 URL 编码
+- `isPublic` 会被自动写入 `otherParams` 内部，建议只在外层传一次
+
+### 6.2 GET /ds/group — 获取数据源分组树
+
+**业务用途**：获取指定 `sourceType` 下的分组树结构，用于数据源选择面板的左侧导航。
+
+**请求参数**：
+
+| 字段 | 类型 | 必填 | 说明 |
+| ---------- | ---- | ---- | ------------ |
+| sourceType | enum | 是 | 数据源类型 |
+| appId | string | 否 | 应用 ID |
+
+**响应示例**：
+
+```json
+{
+ "code": 200,
+ "data": [
+ {
+ "id": "weaver-ebuilder-form-service",
+ "name": "EB表单服务",
+ "children": [
+ { "id": "form_001", "name": "人事表单组" }
+ ]
+ }
+ ]
+}
+```
+
+### 6.3 GET /ds/fields — 获取数据集字段列表
+
+**业务用途**：获取指定数据集的全部字段结构，用于报表字段拖拽配置。
+
+**请求参数**：
+
+| 字段 | 类型 | 必填 | 说明 |
+| ---------- | ------ | ---- | -------------------------- |
+| sourceType | enum | 是 | 数据源类型 |
+| sourceId | string | 是 | 数据集 ID（来自 listByPage） |
+| groupId | string | 否 | 分组 ID |
+
+**响应示例**：
+
+```json
+{
+ "code": 200,
+ "data": [
+ {
+ "fieldId": "field_001",
+ "fieldName": "f_emp_name",
+ "label": "员工姓名",
+ "type": "TEXT",
+ "dbType": "VARCHAR"
+ }
+ ]
+}
+```
+
+### 6.4 GET /ds/options — 获取字段下拉选项
+
+**业务用途**：获取指定字段的下拉选项/枚举值，用于查询条件配置。
+
+**请求参数**：
+
+| 字段 | 类型 | 必填 | 说明 |
+| ---------- | ------ | ---- | ---------------- |
+| sourceType | enum | 是 | 数据源类型 |
+| objId | string | 是 | 数据集 ID |
+| fieldName | string | 是 | 字段名 |
+
+### 6.5 GET /ds/optionsList — 批量获取字段选项
+
+**业务用途**：一次获取多个字段的下拉选项。
+
+**请求参数**：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --------- | ------ | ---- | ---------------------- |
+| fieldList | string | 是 | 字段集合 JSON 字符串 |
+
+### 6.6 GET /ds/checkFunction — 校验函数公式
+
+**业务用途**：校验报表公式/SQL 函数是否可执行，防止运行时报错。
+
+### 6.7 POST /ds/conditionCheck — 校验 where 条件
+
+**业务用途**：预检自定义筛选条件的 SQL 语法和合法性。
+
+### 6.8 GET /ds/callApi — 执行接口数据源调用
+
+**业务用途**：对内部接口类型数据源发起实际调用，获取返回数据。需 `queryDto` 中显式传入 `queryType`。
+
+### 6.9 GET /ds/getApiInfo — 获取接口数据源信息
+
+**业务用途**：获取内部接口数据源的元信息（URL、方法、参数定义）。
+
+### 6.10 GET /ds/pareDataSourceInfo — 根据 URL 解析数据源配置
+
+**业务用途**：从 e-builder 页面/报表 URL 中解析出数据源配置信息。`urlInfo` 为加密/编码字符串。
+
+### 6.11 GET /ds/permission — 数据源权限校验
+
+**业务用途**：校验用户对数仓（ETEAMS）数据源的访问权限。**仅对 ETEAMS 类型有效**。
+
+### 6.12 GET /ds/getDataSourceName — 获取数据源名称
+
+### 6.13 GET /ds/queryForField — 获取 ESB 字段类型
+
+### 6.14 POST /ds/saveFieldsType — 保存 ESB 字段类型
+
+### 6.15 POST /ds/fieldConvert — 字段类型转换
+
+### 6.16 GET /ds/getFinalSql — 获取最终 SQL
+
+> 必须在 `queryDto` 中显式传入 `queryType`，否则无法正确拼接 SQL。
+
+### 6.17 GET /ds/getFinalSqlByType — 按类型获取最终 SQL
+
+> 同样必须传入 `queryType`。
+
+### 6.18 GET /ds/getGroupsForEteams — 获取 ETEAMS 分组
+
+### 6.19 GET /ds/baseDataSourceInfo — 基础数据源信息
+
+### 6.20 GET /ds/list — 全量数据集列表（不分页）
+
+## 7. 应用内 vs 全系统查找（AI 必须遵守）
+
+> 完整规则见 **`app-datasource-lookup-guide.md`**。
+
+1. **用户已给 appId 或 appName** → 只在应用内找数据源（`form list` 或带 `appId`/`appid` 的 `listByPage`），**禁止**遍历全系统 `/ds/group`。
+2. **用户未给 app** → 才走 §3 依赖图中的 `group → listByPage`；且 `listByPage` **必须带 name/condition 关键字**。
+3. **探测预算**：应用内找表合计 ≤2、全系统合计 ≤3；超预算或难辨 → **打断询问用户**（`app-datasource-lookup-guide.md` §六）。
+4. **少挂源 / 连续区域父格**：见 `datasource-selection-and-parent-filter-guide.md`。3. **用户已给 sourceId** → 跳过列表查找，直接 `fields` / `addDataset`。
+4. **性能**：应用内路径目标 ≤3 次 API；全系统空扫常 10+ 次，导致任务响应慢。
+
+## 8. 注意事项（AI 必须遵守）
+
+1. **JSON 字符串参数需 URL 编码**：`otherParams`、`queryDto`、`fieldInfo`、`fieldList` 等均为 JSON 字符串，需 URL Encoded 后传递。
+2. **queryType 必填**：`/ds/getFinalSql` 与 `/ds/getFinalSqlByType` **必须**在 `queryDto` 中显式传入 `queryType`，否则无法正确拼接 SQL。
+3. **参数语义注意**：`/ds/checkFunction` 参数 `groupId` 与 `sourceId` 在代码中使用了同一个 `@Param("sourceId")`，调用时注意传参顺序与语义一致性。
+4. **权限接口限定**：`/ds/permission` 仅对 `ETEAMS` 数仓类型生效。
+5. **urlInfo 来源**：`/ds/pareDataSourceInfo` 的 `urlInfo` 是加密/编码字符串，来源于前端 E10 页面。
+6. **错误结构**：通用错误返回结构为 `{ "code": 500, "message": "xxx", "data": ..., "success": false }`，需识别 `code` 与 `message`。
+7. **分页参数命名差异**：本接口的分页参数是 `pageNo`/`pageSize`（DataSetAction 系列接口）。注意与数据源浏览器接口（`/api/datasource/common/browser/data/*`）的 `current`/`pageSize` 区分——两套接口的分页参数名不同！
+
+## 9. 与数据源浏览器接口的区别
+
+项目中存在两套数据源获取接口，用途不同：
+
+| 对比项 | DataSetAction 接口 | 数据源浏览器接口 |
+| ------ | ------------------ | ---------------- |
+| URL 前缀 | `/api/{module}/ds/*` | `/api/datasource/common/browser/*` |
+| 用途 | 报表搭建时的数据集选择器 | 设计器中数据源弹框选择 |
+| 分页参数 | `pageNo` / `pageSize` | `current` / `pageSize` |
+| 左面板数据 | `GET /ds/group` | `GET .../leftData/xxx` |
+| 右面板数据 | `GET /ds/listByPage` | `GET .../data/xxx` |
+| 认证 | E10 登录态 | 同左 |
+
+**报表搭建时优先使用 DataSetAction 接口**（`/ds/*` 系列），因为它返回的数据结构更完整，且支持 `sourceId` → `fields` → `options` 的完整链路。
+
+## 10. 变更记录
+
+| 版本 | 日期 | 变更说明 |
+| ---- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
+| v1.0 | 2026-08-03 | 基于 `DataSetAction.java` 初版生成，覆盖 list / listByPage / group / fields / options / optionsList / permission / getDataSourceName / queryForField / callApi / getApiInfo / fieldConvert / checkFunction / conditionCheck / getFinalSql / getFinalSqlByType / getGroupsForEteams / pareDataSourceInfo / baseDataSourceInfo / saveFieldsType 共 20 个接口 |
+| v1.1 | 2026-08-03 | 整合到 report-builder-assistant 技能，补充场景 B/C/D、接口依赖图、sourceType 枚举速查、与浏览器接口对比表、分页参数差异说明 |
+| v1.3 | 2026-09-04 | 场景 A 分支：已指定 app → 应用内查找；新增 §7 应用内 vs 全系统规则，链至 app-datasource-lookup-guide.md |

package/skills/weaver-e10-builder/references/report/datasource-selection-and-parent-filter-guide.md

@@ -0,0 +1,148 @@
+# 数据源选用与多源父格（强制）
+
+> **适用**：需求分析、配置生成、API 建表。 
+> **目标**：少挂数据源、少配父格筛选、控制找表空耗。
+
+---
+
+## 〇、左父格默认优先（强制 · 单数据集）
+
+> **事故对照**：同一需求文件生成的「供应商信息管理」`866766714447126529` 与「供应商-1」`1312703681350901760` 均为**单数据集**，却一个把字段左父格串成「逐列自定义链」，一个把明细列都自定义挂到分组列 —— 设计器里大量显示「自定义」，与常规「默认」不一致。
+
+**原则**：无多数据集、且需求**未指定**特殊计算/交叉/合计挂靠时，**Field / 普通 Const** 左父格一律默认（`leftX=-1, leftY=-1` / `["default",0,0]`）。
+
+> **例外（强制）**：**超链接 Const**（`pcHreflink` 含 `{L4}` 等）**不适用**「左父格默认」。上父格仍为 `-1`；左父格须指向占位依赖的数据格。见 `report-self-check-guide.md` §2.2。 
+> **已有报表**：用户未点名时**禁止**批量改父格。
+
+| 场景 | 左父格 | 说明 |
+|------|--------|------|
+| **单数据集**列表 / 简单分组 | **默认** | 引擎按相邻扩展自动解析；**禁止**为「看起来整齐」逐格写 custom |
+| 单数据集但需求写明合计行挂某分组、交叉表行列挂靠、公式指定父格 | **自定义**（仅涉及的格） | 见 building-guide / formula-cell-api-guide |
+| **多数据集**跨源关联 | 连续同源区**仅入口格**自定义 + 父格筛选 | 见 §二；其余默认 |
+
+**硬约束**
+
+1. 报表内有效 `dataSetId` 只有 **1 个**（忽略 `-1`）→ **新建/从需求生成时** Field 左父格用 default；**禁止**链式 `左父格=上一列`、也**禁止**无必要地把所有 List 列挂到同一 Group 列。
+2. 同数据集 **禁止**配 `leftFilterField` / `subordination`（那是跨源用的）。
+3. 只有用户/需求明确「按 XX 分组计算」「合计挂在 A3」「交叉维」时才对该格设自定义父格。
+4. 需求分析列级表：单数据集时「父格」列填 **默认**，勿臆造自定义坐标。
+5. **禁止擅自改已有报表父格**：用户仅强调「规则上默认即可」时，**只更新 Skill/新建逻辑**；**不得**对线上已有报表批量把自定义左/上父格改成 default，除非用户**明确要求修改该报表**。
+6. **上父格**：无交叉/横向扩展需求时保持默认/无；勿给普通列表单元格（如 M4 链接文案）乱设上父格。
+
+---
+
+## 一、尽可能少用数据源（强制）
+
+**原则**：主业务表上**已有**可展示字段时，**禁止**仅为「好看/完整」再挂关联表。
+
+| 场景 | 正确做法 | 错误做法 |
+|------|----------|----------|
+| 考勤表已有用户 ID / 姓名 / 工号 | 直接绑考勤表字段 | 再关联人员表只为显示人员 |
+| 人员表已有部门名称 / 部门 ID | 直接绑人员表部门字段 | 再关联部门表只为显示部门 |
+| 合同表已有供应商名称 | 直接绑合同表字段 | 再挂供应商主数据表只为回显名称 |
+| 需求明确要「主数据维度扩展」（如按部门树下钻、人员多属性）且主表无该字段 | 才允许加第二数据源 | — |
+
+**判定顺序**
+
+1. 先读主表 `fieldsAndOriginFields` / `form read`，列出需求列能否在**同一 sourceId** 上取到。
+2. 能取到 → **只 add 这一张表**（或需求点名的最少表集合）。
+3. 取不到且业务必须跨表关联 → 再加第二源，并走 §二 父格规则。
+
+**禁止**：按「业务实体清单」机械每人/每部门/每组织各挂一张表；禁止未核对字段就先 `addDataset` 多张。
+
+---
+
+## 二、多数据源 · 连续区域父格筛选（强制）
+
+> 跨数据集关联仍遵守 `cross-dataset-filter-guide.md`（fieldKey、`id=currentField` 等）。本节约束 **配多少次**。
+
+### 2.1 规则
+
+同一布局里，若**连续一片区域**（连续行或连续列）的字段**全部来自同一数据源 B**，且需挂到另一数据源 A 的父格下：
+
+| 单元格 | 左/上父格 | subordination + leftFilterField（父格筛选） |
+|--------|-----------|-----------------------------------------------|
+| **该连续区域的第一个**字段（区域入口格） | 指向 **A 侧**父格字段（自定义父格） | **必须配置**（与 A 的关联键） |
+| **同区域后续**字段 | **默认父格**（跟随入口格扩展链，通常 `"default"`） | **禁止**再逐格指定父格为 A，也**禁止**再配一套父格筛选 |
+
+### 2.2 示意
+
+```
+A 区（数据源 A）… 末字段
+B 区连续（数据源 B）：
+ B1 左父格 → A.关联键字段 + 父格筛选（A.key = B.fk） ← 仅此格
+ B2 父格默认
+ B3 父格默认
+ …
+```
+
+### 2.3 反例
+
+- 对 B1、B2、B3 **每个**都设 `leftParent` 指向 A，并各写一遍 `leftFilterField` → 冗余、易错、预览异常风险高。
+- 连续区域被公式列/常量列打断后仍当成「一整块」不配入口格筛选 → 关联失效。若区域被异源单元格打断，**每一段**各自的首字段仍须单独配入口筛选。
+
+### 2.4 与需求分析表的填法
+
+列级配置总表中：
+
+- 连续同源区域：**仅入口列**「父格筛选」写关联；其余列父格筛选填 `-`，父格填 `default`（或文档约定的默认）。
+- **关联键来源**（见 §2.5）：需求已写明 → 直接填；推断得到 → 父格筛选列标注「推断·待确认」，并在待确认项列出。
+
+### 2.5 多表关联键：需求优先 · 推断须确认（强制）
+
+> 报表挂 **≥2 个数据集** 且需跨源父格筛选时适用。配置写法仍见 `cross-dataset-filter-guide.md`。
+
+#### 2.5.1 关联键如何确定
+
+| 优先级 | 来源 | Agent 行为 |
+|--------|------|------------|
+| **1** | 需求/用户**明确**写出两表关联（如「销售单.客户ID = 客户.ID」「按供应商名称关联」） | **直接**按该对字段配入口格 `subordination` + `leftFilterField`；**不必**再问 |
+| **2** | 需求**未写**关联字段 | 用两表字段元数据**检索匹配**（见下）→ 选出候选 → **必须提示用户确认** 后再落库；用户未回时可用置信度最高的一对**先配**，但交付时注明「推断关联·请确认」 |
+| **3** | 无法推断或候选冲突 | **打断询问**关联关系；**禁止**瞎配；可先交单表/已确认部分，关联筛选标待补（非阻塞，见 `failure-cleanup-and-nonblocking-guide.md`） |
+
+#### 2.5.2 字段值/元数据匹配（需求未写明时）
+
+对父表 A、子表 B 的字段列表（优先 `fieldsAndOriginFields` / `e10-cli report join-suggest`）：
+
+1. **显示名全等**（如双方都有「供应商名称」）→ 高置信 
+2. **系统名/业务键同构**（同 `field_*` 后缀模式、`xxxId`↔`xxx`、外键命名含对方表名）→ 中高置信 
+3. **名称近似**（去后缀「编号/名称/ID」后相同、一方「客户」一方「客户名称」）→ 中置信 
+4. **多候选同分** → 全部列出，**禁止**静默任选一个不告知 
+
+**禁止**：仅凭表名臆造 fieldKey；禁止用显示名当 `parentField`/`currentField`（必须三段式 fieldKey）。
+
+#### 2.5.3 必须给用户的确认话术（推断时强制）
+
+推断关联后，交付/询问中**至少**说明：
+
+```
+【关联待确认】表 A「…」与表 B「…」未在需求中写明关联字段。
+已按字段匹配推断：A.{显示名/系统名} Equals B.{显示名/系统名}
+请确认是否正确；若不正确请给出正确关联（A.字段 = B.字段）。
+```
+
+用户确认或纠正后，再改入口格筛选（定点改，见 `targeted-fix-guide.md`）。
+
+#### 2.5.4 CLI（优先）
+
+```bash
+e10-cli report join-suggest --app-id <appId> --parent-source <sourceIdA> --child-source <sourceIdB>
+# 或按表名：
+e10-cli report join-suggest --app-id <appId> --parent-form "销售单" --child-form "销售明细"
+```
+
+输出候选对 + `needConfirm=true`；Agent **优先调 CLI**，勿手写比对脚本。
+
+---
+
+## 三、与找表耗时控制的关系
+
+少挂源 = 少次 `addDataset` / `fields`。找不准表时的打断规则见 **`app-datasource-lookup-guide.md` §七**。
+
+| 文档 | 关系 |
+|------|------|
+| `app-datasource-lookup-guide.md` | 应用内找表 + 多轮打断询问 |
+| `cross-dataset-filter-guide.md` | 入口格筛选的 fieldKey 写法 |
+| `e10-cli report -cli.md` | **CLI 优先**：找表 / join suggest / verify / 删壳 |
+| `api-report-build-fast-path.md` | 建表流程引用本节 |
+| `report-requirement-analysis-template.md` | 列级表父格筛选填法 |

package/skills/weaver-e10-builder/references/report/date-range-query-reference.md

@@ -0,0 +1,102 @@
+# 日期区间查询条件选项参考（已验证样例）
+
+> **来源**：报表 `1304979556231593985`（EBU 经营数据统计）· 查询条件「入职时间」 
+> **完整规范**：`query-condition-api-guide.md`（条件字段形态、系统参数默认值、验证清单） 
+> **filterParam 快照**：`outputs/join_date_filterparam.json`（运行 `本地工作目录` 可重新导出） 
+> **代码实现**：`本地工作目录` → `_default_date_filter_param()`
+
+---
+
+## 一、快捷选项（filterParam.dataOptions · 21 项）
+
+设计器 save 后的正确形态：
+
+| 字段 | 正确值 |
+|------|--------|
+| `selectOptions` | **`[]`** |
+| `filterParam.enableOption` | `true` |
+| `filterParam.isTile` | `true` |
+| `filterParam.dataOptions` | **21 行**（下表） |
+| `filterParam.optionTile` | **`{}`** |
+| `filterParam.dateSelectDefaultValue` | **`""`** |
+
+**勿用旧格式**：15 项数字码（`"9"`、`"{yesterday}"`）+ 9 项 `selectOptions` + 填满 `optionTile` → 齿轮菜单常只剩「自定义」。
+
+---
+
+## 二、dataOptions catalog（id = selectValue）
+
+| selectKey | selectValue / id |
+|-----------|------------------|
+| 近三天 | day3 |
+| 近五天 | day5 |
+| 近七天 | day7 |
+| 今天 | today |
+| 昨天 | yesterday |
+| 明天 | tomorrow |
+| 本周 | thisWeek |
+| 上一周 | lastWeek |
+| 下一周 | nextWeek |
+| 本月 | thisMonth |
+| 上一月 | lastMonth |
+| 下一月 | nextMonth |
+| 本季度 | thisSeason |
+| 上一季 | lastSeason |
+| 下一季 | nextSeason |
+| 今年 | thisYear |
+| 上半年 | firstHalfYear |
+| 下半年 | nextHalfYear |
+| 去年 | lastYear |
+| 明年 | nextYear |
+| 自定义 | custom |
+
+---
+
+## 三、系统参数默认值（与快捷选项独立）
+
+默认值写在顶层 **`defaultValueType` + `defaultValue`**，不是 `dateSelectDefaultValue`。
+
+| 场景 | defaultValueType | defaultValue | handleDefaultValue 示例 |
+|------|------------------|--------------|-------------------------|
+| 本月 | `custom` | `["{thismonth}",""]` | `["2026-08-01,2026-08-31",""]` |
+| 今天 | `custom` | `["{date}","{date}"]` | `["2026-08-19","2026-08-19"]` |
+
+`displayType`：`yyyy-MM-dd` 字段 → `date.ymd`；`yyyy-MM` 字段 → `date.ym`。
+
+---
+
+## 四、filterParam 完整示例
+
+```json
+{
+ "isTile": true,
+ "enableOption": true,
+ "showType": "tile",
+ "multiple": false,
+ "dataOptions": [ { "selectKey": "本月", "selectValue": "thisMonth", "id": "thisMonth" } ],
+ "optionTile": {},
+ "dateSelectDefaultValue": ""
+}
+```
+
+（`dataOptions` 须写满 21 项，此处省略。）
+
+---
+
+## 五、Agent checklist
+
+1. 加载本文 + `query-condition-api-guide.md`
+2. `_default_date_filter_param()` + `defaultValueType: custom` + 系统参数
+3. 校验：21 项 dataOptions、`selectOptions=[]`、`handleDefaultValue` 非空
+4. 设计器：齿轮 21 项 + 默认筛选项生效
+
+---
+
+## 六、相关文件
+
+| 文件 | 用途 |
+|------|------|
+| `query-condition-api-guide.md` | 查询条件总规范 |
+| `outputs/join_date_filterparam.json` | filterParam 参考样本 |
+| `本地工作目录` | 生成/修复 |
+| `本地工作目录` | 扫描导出 |