erpnew/api_man/employee_user_binding.md

# 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.