eryao/docs/protocols/points/points-redeem-code-protocol.md

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:

{
  "code": "RX8P2N6K4JQW"
}

Field rules:

• code: string, normalized uppercase code

Response (200):

{
  "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.