9-01 · 增强层总览：导出边界与双重守卫

// packages/pro-components/component-manifest.json（L1-73：form 组 9 条完整原文）
[
  {
    "name": "search-form",
    "docsGroup": "form",
    "docsText": "SearchForm 搜索表单",
    "installExports": ["XySearchForm"],
    "installChecks": [{ "kind": "component", "name": "xy-search-form" }],
    "styleImports": ["search-form"]
  },
  {
    "name": "pro-form",
    "docsGroup": "form",
    "docsText": "ProForm 增强表单",
    "installExports": ["XyProForm"],
    "installChecks": [{ "kind": "component", "name": "xy-pro-form" }],
    "styleImports": ["pro-form"]
  },
  {
    "name": "overlay-form",
    "docsGroup": "form",
    "docsText": "OverlayForm 浮层表单",
    "installExports": ["XyOverlayForm"],
    "installChecks": [{ "kind": "component", "name": "xy-overlay-form" }],
    "styleImports": ["overlay-form"]
  },
  {
    "name": "dialog-form",
    "docsGroup": "form",
    "docsText": "DialogForm 弹窗表单",
    "installExports": ["XyDialogForm"],
    "installChecks": [{ "kind": "component", "name": "xy-dialog-form" }],
    "styleImports": ["dialog-form"]
  },
  {
    "name": "drawer-form",
    "docsGroup": "form",
    "docsText": "DrawerForm 抽屉表单",
    "installExports": ["XyDrawerForm"],
    "installChecks": [{ "kind": "component", "name": "xy-drawer-form" }],
    "styleImports": ["drawer-form"]
  },
  {
    "name": "steps-form",
    "docsGroup": "form",
    "docsText": "StepsForm 分步表单",
    "installExports": ["XyStepsForm"],
    "installChecks": [{ "kind": "component", "name": "xy-steps-form" }],
    "styleImports": ["steps-form"]
  },
  {
    "name": "filter-panel",
    "docsGroup": "form",
    "docsText": "FilterPanel 筛选面板",
    "installExports": ["XyFilterPanel"],
    "installChecks": [{ "kind": "component", "name": "xy-filter-panel" }],
    "styleImports": ["filter-panel"]
  },
  {
    "name": "request-form",
    "docsGroup": "form",
    "docsText": "RequestForm 请求表单",
    "installExports": ["XyRequestForm"],
    "installChecks": [{ "kind": "component", "name": "xy-request-form" }],
    "styleImports": ["request-form"]
  },
  {
    "name": "login-form",
    "docsGroup": "form",
    "docsText": "LoginForm 登录表单",
    "installExports": ["XyLoginForm"],
    "installChecks": [{ "kind": "component", "name": "xy-login-form" }],
    "styleImports": ["login-form"]
  },

// packages/pro-components/component-manifest.ts（L60-70：manifest 的四个派生导出）
export const proPublicComponentNames = proComponentManifest.map((entry) => entry.name);

export const proInstallableComponentExportNames = proComponentManifest.flatMap(
  (entry) => entry.installExports
);

export const proInstallCheckEntries = proComponentManifest.flatMap((entry) => entry.installChecks);

export const proThemeStyleImportNames = Array.from(
  new Set(proComponentManifest.flatMap((entry) => entry.styleImports))
);

// packages/pro-components/component-manifest.json（L106-113：ProTable 条目；L202-209：ListPage 条目）
  {
    "name": "pro-table",
    "docsGroup": "data",
    "docsText": "ProTable 增强表格",
    "installExports": ["XyProTable"],
    "installChecks": [{ "kind": "component", "name": "xy-pro-table" }],
    "styleImports": ["pro-table"]
  },

// packages/pro-components/component-manifest.json（L202-209：ListPage 条目）
  {
    "name": "list-page",
    "docsGroup": "page",
    "docsText": "ListPage 列表页面容器",
    "installExports": ["XyListPage"],
    "installChecks": [{ "kind": "component", "name": "xy-list-page" }],
    "styleImports": ["list-page"]
  },

// packages/pro-components/exports.ts（L1-31：全文，显式值导出白名单）
export { XySearchForm } from "./search-form";
export { XyProForm } from "./pro-form";
export { XyOverlayForm } from "./overlay-form";
export { XyDialogForm } from "./dialog-form";
export { XyDrawerForm } from "./drawer-form";
export { XyStepsForm } from "./steps-form";
export { XyFilterPanel } from "./filter-panel";
export { XyRequestForm } from "./request-form";
export { XyLoginForm } from "./login-form";
export { XyPageToolbar } from "./page-toolbar";
export { XyPageHeader } from "./page-header";
export { XyPageContainer } from "./page-container";
export { XyAvatarMenu } from "./avatar-menu";
export { XyProTable } from "./pro-table";
export { XyHeaderTabs } from "./header-tabs";
export { XyNoticeCenter } from "./notice-center";
export { XyStatCard } from "./stat-card";
export { XyColumnSettingPanel } from "./column-setting-panel";
export { XySavedViewTabs } from "./saved-view-tabs";
export { XyTableFilterDrawer } from "./table-filter-drawer";
export { XyImportResultTable } from "./import-result-table";
export { XyAuditTimeline } from "./audit-timeline";
export { XyDetailPanel } from "./detail-panel";
export { XyDetailPage } from "./detail-page";
export { XyAsyncStateContainer } from "./async-state-container";
export { XyListPage } from "./list-page";
export { XyCrudPage } from "./crud-page";
export { XySplitLayoutPage } from "./split-layout-page";
export { XyApprovalFlowPanel } from "./approval-flow-panel";
export { XyImportWizard } from "./import-wizard";
export { XyExportTaskPanel } from "./export-task-panel";

// packages/pro-components/index.ts（L1-36：头部与类型白名单开篇）
import type { App, Plugin } from "vue";
import "./style.css";
import * as ProComponentExports from "./exports";
import { proInstallableComponentExportNames } from "./component-manifest";

export * from "./exports";
export type {
  SearchFormField,
  SearchFormInstance,
  SearchFormProps
} from "./search-form";
export type {
  ProFormInstance,
  ProFormProps
} from "./pro-form";
export type {
  OverlayFormInstance,
  OverlayFormProps,
  OverlayFormSubmitPayload
} from "./overlay-form";
export type {
  DialogFormInstance,
  DialogFormProps,
  DialogFormSubmitPayload
} from "./dialog-form";
export type {
  DrawerFormInstance,
  DrawerFormProps,
  DrawerFormSubmitPayload
} from "./drawer-form";
export type {
  StepsFormInstance,
  StepsFormProps,
  StepsFormStep
} from "./steps-form";
export type { FilterPanelProps } from "./filter-panel";

// packages/pro-components/index.ts（L127-144：core.ts 稳定共享协议的 16 个类型）
export type {
  ProActionRef,
  ProDisplayFormatter,
  ProDisplayHtmlRenderer,
  ProDisplayOption,
  ProDisplayOptionGroup,
  ProDisplayRenderContext,
  ProDisplayRenderer,
  ProDisplayValueType,
  ProFieldSchema,
  ProFieldSchemaBuiltinComponent,
  ProFieldSchemaOption,
  ProPageAction,
  ProRequestActionRef,
  ProRequestContext,
  ProRequestData,
  ProRequestResult
} from "./core";

// packages/pro-components/index.ts（L146-183：INSTALL_KEY 幂等锁与聚合安装）
const INSTALL_KEY = Symbol.for("xiaoye-pro-components:installed");

function isInstallableExport(value: unknown): value is Plugin {
  return (
    (typeof value === "function" || typeof value === "object") &&
    value !== null &&
    "install" in value &&
    typeof (value as { install?: unknown }).install === "function"
  );
}

const installableExports = Array.from(
  new Set(
    proInstallableComponentExportNames
      .map((name) => ProComponentExports[name as keyof typeof ProComponentExports])
      .filter(isInstallableExport)
  )
) as Plugin[];

export function install(app: App) {
  const appWithInstallFlag = app as App & {
    [INSTALL_KEY]?: boolean;
  };

  if (appWithInstallFlag[INSTALL_KEY]) {
    return;
  }

  appWithInstallFlag[INSTALL_KEY] = true;

  installableExports.forEach((component) => {
    app.use(component);
  });
}

export default {
  install
};

// tests/types/fixtures/pro-root-boundary.ts（L1-44：全文，@ts-expect-error 断言阵）
// @ts-expect-error 根入口不再暴露 ProTable 工具栏动作细节类型
import type { ProTableToolbarAction } from "@xiaoye/pro-components";
// @ts-expect-error 根入口不再暴露 ProTable 排序载荷细节类型
import type { ProTableSortChangePayload } from "@xiaoye/pro-components";
// @ts-expect-error 根入口不再暴露 ProTable 单元格插槽细节类型
import type { ProTableCellSlotProps } from "@xiaoye/pro-components";
// @ts-expect-error 根入口不再暴露审批动作别名
import type { ApprovalFlowAction } from "@xiaoye/pro-components";
// @ts-expect-error 根入口不再暴露时间线内部状态枚举
import type { AuditTimelineStatus } from "@xiaoye/pro-components";
// @ts-expect-error 根入口不再暴露浮层表单容器细节类型
import type { OverlayFormContainer } from "@xiaoye/pro-components";
// @ts-expect-error 根入口不再暴露浮层表单模式细节类型
import type { OverlayFormMode } from "@xiaoye/pro-components";
// @ts-expect-error 根入口不再暴露详情面板容器细节类型
import type { DetailPanelContainer } from "@xiaoye/pro-components";
// @ts-expect-error 根入口不再暴露分栏布局字面量类型
import type { SplitLayoutPageLayout } from "@xiaoye/pro-components";
// @ts-expect-error 根入口不再暴露 SearchForm 内建组件枚举
import type { SearchFormFieldBuiltinComponent } from "@xiaoye/pro-components";

// @ts-expect-error 经 xiaoye-pro-components 包名解析到同一根入口，同样不再暴露 ProTable 工具栏动作细节类型
import type { ProTableToolbarAction as XiaoyeProTableToolbarAction } from "xiaoye-pro-components";
// @ts-expect-error 经 xiaoye-pro-components 包名解析到同一根入口，同样不再暴露 ProTable 排序载荷细节类型
import type { ProTableSortChangePayload as XiaoyeProTableSortChangePayload } from "xiaoye-pro-components";
// @ts-expect-error 经 xiaoye-pro-components 包名解析到同一根入口，同样不再暴露 ProTable 单元格插槽细节类型
import type { ProTableCellSlotProps as XiaoyeProTableCellSlotProps } from "xiaoye-pro-components";
// @ts-expect-error 经 xiaoye-pro-components 包名解析到同一根入口，同样不再暴露审批动作别名
import type { ApprovalFlowAction as XiaoyeApprovalFlowAction } from "xiaoye-pro-components";
// @ts-expect-error 经 xiaoye-pro-components 包名解析到同一根入口，同样不再暴露时间线内部状态枚举
import type { AuditTimelineStatus as XiaoyeAuditTimelineStatus } from "xiaoye-pro-components";
// @ts-expect-error 经 xiaoye-pro-components 包名解析到同一根入口，同样不再暴露浮层表单容器细节类型
import type { OverlayFormContainer as XiaoyeOverlayFormContainer } from "xiaoye-pro-components";
// @ts-expect-error 经 xiaoye-pro-components 包名解析到同一根入口，同样不再暴露浮层表单模式细节类型
import type { OverlayFormMode as XiaoyeOverlayFormMode } from "xiaoye-pro-components";
// @ts-expect-error 经 xiaoye-pro-components 包名解析到同一根入口，同样不再暴露详情面板容器细节类型
import type { DetailPanelContainer as XiaoyeDetailPanelContainer } from "xiaoye-pro-components";
// @ts-expect-error 经 xiaoye-pro-components 包名解析到同一根入口，同样不再暴露分栏布局字面量类型
import type { SplitLayoutPageLayout as XiaoyeSplitLayoutPageLayout } from "xiaoye-pro-components";
// @ts-expect-error 经 xiaoye-pro-components 包名解析到同一根入口，同样不再暴露 SearchForm 内建组件枚举
import type { SearchFormFieldBuiltinComponent as XiaoyeSearchFormFieldBuiltinComponent } from "xiaoye-pro-components";

void 0;

// scripts/check-pro-components.mjs（L10-75：rootTypeWhitelist——根入口类型白名单的预期表）
const rootTypeWhitelist = {
  "search-form": ["SearchFormField", "SearchFormInstance", "SearchFormProps"],
  "pro-form": ["ProFormInstance", "ProFormProps"],
  "overlay-form": ["OverlayFormInstance", "OverlayFormProps", "OverlayFormSubmitPayload"],
  "dialog-form": ["DialogFormInstance", "DialogFormProps", "DialogFormSubmitPayload"],
  "drawer-form": ["DrawerFormInstance", "DrawerFormProps", "DrawerFormSubmitPayload"],
  "steps-form": ["StepsFormInstance", "StepsFormProps", "StepsFormStep"],
  "filter-panel": ["FilterPanelProps"],
  "request-form": ["RequestFormProps", "RequestFormSubmitContext"],
  "login-form": [
    "LoginFormInstance",
    "LoginFormModel",
    "LoginFormProps",
    "LoginFormThirdPartyItem"
  ],
  "page-toolbar": ["PageToolbarProps"],
  "page-header": ["PageHeaderProps", "PageIcon", "PageMetaItem"],
  "page-container": ["PageContainerProps"],
  "avatar-menu": ["AvatarMenuCommand", "AvatarMenuItem", "AvatarMenuProps"],
  "pro-table": ["ProTableColumn", "ProTableInstance", "ProTableProps"],
  "header-tabs": ["HeaderTabItem", "HeaderTabsMenuAction", "HeaderTabsProps"],
  "notice-center": [
    "NoticeCenterAction",
    "NoticeCenterItem",
    "NoticeCenterProps",
    "NoticeCenterTab"
  ],
  "stat-card": ["StatCardProps", "StatTrend"],
  "column-setting-panel": ["ColumnSettingPanelColumn", "ColumnSettingPanelProps"],
  "saved-view-tabs": ["SavedViewTabItem", "SavedViewTabsProps"],
  "table-filter-drawer": ["TableFilterDrawerProps"],
  "import-result-table": ["ImportResultSummary", "ImportResultTableProps"],
  "audit-timeline": ["AuditTimelineAttachment", "AuditTimelineEntry", "AuditTimelineProps"],
  "detail-panel": ["DetailPanelInstance", "DetailPanelProps"],
  "detail-page": [
    "DetailPageAction",
    "DetailPageAttachmentFile",
    "DetailPageBreadcrumbItem",
    "DetailPageProps"
  ],
  "async-state-container": ["AsyncStateContainerProps"],
  "list-page": ["ListPageActionRef", "ListPageBatchAction", "ListPageProps"],
  "crud-page": ["CrudPageProps"],
  "split-layout-page": ["SplitLayoutPageProps"],
  "approval-flow-panel": ["ApprovalFlowNode", "ApprovalFlowPanelProps"],
  "import-wizard": ["ImportWizardProps", "ImportWizardStep"],
  "export-task-panel": ["ExportTaskItem", "ExportTaskPanelProps"],
  core: [
    "ProDisplayFormatter",
    "ProDisplayHtmlRenderer",
    "ProDisplayOption",
    "ProDisplayOptionGroup",
    "ProDisplayRenderContext",
    "ProDisplayRenderer",
    "ProDisplayValueType",
    "ProActionRef",
    "ProFieldSchema",
    "ProFieldSchemaBuiltinComponent",
    "ProFieldSchemaOption",
    "ProPageAction",
    "ProRequestActionRef",
    "ProRequestContext",
    "ProRequestData",
    "ProRequestResult"
  ]
};

// scripts/check-pro-components.mjs（L98-139：命名导出的抠取与双向 diff）
function normalizeNamedExports(source, regex) {
  const result = {};

  for (const match of source.matchAll(regex)) {
    const names = match[1]
      .split(",")
      .map((value) => value.trim())
      .filter(Boolean)
      .sort();

    result[match[2]] = names;
  }

  return result;
}

function diffNamedExportMap(expected, actual) {
  const messages = [];
  const expectedKeys = Object.keys(expected).sort();
  const actualKeys = Object.keys(actual).sort();

  diff(expectedKeys, actualKeys).forEach((key) => {
    messages.push(`${key} (缺少导出块)`);
  });

  diff(actualKeys, expectedKeys).forEach((key) => {
    messages.push(`${key} (多余导出块)`);
  });

  expectedKeys.forEach((key) => {
    if (!actual[key]) {
      return;
    }

    const missing = diff(expected[key], actual[key]).map((name) => `${key} -> ${name} (缺少导出)`);
    const extra = diff(actual[key], expected[key]).map((name) => `${key} -> ${name} (多余导出)`);

    messages.push(...missing, ...extra);
  });

  return messages.sort();
}

// scripts/check-pro-components.mjs（L226-331：事实采集、11 类校验与收尾）
const componentDirs = listProComponentDirs();
const exportsSource = readFile("packages/pro-components/exports.ts");
const rootIndexSource = readFile("packages/pro-components/index.ts");
const exportedComponentNames = collectByRegex(
  exportsSource,
  /export(?:\s+\{[^}]+\}\s+from|\s+\*\s+from)\s+"\.\/*([^"]+)";/g
);
const exportedComponentValues = normalizeNamedExports(
  exportsSource,
  /export\s+\{([^}]+)\}\s+from\s+"\.\/*([^"]+)";/g
);
const rootTypeExports = normalizeNamedExports(
  rootIndexSource,
  /export type\s+\{([\s\S]*?)\}\s+from\s+"\.\/*([^"]+)";/g
);
const docComponentNames = listBasenames("apps/docs/pro-components", ".md").filter(
  (name) => name !== "overview"
);
const exampleDocNames = listBasenames("apps/docs/examples/pro", ".md").filter(
  (name) => name !== "overview"
);
const typeFixtureNames = listBasenames("tests/types/fixtures", ".ts").filter((name) =>
  componentNames.includes(name)
);
const unitTestNames = listProComponentTestGroups();
const styleImportNames = collectByRegex(
  readFile("packages/pro-components/style.css"),
  /@import "\.\.\/theme\/src\/pro\/([^.]+)\.css";/g
);
const docFiles = fs
  .readdirSync(path.join(repoRoot, "apps/docs/pro-components"))
  .filter((name) => name.endsWith(".md"))
  .map((name) => `apps/docs/pro-components/${name}`);
