feat: 接入起卦后端流程并完善积分扣减链路

docs/protocols/points/points-balance-protocol.md

@@ -0,0 +1,48 @@
+# 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`.