3.7 KiB
3.7 KiB
Soul 创业派对 - 列表标准与角色分工
供管理端开发者、API 开发者参考。基于 2026-02 列表缺陷排查经验归纳。 更新日期：2026-02-25
一、标准列表应具备的能力
| 能力 | 说明 | 优先级 |
|---|---|---|
| 搜索 | 关键词模糊搜索，建议 300ms 防抖 | 高 |
| 筛选 | 状态/类型/时间范围等 | 高 |
| 刷新 | 手动重新加载 | 高 |
| 分页 | 上一页/下一页、页码、每页条数（后端支持时） | 高 |
| 加载状态 | loading 或骨架屏 | 高 |
| 空状态 | 无数据时的提示 | 高 |
| 错误提示 | 加载失败时展示可关闭的提示条 | 高 |
| 排序 | 列头点击排序（可选） | 中 |
| 导出 | CSV/Excel（可选） | 中 |
| 批量操作 | 勾选多行后批量处理（可选） | 低 |
二、角色分工
2.1 管理端开发者（soul-admin）
职责：实现列表页面的交互与展示，对接 soul-api 的管理端接口。
必做：
- 搜索：使用
useDebounce对输入做 300ms 防抖 - 筛选：按业务提供下拉/按钮筛选
- 刷新：提供刷新按钮，加载时禁用并显示 loading
- 加载状态：请求中显示 loading
- 空状态：无数据时显示友好提示
- 错误提示：catch 后设置 error 状态，页面顶部展示可关闭的错误条（红底）
可选：
- 导出：前端基于当前筛选结果生成 CSV（无需后端支持）
- 排序：前端内存排序或后端支持时传 sort 参数
禁止：
- 不得调用
/api/miniprogram/* - 不得用原生
alert/confirm替代错误提示（应使用页面内错误条或 Dialog）
参考：.cursor/skills/SKILL-管理端开发.md、soul-admin-boundary.mdc
2.2 API 开发者（soul-api）
职责：为管理端列表提供分页、筛选、排序等能力。
列表接口建议：
- 分页：支持
page、pageSize查询参数，返回total、records/list - 筛选：支持
status、matchType、startDate、endDate等 - 排序：支持
sortBy、sortOrder（asc/desc）
响应格式：
{
"success": true,
"records": [...],
"total": 100,
"page": 1,
"pageSize": 10
}
错误：失败时返回 { "success": false, "error": "..." }，管理端据此展示错误条。
参考：.cursor/skills/SKILL-API开发.md、soul-api.mdc
三、已补全项（2026-02-25）
| 页面 | 补全内容 |
|---|---|
| 用户管理 | 错误提示、搜索防抖、分页、每页条数、VIP 筛选 |
| 订单管理 | 错误提示、刷新、导出 CSV、搜索防抖、分页、每页条数、后端搜索 |
| 匹配记录 | 错误提示、每页条数选择 |
| 分账提现 | 错误提示、分页、每页条数 |
| 交易中心 | 错误提示、分页（订单/绑定/提现子列表） |
| 章节管理 | 错误提示、刷新 |
四、后端分页支持（已实现）
| 接口 | 分页参数 | 筛选/搜索 |
|---|---|---|
| GET /api/db/users | page, pageSize | search, vip |
| GET /api/orders | page, pageSize | status, search |
| GET /api/admin/withdrawals | page, pageSize | status |
| GET /api/db/distribution | page, pageSize | status |
| GET /api/db/match-records | page, pageSize | matchType |
五、检查清单（管理端新增列表时）
- 分页（后端支持时接入 page、pageSize、total）
- 搜索有防抖（300ms）
- 有刷新按钮
- 加载中显示 loading
- 无数据时显示空状态
- 加载失败时展示错误条（可关闭）
- 仅调用
/api/admin/*或/api/db/* - 不使用原生 alert 做错误提示