const exampleDocFiles = fs
  .readdirSync(path.join(repoRoot, "apps/docs/examples/pro"))
  .filter((name) => name.endsWith(".md"))
  .map((name) => `apps/docs/examples/pro/${name}`);
const proTypeFixtureExists = fs.existsSync(
  path.join(repoRoot, "tests/types/fixtures/xiaoye-pro-components.ts")
);

const mismatches = [
  {
    message: "增强公开组件目录缺失：",
    values: diff(componentNames, componentDirs)
  },
  {
    message: "增强导出入口与 manifest 不一致：",
    values: [
      ...diff(componentNames, exportedComponentNames),
      ...diff(exportedComponentNames, componentNames).map((name) => `${name} (多余导出)`)
    ]
  },
  {
    message: "增强值导出白名单与 manifest 不一致：",
    values: diffNamedExportMap(
      Object.fromEntries(
        manifest.map((entry) => [entry.name, [...entry.installExports].sort()])
      ),
      exportedComponentValues
    )
  },
  {
    message: "增强组件文档缺失：",
    values: diff(componentNames, docComponentNames)
  },
  {
    message: "增强示例文档缺失：",
    values: diff(componentNames, exampleDocNames)
  },
  {
    message: "增强类型夹具缺失：",
    values: diff(componentNames, typeFixtureNames)
  },
  {
    message: "增强组件单测缺失：",
    values: diff(componentNames, unitTestNames)
  },
  {
    message: "增强样式入口缺失：",
    values: diff(styleNames, styleImportNames)
  },
  {
    message: "增强文档 demo 引用缺失：",
    values: [
      ...collectDocDemoMismatches(docFiles),
      ...collectDocDemoMismatches(exampleDocFiles)
    ]
  },
  {
    message: "增强聚合包类型夹具缺失：",
    values: proTypeFixtureExists ? [] : ["tests/types/fixtures/xiaoye-pro-components.ts"]
  },
  {
    message: "增强根入口类型白名单与约定不一致：",
    values: diffNamedExportMap(rootTypeWhitelist, rootTypeExports)
  }
];

