addwin/promotions
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

FEATURE(promotions): add read-only admin endpoints for promotions and referrals

Browse source 
Adds GET /api/v2/promotions/admin/promotions/ and .../referrals/, listing
every Promotion (type derived from Plan.processor) and referral activity
(invited_by = resolved payee, invited_user = raw event.data['user'] --
there's no dedicated referral model or referral_code field in this
codebase). Follows the existing _user/_application file-suffix convention
with a new _admin suffix, backed by real django-filter FilterSets.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Ali Asadi 2026-08-23 17:10:49 +03:30
parent 079c795065
commit d27ae32e27
6 changed files with 401 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
apps/promotions/filters_admin.py Normal file
View file

@ -0,0 +1,36 @@
import django_filters
from .handlers import ProcessorTypeChoices
from .models import Promotion, PaymentStateChoices
class AdminPromotionFilter(django_filters.FilterSet):
user_uuid = django_filters.UUIDFilter(field_name='user_uuid')
plan = django_filters.UUIDFilter(field_name='plan__uuid')
promotion_type = django_filters.ChoiceFilter(field_name='plan__processor', choices=ProcessorTypeChoices.choices)
state = django_filters.ChoiceFilter(field_name='state', choices=PaymentStateChoices.choices)
event_label = django_filters.CharFilter(field_name='event__label', lookup_expr='exact')
created_after = django_filters.DateTimeFilter(field_name='created_at', lookup_expr='gte')
created_before = django_filters.DateTimeFilter(field_name='created_at', lookup_expr='lte')
class Meta:
model = Promotion
fields = ['user_uuid', 'plan', 'promotion_type', 'state', 'event_label', 'created_after', 'created_before']
class AdminReferralFilter(django_filters.FilterSet):
# invited_by == Promotion.user_uuid: in the referral recipient DSL
# ("->event:referral") this is who gets paid, i.e. the referrer.
invited_by = django_filters.UUIDFilter(field_name='user_uuid')
# invited_user lives only in free-form JSON (event.data['user']), so this is a
# CharFilter, not UUIDFilter: JSONField key-transform lookups compare against
# the stored string, not a native UUID the adapter can serialize.
invited_user = django_filters.CharFilter(field_name='event__data__user')
plan = django_filters.UUIDFilter(field_name='plan__uuid')
state = django_filters.ChoiceFilter(field_name='state', choices=PaymentStateChoices.choices)
created_after = django_filters.DateTimeFilter(field_name='created_at', lookup_expr='gte')
created_before = django_filters.DateTimeFilter(field_name='created_at', lookup_expr='lte')
class Meta:
model = Promotion
fields = ['invited_user', 'invited_by', 'plan', 'state', 'created_after', 'created_before']

81
apps/promotions/serializers.py
View file

