112 lines
3.7 KiB
Markdown
112 lines
3.7 KiB
Markdown
# 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）
|
||
|
||
**响应格式**：
|
||
```json
|
||
{
|
||
"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 做错误提示
|