feat: add balance API endpoint

progress.md

@@ -595,3 +595,27 @@
 - 阻塞：无。真实上游标题/图片接口未跑，原因是当前环境未配置可用 `AI_KEY_ENCRYPTION_KEY` + AiModel/ModelAlias + 真实上游 key；图片同步真实耗时风险仍保留到 T-403 部署前校准。
 - 决策：MVP 图片结果先用本地 media 存储返回 URL，不引入 S3 依赖；后续生产对象存储可替换 `default_storage`。
 - 下一步：领取 T-303 余额查询接口。
+
+## 2026-07-02 T-303 余额查询接口
+
+- 状态：DONE
+- 变更：
+  - `apps/billing/services.py`：新增 `BalanceSnapshot` 与 `get_balance_snapshot(user)`，只读返回 `UserWallet.points_balance` 与 `PointsLedger.points_delta` 累加值，供余额接口和后续对账复用。
+  - `apps/api/views.py`：新增 `BalanceView`，继承 `ExternalApiView`，只接受 API Key 鉴权，返回当前用户名与 `points_balance`。
+  - `apps/api/urls.py`：新增 `GET /api/v1/balance` 路由。
+  - `apps/api/tests.py`：新增余额接口测试，覆盖余额响应与流水累加一致、缺失钱包返回 0 且不创建钱包、Web session 不能调用外部余额接口。
+  - 同步更新 `README.md`、`docs/00-ai-start-here.md`、`docs/04-architecture.md`、`docs/api.md`、`docs/06-tasks.md`、`docs/current-state.md`：T-303 完成，下一步 T-304。
+- 验证：
+  - `./init.ps1`：开工前通过，依赖同步与 `manage.py check` 正常。
+  - `py -3.12 -m py_compile apps\billing\services.py apps\api\views.py apps\api\urls.py apps\api\tests.py`：通过。
+  - `py -3.12 manage.py check`：通过，0 issues。
+  - `py -3.12 manage.py makemigrations --check`：通过，No changes detected。
+  - `py -3.12 manage.py test apps.api --noinput --keepdb --verbosity 2`：通过，19 tests OK。
+  - `py -3.12 manage.py test apps.ai.tests.AiModelEncryptionTests --noinput --keepdb --verbosity 2`（设置 `MYSQL_CONNECT_TIMEOUT=90` 补跑失败类）：通过，2 tests OK。
+  - `py -3.12 -m compileall apps config`：通过。
+  - `git diff --check`：通过，仅 Windows CRLF 提示。
+  - `Test-NetConnection 43.128.3.240 -Port 3306`：一次超时，后续通过，`TcpTestSucceeded=True`。
+  - `py -3.12 manage.py test --noinput --keepdb --verbosity 2`：多次未作为绿灯；一次工具超时未取得明细，后续运行分别在 `apps.users.tests.AdminSmokeTests.setUpClass` / `apps.ai.tests.AiModelEncryptionTests.setUpClass` / `apps.billing.tests.ConcurrentDebitTests.setUp` 或测试库 setup 阶段遇到远程 MySQL 连接超时或 reset；已跑过的测试均无断言失败。
+- 阻塞：T-303 功能与相关测试无阻塞；完整测试当前被远程 MySQL `43.128.3.240:3306` 连接稳定性阻塞，后续建议数据库连通稳定后重跑一次 `py -3.12 manage.py test --noinput --keepdb --verbosity 2`。
+- 决策：余额接口返回 `UserWallet.points_balance` 作为对外余额；测试用流水累加值校验账务场景一致性。接口只读，不在 API 层创建或修改钱包。
+- 下一步：领取 T-304 充值回调（微信/支付宝验签 + 幂等入账）。