Реализация системы кошелька клиента для переплат
- Добавлено поле wallet_balance в модель Customer - Создана модель WalletTransaction для истории операций - Реализован сервис WalletService с методами: * add_overpayment - автоматическое зачисление переплаты * pay_with_wallet - оплата заказа из кошелька * adjust_balance - ручная корректировка баланса - Интеграция с Payment.save() для автоматической обработки переплат - UI для оплаты из кошелька в деталях заказа - Отображение баланса и долга на странице клиента - Админка с inline транзакций и запретом ручного создания - Добавлен способ оплаты account_balance - Миграция 0004 для customers приложения
This commit is contained in:
771
nested-singing-rainbow.md
Normal file
771
nested-singing-rainbow.md
Normal file
@@ -0,0 +1,771 @@
|
||||
# План реализации системы личного счета клиента
|
||||
|
||||
## Обзор
|
||||
|
||||
Реализация системы личного счета для клиентов цветочного магазина с поддержкой резервирования средств, смешанной оплаты, автоматического пополнения при переплате и полной историей транзакций.
|
||||
|
||||
## Ключевые бизнес-требования
|
||||
|
||||
1. **Баланс счета**: У каждого клиента есть личный счет (может быть положительным или отрицательным)
|
||||
2. **Пополнение**: Вручную администратором или автоматически при переплате заказа
|
||||
3. **Кредитование**: Разрешен отрицательный баланс для доверенных клиентов
|
||||
4. **История операций**: Полный аудит всех операций со счетом
|
||||
5. **Смешанная оплата**: Можно комбинировать с другими способами оплаты
|
||||
6. **Резервирование**: При создании заказа средства резервируются, при завершении списываются
|
||||
7. **Управление**: Только администраторы/менеджеры имеют доступ
|
||||
|
||||
---
|
||||
|
||||
## 1. Изменения в базе данных
|
||||
|
||||
### 1.1 Расширение модели Customer
|
||||
|
||||
**Файл**: `myproject/customers/models.py`
|
||||
|
||||
Добавить поля для управления балансом:
|
||||
|
||||
```python
|
||||
# Поля баланса
|
||||
account_balance = models.DecimalField(
|
||||
max_digits=10,
|
||||
decimal_places=2,
|
||||
default=0,
|
||||
verbose_name="Баланс счета",
|
||||
help_text="Текущий баланс лицевого счета клиента"
|
||||
)
|
||||
|
||||
available_balance = models.DecimalField(
|
||||
max_digits=10,
|
||||
decimal_places=2,
|
||||
default=0,
|
||||
verbose_name="Доступный баланс",
|
||||
help_text="Баланс за вычетом зарезервированных средств"
|
||||
)
|
||||
|
||||
reserved_balance = models.DecimalField(
|
||||
max_digits=10,
|
||||
decimal_places=2,
|
||||
default=0,
|
||||
verbose_name="Зарезервировано",
|
||||
help_text="Сумма, зарезервированная под активные заказы"
|
||||
)
|
||||
|
||||
allow_negative_balance = models.BooleanField(
|
||||
default=False,
|
||||
verbose_name="Разрешить отрицательный баланс",
|
||||
help_text="Позволяет клиенту уходить в минус"
|
||||
)
|
||||
|
||||
negative_balance_limit = models.DecimalField(
|
||||
max_digits=10,
|
||||
decimal_places=2,
|
||||
default=0,
|
||||
verbose_name="Лимит кредита",
|
||||
help_text="Максимальная сумма отрицательного баланса (0 = без лимита)"
|
||||
)
|
||||
```
|
||||
|
||||
**Взаимосвязь полей**:
|
||||
- `account_balance` = Общий баланс клиента
|
||||
- `reserved_balance` = Сумма, зарезервированная под заказы
|
||||
- `available_balance` = `account_balance` - `reserved_balance`
|
||||
|
||||
### 1.2 Новая модель AccountTransaction
|
||||
|
||||
**Файл**: `myproject/customers/models.py` (или отдельный файл в models/)
|
||||
|
||||
Модель для хранения истории всех операций со счетом:
|
||||
|
||||
```python
|
||||
class AccountTransaction(models.Model):
|
||||
"""
|
||||
Транзакция по лицевому счету клиента.
|
||||
"""
|
||||
TRANSACTION_TYPE_CHOICES = [
|
||||
('deposit', 'Пополнение вручную'),
|
||||
('auto_deposit', 'Авто-пополнение (переплата)'),
|
||||
('reservation', 'Резервирование'),
|
||||
('reservation_release', 'Снятие резерва'),
|
||||
('charge', 'Списание за заказ'),
|
||||
('refund', 'Возврат средств'),
|
||||
('adjustment', 'Корректировка баланса'),
|
||||
]
|
||||
|
||||
STATUS_CHOICES = [
|
||||
('active', 'Активна'),
|
||||
('completed', 'Завершена'),
|
||||
('cancelled', 'Отменена'),
|
||||
]
|
||||
|
||||
customer = models.ForeignKey(
|
||||
'Customer',
|
||||
on_delete=models.PROTECT,
|
||||
related_name='account_transactions'
|
||||
)
|
||||
|
||||
transaction_type = models.CharField(max_length=30, choices=TRANSACTION_TYPE_CHOICES)
|
||||
amount = models.DecimalField(max_digits=10, decimal_places=2)
|
||||
|
||||
balance_before = models.DecimalField(max_digits=10, decimal_places=2)
|
||||
balance_after = models.DecimalField(max_digits=10, decimal_places=2)
|
||||
|
||||
order = models.ForeignKey('orders.Order', null=True, blank=True, on_delete=models.PROTECT)
|
||||
payment = models.ForeignKey('orders.Payment', null=True, blank=True, on_delete=models.SET_NULL)
|
||||
related_transaction = models.ForeignKey('self', null=True, blank=True, on_delete=models.SET_NULL)
|
||||
|
||||
description = models.TextField()
|
||||
notes = models.TextField(blank=True)
|
||||
status = models.CharField(max_length=20, choices=STATUS_CHOICES, default='completed')
|
||||
|
||||
created_at = models.DateTimeField(auto_now_add=True)
|
||||
created_by = models.ForeignKey('accounts.CustomUser', null=True, blank=True, on_delete=models.SET_NULL)
|
||||
|
||||
class Meta:
|
||||
ordering = ['-created_at']
|
||||
indexes = [
|
||||
models.Index(fields=['customer', '-created_at']),
|
||||
models.Index(fields=['transaction_type']),
|
||||
models.Index(fields=['order']),
|
||||
models.Index(fields=['status']),
|
||||
]
|
||||
```
|
||||
|
||||
### 1.3 Новый способ оплаты
|
||||
|
||||
Добавить в команду `create_payment_methods.py`:
|
||||
|
||||
```python
|
||||
{
|
||||
'code': 'account_balance',
|
||||
'name': 'С баланса счета',
|
||||
'description': 'Списание с личного счета клиента',
|
||||
'is_system': True,
|
||||
'order': 0 # Первый в списке
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Бизнес-логика: AccountBalanceService
|
||||
|
||||
**Новый файл**: `myproject/customers/services/account_balance_service.py`
|
||||
|
||||
Создать сервис с методами:
|
||||
|
||||
### Основные методы:
|
||||
|
||||
1. **`deposit(customer, amount, description, user, notes)`**
|
||||
- Пополнение счета вручную администратором
|
||||
- Увеличивает `account_balance` и `available_balance`
|
||||
- Создает транзакцию типа `deposit`
|
||||
|
||||
2. **`auto_deposit_from_overpayment(order, overpayment_amount, user)`**
|
||||
- Автоматическое пополнение при переплате
|
||||
- Вызывается когда `order.amount_paid > order.total_amount`
|
||||
- Создает транзакцию типа `auto_deposit`
|
||||
|
||||
3. **`reserve_balance(customer, order, amount, user)`**
|
||||
- Резервирование средств при создании заказа с оплатой со счета
|
||||
- Проверяет достаточность средств (с учетом кредита)
|
||||
- Уменьшает `available_balance`, увеличивает `reserved_balance`
|
||||
- Создает транзакцию типа `reservation` со статусом `active`
|
||||
|
||||
4. **`charge_reserved_balance(reservation_transaction, user)`**
|
||||
- Списание зарезервированных средств при завершении заказа
|
||||
- Уменьшает `account_balance` и `reserved_balance`
|
||||
- Обновляет статус резервирования на `completed`
|
||||
- Создает транзакцию типа `charge`
|
||||
|
||||
5. **`release_reservation(reservation_transaction, user)`**
|
||||
- Снятие резервирования при отмене заказа
|
||||
- Увеличивает `available_balance`, уменьшает `reserved_balance`
|
||||
- Обновляет статус резервирования на `cancelled`
|
||||
- Создает транзакцию типа `reservation_release`
|
||||
|
||||
6. **`refund(customer, amount, order, description, user, notes)`**
|
||||
- Возврат средств на счет
|
||||
- Используется при индивидуальных решениях по возвратам
|
||||
- Создает транзакцию типа `refund`
|
||||
|
||||
7. **`adjustment(customer, amount, description, user, notes)`**
|
||||
- Корректировка баланса администратором
|
||||
- Может быть положительной или отрицательной
|
||||
- Требует обязательное описание
|
||||
|
||||
### Ключевые особенности реализации:
|
||||
|
||||
- Все методы используют `@transaction.atomic` для атомарности
|
||||
- `select_for_update()` для блокировки записи клиента при изменении
|
||||
- Проверка лимитов кредита перед резервированием
|
||||
- Запись `balance_before` и `balance_after` для аудита
|
||||
|
||||
---
|
||||
|
||||
## 3. Интеграция с существующей системой платежей
|
||||
|
||||
### 3.1 Модификация Payment.save()
|
||||
|
||||
**Файл**: `myproject/orders/models/payment.py`
|
||||
|
||||
В методе `save()` добавить логику:
|
||||
|
||||
```python
|
||||
def save(self, *args, **kwargs):
|
||||
is_new = self.pk is None
|
||||
super().save(*args, **kwargs)
|
||||
|
||||
# Пересчитываем сумму оплаты
|
||||
self.order.amount_paid = sum(p.amount for p in self.order.payments.all())
|
||||
|
||||
# Обработка оплаты с баланса счета
|
||||
if self.payment_method.code == 'account_balance' and is_new:
|
||||
from customers.services.account_balance_service import AccountBalanceService
|
||||
AccountBalanceService.reserve_balance(
|
||||
customer=self.order.customer,
|
||||
order=self.order,
|
||||
amount=self.amount,
|
||||
user=self.created_by
|
||||
)
|
||||
|
||||
self.order.update_payment_status()
|
||||
|
||||
# Проверка переплаты
|
||||
if self.order.amount_paid > self.order.total_amount:
|
||||
overpayment = self.order.amount_paid - self.order.total_amount
|
||||
from customers.services.account_balance_service import AccountBalanceService
|
||||
AccountBalanceService.auto_deposit_from_overpayment(
|
||||
order=self.order,
|
||||
overpayment_amount=overpayment,
|
||||
user=self.created_by
|
||||
)
|
||||
```
|
||||
|
||||
### 3.2 Обработка изменения статуса заказа
|
||||
|
||||
**Новый файл**: `myproject/orders/signals.py`
|
||||
|
||||
Создать сигналы для автоматической обработки:
|
||||
|
||||
```python
|
||||
from django.db.models.signals import post_save
|
||||
from django.dispatch import receiver
|
||||
from .models import Order
|
||||
|
||||
@receiver(post_save, sender=Order)
|
||||
def handle_order_status_change(sender, instance, created, **kwargs):
|
||||
"""Обработка изменения статуса заказа"""
|
||||
if created or not instance.status:
|
||||
return
|
||||
|
||||
from customers.models import AccountTransaction
|
||||
from customers.services.account_balance_service import AccountBalanceService
|
||||
|
||||
# Заказ выполнен успешно - списываем
|
||||
if instance.status.is_positive_end:
|
||||
reservations = AccountTransaction.objects.filter(
|
||||
order=instance,
|
||||
transaction_type='reservation',
|
||||
status='active'
|
||||
)
|
||||
for reservation in reservations:
|
||||
AccountBalanceService.charge_reserved_balance(
|
||||
reservation_transaction=reservation,
|
||||
user=instance.modified_by
|
||||
)
|
||||
|
||||
# Заказ отменен - снимаем резерв
|
||||
elif instance.status.is_negative_end:
|
||||
reservations = AccountTransaction.objects.filter(
|
||||
order=instance,
|
||||
transaction_type='reservation',
|
||||
status='active'
|
||||
)
|
||||
for reservation in reservations:
|
||||
AccountBalanceService.release_reservation(
|
||||
reservation_transaction=reservation,
|
||||
user=instance.modified_by
|
||||
)
|
||||
```
|
||||
|
||||
Подключить сигналы в `myproject/orders/apps.py`:
|
||||
|
||||
```python
|
||||
class OrdersConfig(AppConfig):
|
||||
default_auto_field = 'django.db.models.BigAutoField'
|
||||
name = 'orders'
|
||||
|
||||
def ready(self):
|
||||
import orders.signals # noqa
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Административный интерфейс
|
||||
|
||||
### 4.1 Расширение CustomerAdmin
|
||||
|
||||
**Файл**: `myproject/customers/admin.py`
|
||||
|
||||
Изменения:
|
||||
|
||||
1. **Добавить поля баланса в list_display**:
|
||||
```python
|
||||
list_display = (
|
||||
'full_name', 'email', 'phone',
|
||||
'account_balance_colored', # новое
|
||||
'available_balance_display', # новое
|
||||
'reserved_balance_display', # новое
|
||||
'total_spent',
|
||||
'is_system_customer',
|
||||
'created_at'
|
||||
)
|
||||
```
|
||||
|
||||
2. **Добавить фильтр по кредиту**:
|
||||
```python
|
||||
list_filter = (
|
||||
IsSystemCustomerFilter,
|
||||
'allow_negative_balance', # новое
|
||||
'created_at'
|
||||
)
|
||||
```
|
||||
|
||||
3. **Добавить секцию баланса в fieldsets**:
|
||||
```python
|
||||
('Баланс лицевого счета', {
|
||||
'fields': (
|
||||
'account_balance',
|
||||
'available_balance',
|
||||
'reserved_balance',
|
||||
'allow_negative_balance',
|
||||
'negative_balance_limit',
|
||||
),
|
||||
'classes': ('wide',),
|
||||
}),
|
||||
```
|
||||
|
||||
4. **Добавить inline для транзакций**:
|
||||
```python
|
||||
class AccountTransactionInline(admin.TabularInline):
|
||||
model = AccountTransaction
|
||||
extra = 0
|
||||
can_delete = False
|
||||
readonly_fields = [...]
|
||||
|
||||
inlines = [AccountTransactionInline]
|
||||
```
|
||||
|
||||
5. **Добавить actions**:
|
||||
```python
|
||||
actions = [
|
||||
'add_deposit',
|
||||
'add_refund',
|
||||
'add_adjustment',
|
||||
'enable_negative_balance',
|
||||
]
|
||||
```
|
||||
|
||||
### 4.2 Новый AccountTransactionAdmin
|
||||
|
||||
**Файл**: `myproject/customers/admin.py`
|
||||
|
||||
Создать отдельную админку для просмотра всех транзакций:
|
||||
|
||||
```python
|
||||
@admin.register(AccountTransaction)
|
||||
class AccountTransactionAdmin(admin.ModelAdmin):
|
||||
list_display = [
|
||||
'created_at', 'customer_link', 'transaction_type',
|
||||
'amount_colored', 'balance_after', 'order_link', 'status'
|
||||
]
|
||||
list_filter = ['transaction_type', 'status', 'created_at']
|
||||
search_fields = ['customer__name', 'customer__email', 'description']
|
||||
readonly_fields = [все поля]
|
||||
|
||||
def has_add_permission(self, request):
|
||||
return False # Только через сервис
|
||||
|
||||
def has_delete_permission(self, request, obj=None):
|
||||
return False # Аудит, нельзя удалять
|
||||
```
|
||||
|
||||
### 4.3 Кастомные views для операций
|
||||
|
||||
**Новый файл**: `myproject/customers/admin_views.py`
|
||||
|
||||
Создать views для:
|
||||
- Пополнения баланса (`/admin/customers/deposit/`)
|
||||
- Возврата средств (`/admin/customers/refund/`)
|
||||
- Корректировки (`/admin/customers/adjustment/`)
|
||||
|
||||
**Новый файл**: `myproject/customers/admin_urls.py`
|
||||
|
||||
```python
|
||||
from django.urls import path
|
||||
from . import admin_views
|
||||
|
||||
urlpatterns = [
|
||||
path('deposit/', admin_views.deposit_view, name='customer_deposit'),
|
||||
path('refund/', admin_views.refund_view, name='customer_refund'),
|
||||
path('adjustment/', admin_views.adjustment_view, name='customer_adjustment'),
|
||||
]
|
||||
```
|
||||
|
||||
Подключить в основной `urls.py`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Формы для операций
|
||||
|
||||
**Новый файл**: `myproject/customers/forms.py`
|
||||
|
||||
Создать формы:
|
||||
|
||||
```python
|
||||
class DepositForm(forms.Form):
|
||||
"""Форма пополнения баланса"""
|
||||
customer = forms.ModelChoiceField(queryset=Customer.objects.all())
|
||||
amount = forms.DecimalField(min_value=0.01, max_digits=10, decimal_places=2)
|
||||
description = forms.CharField(widget=forms.Textarea)
|
||||
notes = forms.CharField(widget=forms.Textarea, required=False)
|
||||
|
||||
class RefundForm(forms.Form):
|
||||
"""Форма возврата средств"""
|
||||
customer = forms.ModelChoiceField(queryset=Customer.objects.all())
|
||||
amount = forms.DecimalField(min_value=0.01, max_digits=10, decimal_places=2)
|
||||
order = forms.ModelChoiceField(queryset=Order.objects.all(), required=False)
|
||||
description = forms.CharField(widget=forms.Textarea)
|
||||
notes = forms.CharField(widget=forms.Textarea, required=False)
|
||||
|
||||
class AdjustmentForm(forms.Form):
|
||||
"""Форма корректировки баланса"""
|
||||
customer = forms.ModelChoiceField(queryset=Customer.objects.all())
|
||||
amount = forms.DecimalField(max_digits=10, decimal_places=2) # может быть отрицательным
|
||||
description = forms.CharField(widget=forms.Textarea)
|
||||
notes = forms.CharField(widget=forms.Textarea, required=False)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. UI/UX улучшения
|
||||
|
||||
### 6.1 Отображение баланса в форме заказа
|
||||
|
||||
**Файл**: `myproject/orders/templates/orders/order_form.html`
|
||||
|
||||
Добавить блок с информацией о балансе клиента:
|
||||
|
||||
```html
|
||||
{% if order.customer %}
|
||||
<div class="alert alert-info">
|
||||
<h5>Баланс клиента</h5>
|
||||
<ul>
|
||||
<li>Общий баланс: <strong>{{ order.customer.account_balance }} руб.</strong></li>
|
||||
<li>Доступно: <strong>{{ order.customer.available_balance }} руб.</strong></li>
|
||||
<li>Зарезервировано: <strong>{{ order.customer.reserved_balance }} руб.</strong></li>
|
||||
</ul>
|
||||
</div>
|
||||
{% endif %}
|
||||
```
|
||||
|
||||
### 6.2 Валидация при выборе оплаты со счета
|
||||
|
||||
**Файл**: `myproject/orders/static/orders/js/payment_validation.js`
|
||||
|
||||
Добавить JS-валидацию:
|
||||
|
||||
```javascript
|
||||
// Проверка достаточности средств при выборе оплаты со счета
|
||||
function validateAccountBalance(paymentMethodCode, amount, availableBalance, allowNegative, creditLimit) {
|
||||
if (paymentMethodCode === 'account_balance') {
|
||||
if (amount > availableBalance && !allowNegative) {
|
||||
alert('Недостаточно средств на счете клиента!');
|
||||
return false;
|
||||
}
|
||||
if (allowNegative && creditLimit > 0) {
|
||||
let potentialBalance = availableBalance - amount;
|
||||
if (Math.abs(potentialBalance) > creditLimit) {
|
||||
alert('Превышен лимит кредита клиента!');
|
||||
return false;
|
||||
}
|
||||
}
|
||||
}
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Миграции
|
||||
|
||||
### Последовательность миграций:
|
||||
|
||||
1. **Добавить поля баланса в Customer**:
|
||||
```bash
|
||||
python manage.py makemigrations customers --name add_account_balance_fields
|
||||
```
|
||||
|
||||
2. **Создать модель AccountTransaction**:
|
||||
```bash
|
||||
python manage.py makemigrations customers --name create_account_transaction_model
|
||||
```
|
||||
|
||||
3. **Создать индексы и ограничения**:
|
||||
```bash
|
||||
python manage.py makemigrations customers --name add_balance_constraints
|
||||
```
|
||||
|
||||
4. **Инициализация данных** (data migration):
|
||||
```python
|
||||
def initialize_customer_balances(apps, schema_editor):
|
||||
Customer = apps.get_model('customers', 'Customer')
|
||||
Customer.objects.all().update(
|
||||
account_balance=0,
|
||||
available_balance=0,
|
||||
reserved_balance=0,
|
||||
allow_negative_balance=False,
|
||||
negative_balance_limit=0
|
||||
)
|
||||
```
|
||||
|
||||
5. **Добавить способ оплаты**:
|
||||
```bash
|
||||
python manage.py create_payment_methods
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Обеспечение целостности данных
|
||||
|
||||
### 8.1 Транзакции и блокировки
|
||||
|
||||
- Все операции в `@transaction.atomic`
|
||||
- Использование `select_for_update()` для блокировки записи клиента
|
||||
- Проверка статуса транзакции перед обработкой
|
||||
|
||||
### 8.2 Ограничения БД
|
||||
|
||||
```python
|
||||
# В миграции
|
||||
models.CheckConstraint(
|
||||
check=models.Q(reserved_balance__gte=0),
|
||||
name='reserved_balance_non_negative'
|
||||
)
|
||||
|
||||
models.CheckConstraint(
|
||||
check=models.Q(account_balance__gte=models.F('reserved_balance') * -1),
|
||||
name='available_balance_consistency'
|
||||
)
|
||||
```
|
||||
|
||||
### 8.3 Предотвращение дублирования
|
||||
|
||||
- Проверка `status='active'` перед обработкой резервирования
|
||||
- Связь `related_transaction` для отслеживания цепочки операций
|
||||
- Валидация перед созданием транзакции
|
||||
|
||||
---
|
||||
|
||||
## 9. Типы транзакций: Подробное описание
|
||||
|
||||
### DEPOSIT (Пополнение)
|
||||
- **Когда**: Администратор вручную пополняет счет
|
||||
- **Эффект**: `account_balance ↑`, `available_balance ↑`
|
||||
- **Статус**: `completed`
|
||||
|
||||
### AUTO_DEPOSIT (Авто-пополнение)
|
||||
- **Когда**: `order.amount_paid > order.total_amount`
|
||||
- **Эффект**: `account_balance ↑`, `available_balance ↑`
|
||||
- **Статус**: `completed`
|
||||
|
||||
### RESERVATION (Резервирование)
|
||||
- **Когда**: Создание заказа с оплатой со счета
|
||||
- **Эффект**: `available_balance ↓`, `reserved_balance ↑`
|
||||
- **Статус**: `active` → меняется при charge/release
|
||||
|
||||
### CHARGE (Списание)
|
||||
- **Когда**: Заказ выполнен (`is_positive_end=True`)
|
||||
- **Эффект**: `account_balance ↓`, `reserved_balance ↓`
|
||||
- **Статус**: `completed`
|
||||
|
||||
### RESERVATION_RELEASE (Снятие резерва)
|
||||
- **Когда**: Заказ отменен (`is_negative_end=True`)
|
||||
- **Эффект**: `available_balance ↑`, `reserved_balance ↓`
|
||||
- **Статус**: `completed`
|
||||
|
||||
### REFUND (Возврат)
|
||||
- **Когда**: Администратор принимает решение о возврате
|
||||
- **Эффект**: `account_balance ↑`, `available_balance ↑`
|
||||
- **Статус**: `completed`
|
||||
|
||||
### ADJUSTMENT (Корректировка)
|
||||
- **Когда**: Ручная корректировка администратором
|
||||
- **Эффект**: `account_balance ±`, `available_balance ±`
|
||||
- **Статус**: `completed`
|
||||
|
||||
---
|
||||
|
||||
## 10. Сценарии использования
|
||||
|
||||
### Сценарий 1: Заказ с полной оплатой со счета
|
||||
|
||||
1. Клиент создает заказ на 540 руб.
|
||||
2. На балансе 1000 руб.
|
||||
3. Выбирается способ оплаты "С баланса счета"
|
||||
4. **Создается RESERVATION** на 540 руб.: `available_balance: 1000→460`, `reserved_balance: 0→540`
|
||||
5. При выполнении заказа создается **CHARGE**: `account_balance: 1000→460`, `reserved_balance: 540→0`
|
||||
|
||||
### Сценарий 2: Смешанная оплата
|
||||
|
||||
1. Заказ на 540 руб.
|
||||
2. На балансе 300 руб.
|
||||
3. Создается Payment со счета на 300 руб. → **RESERVATION** 300 руб.
|
||||
4. Создается Payment наличными на 240 руб.
|
||||
5. При выполнении → **CHARGE** 300 руб. со счета
|
||||
|
||||
### Сценарий 3: Переплата с авто-пополнением
|
||||
|
||||
1. Заказ на 540 руб.
|
||||
2. Клиент платит наличными 1000 руб.
|
||||
3. `order.amount_paid = 1000`, `order.total_amount = 540`
|
||||
4. Система создает **AUTO_DEPOSIT** на 460 руб.
|
||||
5. Баланс клиента увеличивается на 460 руб.
|
||||
|
||||
### Сценарий 4: Отмена заказа
|
||||
|
||||
1. Заказ на 540 руб. с резервированием
|
||||
2. `reserved_balance = 540`, `available_balance = 460`
|
||||
3. Заказ меняет статус на "Отменен" (`is_negative_end=True`)
|
||||
4. Сигнал создает **RESERVATION_RELEASE**
|
||||
5. `available_balance: 460→1000`, `reserved_balance: 540→0`
|
||||
|
||||
### Сценарий 5: Кредит доверенного клиента
|
||||
|
||||
1. У клиента баланс 0 руб., но `allow_negative_balance=True`
|
||||
2. Заказ на 540 руб.
|
||||
3. Создается **RESERVATION** на 540 руб.
|
||||
4. `account_balance: 0→0`, `available_balance: 0→-540`, `reserved_balance: 0→540`
|
||||
5. При выполнении **CHARGE**: `account_balance: 0→-540`
|
||||
|
||||
---
|
||||
|
||||
## 11. Тестирование
|
||||
|
||||
### Unit Tests
|
||||
|
||||
**Файл**: `myproject/customers/tests/test_account_balance_service.py`
|
||||
|
||||
Тесты:
|
||||
- `test_deposit_increases_balance`
|
||||
- `test_reserve_decreases_available`
|
||||
- `test_charge_decreases_account_balance`
|
||||
- `test_release_increases_available`
|
||||
- `test_overpayment_creates_auto_deposit`
|
||||
- `test_negative_balance_validation`
|
||||
- `test_credit_limit_enforcement`
|
||||
- `test_concurrent_operations`
|
||||
|
||||
### Integration Tests
|
||||
|
||||
**Файл**: `myproject/orders/tests/test_order_with_account_balance.py`
|
||||
|
||||
Тесты:
|
||||
- `test_order_with_account_payment`
|
||||
- `test_mixed_payment_scenario`
|
||||
- `test_order_completion_charges_balance`
|
||||
- `test_order_cancellation_releases_reservation`
|
||||
- `test_overpayment_auto_deposit`
|
||||
|
||||
---
|
||||
|
||||
## 12. Критические файлы для реализации
|
||||
|
||||
1. **`myproject/customers/models.py`**
|
||||
- Добавить поля баланса в Customer
|
||||
- Создать модель AccountTransaction
|
||||
|
||||
2. **`myproject/customers/services/account_balance_service.py`** (НОВЫЙ)
|
||||
- Все методы управления балансом
|
||||
|
||||
3. **`myproject/orders/models/payment.py`**
|
||||
- Модифицировать `save()` для обработки оплаты со счета
|
||||
|
||||
4. **`myproject/orders/signals.py`** (НОВЫЙ)
|
||||
- Обработка изменения статуса заказа
|
||||
|
||||
5. **`myproject/customers/admin.py`**
|
||||
- Расширить CustomerAdmin
|
||||
- Создать AccountTransactionAdmin
|
||||
|
||||
6. **`myproject/customers/admin_views.py`** (НОВЫЙ)
|
||||
- Views для пополнения/возврата/корректировки
|
||||
|
||||
7. **`myproject/customers/forms.py`** (НОВЫЙ)
|
||||
- Формы для операций с балансом
|
||||
|
||||
8. **`myproject/orders/management/commands/create_payment_methods.py`**
|
||||
- Добавить способ оплаты 'account_balance'
|
||||
|
||||
9. **`myproject/orders/apps.py`**
|
||||
- Подключить сигналы
|
||||
|
||||
---
|
||||
|
||||
## 13. Последовательность реализации
|
||||
|
||||
### Фаза 1: Модели и миграции (основа)
|
||||
1. Добавить поля в Customer
|
||||
2. Создать AccountTransaction
|
||||
3. Создать миграции
|
||||
4. Инициализировать данные
|
||||
|
||||
### Фаза 2: Бизнес-логика (ядро)
|
||||
1. Создать AccountBalanceService со всеми методами
|
||||
2. Покрыть unit-тестами
|
||||
|
||||
### Фаза 3: Интеграция с заказами (связывание)
|
||||
1. Модифицировать Payment.save()
|
||||
2. Создать signals.py
|
||||
3. Добавить способ оплаты
|
||||
4. Покрыть integration-тестами
|
||||
|
||||
### Фаза 4: Административный интерфейс (управление)
|
||||
1. Расширить CustomerAdmin
|
||||
2. Создать AccountTransactionAdmin
|
||||
3. Создать формы и views для операций
|
||||
4. Настроить URLs
|
||||
|
||||
### Фаза 5: UI/UX улучшения (удобство)
|
||||
1. Отображение баланса в форме заказа
|
||||
2. JS-валидация при оплате
|
||||
3. Виджеты истории транзакций
|
||||
|
||||
### Фаза 6: Тестирование и документация (качество)
|
||||
1. Полное покрытие тестами
|
||||
2. Ручное тестирование сценариев
|
||||
3. Документация для администраторов
|
||||
|
||||
---
|
||||
|
||||
## 14. Безопасность и права доступа
|
||||
|
||||
- Только `staff_member_required` для admin views
|
||||
- Транзакции нельзя удалять (`has_delete_permission = False`)
|
||||
- Транзакции нельзя создавать вручную (`has_add_permission = False`)
|
||||
- Все операции требуют `created_by` (аудит)
|
||||
- Mandatory `description` для adjustment
|
||||
|
||||
---
|
||||
|
||||
## Заключение
|
||||
|
||||
Данная архитектура обеспечивает:
|
||||
- ✅ Полную историю операций (аудит)
|
||||
- ✅ Атомарность операций (транзакции БД)
|
||||
- ✅ Защиту от race conditions (блокировки)
|
||||
- ✅ Гибкость (смешанная оплата, кредит)
|
||||
- ✅ Интеграцию с существующей системой
|
||||
- ✅ Простоту управления (admin interface)
|
||||
- ✅ Безопасность (только администраторы)
|
||||
|
||||
Решение готово к production-использованию после прохождения всех фаз тестирования.
|
||||
Reference in New Issue
Block a user