feat: add user api

API.md

@@ -501,6 +501,8 @@ Base 前缀 `/api/v1/admin`。
 |---|---|---|
 | `GET` | `/api/v1/platform/employees` | 列全平台未软删员工;包含停用、锁定及无平台角色用户 |
 | `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`);已软删的过滤掉 |
 | `POST` | `/api/v1/platform/workspaces` | 创建 workspace(返回 201);创建者自动成为 admin 成员 |
 | `GET` | `/api/v1/platform/workspaces/{workspace_id}` | 单个 workspace(含已 disabled 的,用于恢复) |
@@ -513,6 +515,7 @@ Base 前缀 `/api/v1/admin`。
 
 > **不变量**:
 > - 每个 workspace 必须始终保留至少一个 `admin` 角色的活跃成员;对最后 admin 做降级 / 停用 / 删除 → 409。
+> - platform 必须始终保留至少一个 `active` 系统管理员;对最后系统管理员做降级 / 停用 / 删除 → 409。
 > - 系统管理员不能通过 `DELETE .../members/{self}` 把自己移除(403)。唯一退出方式是 `DELETE /workspaces/{id}` 软删整个 workspace,后者会级联软删所有成员。
 > - workspace 与成员列表接口静默 `pageSize=100` 上限,无客户端分页参数(YAGNI);`GET /employees` 按契约返回全部未软删员工,不设隐藏上限。
 > - 跨 workspace 操作**不**需要 `?workspace_id=` query 参数,与 `/api/v1/admin/...`(workspace 内成员管理)不要混淆。
@@ -669,6 +672,56 @@ Base 前缀 `/api/v1/admin`。
 
 - **响应 201**:字段与 §7.8 的员工元素一致,其中 `role_code`、`role_name` 均为 `null`,`meta` 为空对象。
 
+### 7.10 `PATCH /api/v1/platform/employees/{user_id}`
+
+修改平台员工的显示名、邮箱、状态或平台角色。调用者必须是系统管理员。
+
+- **请求体字段**(全部可选):
+
+| 字段 | 类型 | 限制 | 说明 |
+|---|---|---|---|
+| `display_name` | string | 1~100 | trim 后写入 |
+| `email` | string \| null | ≤255 | trim 后写入;空字符串归一为 `null` |
+| `status` | string | `active` \| `disabled` \| `locked` | 直接写入 `users.status` |
+| `role_code` | string | `admin` \| `developer` | 同步设置 `users.platform_role_id`;`admin` 指向 `role_code='admin'` 的 Roles 行,`developer` 指向 `role_code='developer'` 的 Roles 行 |
+
+- 禁止通过该端点修改:`username`、`password`、`password_hash`、`platform_role_id`;请求体中包含这些字段 → 422。
+- `role_code` 只能取 `admin` / `developer`;不能通过本端点把 `platform_role_id` 置为 `null`。
+- 自保护:
+  - 修改自身 `status` 为非 `active` → 409 "不能停用当前登录账号"。
+  - 修改自身 `role_code` 为 `developer`(即降级系统管理员身份)→ 409 "不能降级自身管理员角色"。
+- 最后系统管理员保护:当目标用户当前为 active 系统管理员,本次变更会让其离开"active 系统管理员"集合(降级角色 / 停用账号)时,平台必须仍保留至少一名 active 系统管理员,否则 → 409 "platform 必须保留至少一个 active 系统管理员"。
+- 目标用户不存在或已软删除 → 404 "用户不存在";`role_code` 对应的角色行不存在 → 422。
+
+- **响应 200**:返回更新后的 `PlatformEmployeePayload`,`role_code` / `role_name` 反映最新的 `platform_role_id`。
+
+### 7.11 `DELETE /api/v1/platform/employees/{user_id}`
+
+软删除平台员工;级联软删其所有 `workspace_members` 行。调用者必须是系统管理员。
+
+- 行为:
+  - 设置 `users.status='disabled'`、`users.is_deleted=1`、`users.deleted_at=NOW()`。
+  - 同事务内 `UPDATE workspace_members SET is_deleted=1, deleted_at=NOW() WHERE user_id=:user_id AND is_deleted=0`。
+  - 不级联修改 `workspaces` 记录,workspace 仍可被单独管理。
+- 保护:
+  - 删除自身 → 409 "不能删除当前登录账号"。
+  - 目标为唯一 active 系统管理员 → 409 "platform 必须保留至少一个 active 系统管理员"。
+  - 目标不存在或已软删除 → 404 "用户不存在"(与 §7.4 DELETE workspace 对已 disabled 返回 409 不同,本端点对已软删用户统一返回 404)。
+- 软删后行为:
+  - `GET /api/v1/platform/employees` 不再返回该用户。
+  - `POST /api/v1/platform/workspaces/{id}/members` 用同一 `user_id` 重新加入 → 404。
+  - `POST /api/v1/platform/employees` 用同 `username` 重新创建 → 409(唯一索引)。
+- 本端点不提供恢复接口,与其他 DELETE 端点行为一致。
+
+- **响应 200**:
+  ```json
+  {
+    "request_id": "...",
+    "data": { "user_id": "01HXY...", "deleted": true },
+    "meta": {}
+  }
+  ```
+
 ---
 
 ## 八、Jupyter 路由