feat: add recharge create and status APIs

progress.md

@@ -649,3 +649,31 @@
 - 阻塞：T-304 功能与相关测试无阻塞；完整测试仍被远程 MySQL `43.128.3.240:3306` 连接稳定性阻塞。生产真实支付还需要安装/配置微信、支付宝 SDK 与商户密钥/证书；当前 mock 仅用于本地/测试联调。
 - 决策：T-304 只做回调验签与幂等入账；扫码下单、订单状态查询、前端轮询留给 T-305。`PointsLedger.ref_order_id` 本轮仍保持数值引用，配合复合唯一约束兜底防重复充值流水。
 - 下一步：领取 T-305 扫码充值下单 + 轮询（create/status）。
+
+## 2026-07-03 T-305 扫码充值下单 + 轮询（create/status）
+
+- 状态：DONE
+- 变更：
+  - `apps/billing/services.py`：新增 `create_recharge_order()`，创建 pending 订单并绑定发起用户；下单时锁定当前 `ExchangeRate.points_per_unit` 与 `points_granted`，再调用支付网关下单取二维码票据；支付平台下单失败时订单标记 `failed`。
+  - `apps/billing/payment_gateways.py`：新增 `PaymentOrderCode`、`create_payment_order()`、微信/支付宝 mock 二维码生成、微信金额分转换、支付宝金额元格式化，以及 SDK 模式下单/查单入口；mock 查单明确返回不可用，等待回调或测试注入主动查单结果。
+  - `apps/api/views.py` / `apps/api/serializers.py` / `apps/api/urls.py`：新增 `POST /api/v1/recharge/create` 与 `GET /api/v1/recharge/status`；两个端点走 `SessionAuthentication + IsAuthenticated`，不继承外部 API Key 视图；create 受 CSRF 保护，status 只允许订单所属用户访问，并在 pending 时尝试主动查单补入账。
+  - `config/settings.py` / `.env.example` / `docs/env.md`：新增 `PAYMENT_QR_EXPIRES_MINUTES`，仅作为二维码本地有效期提示，不自动把 pending 订单改 expired。
+  - `apps/billing/tests.py`：覆盖创建充值订单锁定汇率/点数/二维码票据、网关下单失败时订单标记 failed。
+  - `apps/api/tests.py`：覆盖 session 下单、API Key 不能调用充值下单、真实 session 客户端无 CSRF 被拒、支付宝 mock 二维码、状态查询本人可见/他人 404、主动查单补入账且不重复入账。
+  - 同步更新 `README.md`、`docs/00-ai-start-here.md`、`docs/03-tech-stack.md`、`docs/04-architecture.md`、`docs/api.md`、`docs/06-tasks.md`、`docs/current-state.md`。
+- 验证：
+  - `./init.ps1`：开工前通过，依赖同步与基础检查正常。
+  - `py -3.12 -m py_compile apps\billing\payment_gateways.py apps\billing\services.py apps\billing\tests.py apps\api\serializers.py apps\api\views.py apps\api\urls.py apps\api\tests.py config\settings.py`：通过。
+  - `py -3.12 manage.py test apps.billing apps.api --noinput --keepdb --verbosity 2`：通过，53 tests OK。
+  - `py -3.12 manage.py check`：通过，0 issues。
+  - `py -3.12 manage.py makemigrations --check`：通过，No changes detected。
+  - `py -3.12 -m compileall apps config`：通过。
+  - `git diff --check`：通过，仅 Windows CRLF 提示。
+  - `py -3.12 manage.py test --noinput --keepdb --verbosity 2`：未作为绿灯；发现 81 tests，跑过 71 tests，已运行用例均无断言失败；远程 MySQL `43.128.3.240:3306` 连接超时导致 `BillingCoreModelTests.setUpClass` 与 `AdminSmokeTests.setUpClass` 失败。
+  - `$env:MYSQL_CONNECT_TIMEOUT='90'; py -3.12 manage.py test apps.billing.tests.BillingCoreModelTests apps.users.tests.AdminSmokeTests --noinput --keepdb --verbosity 2`：通过，10 tests OK。
+  - 补微信主动查单 SDK 入口后，`py -3.12 -m py_compile apps\billing\payment_gateways.py apps\billing\services.py apps\api\views.py apps\api\tests.py`：通过；`py -3.12 manage.py check`：通过。
+  - `py -3.12 manage.py test apps.api.tests.RechargeCreateStatusApiTests apps.billing.tests.BillingServiceTests.test_create_recharge_order_locks_exchange_rate_points_and_qr_code apps.billing.tests.BillingServiceTests.test_create_recharge_order_marks_order_failed_when_gateway_fails --noinput --keepdb --verbosity 2`：未作为绿灯；API 新增 6 tests OK 后，进入 billing 测试类时远程 MySQL 连接超时。
+  - `$env:MYSQL_CONNECT_TIMEOUT='90'; py -3.12 manage.py test apps.billing.tests.BillingServiceTests.test_create_recharge_order_locks_exchange_rate_points_and_qr_code apps.billing.tests.BillingServiceTests.test_create_recharge_order_marks_order_failed_when_gateway_fails --noinput --keepdb --verbosity 2`：通过，2 tests OK。
+- 阻塞：T-305 功能与相关测试无阻塞；完整测试仍被远程 MySQL 连接稳定性阻塞。真实支付生产下单 / 查单仍需要安装 SDK 并提供微信、支付宝商户密钥/证书与公网 notify_url；当前 mock 用于本地/测试联调。
+- 决策：状态轮询不因本地 `expires_at` 自动把 pending 订单改 expired，避免误挡延迟到达的真实支付回调；二维码过期只作为前端提示，支付结果仍以回调或主动查单入账为准。T-305 只提供服务端 create/status，实际用户端充值页面留给 T-504。
+- 下一步：领取 T-501 注册 / 登录（allauth）。