Admin Shared Components Instructions

适用范围

本文件适用于 src/shared/components/ 及其直接测试。业务页面使用这些组件时，同时遵守 ../../../AGENTS.md 和 ../../../../../docs/Admin-Client前端原型还原验收规则.md。
这里只放与具体业务无关、已被多个模块真实复用的后台组件；纯业务字段、状态和流程留在所属模块。

标准列表使用 ListPageLayout 组织查询区和表格区，保持单一 16px 间距；不叠加页面级空白操作区或重复面板间距。
查询与筛选使用 QueryToolbar.vue，通过 fields、v-model、search、reset 接入；查询即刷新当前结果，不另设独立刷新按钮。
数据列表使用 DataTable.vue，通过 columns、命名插槽、v-model:page、v-model:page-size 和 total 接入，不重复拼装 el-table 与分页器。
“操作”列放在第一列，需要固定时固定在左侧。单行操作不超过 3 个时直接显示“图标 + 文案”；第 4 个起使用 MoreHorizontal 菜单，并优先直接保留详情、编辑、下载等高频操作。
列表操作统一使用 RowActions.vue：默认直接展示 3 个，通过 priority 决定高频或关键操作的展示资格，其余自动进入带可访问名称的“更多”菜单；权限和状态由业务页面生成 actions 时决定，组件不推导业务资格。
新增、导入、导出和批量操作放入 DataTable 的 toolbar-actions；不放入查询栏，不用 toolbar-start 重复列表标题、数量或说明，数量统一放在 pagination-left。
路由标题和说明默认由 AppLayout 的 page-heading 根据路由元数据展示；标准列表正文不重复标题。只有明确关闭路由页头的详情页或工作台才自带独立页头。

XLSX 批量导入使用 BatchImportDialog.vue；页面只提供模板下载、导入调用和成功后刷新，不复制文件校验、上传状态、错误报告或弹窗 CSS。
模态框和抽屉优先使用 AppDialog.vue、AppDrawer.vue；但独立页面、弹框或抽屉的选择必须服从对应原型，不因已有组件方便而替换承载方式。
AppDialog 未提供自定义 #header 时保留 Element 原生 title 标题栏；fullscreenable 只在原标题栏追加全屏控件，不得仅为标题或全屏按钮再造一层 header。只有原型确有复合标题结构时才使用 #header。
加载失败组合 LoadErrorState.vue 与 ApiErrorMeta.vue，保留重试和 requestId/traceId；状态与复制优先使用 StatusBadge.vue、CopyButton.vue。
参考页面：查询和表格见 ../../modules/master-data/express-companies/pages/ExpressCompaniesView.vue，批量导入见该页面与 ../../modules/master-data/counterparties/pages/PartnersView.vue，抽屉见 ../../modules/downloads/pages/DownloadCenterView.vue。

原型已定义图标时复用原型资源；原型未定义时使用 Lucide：查看 Eye、编辑 Pencil、更多 MoreHorizontal、新增 Plus、删除 Trash2、启停 Power、刷新 RefreshCw、导入 FileUp、导出/下载 Download、返回 ArrowLeft、保存 Save、复制 Copy。
危险操作保留明确文案、危险色、确认过程和成功/失败反馈，不只显示图标。
组件按适用语义覆盖加载、空数据、错误、禁用和无权限状态；保留键盘操作、可见焦点、表单标签、图标按钮名称和颜色对比度，不只用颜色表达状态。