zuowei/erpnew
1
0
Fork 0
forked from erp-dev/erp
Code Pull Requests Activity

feat: added user profile model & api & admin, it uses by found user with merchant

Browse Source
This commit is contained in:
colaftc
2025-11-24 12:58:29 +08:00
parent 0e77496d9a
commit 506b0cb448
11 changed files with 588 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

300
api_man/employee_user_binding.md Normal file
View 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.

21
api_man/serializers.py
View File

@@ -1,5 +1,6 @@
from rest_framework import serializers
from basic_info import models as basic_models
from django.contrib.auth.models import User
import logging
@@ -159,3 +160,23 @@ class VehicleTransportRecordSerializer(BaseSerializer):
model = basic_models.VehicleTransportRecord
fields = '__all__'
depth = 1 # 展开外键关系
class UserSerializerSimple(serializers.ModelSerializer):
class Meta:
model = basic_models.User
fields = ['id', 'username', 'email', 'is_active', 'is_superuser', 'last_login']
class UserProfileSerializer(BaseSerializer):
user = serializers.PrimaryKeyRelatedField(
queryset=User.objects.all()
)
user_detail = UserSerializerSimple(source='user', read_only=True)
class Meta:
model = basic_models.UserProfile
fields = ['id', 'user', 'user_detail', 'merchant', 'description', 'created_at', 'updated_at']
extra_kwargs = {
'merchant': {'required': False} # 创建时由视图层设置
}

153
api_man/tests.py
View File

@@ -303,3 +303,156 @@ class EmployeeAPITestCase(TestCase):
response = self.client.patch(f'/api/backend/employees/{employee.id}/', data, format='json')
self.assertEqual(response.status_code, status.HTTP_200_OK)
self.assertEqual(response.data['job_type'], '打纸工') # 应该保持不变
class UserProfileAPITestCase(TestCase):
"""测试用户资料 API"""
def setUp(self):
"""设置测试数据"""
# 创建商户
self.merchant = Merchant.objects.create(
name='测试商户',
type=MerchantTypeEnum.STORE
)
# 创建用户和员工
self.user = User.objects.create_user(
username='testuser',
password='testpass123',
email='test@example.com'
)
self.employee = Employee.objects.create(
merchant=self.merchant,
sys_user=self.user,
name='测试员工'
)
# 创建另一个用户用于测试
self.user2 = User.objects.create_user(
username='testuser2',
password='testpass123',
email='test2@example.com'
)
# 设置 API 客户端
self.client = APIClient()
self.client.force_authenticate(user=self.user)
def test_create_user_profile(self):
"""测试创建用户资料"""
data = {
'user': self.user2.id,
'description': '测试用户资料描述'
}
response = self.client.post('/api/backend/user-profiles/', data, format='json')
self.assertEqual(response.status_code, status.HTTP_201_CREATED)
self.assertEqual(response.data['user'], self.user2.id)
self.assertEqual(response.data['merchant'], self.merchant.id) # 应该由BaseViewSet自动设置
self.assertEqual(response.data['description'], '测试用户资料描述')
def test_list_user_profiles(self):
"""测试列出所有用户资料"""
from basic_info.models import UserProfile
UserProfile.objects.create(
user=self.user,
merchant=self.merchant,
description='用户1资料'
)
UserProfile.objects.create(
user=self.user2,
merchant=self.merchant,
description='用户2资料'
)
response = self.client.get('/api/backend/user-profiles/')
self.assertEqual(response.status_code, status.HTTP_200_OK)
results = response.data['results'] if isinstance(response.data, dict) else response.data
self.assertEqual(len(results), 2) # 应该只返回当前商户的用户资料
def test_retrieve_user_profile(self):
"""测试检索单个用户资料"""
from basic_info.models import UserProfile
profile = UserProfile.objects.create(
user=self.user,
merchant=self.merchant,
description='测试资料'
)
response = self.client.get(f'/api/backend/user-profiles/{profile.id}/')
self.assertEqual(response.status_code, status.HTTP_200_OK)
self.assertEqual(response.data['id'], profile.id)
self.assertEqual(response.data['description'], '测试资料')
self.assertEqual(response.data['user_detail']['username'], 'testuser') # 检查嵌套用户对象
def test_update_user_profile(self):
"""测试更新用户资料"""
from basic_info.models import UserProfile
profile = UserProfile.objects.create(
user=self.user,
merchant=self.merchant,
description='原始描述'
)
data = {'description': '更新后的描述'}
response = self.client.patch(f'/api/backend/user-profiles/{profile.id}/', data, format='json')
self.assertEqual(response.status_code, status.HTTP_200_OK)
self.assertEqual(response.data['description'], '更新后的描述')
# 验证数据库
profile.refresh_from_db()
self.assertEqual(profile.description, '更新后的描述')
def test_delete_user_profile(self):
"""测试删除用户资料"""
from basic_info.models import UserProfile
profile = UserProfile.objects.create(
user=self.user,
merchant=self.merchant,
description='待删除资料'
)
response = self.client.delete(f'/api/backend/user-profiles/{profile.id}/')
self.assertEqual(response.status_code, status.HTTP_204_NO_CONTENT)
self.assertFalse(UserProfile.objects.filter(id=profile.id).exists())
def test_user_profile_filter_by_merchant(self):
"""测试用户资料按商户过滤"""
# 创建另一个商户
other_merchant = Merchant.objects.create(
name='其他商户',
type=MerchantTypeEnum.FACTORY
)
# 创建另一个商户的员工
other_user = User.objects.create_user(
username='otheruser',
password='testpass123'
)
other_employee = Employee.objects.create(
merchant=other_merchant,
sys_user=other_user,
name='其他员工'
)
# 为两个商户分别创建用户资料
from basic_info.models import UserProfile
UserProfile.objects.create(
user=self.user,
merchant=self.merchant,
description='本商户用户资料'
)
UserProfile.objects.create(
user=other_user,
merchant=other_merchant,
description='其他商户用户资料'
)
# 使用当前用户（属于self.merchant）访问API
response = self.client.get('/api/backend/user-profiles/')
self.assertEqual(response.status_code, status.HTTP_200_OK)
results = response.data['results'] if isinstance(response.data, dict) else response.data
self.assertEqual(len(results), 1) # 只应该返回当前商户的用户资料
self.assertEqual(results[0]['description'], '本商户用户资料')

