2026-04-03 19:04:46 +08:00
|
|
|
# Points Balance Protocol (Frontend <-> Backend)
|
|
|
|
|
|
|
|
|
|
This document defines the read-only points balance contract for authenticated 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`
|
2026-05-21 16:26:58 +08:00
|
|
|
- Related redeem protocol: `docs/protocols/points/points-redeem-code-protocol.md`
|
2026-04-03 19:04:46 +08:00
|
|
|
|
|
|
|
|
## Compatibility strategy
|
|
|
|
|
|
|
|
|
|
- Additive evolution only.
|
|
|
|
|
- Existing response fields are stable and must remain backward-compatible.
|
|
|
|
|
|
|
|
|
|
## Route
|
|
|
|
|
|
|
|
|
|
- `GET /api/v1/points/balance`
|
|
|
|
|
|
|
|
|
|
## Authorization
|
|
|
|
|
|
|
|
|
|
- Requires authenticated session.
|
|
|
|
|
- User identity is derived from verified backend auth context.
|
|
|
|
|
|
|
|
|
|
## Response (200)
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
{
|
|
|
|
|
"balance": 120,
|
|
|
|
|
"frozenBalance": 20,
|
|
|
|
|
"availableBalance": 100,
|
|
|
|
|
"runCost": 20,
|
|
|
|
|
"canRun": true
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Field rules:
|
|
|
|
|
|
|
|
|
|
- `balance`: integer `>= 0`
|
|
|
|
|
- `frozenBalance`: integer `>= 0`
|
|
|
|
|
- `availableBalance`: integer `>= 0`, computed as `max(balance - frozenBalance, 0)`
|
|
|
|
|
- `runCost`: integer `> 0`, current value `20`
|
|
|
|
|
- `canRun`: boolean, equivalent to `availableBalance >= runCost`
|
|
|
|
|
|
|
|
|
|
## Error contract linkage
|
|
|
|
|
|
|
|
|
|
- RFC7807 + extension `code`, optional `params`.
|
|
|
|
|
- Shared registry: `docs/protocols/common/http-error-codes.md`.
|