mismatches
  .filter((entry) => entry.values.length > 0)
  .forEach((entry) => fail(entry.message, entry.values));

if (process.exitCode !== 1) {
  console.log(`增强组件一致性校验通过，共校验 ${componentNames.length} 个增强组件。`);
}

// packages/pro-components/__tests__/install.spec.ts（L1-35：全文，聚合安装幂等断言）
import { createApp, defineComponent, h } from "vue";
import { describe, expect, it, vi } from "vitest";
import XiaoyeProComponents from "../index";
import { proInstallCheckEntries } from "../component-manifest";

describe("XiaoyeProComponents", () => {
  it("重复 install 到同一个 app 时保持幂等", () => {
    const app = createApp(
      defineComponent({
        render() {
          return h("div");
        }
      })
    );

    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});

    XiaoyeProComponents.install(app);
    XiaoyeProComponents.install(app);

    proInstallCheckEntries.forEach((entry) => {
      if (entry.kind === "component") {
        expect(app.component(entry.name)).toBeTruthy();
      }
    });

    expect(
      warnSpy.mock.calls.some((args) =>
        String(args[0]).includes("already been registered in target app")
      )
    ).toBe(false);

    warnSpy.mockRestore();
  });
});

// packages/pro-components/package.json（L3 与 L44-48：版本与 peerDependencies）
  "version": "2.0.0",
  "peerDependencies": {
    "vue": "^3.5.0",
    "vue-router": "^4.6.0",
    "xiaoye-components": "workspace:^"
  },