@finebi/finebi-cli 1.5.0 → 1.6.0

package/skills/finebi-cli-agent/references/dashboard-dsl-core.md

@@ -0,0 +1,194 @@
+# Dashboard DSL API：根入口、布局与移动端
+
+> Dashboard DSL API 总导航见 [dashboard-dsl-api.md](dashboard-dsl-api.md)。
+
+## 1. 根入口
+
+嵌入的数据图表沿用 [Widget DSL API §4.7.2](widget-dsl-styles.md#472-值轴与双-y-轴) 的
+`.valueAxis(measureRef, ValueAxis.builder()...build())`，无需 Dashboard 专属双轴开关。
+`dashboard dsl` 可回读支持的值轴设置；替换更新应保留导出的完整组件 DSL，
+遇到不能表达的有效轴公式或样式时先处理明确报错，不删除设置后强行更新。
+
+```js
+DashboardDsl.create("仪表板名")
+```
+
+业务含义：
+
+- 新建一个仪表板 Builder。
+- 仪表板负责组织组件、控件、文本、布局、样式和移动端配置。
+
+## 2. 顶层 Builder
+
+| DSL API           | 业务含义                        |
+|-------------------|-----------------------------|
+| `.content()`      | 进入内容域，定义仪表板上有哪些条目。          |
+| `.presentation()` | 进入布局与样式域，定义条目如何摆放、整板采用什么风格。 |
+| `.mobile()`       | 进入移动端域，定义移动端展示顺序。           |
+| `.build()`        | 结束编排，生成 `ReportModel`。      |
+
+## 3. 内容域
+
+### 3.1 条目挂载
+
+| DSL API                   | 业务含义                  |
+|---------------------------|-----------------------|
+| `.reference("已有组件名")`     | 引用已有数据组件，不在当前脚本内重新定义。 |
+| `.control(controlItem)`   | 挂载一个筛选控件。             |
+| `.text(textItem)`         | 挂载一个文本组件。             |
+| `.image(imageItem)`       | 挂载一个图片组件。             |
+| `.web(webItem)`           | 挂载一个 Web 组件（内嵌 iframe 打开外部地址）。 |
+| `.generalQuery(generalQueryItem)` | 挂载一个复合过滤组件：用 `.where(...)` / `.orGroup(...)` 声明初始过滤条件（省略 = 空骨架，查看者在查看态自行增删条件、且或组合并触发查询）（见 [§6.13](dashboard-dsl-items.md#613-generalqueryitem复合过滤组件)）。 |
+| `.aiDiagnosis(aiDiagnosisItem)` | 挂载一个 AI 诊断组件：对选中组件做 AI 诊断/产出分析（见 [§6.14](dashboard-dsl-items.md#614-aidiagnosisitemai-诊断组件)）。 |
+| `.combine(combineItem)`   | 挂载一个组件组合（区块容器）：成员为已声明的非容器条目名（至少 2 个），成员布局移入组合内容区（见 [§6.10](dashboard-dsl-items.md#610-combineitem组件组合)）。 |
+| `.tab(tabItem)`           | 挂载一个 Tab 组件：多页签切换展示，每页持成员（见 [§6.11](dashboard-dsl-items.md#611-tabitemtab-组件)）。 |
+| `.freeze(freezeItem)`     | 挂载一个过滤组件冻结栏：成员为控件与复合过滤组件，查看态钉在页面上方（见 [§6.12](dashboard-dsl-items.md#612-freezeitem过滤组件冻结栏)）。 |
+| `.title("组件名", "标题")`     | 给已声明的数据组件设置显示标题；第二参数也可传 `RichText.of()...build()`（富文本标题，含动态字段值，见 [§8.3](dashboard-dsl-examples.md#83-数据组件标题)）。 |
+| `.showTitle("组件名", true)` | 设置已声明的数据组件是否显示标题。     |
+
+容器公共口径（三件套同构）：
+
+- 成员是**同板已声明的条目名**，可在容器声明之后才声明；一个条目至多加入一个容器；成员不得再 `position` 到顶层（其布局在容器内局部 72×36 网格）。
+- 容器自身占一个画布位：不 `position` 时默认尺寸 组合 72×24 / Tab 72×16 / 冻结栏 72×8，与其他条目一起自动排；组合与 Tab 可悬浮（`float` 作用于容器名），**冻结栏自身不可悬浮**（设计器工具栏无该入口）。
+- **组合容器浮 = 成员全浮**：`float(组合名)` 时**全部成员都须 `float`**（否则 fail-loud）。设计器按「成员全悬浮 → 容器悬浮」派生（帮助文档 §4），因此容器不浮而部分成员悬浮是合法的（对应设计器的「部分悬浮组合」形态）。
+- 组合/Tab 页成员可悬浮（`float(成员名)`，须显式 `place`）；冻结栏成员不可悬浮。组合不可嵌任何容器；Tab 页可含组合与冻结栏（冻结栏每页至多 1 个）；Tab 不可嵌 Tab。
+
+### 3.2 联动与跳转
+
+| DSL API                                     | 业务含义                       |
+|---------------------------------------------|----------------------------|
+| `.linkage("源组件名", linkage1, linkage2, ...)` | 给已声明的数据组件追加主动联动配置（显式字段对，查看态按声明字段过滤；被联动组件上的反向条目自动派生）。 |
+| `.linkageEffect("源组件名", click, "目标1", "目标2", ...)` | 声明一条持久化联动效果（设计器里点击组件联动后的自动保存产物，打开仪表板即生效）。 |
+| `.jump("源组件名", jump1, jump2, ...)`          | 给已声明的数据组件追加跳转配置。           |
+| `.cancelDefaultLinkage()`                   | 关闭仪表板默认联动，只保留显式声明的联动规则。    |
+
+业务补充：
+
+- `linkage` 和 `jump` 都按组件业务名工作；多次调用是累加关系。
+- 联动目标必须是同板已声明的数据组件或文本组件（控件、图片不可被联动）；不声明联动 = 平台天然联动（同表/关联表/同指标集自动配对）。
+- `LinkageModel.of(源字段, "目标组件名", 目标字段)` 声明显式字段对；`LinkageModel.disable("目标组件名")` 对单个目标显式关闭联动（含天然联动）。
+- `linkageEffect` 与 `linkage` 正交：`linkage` 描述「怎么联动」（配置），`linkageEffect` 描述「当前联动已发生」（持久化点击态）。点击坐标 `LinkageEffect.click(点击轴字段)` + `.cell(维度字段, "显示值")` 维度坐标 / `.summaryCell("合计")` 合计行坐标 / `.metricNameCell("指标名")` 指标名称坐标（源组件须声明指标名称维度）。同一源至多一条；目标集可为空（点击时源无可联动目标）；每条效果独立一跳、**不传递**（A 联动 B、B 联动 C 时点击 A 不会传导到 C——前端运行态限制）；明细表不可发起（同 `linkage`）。
+- 跳转名称（`.name(...)`）同一组件内不可重复；未命名的跳转用平台默认名（分析模板/网页链接），可多条。
+- 跳转目标仪表板可跨主题：目标板按名称解析（同主题同名板优先，未命中查全局）；目标字段的 fieldId 属于目标板用到的表，跨主题前先 `dashboard tables --id <目标板id>` 查候选字段名。
+- `title` 和 `showTitle` 只作用于数据组件，不作用于控件、文本和图片组件。
+
+## 4. 布局与样式域
+
+### 4.1 布局与自适应
+
+```js
+AdaptiveModel.flowLayout()
+AdaptiveModel.origin(width, height)
+```
+
+| DSL API                                   | 业务含义                  |
+|-------------------------------------------|-----------------------|
+| `.adaptive(AdaptiveModel.flowLayout())`   | 自动适应：仅重排布局，不整体缩放（省略语句 = 自动适应 + 整体缩放，即设计器默认）。 |
+| `.adaptive(AdaptiveModel.origin(w, h))`   | 固定基准尺寸：保持原始尺寸不缩放。 |
+| `.adaptive(AdaptiveModel.fitWidth(w, h))` | 固定基准尺寸：按宽度铺满等比缩放。 |
+| `.adaptive(AdaptiveModel.fitHeight(w, h))`| 固定基准尺寸：按高度铺满等比缩放。 |
+| `.adaptive(AdaptiveModel.fitAuto(w, h))`  | 固定基准尺寸：按屏幕自适应铺满（宽高取小）。 |
+| `.position(name, col, row, wCols, hRows)` | 按 72 列网格给条目设置位置和占位大小。 |
+
+参数语义（adaptive）：
+
+- `w` / `h`：基准尺寸，取值 100~10000（整数，超界 fail-loud）
+
+参数语义（position）：
+
+- `name`：已声明条目的业务名
+- `col`：起始列
+- `row`：起始行
+- `wCols`：占用列数
+- `hRows`：占用行数
+
+业务规则：
+
+- 仪表板宽度固定为 72 列。
+- `col + wCols` 不能超过 72。
+- `row` 与 `hRows` 不做画布行上限硬校验（支持纵向延展，超出一屏时可滚动查看）。
+- 没有显式 `position(...)` 的条目会按默认尺寸自动排版；显式和 auto 条目统一经全量压实（对齐前端查看态）；**悬浮条目例外**（原样落位不压实）。
+
+### 4.2 悬浮与图层
+
+```js
+.float(name)
+```
+
+| DSL API | 业务含义 |
+|-------------------------------------------|-----------------------|
+| `.float(name)` | 声明条目悬浮：允许重叠、不参与压实，悬浮恒压网格条目。 |
+
+参数语义：
+
+- `name`：已声明条目的业务名；多次调用累加
+- **声明序即图层顺序**：后 `.float(...)` 声明的条目在上（置顶 = 调整声明序）
+- 悬浮条目必须同时有显式 `.position(...)`（自由层无自动排布，缺省 fail-loud）
+- 同名重复悬浮 fail-loud
+
+### 4.3 模板样式
+
+| DSL API                        | 业务含义                      |
+|--------------------------------|---------------------------|
+| `.stylePreset("DEFAULT_DARK")` | 使用平台内置的整板样式预设，按预设 id 选择。  |
+| `.customStyle("我的样式")`         | 使用管理员保存的全局自定义样式，按样式显示名选择。 |
+| `.templateStyle(TemplateStyle.of()....build())` | 在基底上分区微调样式（可与上面任一组合：基底 + 逐项覆盖）。 |
+
+业务补充：
+
+- `stylePreset` 适合快速套用平台标准主题。
+- `customStyle` 适合复用团队已有的大屏或看板风格。
+- `templateStyle` 全部可选、省略 = 基底值/平台默认；只声明要改的项。
+
+微调方法速查（按面板 6 分区）：
+
+| 分区 | 方法 | 值域 |
+|---|---|---|
+| 仪表板 | `widgetGap(gap)` / `background(color)` / `background(TemplateBackground)` | gap 偶数 0~20；颜色 `#RGB`/`#RRGGBB`/`transparent` |
+| 组件 | `widgetBackground(color)` 或 `widgetBackground(color, radius, borderSize, borderColor)` 或 `widgetBackground(TemplateBackground)` / `hoverShadow(bool)` / `titleBackground(color\|TemplateBackground)` / `titleFont(font)` | 圆角 0~6、边框 0~5 |
+| 图表 | `chartColor([colors])` / `clearChartColor()` / `chartFont(font)` | 色板非空；`clearChartColor()` = 面板「自动」回退平台配色；图表字体无对齐 |
+| 表格 | `tableStyle(TemplateStyle.PLAIN\|BLUE_HEADER\|INTERVAL)` / `tableThemeColor(color)` / `tableFont(font)` / `scrollbar(TemplateStyle.STATIC\|DYNAMIC)` | |
+| 过滤组件 | `controlTheme(color)` / `controlTitleFont(font)` / `controlTitleBackground(color\|TemplateBackground)` / `controlBackground(color[...]\|TemplateBackground)` | 此分区背景无样式皮肤入口 |
+| 图片组件 | `imageBackground(color[...]\|TemplateBackground)` | |
+
+背景值对象（6 个背景槽位通用，镜像设计器背景面板的颜色/图片/组件样式三选一）：
+
+```js
+TemplateBackground.color("#13141f")                          // 纯色（等价于 background("#13141f") 便捷形态）
+TemplateBackground.color("#1a1a2e", 4, 1, "#5a80ff")        // 纯色 + 圆角 0~6 / 边框 0~5 / 边框色
+TemplateBackground.image("image1788431093821_aft0uG6q_png")  // 上传图片（attach id，先跑 dashboard upload-image）
+TemplateBackground.style(TemplateBackground.STYLE2)          // 预置装饰皮肤 STYLE1..STYLE6
+```
+
+- 图片 `attachId` 必须来自 `dashboard upload-image`（或 `data:image...`、`resources?path=`）；绝对 URL 渲染不出，构造期报错。
+- 样式皮肤仅组件背景（`STYLE1/2/3/5/6`）、标题背景（`STYLE1..STYLE6`）、图片组件背景（`STYLE1/2/3/5/6`）可用；模板背景与过滤组件分区无此入口。
+- 边框三件只在组件 / 过滤组件 / 图片组件背景三个分区设置；图片与皮肤形态不消费颜色与边框。
+
+字体值（`FontModel.of().family(...).size(...).bold(bool).italic(bool).underline(bool).color(...).align(FontModel.LEFT|CENTER|RIGHT).build()`；`FontModel.auto()` 把槽位重置回自动）：
+
+- `size` 必须是设计器字号选项之一：12~40（步进见面板）、64、128。
+- 表格字体 `TableFont.of().header(FontModel).body(TableBodyFont.of()....dimAlign(...).tarAlign(...).build()).build()`（表头单对齐、表身维度/指标双对齐）；`TableFont.auto()` 整体重置（表头/表身共用一个开关）。
+
+## 5. 移动端域
+
+| DSL API                                               | 业务含义         |
+|-------------------------------------------------------|--------------|
+| `.mobileConfig(MobileConfigModel.defaults())`         | 使用默认移动端配置。   |
+| `.mobileConfig(MobileConfigModel.of(["组件A", "组件B"]))` | 显式指定移动端组件顺序。 |
+
+默认配置语义：
+
+- `controlShowType = 1`
+- `fitGap = 10`
+- `autoSequence = true`
+
+## 7. 字段写法
+
+Dashboard DSL 中涉及字段的地方，包括控件、联动和跳转，都统一使用 source-scoped 写法：
+
+```js
+from("销售表").dim("地区")
+from("销售表").sum("销售额")
+from("销售表").measure("销售额")
+```
+

package/skills/finebi-cli-agent/references/dashboard-dsl-examples.md

@@ -0,0 +1,378 @@
+# Dashboard DSL API：推荐写法示例与场景要点
+
+> Dashboard DSL API 总导航见 [dashboard-dsl-api.md](dashboard-dsl-api.md)。
+
+## 8. 推荐写法示例
+
+### 8.1 引用已有组件
+
+```js
+DashboardDsl.create("经营总览")
+    .content()
+    .reference("区域销售额")
+    .reference("月度趋势")
+    .presentation()
+    .position("区域销售额", 0, 0, 24, 16)
+    .position("月度趋势", 24, 0, 24, 16)
+    .build()
+```
+
+适用场景：已有组件已经保存到平台，只负责组织它们在仪表板上的摆放。
+
+### 8.2 筛选控件
+
+```js
+DashboardDsl.create("带筛选控件")
+    .content()
+    .reference("月度趋势")
+    .control(
+        ControlItem.builder("区域筛选", ControlItem.TEXT)
+            .bindField(from("销售表").dim("地区"))
+            .controlRange(["月度趋势"])
+            .title("区域")
+            .showTitle(true)
+            .build()
+    )
+    .presentation()
+    .position("月度趋势", 0, 0, 24, 16)
+    .position("区域筛选", 0, 16, 24, 4)
+    .build()
+```
+
+适用场景：给指定组件加一个局部生效的文本筛选控件。
+
+### 8.3 数据组件标题
+
+```js
+DashboardDsl.create("经营总览")
+    .content()
+    .reference("区域销售额")
+    .title("区域销售额", "各区域销售额")
+    .showTitle("区域销售额", true)
+    .presentation()
+    .position("区域销售额", 0, 0, 24, 16)
+    .build()
+```
+
+标题也可以带动态字段值（富文本标题，形态与文本组件富文本一致）：
+
+```js
+DashboardDsl.create("经营总览")
+    .content()
+    .reference("区域销售额")
+    .title("区域销售额", RichText.of()
+        .line("各区域销售额（", widgetName(), "）")   // 组件名只有标题可用
+        .line("更新至：", from("销售表").dim("统计日期"))
+        .build())
+    .presentation()
+    .position("区域销售额", 0, 0, 24, 16)
+    .build()
+```
+
+标题富文本的片段类型与文本组件一致（`line` / `listItem` / `styled` / `link` / 字段引用 / `widgetName()` / `componentField(...)`），但**标题没有整块垂直对齐**（前端标题面板无该入口，声明 `verticalAlign(...)` 会报错）。
+
+适用场景：复用已有组件，但在当前仪表板中使用新的业务标题。
+
+### 8.4 时间控件
+
+```js
+DashboardDsl.create("按月分析")
+    .content()
+    .reference("月度趋势")
+    .control(
+        ControlItem.builder("月份控件", ControlItem.MONTH)
+            .bindField(from("销售表").dim("月份"))
+            .title("月份")
+            .showTitle(true)
+            .build()
+    )
+    .presentation()
+    .position("月份控件", 0, 0, 24, 4)
+    .position("月度趋势", 0, 4, 24, 16)
+    .build()
+```
+
+适用场景：用月份控件驱动时间分析。
+
+### 8.5 文本 + 数据组件
+
+```js
+DashboardDsl.create("销售总览")
+    .content()
+    .text(
+        TextItem.ofRichText("标题", RichText.of()
+            .line(styled("销售总览", {"font-size": "24px", "font-weight": "600", "color": "#333333"}))
+            .build())
+    )
+    .reference("区域销售额")
+    .presentation()
+    .position("标题", 0, 0, 24, 4)
+    .position("区域销售额", 0, 4, 24, 16)
+    .build()
+```
+
+适用场景：用标题文本、说明文本给数据组件做语义包装。
+
+### 8.6 富文本动态指标（KPI 风格）
+
+```js
+DashboardDsl.create("经营速览")
+    .content()
+    .text(TextItem.ofRichText("核心指标", RichText.of()
+            .line("总销售额：", from("销售表").sum("销售额"), " 元")
+            .line("订单数：", count(from("销售表").dim("订单号")))
+            .build()))
+    .presentation()
+    .position("核心指标", 0, 0, 24, 8)
+    .build()
+```
+
+适用场景：在文本组件里展示字段真实数据（维度值、聚合指标、记录数），做 KPI 概览或说明行；字段写法同 [§7](dashboard-dsl-core.md#7-字段写法)。
+
+### 8.7 主动联动
+
+```js
+DashboardDsl.create("区域销售分析")
+    .content()
+    .reference("区域销售图")
+    .reference("订单明细")
+    .linkage(
+        "区域销售图",
+        LinkageModel.of(
+            from("销售表").dim("地区"),
+            "订单明细",
+            from("销售表").dim("地区")
+        )
+    )
+    .presentation()
+    .position("区域销售图", 0, 0, 24, 16)
+    .position("订单明细", 24, 0, 24, 16)
+    .build()
+```
+
+适用场景：点击左侧汇总图，右侧明细表跟随过滤。
+
+### 8.8 组件跳转
+
+```js
+DashboardDsl.create("销售驾驶舱")
+    .content()
+    .reference("区域销售图")
+    .jump(
+        "区域销售图",
+        JumpModel.toReport(
+            from("销售表").dim("地区"),
+            "区域专题看板",
+            from("销售表").dim("地区")
+        )
+        .openPosition(JumpModel.DIALOG)
+        .name("查看区域专题")
+    )
+    .presentation()
+    .position("区域销售图", 0, 0, 24, 16)
+    .build()
+```
+
+适用场景：从总览看板跳到专题看板（也可用 `JumpModel.toUrl` 跳网页链接）。
+
+### 8.9 关闭默认联动与单目标禁用
+
+```js
+DashboardDsl.create("显式联动看板")
+    .content()
+    .reference("chartA")
+    .reference("chartB")
+    .reference("chartC")
+    .linkage("chartA", LinkageModel.of(
+        from("销售表").dim("地区"),
+        "chartB",
+        from("销售表").dim("地区")
+    ))
+    .linkage("chartA", LinkageModel.disable("chartC"))
+    .cancelDefaultLinkage()
+    .presentation()
+    .position("chartA", 0, 0, 24, 16)
+    .position("chartB", 24, 0, 24, 16)
+    .position("chartC", 48, 0, 24, 16)
+    .build()
+```
+
+适用场景：只保留显式编排的联动关系（天然联动整板关闭；`LinkageModel.disable` 对单个目标关闭）。
+
+### 8.10 持久化联动效果
+
+```js
+DashboardDsl.create("留存联动看板")
+    .content()
+    .reference("区域销售图")
+    .reference("订单明细")
+    .text(TextItem.of("区域说明", "当前聚焦区域"))
+    .linkageEffect(
+        "区域销售图",
+        LinkageEffect.click(from("销售表").dim("销售额"))
+            .cell(from("销售表").dim("地区"), "华东")
+            .summaryCell("合计"),
+        "订单明细", "区域说明"
+    )
+    .presentation()
+    .position("区域销售图", 0, 0, 24, 16)
+    .position("订单明细", 24, 0, 24, 16)
+    .position("区域说明", 0, 16, 24, 4)
+    .build()
+```
+
+适用场景：看板打开即呈现「区域销售图点击华东后」的联动状态（数据/文本目标跟随过滤）。与 `linkage` 配置正交；一条效果一跳生效、不传递。
+
+### 8.11 使用平台预设样式
+
+```js
+DashboardDsl.create("大屏主题示例")
+    .content()
+    .reference("经营概览")
+    .presentation()
+    .stylePreset("DEFAULT_DARK")
+    .position("经营概览", 0, 0, 24, 16)
+    .build()
+```
+
+适用场景：快速套用平台内置深色或浅色风格。
+
+### 8.12 使用全局自定义样式
+
+```js
+DashboardDsl.create("品牌看板")
+    .content()
+    .reference("区域销售额")
+    .presentation()
+    .customStyle("销售总览样式")
+    .position("区域销售额", 0, 0, 24, 16)
+    .build()
+```
+
+适用场景：复用团队统一维护的品牌样式。
+
+### 8.13 移动端顺序
+
+```js
+DashboardDsl.create("移动端示例")
+    .content()
+    .reference("w1")
+    .reference("w2")
+    .reference("w3")
+    .mobile()
+    .mobileConfig(MobileConfigModel.of(["w2", "w1", "w3"]))
+    .build()
+```
+
+适用场景：移动端展示顺序与桌面端布局顺序不同，需要单独编排。
+
+### 8.14 多字段控件
+
+```js
+DashboardDsl.create("多字段筛选")
+    .content()
+    .reference("区域销售额")
+    .reference("订单明细")
+    .control(
+        ControlItem.builder("地区与大区筛选", ControlItem.TEXT_LIST)
+            .bindFields([
+                from("销售表").dim("地区"),
+                from("销售表").dim("大区")
+            ])
+            .controlRange(["区域销售额", "订单明细"])
+            .title("区域范围")
+            .showTitle(true)
+            .build()
+    )
+    .presentation()
+    .position("地区与大区筛选", 0, 0, 24, 8)
+    .position("区域销售额", 0, 8, 24, 16)
+    .position("订单明细", 24, 8, 24, 16)
+    .build()
+```
+
+适用场景：同一个控件要同时绑定多个业务字段，用一组筛选驱动多个组件。
+
+### 8.15 控件默认值与排序
+
+```js
+DashboardDsl.create("带默认值的筛选")
+    .content()
+    .reference("月度趋势")
+    .control(
+        ControlItem.builder("地区筛选", ControlItem.TEXT_BUTTON_GROUP)
+            .bindField(from("销售表").dim("地区"))
+            .defaultValue(["华东"])
+            .sort("asc")
+            .multiSelect(false)
+            .build()
+    )
+    .presentation()
+    .position("地区筛选", 0, 0, 24, 8)
+    .position("月度趋势", 0, 8, 24, 16)
+    .build()
+```
+
+适用场景：控件需要预选某个业务值，并按升序稳定展示候选项。
+
+### 8.16 带目标字段的跳转
+
+```js
+DashboardDsl.create("区域驾驶舱")
+    .content()
+    .reference("区域销售图")
+    .jump(
+        "区域销售图",
+        JumpModel.toReport(
+            from("销售表").dim("地区"),
+            "区域专题看板",
+            from("销售表").dim("地区")
+        )
+    )
+    .presentation()
+    .position("区域销售图", 0, 0, 24, 16)
+    .build()
+```
+
+适用场景：从当前看板跳转到目标看板时，把当前选中的业务字段一并带过去做定位。
+
+### 8.17 默认移动端配置
+
+```js
+DashboardDsl.create("移动端默认配置")
+    .content()
+    .reference("经营概览")
+    .reference("订单明细")
+    .mobile()
+    .mobileConfig(MobileConfigModel.defaults())
+    .build()
+```
+
+适用场景：明确声明“移动端沿用平台默认配置”，避免由调用方再补默认值。
+
+## 9. 场景模板与设计要点
+
+`dashboard template` 的每个场景都给出可抄脚本 + 变量契约 + `guidance`（设计要点，共享要点在前、
+场景专属在后）。设计要点只讲**决策**（怎么摆、怎么取舍），语法与取值约束以本文档与
+`dashboard schema` 为准。
+
+| 场景 id | 形态 | 覆盖能力 |
+|---|---|---|
+| `basic` | 经营看板：筛选条 + KPI 富文本行 + 封面图 + 双图表联动 | 引用/标题/富文本（列表、链接、行内样式）/图片/控件 + controlRange/联动/网格 position/stylePreset/移动端 |
+| `kpi` | KPI 概览：富文本指标行 + 一张图 | 富文本动态字段；注释给出 KPI 指标卡组件的替代路径（`widget template --chart-type KPI_CARD`） |
+| `filter` | 筛选控件：多选列表 + 数值区间 + 日期区间 + 查询/重置/清空 | 控件属性族（title/required/sortByField/closeRange）与按钮族；日期过滤不写死默认区间 |
+| `style` | 样式面：预设基底 + 六分区微调 | stylePreset/customStyle + templateStyle（背景/卡片/图表配色/表格/过滤/图片）+ FontModel/TableFont |
+| `screen` | 大屏驾驶舱：固定基准 + 悬浮装饰 + 深色预设 | adaptive(AdaptiveModel.fitAuto/origin) + float + dynamicDefault 日期控件 |
+| `rich-text` | 富文本与动态字段：富标题 + 组件字段 + 行内样式 + 列表链接 | title(name, RichText)/widgetName()/componentField/styled/formatted/fieldValue 子链/图片 withHref |
+| `linkage-jump` | 联动与跳转：跨表自定义依赖字段联动 + 两型跳转（分析模板传值 / 网页链接占位符）+ 持久化联动效果 | linkage(LinkageModel.of)/linkageEffect(LinkageEffect.click + cell)/jump(JumpModel.toReport/toUrl + openPosition/name)；目标板字段先 `dashboard tables --id` 查候选；clickedValue 须取源组件数据里的真实显示值（空组合联动结果为空） |
+| `tree-time` | 层级与时间筛选：二级树（省→市）+ 时间按钮组驱动一张图 | TREE 的 bindField 声明序=层级（跨表层级须同关联分量）/多层级树无 defaultValue；TIME_GROUP + timeTags(TimeTag.preset(...).selected())，未标 selected 则首屏不过滤 |
+| `blocks` | 容器区块：冻结筛选栏 + Tab 页签（页内组合区块 + 明细页）+ 页脚长板 | combine(CombineItem.of/gap/withTitle)/tab(TabItem.of/page/selected/style)/freeze(FreezeItem.of/gap/showExpand)；成员单容器归属、成员不得顶层 position、组合悬浮须成员全悬浮 |
+
+通用设计要点（每个场景响应都会带回，节选）：
+
+- 结构：标题 → 筛选区 → 关键指标行 → 主分析区（1–2 行图表）→ 明细表（可选）。
+- 节奏：一屏 2–3 行组件；同类组件等宽（36+36 或 24+24+24）；`widgetGap` 8–16 留白。
+- 自适应：日常分析用省略态；汇报/大屏改固定基准尺寸（`origin`/`fitWidth`/`fitAuto`）。
+- 样式：整板一个基底 + `templateStyle` 局部微调；图表配色统一；字号不超过三档。
+- 交互：筛选组件置顶并用 `controlRange` 圈定；查询按钮保持默认自动查询（写 `autoQuery(false)`
+  且无默认值时首屏可能空板）。