Dashboard-level filters follow-ups: showcase, more examples, docs, spec pairing (#2576 / framework#2501)

[os-zhuang]

#2576(dashboard 级过滤器,framework#2501 的 objectui 侧)已合并。本 issue 汇总合并时明确留下的后续任务,可按条目拆分认领。

1. 完善 showcase / 增加示例

• schema-catalog 目前只有一个 plugin-dashboard/filtered-dashboard 示例;补充更多形态:
  • optionsFrom 动态选项(从对象记录取 distinct 值)的示例;
  • text / number / lookup 过滤器示例;
  • dataset 部件(dataset + runtimeFilter)与 inline 部件混排的示例;
  • targetWidgets 白名单兼容语义的示例;
  • 自定义日期区间(allowCustomRange)+ 各日期预设的演示。
• 在 console/app-shell 的演示环境(有真实 dataSource)里加一个可交互的 filtered dashboard showcase,验证跨对象图表联动的真实取数路径。
• 示例数据:为 showcase 准备两个不同对象(如 invoices / accounts)的种子数据,让"各图表绑定各自字段"肉眼可见。

2. 更新文档

• content/docs 的 dashboard 指南页(guide 侧)补一节完整教程:从零配置 dateRange + globalFilters + filterBindings,含截图;
• 补充 page.<name> 表达式在 widget 内引用过滤值的用法示例;
• 文档化已知限制并给出规避方式:
  • 嵌入带自有 variables 的 Page 时,dashboard 内层 PageVariablesProvider 会遮蔽外层(合并上下文为候选方案);
  • 静态数据部件(inline data)不受过滤;
  • 缺省绑定命中对象上不存在的字段时部件会空/报错 → 用 filterBindings: false 退出。
• i18n:DashboardFilterBar 文案目前走 useSafeTranslate 英文兜底,补 dashboard.filters.* 的 en / zh-CN 词条。

3. Spec 配对(framework 仓)

• 在 @objectstack/spec 落地 GlobalFilterSchema.name 与 DashboardWidgetSchema.filterBindings(objectui 本地类型已按 dataset/categoryGranularity 先例以 "Pending alignment" JSDoc 标注);落地后移除标注。
• spec 落地后确认 metadata-admin 检查器(dashboard-schema.ts,直接从 spec 派生)自动出现新属性。

4. Studio / 设计器

• Studio 部件检查器增加 filterBindings 可视化编辑(每个 dashboard 过滤器 → 本部件字段的下拉映射 + 退出开关);当前仅可通过 JSON 元数据配置。

5. 增强项(低优先)

• optionsFrom 目前客户端取 top 200 去重;改为服务端 distinct 查询;
• 缺省绑定做 metadata 感知:字段在对象上不存在时自动跳过并告警,而不是发出无效查询;
• 嵌套 Page variables 的上下文合并(解除遮蔽限制)。

Refs: #2576, objectstack-ai/objectstack#2501

[os-zhuang]

认领并已提交 PR 覆盖以下条目(两个 PR 同分支名配对):

• objectui feat(dashboard-filters): #2578 follow-ups — catalog examples, guide tutorial, i18n entries, spec-alignment cleanup #2581:
  • §1 showcase 示例:schema-catalog 新增 5 个 plugin-dashboard/filtered-dashboard-* 示例(optionsFrom 动态选项、text/number/lookup 过滤器、dataset + inline 混排、targetWidgets 白名单、日期预设 + allowCustomRange);
  • §2 文档:新增 guide 页 content/docs/guide/dashboard-filters.md(从零教程、page.* 表达式用法、已知限制与规避方式),plugin-dashboard.mdx 交叉链接;
  • §2 i18n:dashboard.filters.* 的 en / zh 词条;
  • §3 objectui 侧:Pending alignment 标注改为 Aligned。
• framework #3035(§3 spec 配对):GlobalFilterSchema.name + DashboardWidgetSchema.filterBindings 落地 @objectstack/spec(附测试 + changeset),并补了 content/docs/ui/dashboards.mdx 对应章节。metadata-admin 检查器(dashboard-schema.ts)从 spec 派生,objectui 升级 spec 依赖后新属性会自动出现——这一确认需等 spec 发版后跟进。

仍待认领:§1 的 console/app-shell 可交互 showcase + invoices/accounts 种子数据(guide 页截图也依赖它)、§4 Studio 检查器可视化编辑、§5 三项低优先增强。

---

Generated by Claude Code

[os-zhuang]

本 issue 各条目已全部处理完毕,共 5 个 PR 全部合并:

条目	PR	内容
§3 spec 配对	objectstack-ai/objectstack#3035	GlobalFilterSchema.name + DashboardWidgetSchema.filterBindings 落地 @objectstack/spec(附测试 + changeset);content/docs/ui/dashboards.mdx 补齐对应章节
§1 示例 + §2 文档/i18n	#2581	schema-catalog 新增 5 个 filtered-dashboard-* 示例;新 guide 页 dashboard-filters.md(从零教程、page.* 表达式、已知限制);dashboard.filters.* en/zh 词条;"Pending alignment" 标注清理
§1 可交互 showcase + 种子数据	objectstack-ai/objectstack#3038	showcase 新增 showcase_revenue_pulse 仪表盘(日期 + 地区过滤器驱动发票/账户两个对象,issued_on/region vs signed_on/sales_region 逐部件映射 + 双退出 KPI);账户/发票对象补字段,发票种子 4 → 12 跨约 6 个月三地区;已在 objectstack dev --fresh 真实后端验证元数据往返与 runtimeFilter SQL/行数
§4 Studio 检查器	#2586	部件检查器新增"仪表盘过滤器绑定"区:每个过滤器一行,「应用」开关(退出)+ 字段下拉(留空 = 默认,可恢复);行列表复用运行时 resolveDashboardFilterDefs
§5 三项增强	#2590	① 嵌套 PageVariablesProvider 合并(外层变量在仪表盘内可读,仅同名遮蔽,写入路由到定义方作用域);② 缺省绑定 metadata 感知(字段不存在时跳过 + 告警,显式绑定始终生效);③ optionsFrom 服务端 distinct(dataset GROUP BY,客户端 top-200 为回退)

遗留(已在文档注明,暂不单开条目):

• guide 页截图:待一次浏览器走查(Revenue Pulse showcase 已具备真实环境,可随下次 dogfood 顺手补);
• dataset 部件的缺省绑定无法做 metadata 校验(仪表盘不知道 dataset 基对象字段)——guide 已注明用显式 filterBindings 规避;
• metadata-admin 检查器将在 objectui 升级 @objectstack/spec 依赖(含 framework#3035 的发版)后自动出现新属性,届时确认即可。

可以关闭本 issue。

---

Generated by Claude Code