feat: add invite rewards and redeem codes

2026-05-21 16:26:58 +08:00
parent d712645754
commit 673f8fed30
67 changed files with 3813 additions and 265 deletions
@@ -7,6 +7,7 @@ Protocol verification status:
 - Backend route source: `backend/src/v1/points/router.py`
 - Backend service source: `backend/src/v1/points/service.py`
 - Response schema source: `backend/src/v1/points/schemas.py`
+- Related redeem protocol: `docs/protocols/points/points-redeem-code-protocol.md`

 ## Compatibility strategy

@@ -0,0 +1,78 @@
+# Points Redeem Code Protocol (Frontend <-> Backend)
+
+This document defines the redeem-code activation contract for authenticated web users.
+
+Protocol verification status:
+
+- Backend route source: `backend/src/v1/points/router.py`
+- Backend service source: `backend/src/v1/points/service.py`
+- Response schema source: `backend/src/v1/points/schemas.py`
+- Web mapping source: `web/src/lib/api.ts`
+
+## Compatibility strategy
+
+- Additive evolution only.
+- Existing read-only balance/package routes remain backward-compatible.
+
+## Route
+
+### POST /api/v1/points/redeem-codes/redeem
+
+Redeem a one-time activation code and credit the matching package points to the current account.
+
+**Authorization**: Requires authenticated session.
+
+**Request**:
+
+```json
+{
+  "code": "RX8P2N6K4JQW"
+}
+```
+
+Field rules:
+
+- `code`: string, normalized uppercase code
+
+**Response (200)**:
+
+```json
+{
+  "packageProductCode": "popular_pack",
+  "packageName": "常用加量包",
+  "creditsAdded": 210,
+  "newBalance": 330,
+  "redeemedAt": "2026-05-21T12:30:00+00:00"
+}
+```
+
+Field rules:
+
+- `packageProductCode`: package mapping key from backend static package config
+- `packageName`: current package display label snapshot stored in the redeem code record
+- `creditsAdded`: integer `> 0`
+- `newBalance`: integer `>= 0`
+- `redeemedAt`: ISO 8601 datetime
+
+## Business rules
+
+- Redeem codes are one-time use.
+- Redeem codes do not count as a successful recharge for invite reward qualification.
+- Redeem crediting is written to points ledger and points audit ledger.
+- Redeem activation must also write a system audit log entry.
+
+## Error contract linkage
+
+- RFC7807 + extension `code`, optional `params`.
+- Shared registry: `docs/protocols/common/http-error-codes.md`.
+- Error codes for this feature:
+  - `REDEEM_CODE_NOT_FOUND` (404): Redeem code does not exist
+  - `REDEEM_CODE_ALREADY_REDEEMED` (409): Redeem code was already activated
+  - `REDEEM_CODE_DISABLED` (409): Redeem code is disabled or unavailable
+  - `REDEEM_CODE_INVALID` (422): Redeem code format is invalid
+
+## Data model linkage
+
+- Redeem code batches are stored in `redeem_code_batches`.
+- Redeem codes are stored in `redeem_codes`.
+- Package snapshots come from `backend/src/core/config/static/packages/mapping.yaml`.