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

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

When creating a new Employee, you can directly include the sys_user field with the User ID to bind them immediately.

Request Body Example:

{
  "name": "张三",
  "position": 1,  // EmployeeType ID
  "mobile": "13800138000",
  "status": "在职",
  "sys_user": 123  // User ID to bind
}

Response Example:

{
  "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):

{
  "name": "张三",
  "position": 1,
  "mobile": "13800138000",
  "status": "在职",
  "sys_user": 123  // New User ID to bind
}

PATCH Request Body Example (Partial Update):

{
  "sys_user": 123  // User ID to bind
}

Response Example:

{
  "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:

{
  "sys_user": null
}

Response Example:

{
  "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:

{
  "user": 123,  // User ID
  "merchant": 1,  // Merchant ID
  "description": "User profile for system access"
}

Response Example:

{
  "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):

{
  "description": "Updated user profile for system access"
}

Response Example:

{
  "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. 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:

{
  "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:

{
  "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.
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

{
  "sys_user": [
    "User with id 123 is already bound to an existing employee."
  ]
}

User already has a UserProfile

{
  "user": [
    "User with id 123 already has a UserProfile."
  ]
}

6.1 User Creation API Errors

Username already exists

{
  "username": [
    "用户名已存在"
  ]
}

Merchant does not exist

{
  "merchant_id": [
    "商户不存在"
  ]
}

Password too short

{
  "password": [
    "Ensure this field has at least 6 characters."
  ]
}

Unauthenticated request

{
  "error": "未授权"
}

Server error during creation

{
  "error": "创建用户失败: [detailed error message]"
}

7. Usage Examples

7.1 Creating a Complete User Flow

# 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

{
  "sys_user": [
    "Invalid pk \"999\" - object does not exist."
  ]
}

Permission denied

{
  "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.