6
api_man/urls.py
View File

@@ -38,6 +38,9 @@ device_info_router.register(prefix='', viewset=views.DeviceInfoViewSet)
vehicle_transport_record_router = routers.DefaultRouter()
vehicle_transport_record_router.register(prefix='', viewset=views.VehicleTransportRecordViewSet)
# UserProfile router
user_profile_router = routers.DefaultRouter()
user_profile_router.register(prefix='', viewset=views.UserProfileViewSet)
urlpatterns = [
path('quick-inputs/', include(quick_input_router.urls)),
@@ -52,4 +55,5 @@ urlpatterns = [
path('bank-accounts/', include(bank_account_router.urls)),
path('device-info/', include(device_info_router.urls)),
path('vehicle-transport-records/', include(vehicle_transport_record_router.urls)),
]
path('user-profiles/', include(user_profile_router.urls)),
]

12
api_man/views.py
View File

@@ -99,3 +99,15 @@ class DeviceInfoViewSet(BaseViewSet):
class VehicleTransportRecordViewSet(BaseViewSet):
queryset = serializers.basic_models.VehicleTransportRecord.objects
serializer_class = serializers.VehicleTransportRecordSerializer
class UserProfileViewSet(BaseViewSet):
queryset = serializers.basic_models.UserProfile.objects
serializer_class = serializers.UserProfileSerializer
def filter_queryset(self, queryset):
try:
merchant = self.request.user.employee.merchant
return super().filter_queryset(queryset).filter(merchant=merchant)
except AttributeError:
raise PermissionDenied("无权限访问该对象")