feat: relaxed in restrict out

2025-11-24 15:57:19 +08:00
parent 113818f73d
commit cd6a2370fc
11 changed files with 840 additions and 5 deletions
--- a/api_man/employee_user_binding.md
+++ b/api_man/employee_user_binding.md
@@ -68,6 +68,13 @@ Base URL: `/api_man/user-profiles/`
 | PATCH | `/api_man/user-profiles/{id}/` | Partially update an existing user profile |
 | DELETE | `/api_man/user-profiles/{id}/` | Delete a user profile |

+### 2.3 User Creation API Endpoint
+Base URL: `/api_v1/users/`
+
+| Method | URL Pattern | Action |
+|--------|-------------|--------|
+| POST | `/api_v1/users/create/` | Create a new User and associated UserProfile |
+
 ## 3. Binding User to Employee

 ### 3.1 During Employee Creation
@@ -216,7 +223,70 @@ To update an existing UserProfile, use the PUT or PATCH method.
 }
 ```

-## 5. Validation Rules
+## 5. Creating User with Profile
+
+### 5.1 User and Profile Creation
+This API creates a new Django User and associated UserProfile in a single request. The UserProfile links the User to a specific Merchant.
+
+#### Request Body Example:
+```json
+{
+  "username": "newuser",
+  "email": "newuser@example.com",
+  "password": "securepass123",
+  "is_staff": false,
+  "description": "New user account",
+  "merchant_id": 1
+}
+```
+
+#### Request Parameters:
+- `username` (required): The username for the new user account
+- `email` (optional): The email address for the user
+- `password` (required): The password for the user account (minimum 6 characters)
+- `is_staff` (optional, default: false): Whether the user should have staff privileges
+- `description` (optional): Description for the UserProfile
+- `merchant_id` (required): ID of the merchant to associate with the user
+
+#### Response Example:
+```json
+{
+  "user": {
+    "id": 124,
+    "username": "newuser",
+    "email": "newuser@example.com",
+    "is_staff": false,
+    "is_active": true,
+    "date_joined": "2025-11-24T14:00:00Z"
+  },
+  "profile": {
+    "id": 790,
+    "user": {
+      "id": 124,
+      "username": "newuser",
+      "email": "newuser@example.com",
+      "is_staff": false,
+      "is_active": true,
+      "date_joined": "2025-11-24T14:00:00Z"
+    },
+    "merchant": 1,
+    "description": "New user account",
+    "created_at": "2025-11-24T14:00:00Z",
+    "updated_at": "2025-11-24T14:00:00Z"
+  }
+}
+```
+
+### 5.2 Authentication Requirements
+- The request must be authenticated with a valid user session
+- The authenticated user must have appropriate permissions to create new users
+
+### 5.3 Validation Rules
+- Username must be unique across the system
+- Password must be at least 6 characters long
+- merchant_id must correspond to an existing merchant in the system
+
+## 6. Validation Rules

 ### 5.1 Employee-User Binding Rules
 1. **One-to-one constraint**: A User can only be bound to one Employee at a time.
@@ -250,6 +320,78 @@ To update an existing UserProfile, use the PUT or PATCH method.
 }
 ```

+### 6.1 User Creation API Errors
+
+#### Username already exists
+```json
+{
+  "username": [
+    "用户名已存在"
+  ]
+}
+```
+
+#### Merchant does not exist
+```json
+{
+  "merchant_id": [
+    "商户不存在"
+  ]
+}
+```
+
+#### Password too short
+```json
+{
+  "password": [
+    "Ensure this field has at least 6 characters."
+  ]
+}
+```
+
+#### Unauthenticated request
+```json
+{
+  "error": "未授权"
+}
+```
+
+#### Server error during creation
+```json
+{
+  "error": "创建用户失败: [detailed error message]"
+}
+```
+
+## 7. Usage Examples
+
+### 7.1 Creating a Complete User Flow
+```bash
+# 1. Create a new user with profile
+curl -X POST http://localhost/api/v1/users/create/ \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer [token]" \
+  -d '{
+    "username": "john_doe",
+    "email": "john@example.com",
+    "password": "securepass123",
+    "description": "Store employee",
+    "merchant_id": 1
+  }'
+
+# Response will contain both user and profile IDs
+# Use the user ID to create an Employee record and bind the user
+curl -X POST http://localhost/api_man/employees/ \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer [token]" \
+  -d '{
+    "name": "John Doe",
+    "position": 1,
+    "mobile": "1234567890",
+    "sys_user": 124  # User ID from the previous response
+  }'
+```
+
 ### Invalid User ID
 ```json
 {