openyida 宜搭 Dashboard 经营看板技能
核心定位
本技能负责完整 Dashboard 产品化交付：业务指标、真实数据、交互筛选、洞察、派单、截图和分享闭环。它决定“看什么、怎么组织、怎么验收”：
- 页面容器、状态、筛选、响应式、副作用：
yida-canvas-custom-page。 - Canvas 真实数据：
yida-canvas-data-binding。 - 常规图表：
yida-rechart。 - 只有用户明确要求 ECharts、需要复杂 ECharts
option/扩展系列，或维护已有图表时，才使用yida-chart。
何时触发
- 看板 / 驾驶舱 / 大屏 / Dashboard / 数据大屏。
- 经营看板 / 业务看板 / 管理驾驶舱 / 高层汇报。
- 指标卡截图、组织内短链、隐藏导航、看板派单闭环。
单个普通统计报表优先 yida-report；只解决单张图的实现问题时按“图表路由边界”选择 yida-rechart 或 yida-chart。
默认交付物
- 单屏控制塔结构，见
references/structure-and-layout.md。 - 真实数据绑定：聚合指标走报表/聚合结果，明细走分页查询；禁止前端拉全量后聚合。
- 视觉主题和信息层级，见
references/theme-presets.md。默认从podBlue、podGreen、podOrange等应用主题中选择；平台预置主题使用应用--theme，自定义色盘使用应用级主题 CSS 文件，页面只消费运行时变量。 - 筛选与图表联动；控件必须受控并真实改变下方数据。
- 每元素可派单：
saveFormData → 集成自动化 → 待办2.0 ConnectorCall。 - 卡片截图分享：真实可点击，截图时排除截图按钮本身。
- PC / 平板 / 手机响应式。
- 隐藏导航时的组织内分享 URL；需要页面内导航壳时调用
yida-nav-shell。 - loading / empty / error / freshness 状态与 1–3 条业务洞察。
实现边界
| 信号 | 处理 |
|---|---|
| 表单/报表/连接器数据进入 Canvas | yida-canvas-data-binding，用同源 HTTP 数据桥 |
| 用户明确要求 ECharts 或提供 ECharts option | yida-chart |
| 地图、桑基、graph、custom series 等 Recharts 不覆盖的复杂图 | 明确说明原因后使用 yida-chart |
| 单个原生统计报表 | yida-report |
维护平台 JSX 组件页面时看到的 .oyd.jsx、renderJsx、didMount 片段属于平台实例桥写法，只能作为对应运行时参考。
交付流程
[Step 1] 澄清业务范围 → 5–8 个经营维度、指标、角色与刷新频率
↓
[Step 2] 数据契约 → appType/formUuid/fieldId/report/connector endpoint
↓
[Step 3] 需要派单时创建“看板派单触发表”并配置集成自动化
↓
[Step 4] 用 yida-design 决定 dashboard/screen、主题、Shell、Archetype
↓
[Step 5] 生成或编写 dashboard-overview.canvas.jsx / data-screen.canvas.jsx
↓
[Step 6] 用 hooks 实现筛选、轮询、截图、hash/导航与 cleanup
↓
[Step 7] 常规图表交 yida-rechart；仅命中 ECharts 条件才交 yida-chart
↓
[Step 8] compileCanvasLocal 快检；获用户确认后发布并回读 Schema
↓
[Step 9] 隐藏导航、验证组织内 URL、截图、数据刷新和派单闭环
自定义页面入口：
prd.md决定页面目标、指标、区块和交互，design.md决定主题、布局和视觉状态；page-spec.json只作为生成器需要时的派生输入。- 默认主题从
podBlue、podGreen、podOrange等应用主题中选择；用户明确要求应用主题风格/应用主题色时，才使用yida-app-theme。 - 用户强调“大屏 / 指挥舱 / 实时监控”时使用
screen场景；普通经营看板使用dashboard场景。 .canvas.jsx编译与发布细节以yida-canvas-custom-page为准；不要把openyida check-page、.oyd.jsx或renderJsx写成默认步骤。
数据与派单边界
真实数据
- KPI / 趋势 / 占比必须来自服务端聚合、报表结果或明确的聚合接口。
- 明细查询必须分页；不得拉全量后
reduce冒充生产聚合。 - 使用
YidaCodeCanvas组件实现的页面使用dataBinding+DataBridge+ 外层 yida JS-API 桥；只有桥不可用时才降级同源fetch，并保留错误态与 cleanup。 - 不得在
YidaCodeCanvas组件内使用this.dataSourceMap；连接器代理转yida-canvas-data-binding。 - demo/seed 只能用于离线预览，并明确标记；真实交付无数据时展示真实空态。
派单
需要派单时固定使用：
yida-create-form-page创建“看板派单触发表”，至少包含subject/executor/description/dueTime/priority/priorityNum。openyida integration create ... --events create配置待办2.0 ConnectorCall。- 前端只写触发表；连接器鉴权和调用留在后端集成自动化。
priority 连接器入参必须来自 NumberField priorityNum（10/20/30/40），不能直接透传 SelectField/RadioField。不得把工作通知包装成真实待办。
自定义页面实现纪律
- 使用
YidaCompReact 函数组件和 hooks；不使用_customState/forceUpdate。 useEffect注册的轮询、键盘、resize、hash、截图资源或图表副作用必须 cleanup。- 筛选、周期切换、Tabs、刷新按钮均为受控状态，并真实驱动列表/KPI/图表派生数据。
- 所有数据请求都有 loading / error / retry；静默刷新保留旧数据。
- 所有可见按钮必须有真实 handler 或显式 disabled。
- 截图按钮必须可用，并在截图时用 class/属性排除自身。
- 移动端 KPI 改 2 列或横向滚动，图表纵向堆叠。
- 隐藏应用导航后需要跨模块切换时，交
yida-nav-shell，默认用 ReactuseState/ hash。
图表路由边界
默认：yida-rechart
以下图表默认调用：
use_skill("yida-rechart", "在自定义页面看板中实现常规业务图表")
- 折线、面积、柱、条、饼/环、组合图。
- 常规 tooltip、legend、响应式容器、主题色和数据格式化。
- KPI 趋势、区域营收、渠道贡献、客群分布、排行与同比环比。
例外：yida-chart
只有出现以下任一信号时调用：
use_skill("yida-chart", "实现明确要求的 ECharts 或维护旧 native 图表")
- 用户明确说 ECharts。
- 用户提供或要求维护复杂 ECharts
option。 - 地图、桑基、graph、custom series、复杂 visualMap 等 Recharts 不覆盖能力。
- 维护已有普通自定义页 / native ECharts 页面。
不要仅因“看板里有图”就调用 yida-chart。
平台 JSX 组件维护注意事项
.oyd.jsx / .oyb.jsx / renderJsx / 平台 Jsx 组件页面，若现有页面依赖 this.utils.yida.*、this.dataSourceMap、renderJsx、didMount 等实例桥，维护时注意：
- 页面规范按平台 JSX 组件页面规则执行。
- 旧 ECharts 图表交
yida-chart。 - 本地使用
.oyd.jsx、openyida check-page、openyida compile。 - references 中的
renderJsx/didMount片段仅供维护平台 JSX 组件页面。
严格禁止
- 禁止生成与目标运行时不匹配的页面源码。
- 禁止前端拉全量明细聚合 KPI。
- 禁止 Canvas 使用
this.dataSourceMap、this.utils.yida.*或平台 JSX 组件生命周期。 - 禁止在前端直连钉钉 OpenAPI、硬编码 accessToken/Cookie/密钥。
- 禁止把工作通知声称为真实待办。
- 禁止 mock/seed 数据冒充真实交付。
- 禁止无 handler 的按钮。
- 禁止常规图表无条件路由
yida-chart。
参考文档
| 文档 | 何时读 |
|---|---|
references/structure-and-layout.md |
设计 Dashboard 层次、Canvas 组件树和响应式 |
references/theme-presets.md |
选择主题、色板和图表视觉强度 |
references/interaction-patterns.md |
派单、搜人、截图、marquee、短链；旧普通页代码仅作维护参考 |
references/pitfalls.md |
发布前检查数据、连接器、截图与平台 JSX 组件页面兼容问题 |
验收
- Canvas 本地编译通过，依赖只包含白名单模块。
- 发布后回读到
YidaCodeCanvas与非空runtimeCode。 - 至少一个 KPI/列表/图表来自真实数据契约；否则标记 draft。
- 筛选、刷新、移动端、截图、空/载/错态实际可用。
- 常规图表已使用
yida-rechart；使用yida-chart时交付说明明确命中了哪条 ECharts 例外。 - 需要派单时，真实待办 ConnectorCall 和字段映射验证通过。
- 隐藏导航时，最终组织内 URL 保留
isRenderNav=false。