fin

docs/api_core_api_2026-07-03.md

@@ -0,0 +1,332 @@
+# /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