# /api/core/ 核心权限 API 文档

`/api/core/` 是系统核心权限管理 API 集合，用于管理 Django auth 层的 `User`、`Group` 和 `Permission`。

这组接口权限极高，必须谨慎使用。一般业务开通用户、员工绑定、商户业务身份维护，不应该优先使用这里的用户创建接口，而应该使用业务侧 Employee / UserProfile / 员工开通流程。

## 访问控制

所有 `/api/core/` 接口都必须同时满足：

```text
1. 已登录
2. request.user.is_superuser == True
3. request.user.employee 存在
4. request.user.employee.merchant 存在
```

不满足时返回：

```text
未登录：401
已登录但不是 superadmin，或没有 employee/merchant：403
```

认证方式：

```http
Authorization: Bearer <access_token>
```

登录接口仍为：

```http
POST /api/auth/login/
```

## Merchant 隔离

`users` 接口引入 merchant 隔离。

当前 merchant 来自：

```text
request.user.employee.merchant
```

`/api/core/users/` 只返回和操作当前 merchant 范围内的用户：

```text
User.employee.merchant == 当前 merchant
或
User.profile.merchant == 当前 merchant
```

`groups` 暂时是全局资源，不做 merchant 隔离。

`permissions` 是 Django 全局权限，只读，不做 merchant 隔离。

## Users

### 列表

```http
GET /api/core/users/
```

支持分页：

```http
GET /api/core/users/?limit=100&offset=0
```

支持搜索和排序：

```http
GET /api/core/users/?search=admin
GET /api/core/users/?ordering=username
GET /api/core/users/?ordering=-date_joined
```

返回字段包含：

```json
{
  "id": 1,
  "username": "admin",
  "email": "admin@example.com",
  "first_name": "",
  "last_name": "",
  "is_active": true,
  "is_staff": true,
  "is_superuser": true,
  "last_login": "2026-07-03T10:00:00+08:00",
  "date_joined": "2026-07-03T09:00:00+08:00",
  "merchant_id": 1,
  "employee_id": 10,
  "employee_name": "管理员",
  "groups": [1, 2],
  "group_details": [
    {"id": 1, "name": "管理员"}
  ],
  "user_permissions": [101, 102],
  "permission_details": []
}
```

### 详情

```http
GET /api/core/users/{id}/
```

如果目标用户不属于当前 merchant 范围，返回 `404`。

### 创建

```http
POST /api/core/users/
```

示例：

```json
{
  "username": "core_user",
  "password": "strongPass123",
  "email": "core@example.com",
  "first_name": "Core",
  "last_name": "User",
  "is_active": true,
  "is_staff": false,
  "is_superuser": false,
  "groups": [1],
  "user_permissions": [101]
}
```

创建行为：

```text
1. 创建 Django User
2. 创建 UserProfile，并将 merchant 设置为当前 superadmin 的 merchant
3. 不创建 Employee
4. 不绑定业务身份
```

重要说明：

```text
/api/core/users/ 创建出来的是 core auth 用户，不是完整业务用户。
因为不会创建 Employee，新用户通常不能直接登录业务系统。
一般情况下，不建议在这里创建业务用户。
```

### 更新

```http
PATCH /api/core/users/{id}/
PUT /api/core/users/{id}/
```

可更新字段包括：

```text
username
email
first_name
last_name
is_active
is_staff
is_superuser
groups
user_permissions
password
```

安全限制：

```text
不允许停用当前登录用户自己
不允许取消当前登录用户自己的 is_superuser
```

### 停用用户

用户不允许删除，只能停用：

```http
PATCH /api/core/users/{id}/
Content-Type: application/json

{
  "is_active": false
}
```

### 删除用户

不允许：

```http
DELETE /api/core/users/{id}/
```

返回：

```text
405 Method Not Allowed
```

## Groups

`groups` 使用 Django `Group`，暂时是全局资源，不做 merchant 隔离。

但是所有 group API 仍然必须通过 `/api/core/` 的 superadmin 访问控制。

### 列表

```http
GET /api/core/groups/
```

### 详情

```http
GET /api/core/groups/{id}/
```

### 创建

```http
POST /api/core/groups/
```

```json
{
  "name": "财务管理员",
  "permissions": [101, 102, 103]
}
```

### 更新

```http
PATCH /api/core/groups/{id}/
PUT /api/core/groups/{id}/
```

设置 permissions 时传完整权限 id 列表：

```json
{
  "permissions": [101, 102, 103]
}
```

### 删除

```http
DELETE /api/core/groups/{id}/
```

删除 group 会影响已分配该 group 的用户，请谨慎操作。

## Permissions

`permissions` 使用 Django `Permission`，只读。

权限通常来自 Django model 默认权限和代码中的 `Meta.permissions`，不应该由前端任意创建、修改或删除。

### 列表

```http
GET /api/core/permissions/
```

支持搜索：

```http
GET /api/core/permissions/?search=salesorder
GET /api/core/permissions/?search=business
```

返回字段：

```json
{
  "id": 101,
  "name": "Can view sales order",
  "codename": "view_salesorder",
  "content_type": 12,
  "app_label": "business",
  "model": "salesorder",
  "full_code": "business.view_salesorder"
}
```

### 详情

```http
GET /api/core/permissions/{id}/
```

### 不允许写操作

以下操作不允许：

```http
POST /api/core/permissions/
PATCH /api/core/permissions/{id}/
PUT /api/core/permissions/{id}/
DELETE /api/core/permissions/{id}/
```

返回：

```text
405 Method Not Allowed
```

## 前端使用建议

```text
1. /api/core/ 只给最高权限管理界面使用。
2. 普通业务用户开通不要默认走 /api/core/users/。
3. 创建业务用户应优先走员工/业务身份流程。
4. 修改 is_superuser、is_staff、groups、user_permissions 时必须二次确认。
5. permissions 只作为可分配权限源，不允许前端创建权限。
6. group 暂时是全局资源，删除或改名会影响所有 merchant。
```

更新日期：2026-07-03