# 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 做错误提示