49 lines
1.2 KiB
Markdown
49 lines
1.2 KiB
Markdown
|
# 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`
|
||
|
|
|
||
|
|
## 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`.
|