优化

AGENTS.md

@@ -52,6 +52,16 @@
 - 保持键盘可操作、可见焦点、表单标签和足够的颜色对比度；不要只用颜色表达状态。
 - 新页面至少适配现有 320px 最小宽度策略，并检查侧栏、表格、抽屉和表单在窄屏下的退化方式。
 
+## 公共前端组件复用
+
+- 开发或重构页面前，先检查 `src/shared/components/`，不得在业务页面重复实现已有的查询栏、数据表格、批量导入、弹窗、抽屉、加载错误、状态和复制交互。公共组件无法满足时，先判断能力是否具有跨模块复用价值：通用能力扩展公共组件并补测试；纯业务特例留在所属模块，不用页面级 CSS 覆盖破坏公共组件契约。
+- 查询与筛选统一使用 `src/shared/components/QueryToolbar.vue`。通过 `fields` 配置 `input`、`select`、`date`、`daterange`，使用 `v-model` 管理查询模型，并监听 `search`、`reset`；额外操作放入 `actions` 插槽。不要在每个列表页重新编写筛选容器、查询/重置按钮和移动端换行样式。
+- 业务数据列表统一使用 `src/shared/components/DataTable.vue`。通过 `columns` 和命名插槽定义列，使用 `v-model:page`、`v-model:page-size` 及 `total` 接入分页；无需分页时可省略 `total`。不得重复拼装 `el-table` 与分页器；“操作”列仍须遵守仓库根规则，放在第一列，固定时固定在左侧。
+- 标准 XLSX 批量导入/上传统一使用 `src/shared/components/BatchImportDialog.vue`。页面只维护弹窗开关，传入标题、实体名称、模板文件名、`downloadTemplate` 和 `importFile`，并在 `success` 后刷新列表；文件格式和大小校验、模板下载、提交状态、接口错误、整批校验结果、CSV 错误报告及响应式样式由组件负责。不要在页面内重复创建文件输入框、上传状态、错误报告逻辑或导入弹窗 CSS。
+- 普通模态框和侧滑编辑/详情优先使用 `src/shared/components/AppDialog.vue`、`AppDrawer.vue`，复用提交锁定、加载态、底部按钮和窄屏约束；仅当业务交互与其契约明显不同时直接使用 Element Plus 原始容器。
+- 列表或详情加载失败优先组合 `src/shared/components/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`。扩展公共组件时同步检查所有现有消费者，并至少运行组件测试和直接受影响页面测试。
+
 ## 本地命令与质量门禁
 
 在 `apps/admin-web` 目录执行：