# 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`。
- 危险操作保留明确文案、危险色、确认过程和成功/失败反馈，不只显示图标。
- 组件按适用语义覆盖加载、空数据、错误、禁用和无权限状态；保留键盘操作、可见焦点、表单标签、图标按钮名称和颜色对比度，不只用颜色表达状态。

## 修改与验证

- 扩展公共组件前定向检查全部消费者；通用能力扩展公共组件，纯业务特例留在模块，不用页面级 CSS 覆盖破坏公共契约。
- 至少运行组件测试、直接受影响页面测试和 `pnpm typecheck`；交付前按项目指引运行完整测试与构建。