5.6 KiB
/api/core/ 核心权限 API 文档
/api/core/ 是系统核心权限管理 API 集合，用于管理 Django auth 层的 User、Group 和 Permission。
这组接口权限极高，必须谨慎使用。一般业务开通用户、员工绑定、商户业务身份维护，不应该优先使用这里的用户创建接口，而应该使用业务侧 Employee / UserProfile / 员工开通流程。
访问控制
所有 /api/core/ 接口都必须同时满足：
1. 已登录
2. request.user.is_superuser == True
3. request.user.employee 存在
4. request.user.employee.merchant 存在
不满足时返回：
未登录：401
已登录但不是 superadmin，或没有 employee/merchant：403
认证方式：
Authorization: Bearer <access_token>
登录接口仍为：
POST /api/auth/login/
Merchant 隔离
users 接口引入 merchant 隔离。
当前 merchant 来自：
request.user.employee.merchant
/api/core/users/ 只返回和操作当前 merchant 范围内的用户：
User.employee.merchant == 当前 merchant
或
User.profile.merchant == 当前 merchant
groups 暂时是全局资源，不做 merchant 隔离。
permissions 是 Django 全局权限，只读，不做 merchant 隔离。
Users
列表
GET /api/core/users/
支持分页：
GET /api/core/users/?limit=100&offset=0
支持搜索和排序：
GET /api/core/users/?search=admin
GET /api/core/users/?ordering=username
GET /api/core/users/?ordering=-date_joined
返回字段包含：
{
"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": []
}
详情
GET /api/core/users/{id}/
如果目标用户不属于当前 merchant 范围，返回 404。
创建
POST /api/core/users/
示例：
{
"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]
}
创建行为：
1. 创建 Django User
2. 创建 UserProfile，并将 merchant 设置为当前 superadmin 的 merchant
3. 不创建 Employee
4. 不绑定业务身份
重要说明：
/api/core/users/ 创建出来的是 core auth 用户，不是完整业务用户。
因为不会创建 Employee，新用户通常不能直接登录业务系统。
一般情况下，不建议在这里创建业务用户。
更新
PATCH /api/core/users/{id}/
PUT /api/core/users/{id}/
可更新字段包括：
username
email
first_name
last_name
is_active
is_staff
is_superuser
groups
user_permissions
password
安全限制：
不允许停用当前登录用户自己
不允许取消当前登录用户自己的 is_superuser
停用用户
用户不允许删除，只能停用：
PATCH /api/core/users/{id}/
Content-Type: application/json
{
"is_active": false
}
删除用户
不允许：
DELETE /api/core/users/{id}/
返回：
405 Method Not Allowed
Groups
groups 使用 Django Group，暂时是全局资源，不做 merchant 隔离。
但是所有 group API 仍然必须通过 /api/core/ 的 superadmin 访问控制。
列表
GET /api/core/groups/
详情
GET /api/core/groups/{id}/
创建
POST /api/core/groups/
{
"name": "财务管理员",
"permissions": [101, 102, 103]
}
更新
PATCH /api/core/groups/{id}/
PUT /api/core/groups/{id}/
设置 permissions 时传完整权限 id 列表：
{
"permissions": [101, 102, 103]
}
删除
DELETE /api/core/groups/{id}/
删除 group 会影响已分配该 group 的用户，请谨慎操作。
Permissions
permissions 使用 Django Permission，只读。
权限通常来自 Django model 默认权限和代码中的 Meta.permissions，不应该由前端任意创建、修改或删除。
列表
GET /api/core/permissions/
支持搜索：
GET /api/core/permissions/?search=salesorder
GET /api/core/permissions/?search=business
返回字段：
{
"id": 101,
"name": "Can view sales order",
"codename": "view_salesorder",
"content_type": 12,
"app_label": "business",
"model": "salesorder",
"full_code": "business.view_salesorder"
}
详情
GET /api/core/permissions/{id}/
不允许写操作
以下操作不允许：
POST /api/core/permissions/
PATCH /api/core/permissions/{id}/
PUT /api/core/permissions/{id}/
DELETE /api/core/permissions/{id}/
返回：
405 Method Not Allowed
前端使用建议
1. /api/core/ 只给最高权限管理界面使用。
2. 普通业务用户开通不要默认走 /api/core/users/。
3. 创建业务用户应优先走员工/业务身份流程。
4. 修改 is_superuser、is_staff、groups、user_permissions 时必须二次确认。
5. permissions 只作为可分配权限源，不允许前端创建权限。
6. group 暂时是全局资源，删除或改名会影响所有 merchant。
更新日期：2026-07-03