Zareian
ae0375c26c
The Swagger header was a list of features. That is what the project does, not what a caller needs. It now opens with the three things anyone integrating against this API asks first: how do I get a token, what does an error look like, and when do I get rate limited -- plus the field-naming and date conventions, and a note that the schema is the contract and clients should be generated from it rather than written from memory. Swagger UI and Redoc both render Markdown, so it is structured rather than one long paragraph, which also fixes how badly the old mixed Persian/Latin line wrapped right-to-left. Two defects surfaced while checking the rendered schema: - /api/health was absent from the schema entirely. The trailing-slash alias was excluded with extend_schema(exclude=True)(HealthView), but that decorator mutates the class, and both routes pointed at the same class, so the canonical route disappeared with it. A subclass now carries the exclusion, and the endpoint is back, exactly once. Endpoint count is 56, not 55. - One endpoint was tagged 'محتوا (content)' while every other content endpoint used 'Curriculum (content)', which split the group into two sections. Tags are now declared with descriptions and ordered by the path a real user takes, rather than alphabetically. Comment pass over the codebase, keeping the substance and dropping the noise: the "⚠️ اضافه شده" prefixes dated comments against a moment no current reader shares; "فاز ۲ / بخش ۴" referenced a plan that no longer exists and only repeated the app name on the next line; "فاز اول - ۴ از ۱۱ اپ" had drifted (there are fourteen). INSTALLED_APPS is now grouped by responsibility. The TEST_LOGIN_PHONES block in settings shrank from 29 lines to 8 now that the same explanation lives in docs/operations.md and .env.example -- a comment beside the code should carry what a code reader needs, not a copy of the runbook. Checked mechanically that no comment references an identifier that no longer exists: zero. The dated measurements in rag/services/ingest.py and generate_questions_from_chunks.py were deliberately left alone -- a measurement carrying the date it was taken is the useful kind. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
123 lines
5.7 KiB
Python
123 lines
5.7 KiB
Python
from django.shortcuts import get_object_or_404
|
||
from drf_spectacular.utils import extend_schema
|
||
from rest_framework.exceptions import ValidationError
|
||
from rest_framework.permissions import IsAuthenticated
|
||
from rest_framework.response import Response
|
||
from rest_framework.throttling import ScopedRateThrottle
|
||
from rest_framework.views import APIView
|
||
|
||
from .models import AffiliateAccount, Conversion
|
||
from .serializers import (
|
||
AffiliateMeResponseSerializer,
|
||
ConversionListResponseSerializer,
|
||
TrackRequestSerializer,
|
||
TrackResponseSerializer,
|
||
)
|
||
|
||
|
||
class GuestAwareAffiliateThrottle(ScopedRateThrottle):
|
||
"""
|
||
همان الگویِ GuestAwareDiscountThrottle/GuestAwareFamilyThrottle
|
||
و بقیه؛ چرخشِ حسابِ مهمان (deviceId جدید → pk جدید) یک ScopedRateThrottleِ
|
||
سادهٔ per-user رو دور می‌زد. اینجا حساس‌تره چون referralCode یک
|
||
شناسه‌ی حدس‌زدنی‌ست (404 برای کدِ نامعتبر = oracle) و یک حدسِ درست
|
||
یک Conversion واقعی می‌سازه که به کمیسیونِ مالیِ affiliate صاحبِ کد
|
||
منجر می‌شه؛ یعنی بدونِ این throttle، چرخشِ حساب مهمان به مهاجم
|
||
guessهای عملاً نامحدودی برای enumerate/fraud کردنِ کدهای رفرال
|
||
می‌داد. برای کاربرهای مهمان کلیدِ cache از pk به IP کلاینت تغییر
|
||
می‌کنه؛ رفتارِ throttle برای کاربرهای غیرمهمان (per-user، مثلِ
|
||
قبل) دست‌نخورده می‌مونه.
|
||
"""
|
||
|
||
def get_cache_key(self, request, view):
|
||
user = request.user
|
||
if user and user.is_authenticated and getattr(user, 'is_guest', False):
|
||
ident = f'guest-ip:{self.get_ident(request)}'
|
||
elif user and user.is_authenticated:
|
||
ident = user.pk
|
||
else:
|
||
ident = self.get_ident(request)
|
||
|
||
return self.cache_format % {'scope': self.scope, 'ident': ident}
|
||
|
||
|
||
class AffiliateMeView(APIView):
|
||
"""GET /api/affiliate/me — حساب و کد ارجاع کاربر"""
|
||
|
||
permission_classes = [IsAuthenticated]
|
||
|
||
@extend_schema(responses=AffiliateMeResponseSerializer, tags=['Affiliate (affiliate)'])
|
||
def get(self, request):
|
||
account, _ = AffiliateAccount.objects.get_or_create(user_id=request.user.id)
|
||
|
||
data = {'referralCode': account.referral_code, 'commissionRate': account.commission_rate}
|
||
return Response(AffiliateMeResponseSerializer(data).data)
|
||
|
||
|
||
class TrackConversionView(APIView):
|
||
"""
|
||
POST /api/affiliate/track — ثبت کلیک/ارجاع
|
||
|
||
طبق سند، این اپ فقط با referralCode به AffiliateAccount وصل می‌شه.
|
||
referredUserId دیگه ورودیِ کلاینت نیست: چون این درخواست باید توسطِ
|
||
خودِ کاربرِ تازه‌ارجاع‌شده (بعد از لاگین/ثبت‌نام) زده بشه، هویتش رو
|
||
از توکن احرازشده (request.user) می‌گیریم، نه از بدنه‌ی درخواست.
|
||
|
||
# هویت از request.user گرفته می‌شه (نه بدنه‌ی درخواست) چون یک
|
||
# referredUserIdِ کلاینت‌دار یعنی هر کلاینتِ ناشناس می‌تونست برای هر
|
||
# کاربرِ دیگه‌ای Conversion بسازه یا با اشغالِ همه‌ی userId ها (قیدِ
|
||
# unique رو دورزدن) مسیرِ ارجاعِ واقعی رو مسدود کنه.
|
||
"""
|
||
|
||
permission_classes = [IsAuthenticated]
|
||
# referralCode نامعتبر ۴۰۴ می‌گیره (یک oracle قابلprobe)، پس throttle
|
||
# مجزا هم probe رو کند می‌کنه هم (با GuestAwareAffiliateThrottle) جلویِ
|
||
# bucket تازه از چرخشِ حساب مهمان رو می‌گیره.
|
||
throttle_scope = 'affiliate_track'
|
||
throttle_classes = [GuestAwareAffiliateThrottle]
|
||
|
||
@extend_schema(
|
||
request=TrackRequestSerializer, responses=TrackResponseSerializer, tags=['Affiliate (affiliate)']
|
||
)
|
||
def post(self, request):
|
||
serializer = TrackRequestSerializer(data=request.data)
|
||
serializer.is_valid(raise_exception=True)
|
||
v = serializer.validated_data
|
||
|
||
account = get_object_or_404(AffiliateAccount, referral_code=v['referralCode'])
|
||
referred_user_id = request.user.id
|
||
|
||
if referred_user_id == account.user_id:
|
||
raise ValidationError({'referredUserId': 'امکان ثبت ارجاع برای خودِ صاحب کد وجود ندارد.'})
|
||
|
||
conversion, _ = Conversion.objects.get_or_create(
|
||
referred_user_id=referred_user_id,
|
||
defaults={'affiliate_account': account},
|
||
)
|
||
|
||
data = {'success': True, 'conversionId': str(conversion.pk), 'status': conversion.status}
|
||
return Response(TrackResponseSerializer(data).data)
|
||
|
||
|
||
class ConversionsListView(APIView):
|
||
"""GET /api/affiliate/conversions — لیست تبدیل‌ها و کمیسیون"""
|
||
|
||
permission_classes = [IsAuthenticated]
|
||
|
||
@extend_schema(responses=ConversionListResponseSerializer, tags=['Affiliate (affiliate)'])
|
||
def get(self, request):
|
||
account = AffiliateAccount.objects.filter(user_id=request.user.id).first()
|
||
conversions = account.conversions.all() if account else Conversion.objects.none()
|
||
|
||
items = [
|
||
{
|
||
'id': str(c.pk),
|
||
'referredUserId': str(c.referred_user_id),
|
||
'status': c.status,
|
||
'commissionAmount': c.commission_amount,
|
||
}
|
||
for c in conversions
|
||
]
|
||
data = {'conversions': items}
|
||
return Response(ConversionListResponseSerializer(data).data)
|