# 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`.