@ -90,6 +90,87 @@ class PromotionStatusSerializer(serializers.Serializer):
promotion_amount = serializers.IntegerField(read_only=True, allow_null=True) promotion_amount = serializers.IntegerField(read_only=True, allow_null=True)
class AdminPlanSummarySerializer(serializers.ModelSerializer):
class Meta:
model = Plan
fields = ("uuid", "title", "processor")
class AdminPromotionSerializer(serializers.ModelSerializer):
"""Every Promotion row, i.e. every promotion received by a user."""
user = serializers.UUIDField(source='user_uuid', read_only=True)
plan = AdminPlanSummarySerializer(read_only=True)
promotion_type = serializers.SerializerMethodField()
event_label = serializers.SerializerMethodField()
state_display = serializers.CharField(source='get_state_display', read_only=True)
reward_amount = serializers.IntegerField(source='promotion_amount', read_only=True)
date = serializers.DateTimeField(source='created_at', read_only=True)
class Meta:
model = Promotion
fields = (
"uuid",
"user",
"plan",
"promotion_type",
"event_label",
"base_amount",
"reward_amount",
"state",
"state_display",
"date",
"updated_at",
)
def get_promotion_type(self, obj):
return obj.plan.processor if obj.plan_id else None
def get_event_label(self, obj):
return obj.event.label if obj.event_id else None
class AdminReferralSerializer(serializers.ModelSerializer):
"""
Referral activity, derived from Promotion rows on plans whose processor is
'referral'. There is no dedicated referral model and no referral_code field
in this codebase today (see docs/adminpanel_technical.md, "Known limitations").
In the recipient DSL a referral plan's Recipient resolves to
"->event:referral", so Promotion.user_uuid is the referrer being paid
(invited_by) -- not the person who triggered the event. The invited user
only exists as free-form JSON on the triggering Event (event.data['user']).
"""
invited_by = serializers.UUIDField(source='user_uuid', read_only=True)
invited_user = serializers.SerializerMethodField()
plan = AdminPlanSummarySerializer(read_only=True)
event_label = serializers.SerializerMethodField()
reward_amount = serializers.IntegerField(source='promotion_amount', read_only=True)
state_display = serializers.CharField(source='get_state_display', read_only=True)
date = serializers.DateTimeField(source='created_at', read_only=True)
class Meta:
model = Promotion
fields = (
"uuid",
"invited_user",
"invited_by",
"plan",
"event_label",
"reward_amount",
"state",
"state_display",
"date",
)
def get_invited_user(self, obj):
if obj.event_id and obj.event.data:
return obj.event.data.get('user')
return None
def get_event_label(self, obj):
return obj.event.label if obj.event_id else None
class UserPlanSerializer(serializers.ModelSerializer): class UserPlanSerializer(serializers.ModelSerializer):
recipients = UserRecipientSerializer(many=True, read_only=True) recipients = UserRecipientSerializer(many=True, read_only=True)
class Meta: class Meta:

12
apps/promotions/urls_admin.py Normal file
View file

@ -0,0 +1,12 @@
from django.urls import path
from . import views_admin
app_name = 'promotions-admin'
urlpatterns = [
path('promotions/', views_admin.AdminPromotionListApiView.as_view(), name='promotion-list'),
path('promotions/<uuid:uuid>/', views_admin.AdminPromotionDetailApiView.as_view(), name='promotion-detail'),
path('referrals/', views_admin.AdminReferralListApiView.as_view(), name='referral-list'),
path('referrals/<uuid:uuid>/', views_admin.AdminReferralDetailApiView.as_view(), name='referral-detail'),
]

62
apps/promotions/views_admin.py Normal file
View file

@ -0,0 +1,62 @@
from django_filters.rest_framework import DjangoFilterBackend
from rest_framework.generics import ListAPIView, RetrieveAPIView
from apps.gooyal_oauth2.rest_framework import IsAuthenticatedOrTokenMatchesOASRequirements
from .filters_admin import AdminPromotionFilter, AdminReferralFilter
from .handlers import ProcessorTypeChoices
from .models import Promotion
from .serializers import AdminPromotionSerializer, AdminReferralSerializer
ADMIN_PROMOTION_QUERYSET = Promotion.objects.select_related('plan', 'event').order_by('-created_at')
class AdminPromotionListApiView(ListAPIView):
"""Read-only: every Promotion received, per user, with type/amount/date."""
queryset = ADMIN_PROMOTION_QUERYSET
serializer_class = AdminPromotionSerializer
permission_classes = [IsAuthenticatedOrTokenMatchesOASRequirements]
required_alternate_scopes = {
"GET": [["admin.promotions:retrieve"]],
}
filter_backends = [DjangoFilterBackend]
filterset_class = AdminPromotionFilter
class AdminPromotionDetailApiView(RetrieveAPIView):
queryset = ADMIN_PROMOTION_QUERYSET
serializer_class = AdminPromotionSerializer
lookup_field = 'uuid'
permission_classes = [IsAuthenticatedOrTokenMatchesOASRequirements]
required_alternate_scopes = {
"GET": [["admin.promotions:retrieve"]],
}
class AdminReferralListApiView(ListAPIView):
"""
Read-only: referral activity. Scoped to Promotion rows on plans whose
processor == 'referral'. No dedicated Referral model / referral_code
field exists in this codebase; see docs/adminpanel_technical.md.
"""
serializer_class = AdminReferralSerializer
permission_classes = [IsAuthenticatedOrTokenMatchesOASRequirements]
required_alternate_scopes = {
"GET": [["admin.referrals:retrieve"]],
}
filter_backends = [DjangoFilterBackend]
filterset_class = AdminReferralFilter
def get_queryset(self):
return ADMIN_PROMOTION_QUERYSET.filter(plan__processor=ProcessorTypeChoices.REFERRAL)
class AdminReferralDetailApiView(RetrieveAPIView):
serializer_class = AdminReferralSerializer
lookup_field = 'uuid'
permission_classes = [IsAuthenticatedOrTokenMatchesOASRequirements]
required_alternate_scopes = {
"GET": [["admin.referrals:retrieve"]],
}
def get_queryset(self):
return ADMIN_PROMOTION_QUERYSET.filter(plan__processor=ProcessorTypeChoices.REFERRAL)

