From 53999cbd5b3770ab46bf0ea0150915d6cf913e9d Mon Sep 17 00:00:00 2001
From: "tao.chen" <93983997+taochen-ct@users.noreply.github.com>
Date: Thu, 6 Aug 2026 10:26:16 +0800
Subject: [PATCH] docs: add API

---
 API.md | 35 +++++++++++++++++++++++++++++++++--
 1 file changed, 33 insertions(+), 2 deletions(-)

diff --git a/API.md b/API.md
index e4daa7f..7fb807c 100644
--- a/API.md
+++ b/API.md
@@ -492,13 +492,14 @@ Base 前缀 `/api/v1/admin`。
 
 ## 七、系统管理 (`/api/v1/platform/...`)
 
-平台级(跨 workspace)管理接口,用于管理 workspace 实体与 workspace 成员。
+平台级(跨 workspace)管理接口,用于管理员工、workspace 实体与 workspace 成员。
 所有端点要求调用者是**系统管理员**——其 `users.platform_role_id` 指向
 `role_code='admin'` 的角色行,且 `users.status == 'active'`。系统管理员判定
 通过 `GET /api/v1/auth/me` 响应中的 `data.user.is_system_admin` 字段(详见 §一)。
 
 | 方法 | 路径 | 说明 |
 |---|---|---|
+| `GET` | `/api/v1/platform/employees` | 列全平台未软删员工;包含停用、锁定及无平台角色用户 |
 | `GET` | `/api/v1/platform/workspaces` | 列 workspace(`active`/`archived`);已软删的过滤掉 |
 | `POST` | `/api/v1/platform/workspaces` | 创建 workspace(返回 201);创建者自动成为 admin 成员 |
 | `GET` | `/api/v1/platform/workspaces/{workspace_id}` | 单个 workspace(含已 disabled 的,用于恢复) |
@@ -512,7 +513,7 @@ Base 前缀 `/api/v1/admin`。
 > **不变量**:
 > - 每个 workspace 必须始终保留至少一个 `admin` 角色的活跃成员;对最后 admin 做降级 / 停用 / 删除 → 409。
 > - 系统管理员不能通过 `DELETE .../members/{self}` 把自己移除(403)。唯一退出方式是 `DELETE /workspaces/{id}` 软删整个 workspace,后者会级联软删所有成员。
-> - 列表类接口静默 `pageSize=100` 上限,无客户端分页参数(YAGNI)。
+> - workspace 与成员列表接口静默 `pageSize=100` 上限,无客户端分页参数(YAGNI);`GET /employees` 按契约返回全部未软删员工,不设隐藏上限。
 > - 跨 workspace 操作**不**需要 `?workspace_id=` query 参数,与 `/api/v1/admin/...`(workspace 内成员管理)不要混淆。
 
 ### 7.1 `POST /api/v1/platform/workspaces`
@@ -616,6 +617,36 @@ Base 前缀 `/api/v1/admin`。
 - **末位 admin 保护**:若删除的是最后一个 `admin` 角色活跃成员 → 409
 - 不存在的成员 → 404
 
+### 7.8 `GET /api/v1/platform/employees`
+
+返回全平台所有未软删除员工。调用者必须是系统管理员;已认证但不是系统管理员时返回 `403`。
+
+- 无请求体或查询参数。
+- 包含 `active`、`disabled`、`locked` 状态及未分配平台角色的员工。
+- `users.is_deleted != 0` 的员工不会返回。
+- 不设隐藏数量上限,结果按 `created_at`、`user_id` 排序。
+- `role_code`、`role_name` 表示 `users.platform_role_id` 对应的平台角色;未分配时均为 `null`。
+
+- **响应 200**:
+  ```json
+  {
+    "request_id": "...",
+    "data": [
+      {
+        "user_id": "01HXY...",
+        "username": "developer",
+        "display_name": "开发人员",
+        "email": "developer@example.com",
+        "status": "active",
+        "role_code": null,
+        "role_name": null,
+        "created_at": "2026-08-06T12:00:00.000"
+      }
+    ],
+    "meta": {"count": 1}
+  }
+  ```
+
 ---
 
 ## 八、Jupyter 路由