update:添加分页、成员添加优化

API.md

@@ -630,11 +630,11 @@ Base 前缀 `/api/v1/admin`。
 
 | 方法 | 路径 | 说明 |
 |---|---|---|
-| `GET` | `/api/v1/platform/employees` | 列全平台未软删员工;包含停用、锁定及无平台角色用户 |
+| `GET` | `/api/v1/platform/employees` | 列全平台未软删员工（cursor 分页 + `q` 搜索，见 §7.0） |
 | `POST` | `/api/v1/platform/employees` | 创建平台员工账号(返回 201);不自动加入任何 workspace |
 | `PATCH` | `/api/v1/platform/employees/{user_id}` | 改员工资料/状态/平台角色(仅系统管理员) |
 | `DELETE` | `/api/v1/platform/employees/{user_id}` | 软删员工;级联软删其 workspace 成员关系(仅系统管理员) |
-| `GET` | `/api/v1/platform/workspaces` | 列 workspace(`active`/`archived`);已软删的过滤掉 |
+| `GET` | `/api/v1/platform/workspaces` | 列 workspace(`active`/`archived`)（cursor 分页 + `q` 搜索，见 §7.0） |
 | `POST` | `/api/v1/platform/workspaces` | 创建 workspace(返回 201);创建者自动成为 admin 成员 |
 | `GET` | `/api/v1/platform/workspaces/{workspace_id}` | 单个 workspace(含已 disabled 的,用于恢复) |
 | `PATCH` | `/api/v1/platform/workspaces/{workspace_id}` | 改 workspace 字段;`status` 仅允许 `active`/`archived` |
@@ -651,9 +651,35 @@ Base 前缀 `/api/v1/admin`。
 > - 每个 workspace 必须始终保留至少一个 `admin` 角色的活跃成员;对最后 admin 做降级 / 停用 / 删除 → 409。
 > - `PATCH /employees/{user_id}` 降级 admin → developer 时同样触发 workspace last-admin 守卫(因为 workspace 角色继承自 platform 角色,降级会级联到所有活跃 membership);platform 必须始终保留至少一个 `active` 系统管理员;对最后系统管理员做降级 / 停用 / 删除 → 409。
 > - 系统管理员不能通过 `DELETE .../members/{self}` 把自己移除(403)。唯一退出方式是 `DELETE /workspaces/{id}` 软删整个 workspace,后者会级联软删所有成员。
-> - workspace 与成员列表接口静默 `pageSize=100` 上限,无客户端分页参数(YAGNI);`GET /employees` 按契约返回全部未软删员工,不设隐藏上限。
+> - `GET /employees` 与 `GET /workspaces` 支持 cursor 分页与关键字搜索（见 §7.0）；成员列表仍静默 `pageSize=100` 上限。
 > - 跨 workspace 操作**不**需要 `?workspace_id=` query 参数,与 `/api/v1/admin/...`(workspace 内成员管理)不要混淆。
 
+### 7.0 列表分页约定（employees / workspaces）
+
+`GET /api/v1/platform/employees` 与 `GET /api/v1/platform/workspaces` 使用 **keyset cursor** 分页（无 `offset` / `page`）。
+
+| Query | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `limit` | int | `10` | 每页条数，范围 1~200 |
+| `cursor` | string | 无 | 上一页返回的 `meta.next_cursor`；缺省为第一页；非法值 → 400 |
+| `q` | string | 无 | 关键字搜索。employees 匹配 `display_name`/`username`/`email`；workspaces 匹配 `workspace_name`/`workspace_code`/`description` |
+
+响应 `meta`：
+
+```json
+{
+  "limit": 10,
+  "page_count": 10,
+  "total_count": 156,
+  "has_more": true,
+  "next_cursor": "..."
+}
+```
+
+- `total_count`：当前筛选条件下的总条数（用于页码展示）。
+- `next_cursor`：无下一页时为 `null`。
+- 排序键：`(created_at ASC, id ASC)`。前端用 cursor 栈实现「上一页 / 下一页 + 已访问页码」；不支持任意跳到未访问过的深页。
+
 ### 7.1 `POST /api/v1/platform/workspaces`
 
 创建 workspace;创建者(当前系统管理员)自动成为该 workspace 的 `admin` 成员。