209
docs/adminpanel_technical.md Normal file
View file

@ -0,0 +1,209 @@
# Admin panel — technical reference
Two read-only endpoints added for the admin panel: **Promotions** (every promotion received, per user) and **Referral System** (referral activity). Both live in `apps/promotions`, following this repo's existing `_user` / `_application` file-suffix convention with a new `_admin` suffix:
| File | Purpose |
|---|---|
| `apps/promotions/views_admin.py` | `AdminPromotionListApiView`, `AdminPromotionDetailApiView`, `AdminReferralListApiView`, `AdminReferralDetailApiView` |
| `apps/promotions/urls_admin.py` | URL routes, `app_name = 'promotions-admin'` |
| `apps/promotions/filters_admin.py` | `AdminPromotionFilter`, `AdminReferralFilter` (django-filter `FilterSet`s) |
| `apps/promotions/serializers.py` | `AdminPromotionSerializer`, `AdminReferralSerializer`, `AdminPlanSummarySerializer` (added alongside the existing serializers, this repo does not split serializers by audience) |
Mounted in `main/urls.py`:
```python
path('api/v2/promotions/admin/', include('apps.promotions.urls_admin', namespace='promotions-admin')),
```
No models or migrations were changed. Both endpoints are pure `ListAPIView`/`RetrieveAPIView` reads over the existing `Promotion` table.
---
## Auth
Same pattern as every other view in this app: `IsAuthenticatedOrTokenMatchesOASRequirements` (`apps/gooyal_oauth2/rest_framework.py`) with a `required_alternate_scopes` dict keyed by HTTP method.
| Endpoint | Scope |
|---|---|
| Promotions (list + detail) | `admin.promotions:retrieve` |
| Referral System (list + detail) | `admin.referrals:retrieve` |
These are new scope names — introspected the same way as every other scope in this app, via the central **accounts** OAuth2 provider. They are not yet registered there; that's an operational step outside this checkout (see Known limitations).
---
## 1. Promotions
`GET /api/v2/promotions/admin/promotions/` — list
`GET /api/v2/promotions/admin/promotions/<uuid>/` — detail
Every `Promotion` row (i.e. every promotion a user has received or is in-flight for), across all plans and all users.
### Query params (filters)
| Param | Type | Maps to | Notes |
|---|---|---|---|
| `user_uuid` | UUID | `Promotion.user_uuid` | exact |
| `plan` | UUID | `Promotion.plan.uuid` | exact |
| `promotion_type` | choice: `percentage` \| `referral` \| `others` | `Promotion.plan.processor` | see "Promotion type", below |
| `state` | choice: `1`-`7` | `Promotion.state` | see state table below |
| `event_label` | string | `Promotion.event.label` | exact |
| `created_after` | ISO datetime | `Promotion.created_at >=` | |
| `created_before` | ISO datetime | `Promotion.created_at <=` | |
| `limit`, `offset` | int | pagination | `LimitOffsetPagination`, project default `PAGE_SIZE=200` |
### Response fields
| Field | Type | Description |
|---|---|---|
| `uuid` | UUID | Promotion row id |
| `user` | UUID | `Promotion.user_uuid` — who received/will receive the payout |
| `plan.uuid` | UUID | The triggering plan |
| `plan.title` | string | Plan title |
| `plan.processor` | string | Raw `Plan.processor` value |
| `promotion_type` | string \| null | Same as `plan.processor`; null only if `plan` itself is null (see limitations) |
| `event_label` | string \| null | Label of the `Event` that triggered this promotion; null for synchronous per-plan promotes with no linked event |
| `base_amount` | int \| null | Amount before percentage/cap math |
| `reward_amount` | int \| null | `Promotion.promotion_amount` — the actual payout amount |
| `state` | int | Raw `PaymentStateChoices` value (1-7) |
| `state_display` | string | Human-readable state |
| `date` | datetime | `Promotion.created_at` |
| `updated_at` | datetime | `Promotion.updated_at` |
### Payment states
| Value | Label |
|---|---|
| 1 | created |
| 2 | delayed |
| 3 | pending |
| 4 | incomplete |
| 5 | success |
| 6 | failed |
| 7 | expected_failure |
### Example
```
GET /api/v2/promotions/admin/promotions/?promotion_type=referral&state=5
```
```json
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"uuid": "7cb39284-cf95-43a5-b9d0-9c230f7e2f21",
"user": "1bb3b561-2823-4a3e-be12-edc5a6e623e8",
"plan": {
"uuid": "57a9f996-5e64-4541-b928-1e0f82ca3795",
"title": "referral-plan",
"processor": "referral"
},
"promotion_type": "referral",
"event_label": "referral::signup",
"base_amount": 1000,
"reward_amount": 1000,
"state": 5,
"state_display": "success",
"date": "2026-08-23T12:41:09.823169Z",
"updated_at": "2026-08-23T12:41:09.823175Z"
}
]
}
```
---
## 2. Referral System
`GET /api/v2/promotions/admin/referrals/` — list
`GET /api/v2/promotions/admin/referrals/<uuid>/` — detail
Scoped to `Promotion` rows whose `plan.processor == 'referral'`. There is **no dedicated referral model** in this codebase — see Known limitations before relying on any field name below.
### Field derivation (read this before trusting the data)
The referral recipient pattern used throughout `apps/promotions/tests.py` is:
```python
Recipient.objects.create(
recipient_uuid_field="->event:referral", # pays whoever event.data['referral'] names
...
)
```
i.e. the calling app submits an `Event` with `data = {"user": <the person who acted>, "referral": <the referrer>}`, and the `Recipient` DSL resolves the **payee** off `event.data['referral']`. That resolved payee becomes `Promotion.user_uuid`. So:
- **`invited_by`** = `Promotion.user_uuid` — the resolved recipient of the reward, i.e. the referrer. This comes straight off the `Promotion` row (the value Recipient DSL actually resolved and paid), not raw event JSON, so it's authoritative even for more complex referral recipient expressions (e.g. the `QS:Event:...` settlement pattern also in the test suite).
- **`invited_user`** = `event.data.get('user')` — the person who performed the referred action. This is *not* authoritative: it's whatever the calling app happened to put in `data['user']` on event submission, with no model-level guarantee the key exists or is even a UUID.
### Query params (filters)
| Param | Type | Maps to | Notes |
|---|---|---|---|
| `invited_by` | UUID | `Promotion.user_uuid` | exact; the referrer being paid |
| `invited_user` | string | `Event.data['user']` (JSON key lookup) | exact string match; not type-checked |
| `plan` | UUID | `Promotion.plan.uuid` | exact |
| `state` | choice: `1`-`7` | `Promotion.state` | |
| `created_after` / `created_before` | ISO datetime | `Promotion.created_at` | |
### Response fields
| Field | Type | Description |
|---|---|---|
| `uuid` | UUID | Promotion row id |
| `invited_user` | string \| null | `event.data['user']`, raw — **not a `referral_code`, doesn't exist** |
| `invited_by` | UUID | `Promotion.user_uuid` — the referrer who was paid |
| `plan.uuid` / `.title` / `.processor` | | The referral plan |
| `event_label` | string \| null | Triggering event's label |
| `reward_amount` | int \| null | `Promotion.promotion_amount` |
| `state` / `state_display` | int / string | Same as Promotions endpoint |
| `date` | datetime | `Promotion.created_at` |
There is **no `referral_code` field** in the response — it does not exist anywhere in this codebase (models, migrations, or elsewhere). See Known limitations.
### Example
```
GET /api/v2/promotions/admin/referrals/?invited_by=1bb3b561-2823-4a3e-be12-edc5a6e623e8
```
```json
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"uuid": "7cb39284-cf95-43a5-b9d0-9c230f7e2f21",
"invited_user": "fe208494-254c-412b-8f81-f6f816b219fb",
"invited_by": "1bb3b561-2823-4a3e-be12-edc5a6e623e8",
"plan": {
"uuid": "57a9f996-5e64-4541-b928-1e0f82ca3795",
"title": "referral-plan",
"processor": "referral"
},
"event_label": "referral::signup",
"reward_amount": 1000,
"state": 5,
"state_display": "success",
"date": "2026-08-23T12:41:09.823169Z"
}
]
}
```
---
## Known limitations
- **No `referral_code`.** There is no referral-code concept anywhere in this codebase — grepped for `referral_code` / `invite_code` / `invited_by` across every `.py` file; nothing exists outside this new admin code. Referral linking today is entirely raw UUIDs passed through `Event.data` by convention, not a schema-enforced relationship. If a real invite-code system is wanted, that's a model change (new field or table) requiring a migration — intentionally out of scope here.
- **`invited_user` is unreliable.** It's read from untyped JSON (`Event.data['user']`) with no model-level guarantee it exists, is a UUID, or even refers to a real user. Treat it as informational only; `invited_by` (a real FK-adjacent field, `Promotion.user_uuid`) is the trustworthy half of this endpoint.
- **`Recipient.promotion_type` is not used for `promotion_type`.** That field exists on the model but its choices enum (`PromotionTypeChoices` in `handlers.py`) is empty, so it's always blank in real data. `promotion_type` here is `Plan.processor` instead.
- **The `ReferralHandler` in `handlers.py` is dead code.** `calculate()` references an undefined `base_amount`, `promote()` opens with a bare `return`. It plays no role in producing the `Promotion` rows this endpoint reads — referral payouts happen through the same generic `Recipient.promote()` path as every other plan type (see the repo's `README.md` "Watch list").
- **Detail routes are of limited independent use.** `AdminPromotionDetailApiView` / `AdminReferralDetailApiView` return the same shape as one row of the list endpoint; included for REST completeness (e.g. deep-linking from a table row in the admin UI) but the list endpoint with `plan`/`state` filters covers most real usage.
- **New scopes (`admin.promotions:retrieve`, `admin.referrals:retrieve`) need to be registered on the central accounts OAuth2 provider** before any real token can carry them — that's outside this checkout.
- **No automated tests were added** for these two endpoints (matching the request's scope: verified via `manage.py check`, URL resolution, and an `APIRequestFactory` smoke test against an in-memory SQLite DB with the app's Postgres/JSONField-`GinIndex` usage stubbed around, run manually — see `apps/promotions/tests.py` for the existing `APITestCase` pattern if formal tests are wanted later).

1
main/urls.py
View file

@ -30,6 +30,7 @@ urlpatterns = [
path('oauth2/', include('oauth2_provider.urls', namespace='oauth2_provider')), path('oauth2/', include('oauth2_provider.urls', namespace='oauth2_provider')),
path('promotions/', include('apps.promotions.urls_user', namespace='promotions')), path('promotions/', include('apps.promotions.urls_user', namespace='promotions')),
path('api/v2/promotions/application/<user_uuid>/', include('apps.promotions.urls_application', namespace='promotions-application')), path('api/v2/promotions/application/<user_uuid>/', include('apps.promotions.urls_application', namespace='promotions-application')),
path('api/v2/promotions/admin/', include('apps.promotions.urls_admin', namespace='promotions-admin')),
] ]
urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT) urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)