仪表盘

如何创建仪表盘小部件并用 AppRegistry.dashboard.add 注册。DashboardItem 必须内联在 index.tsx，不要包在 widget 文件里。

概述

插件在 register(AppRegistry) 时向共享 ERP 仪表盘贡献小部件。Shell 负责布局、日期范围与持久化。

在 frontend/src/index.tsx 中调用 AppRegistry.dashboard.add
在注册处内联 DashboardItem — widget 文件只导出内容
注册 id 与 DashboardItem id 必须一致
在 DashboardItem 上传入 requiredApis 做 RBAC

1. 创建小部件（仅内容）

放在 frontend/src/page/dashboard/ 等路径。只导出内容组件，不要包 DashboardItem。日期范围用 useDashboardContext。

不要在 widget 文件中使用 DashboardItem
用 flex + h-full 填满单元格
按日期筛选时读取 startDate / endDate

TSXfrontend/src/page/dashboard/analytics-widget.tsx

import { useDashboardContext } from "@quan-erp/base-frontend";

export function AnalyticsWidget() {
  const { startDate, endDate } = useDashboardContext();

  return (
    <div className="flex flex-col w-full h-full p-4 gap-2">
      <h3>Analytics</h3>
      <span>Start {startDate.toLocaleDateString()}</span>
      <span>End {endDate.toLocaleDateString()}</span>
    </div>
  );
}

2. 用 AppRegistry.dashboard.add 注册

在插件入口内联 DashboardItem，并调用 AppRegistry.dashboard.add。

id — 全插件唯一；建议 `${metadata.name}-…`
pluginName — 等于 module.metadata.json 的 name
DashboardItem id — 必须等于注册 id
requiredApis — 使用 withApiMetadataFetchFn 的 .api

TSXfrontend/src/index.tsx

import type { AppRegistryState, PluginModule } from "@quan-erp/shared-types";
import { DashboardItem } from "@quan-erp/shared-ui";
import metadata from "../module.metadata.json" with { type: "json" };
import { getAnalyticsApi } from "./api/analytics.api";
import { AnalyticsWidget } from "./page/dashboard/analytics-widget";

const Plugin: PluginModule = {
  register(AppRegistry: AppRegistryState) {
    AppRegistry.dashboard.add({
      id: `${metadata.name}-analytics`,
      pluginName: metadata.name,
      element: (
        <DashboardItem
          id={`${metadata.name}-analytics`}
          colSpan={2}
          rowSpan={1}
          pluginName={metadata.name}
          requiredApis={[getAnalyticsApi.api]}
        >
          <AnalyticsWidget />
        </DashboardItem>
      ),
    });
  },
};

export default Plugin;

3. 仪表盘上下文

useDashboardContext() 提供全局筛选（如 startDate、endDate）。范围变化时让查询保持同步。

TSXuseDashboardContext

import { useDashboardContext } from "@quan-erp/base-frontend";

const { startDate, endDate } = useDashboardContext();
// Pass into react-query keys / API params so the widget refetches on range change

关键规则

在 index.tsx 内联 DashboardItem — 不要在 widget 内包装
注册 id 与 DashboardItem id 必须一致
id 在所有已安装插件中唯一
传入 requiredApis 做权限控制
Widget 文件只导出内容

检查清单

在 page/dashboard/ 创建仅内容小部件
按日期时使用 useDashboardContext
在 register() 中用匹配 id 调用 add
DashboardItem 带上 pluginName、colSpan、rowSpan、requiredApis
quan-erp watch 并安装后确认出现

常见失败

仪表盘上看不到 — 未注册 / pluginName 错误 / 未安装
布局跳动 — 注册 id ≠ DashboardItem id
无权限或空白 — requiredApis 缺失或错误
日期范围无效 — 未读 useDashboardContext
布局损坏 — 在 widget 文件中包装了 DashboardItem