Neo-ZQYY/docs/prd/Neo_Specs/review-audit/P10-NS4-06.md

P10-NS4-06：表格组件的统一规范

简要结论

• 状态：⚠️ 部分解决
• tenant-admin 各页面表格在分页大小、loading 状态、筛选器位置上已形成事实一致的模式，但缺少显式的统一配置抽象层；排序交互完全缺失；空数据展示未统一；部分表格分页大小不一致（20 vs 10）。

详细审查

前端代码

1. 分页大小

页面/组件	默认 pageSize	showSizeChanger	showTotal	后端分页
UserApproval	20	✅	✅ 共 N 条	✅ page/page_size
UserManagement	20	✅	✅ 共 N 条	✅ page/page_size
ExcelUpload — 上传记录	20	✅	✅ 共 N 条	✅ page/page_size
ExcelUpload — 校验详情	10	❌	❌	前端分页
RetentionClues — 客户搜索	false	—	—	无分页（LIMIT 50）
RetentionClues — 线索列表	10	❌	❌	无分页（全量返回）
DiffTable — 冲突表	false	—	—	前端数据

结论：主列表页统一为 20 条/页 + showSizeChanger + showTotal，但子表格（校验详情、线索列表）使用 10 条/页且缺少 showSizeChanger 和 showTotal，不一致。

2. 排序交互

所有 5 个表格组件均未配置 sorter 属性，前端不支持列排序。后端 SQL 统一使用 ORDER BY created_at DESC（固定倒序），无动态排序参数。

结论：完全缺失。用户无法按任意列排序。

3. 筛选器位置

页面	筛选器位置	筛选方式
UserApproval	表格上方独立区域	Select（状态筛选）
UserManagement	表格上方独立区域	Select（角色）+ Input.Search（关键词）
ExcelUpload — 上传记录	无筛选	—
RetentionClues	Card title 区域 + Card extra 区域	Input.Search + SiteSelector（上方）；Select×2（Card extra 右侧）

结论：筛选器统一放在表格上方（非表格内 column filter），位置一致。但 RetentionClues 的线索筛选器放在 Card extra 右侧，与其他页面的左对齐布局略有差异。

4. loading 状态

所有带后端请求的表格均通过 loading={loading} 传入 Ant Design Table 的 loading 属性，统一且正确。

5. 空数据展示

页面	空数据处理
UserApproval	Ant Design Table 默认空状态（无自定义）
UserManagement	Ant Design Table 默认空状态（无自定义）
ExcelUpload	Ant Design Table 默认空状态（无自定义）
RetentionClues — 客户搜索	<Empty description="未找到匹配客户" /> ✅ 自定义
RetentionClues — 线索列表	Ant Design Table 默认空状态（无自定义）
DiffTable	Ant Design Table 默认空状态（无自定义）

结论：仅 RetentionClues 客户搜索有自定义空状态文案，其余均依赖 Ant Design 默认的英文 "No Data"。未统一，且未做中文化。

对比 admin-web：TaskManager 页面使用了 locale={{ emptyText: <Empty description="队列为空" /> }} 自定义空状态，tenant-admin 未跟进。

6. 统一配置抽象

• tenant-admin 中不存在统一的表格配置文件、常量定义或封装组件
• 每个页面独立定义 pageSize、pagination 配置、handleTableChange 等
• 分页响应结构 { items, total, page, pageSize } 在前后端已统一，但属于隐式约定

后端代码

分页参数统一性

路由	参数名	默认值	范围约束
GET /applications	page + page_size	1 / 20	ge=1 / ge=1,le=100
GET /users	page + page_size	1 / 20	ge=1 / ge=1,le=100
GET /excel/logs	page + page_size	1 / 20	ge=1 / ge=1,le=100
GET /customers/search	无分页	—	LIMIT 50 硬编码
GET /customers/{id}/clues	无分页	—	全量返回

结论：三个主列表接口的分页参数完全统一（page/page_size，默认 20，上限 100）。客户搜索和线索列表不分页，属于业务设计选择（数据量可控），但线索列表在数据量增长后可能需要补充分页。

响应格式统一为 { items: T[], total: int, page: int, pageSize: int }，一致。

差距分析

与 P10 标杆文件要求的差距：

规范项	P10 要求（推断）	当前状态	差距
默认分页大小	统一值（如 20）	主表 20，子表 10	🟡 子表不一致
showSizeChanger	所有分页表格启用	仅主表启用	🟡 子表缺失
showTotal	所有分页表格显示	仅主表显示	🟡 子表缺失
排序交互	至少关键列支持排序	完全缺失	🔴 缺失
筛选器位置	统一在表格上方	基本一致	✅
loading 状态	统一 loading 属性	全部已配置	✅
空数据展示	统一中文空状态	仅 1 处自定义，其余默认	🟡 未统一
统一配置抽象	提取公共 Table 配置	不存在	🔴 缺失

建议

1. 提取统一表格配置常量（优先级：高）

   在 apps/tenant-admin/src/constants/table.ts 中定义：

   export const DEFAULT_PAGE_SIZE = 20;
   export const PAGE_SIZE_OPTIONS = ['10', '20', '50'];
   export const TABLE_LOCALE = {
     emptyText: '暂无数据',
   };
   export const defaultPagination = (total: number, page: number, pageSize: number) => ({
     current: page,
     pageSize,
     total,
     showSizeChanger: true,
     showTotal: (t: number) => `共 ${t} 条`,
     pageSizeOptions: PAGE_SIZE_OPTIONS,
   });
   

2. 统一空数据展示（优先级：高）

   通过 Ant Design ConfigProvider 全局设置中文 locale 和空状态：

   import zhCN from 'antd/locale/zh_CN';
   <ConfigProvider locale={zhCN} renderEmpty={() => <Empty description="暂无数据" />}>
   

3. 子表格分页对齐（优先级：中）

   ExcelUpload 校验详情和 RetentionClues 线索列表的 pageSize 改为 20，并补充 showSizeChanger 和 showTotal。

4. 排序交互（优先级：低）

   对时间列（申请时间、上传时间、记录时间）添加前端 sorter 支持。如数据量增长需后端排序，可在 API 中增加 sort_by + sort_order 参数。当前数据量下前端排序即可。

5. 线索列表补充分页（优先级：低）

   GET /customers/{member_id}/clues 当前全量返回，建议在数据量可能超过 50 条时补充后端分页。