forked from erp-dev/erp
feat: added user profile model & api & admin, it uses by found user with merchant
This commit is contained in:
300
api_man/employee_user_binding.md
Normal file
300
api_man/employee_user_binding.md
Normal file
@@ -0,0 +1,300 @@
|
||||
# Employee-User Binding API Documentation
|
||||
|
||||
This document explains how to use the employee API endpoints to bind a Django User object to an Employee object, either during creation or update operations. It also includes information about the UserProfile model which extends the Django User model with merchant association.
|
||||
|
||||
## 1. Model Relationship Overview
|
||||
|
||||
### 1.1 Core Model Relationships
|
||||
The system has three key models related to user management:
|
||||
- `django.contrib.auth.models.User`: Django's built-in user model for authentication
|
||||
- `Employee`: Represents an employee in the system
|
||||
- `UserProfile`: Extends the User model with additional information (merchant association)
|
||||
|
||||
### 1.2 Field Relationships
|
||||
- `Employee` has a **one-to-one** field `sys_user` that references `django.contrib.auth.models.User`
|
||||
- Field name: `sys_user`
|
||||
- It accepts the User ID as input
|
||||
- It's a nullable field, so an Employee can exist without being bound to a User initially
|
||||
|
||||
- `UserProfile` has a **one-to-one** field `user` that references `django.contrib.auth.models.User`
|
||||
- Field name: `user`
|
||||
- It also has a `merchant` field that links the user to a specific merchant
|
||||
- A User can have only one UserProfile, and a UserProfile belongs to only one merchant
|
||||
|
||||
### 1.3 Relationship Diagram
|
||||
```
|
||||
+------------------------+ +------------------------+
|
||||
| django.contrib.auth.User| | Employee |
|
||||
+------------------------+ +------------------------+
|
||||
| id | | id |
|
||||
| username |<----->| sys_user | (one-to-one)
|
||||
| email | | name |
|
||||
| password | | position |
|
||||
+------------------------+ +------------------------+
|
||||
|
||||
+------------------------+ +------------------------+
|
||||
| django.contrib.auth.User| | UserProfile |
|
||||
+------------------------+ +------------------------+
|
||||
| id |<----->| user | (one-to-one)
|
||||
| username | | merchant |
|
||||
| email | | description |
|
||||
| password | +------------------------+
|
||||
+------------------------+
|
||||
```
|
||||
|
||||
## 2. API Endpoints
|
||||
|
||||
### 2.1 Employee API Endpoints
|
||||
Base URL: `/api_man/employees/`
|
||||
|
||||
| Method | URL Pattern | Action |
|
||||
|--------|-------------|--------|
|
||||
| GET | `/api_man/employees/` | List all employees |
|
||||
| GET | `/api_man/employees/{id}/` | Retrieve a single employee |
|
||||
| POST | `/api_man/employees/` | Create a new employee |
|
||||
| PUT | `/api_man/employees/{id}/` | Update an existing employee |
|
||||
| PATCH | `/api_man/employees/{id}/` | Partially update an existing employee |
|
||||
| DELETE | `/api_man/employees/{id}/` | Delete an employee |
|
||||
|
||||
### 2.2 UserProfile API Endpoints
|
||||
Base URL: `/api_man/user-profiles/`
|
||||
|
||||
| Method | URL Pattern | Action |
|
||||
|--------|-------------|--------|
|
||||
| GET | `/api_man/user-profiles/` | List all user profiles |
|
||||
| GET | `/api_man/user-profiles/{id}/` | Retrieve a single user profile |
|
||||
| POST | `/api_man/user-profiles/` | Create a new user profile |
|
||||
| PUT | `/api_man/user-profiles/{id}/` | Update an existing user profile |
|
||||
| PATCH | `/api_man/user-profiles/{id}/` | Partially update an existing user profile |
|
||||
| DELETE | `/api_man/user-profiles/{id}/` | Delete a user profile |
|
||||
|
||||
## 3. Binding User to Employee
|
||||
|
||||
### 3.1 During Employee Creation
|
||||
When creating a new Employee, you can directly include the `sys_user` field with the User ID to bind them immediately.
|
||||
|
||||
#### Request Body Example:
|
||||
```json
|
||||
{
|
||||
"name": "张三",
|
||||
"position": 1, // EmployeeType ID
|
||||
"mobile": "13800138000",
|
||||
"status": "在职",
|
||||
"sys_user": 123 // User ID to bind
|
||||
}
|
||||
```
|
||||
|
||||
#### Response Example:
|
||||
```json
|
||||
{
|
||||
"id": 456,
|
||||
"name": "张三",
|
||||
"position": { "id": 1, "name": "仓库管理员" },
|
||||
"mobile": "13800138000",
|
||||
"status": "在职",
|
||||
"sys_user": 123, // User ID is now bound
|
||||
// Other fields...
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 During Employee Update
|
||||
To bind an existing User to an existing Employee, use the PUT or PATCH method and include the `sys_user` field.
|
||||
|
||||
#### PUT Request Body Example (Full Update):
|
||||
```json
|
||||
{
|
||||
"name": "张三",
|
||||
"position": 1,
|
||||
"mobile": "13800138000",
|
||||
"status": "在职",
|
||||
"sys_user": 123 // New User ID to bind
|
||||
}
|
||||
```
|
||||
|
||||
#### PATCH Request Body Example (Partial Update):
|
||||
```json
|
||||
{
|
||||
"sys_user": 123 // User ID to bind
|
||||
}
|
||||
```
|
||||
|
||||
#### Response Example:
|
||||
```json
|
||||
{
|
||||
"id": 456,
|
||||
"name": "张三",
|
||||
"position": { "id": 1, "name": "仓库管理员" },
|
||||
"mobile": "13800138000",
|
||||
"status": "在职",
|
||||
"sys_user": 123, // User ID is now bound
|
||||
// Other fields...
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 Unbinding User from Employee
|
||||
To unbind a User from an Employee, set the `sys_user` field to `null` using PUT or PATCH.
|
||||
|
||||
#### PATCH Request Body Example:
|
||||
```json
|
||||
{
|
||||
"sys_user": null
|
||||
}
|
||||
```
|
||||
|
||||
#### Response Example:
|
||||
```json
|
||||
{
|
||||
"id": 456,
|
||||
"name": "张三",
|
||||
"position": { "id": 1, "name": "仓库管理员" },
|
||||
"mobile": "13800138000",
|
||||
"status": "在职",
|
||||
"sys_user": null, // User is now unbound
|
||||
// Other fields...
|
||||
}
|
||||
```
|
||||
|
||||
## 4. UserProfile Management
|
||||
|
||||
### 4.1 Creating a UserProfile
|
||||
When creating a new UserProfile, you need to provide the User ID and Merchant ID.
|
||||
|
||||
#### Request Body Example:
|
||||
```json
|
||||
{
|
||||
"user": 123, // User ID
|
||||
"merchant": 1, // Merchant ID
|
||||
"description": "User profile for system access"
|
||||
}
|
||||
```
|
||||
|
||||
#### Response Example:
|
||||
```json
|
||||
{
|
||||
"id": 789,
|
||||
"user": {
|
||||
"id": 123,
|
||||
"username": "system_user",
|
||||
"email": "user@example.com",
|
||||
"is_active": true,
|
||||
"is_superuser": false,
|
||||
"last_login": "2025-11-24T12:34:56Z"
|
||||
},
|
||||
"merchant": 1,
|
||||
"description": "User profile for system access",
|
||||
"created_at": "2025-11-24T13:00:00Z",
|
||||
"updated_at": "2025-11-24T13:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 Updating a UserProfile
|
||||
To update an existing UserProfile, use the PUT or PATCH method.
|
||||
|
||||
#### PATCH Request Body Example (Partial Update):
|
||||
```json
|
||||
{
|
||||
"description": "Updated user profile for system access"
|
||||
}
|
||||
```
|
||||
|
||||
#### Response Example:
|
||||
```json
|
||||
{
|
||||
"id": 789,
|
||||
"user": {
|
||||
"id": 123,
|
||||
"username": "system_user",
|
||||
"email": "user@example.com",
|
||||
"is_active": true,
|
||||
"is_superuser": false,
|
||||
"last_login": "2025-11-24T12:34:56Z"
|
||||
},
|
||||
"merchant": 1,
|
||||
"description": "Updated user profile for system access",
|
||||
"created_at": "2025-11-24T13:00:00Z",
|
||||
"updated_at": "2025-11-24T13:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 5. 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.
|
||||
2. **Permission check**: Only super users or users with appropriate permissions can perform binding operations.
|
||||
3. **User existence**: The provided User ID must exist in the system.
|
||||
4. **Merchant isolation**: Both the User (via UserProfile) and Employee must belong to the same Merchant.
|
||||
|
||||
### 5.2 UserProfile Rules
|
||||
1. **One-to-one constraint**: A User can only have one UserProfile at a time.
|
||||
2. **Permission check**: Only users with appropriate permissions can access UserProfiles from the same merchant.
|
||||
3. **User existence**: The provided User ID must exist in the system.
|
||||
4. **Merchant existence**: The provided Merchant ID must exist in the system.
|
||||
|
||||
## 6. Error Handling
|
||||
|
||||
### User already bound to another Employee
|
||||
```json
|
||||
{
|
||||
"sys_user": [
|
||||
"User with id 123 is already bound to an existing employee."
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### User already has a UserProfile
|
||||
```json
|
||||
{
|
||||
"user": [
|
||||
"User with id 123 already has a UserProfile."
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Invalid User ID
|
||||
```json
|
||||
{
|
||||
"sys_user": [
|
||||
"Invalid pk \"999\" - object does not exist."
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Permission denied
|
||||
```json
|
||||
{
|
||||
"detail": "无权限创建该对象"
|
||||
}
|
||||
```
|
||||
|
||||
## 7. Front-End Implementation Tips
|
||||
|
||||
1. **User selection flow**:
|
||||
- First fetch the list of available Users with active UserProfiles
|
||||
- Then allow users to select from this list when binding to an Employee
|
||||
|
||||
2. **State management**:
|
||||
- After binding, update the UI to reflect the bound status
|
||||
- Ensure consistency between User, UserProfile, and Employee data
|
||||
|
||||
3. **Error handling**:
|
||||
- Implement proper error messages based on the API responses
|
||||
- Distinguish between binding errors and UserProfile management errors
|
||||
|
||||
4. **Data consistency**:
|
||||
- Ensure that the User and Employee belong to the same Merchant
|
||||
- Verify that a User has a UserProfile before attempting to bind to an Employee
|
||||
|
||||
## 8. Example Workflow
|
||||
|
||||
### Full Workflow (Creating User, UserProfile, and Bound Employee)
|
||||
1. **Create User**: First create a User via Django's authentication system.
|
||||
2. **Fetch User ID**: Retrieve the User ID from the response.
|
||||
3. **Create UserProfile**: Create a UserProfile and include the User ID and Merchant ID.
|
||||
4. **Create Employee**: Create an Employee and include the User ID in the `sys_user` field to bind them.
|
||||
5. **Verify binding**: Retrieve the Employee to confirm the User is bound.
|
||||
|
||||
### Partial Workflow (Binding Existing User to Existing Employee)
|
||||
1. **Fetch existing User**: Retrieve User IDs that have active UserProfiles.
|
||||
2. **Fetch existing Employee**: Retrieve the Employee to bind to.
|
||||
3. **Update Employee**: Update the Employee with the User ID to bind them.
|
||||
4. **Verify binding**: Retrieve the Employee to confirm the User is bound.
|
||||
Reference in New Issue
Block a user