79 lines
2.2 KiB
Markdown
79 lines
2.2 KiB
Markdown
|
# 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`.
|