feat: add recharge callback processing

progress.md

@@ -619,3 +619,33 @@
 - 阻塞：T-303 功能与相关测试无阻塞；完整测试当前被远程 MySQL `43.128.3.240:3306` 连接稳定性阻塞，后续建议数据库连通稳定后重跑一次 `py -3.12 manage.py test --noinput --keepdb --verbosity 2`。
 - 决策：余额接口返回 `UserWallet.points_balance` 作为对外余额；测试用流水累加值校验账务场景一致性。接口只读，不在 API 层创建或修改钱包。
 - 下一步：领取 T-304 充值回调（微信/支付宝验签 + 幂等入账）。
+
+## 2026-07-03 T-304 充值回调（微信/支付宝验签 + 幂等入账）
+
+- 状态：DONE
+- 变更：
+  - `apps/billing/models.py`：新增 `RechargeOrder`，保存 `order_no`、用户、金额、通道、下单锁定汇率、预计/实际入账点数、订单状态、支付流水号与支付时间；新增 `points_ledger(ref_order_id, change_type)` 复合唯一约束，作为同一订单重复充值流水的 DB 兜底。
+  - `apps/billing/services.py`：新增 `RechargePayment` / `RechargeResult`、`apply_recharge_payment()` 与 `query_and_apply_recharge_payment()`；入账时锁订单，校验 pending、金额、通道，锁 `UserWallet` 加点，写 `PointsLedger(recharge)`，重复回调幂等返回不重复加点。
+  - `apps/billing/payment_gateways.py`：新增微信 / 支付宝回调 verifier；`PAYMENT_CALLBACK_MODE=mock` 用 HMAC 模拟验签，`sdk` 模式走 `wechatpayv3` / `python-alipay-sdk` 入口，缺 SDK 或配置时失败不入账。
+  - `apps/api/views.py` / `apps/api/urls.py`：新增 `POST /api/v1/recharge/callback/wechat` 与 `/alipay`，两个端点均无登录态、显式 `@csrf_exempt`；微信成功返回 `{"code":"SUCCESS","message":"成功"}`，支付宝成功返回纯文本 `success`。
+  - `apps/billing/admin.py`：注册只读 `RechargeOrderAdmin`。
+  - `apps/billing/tests.py`：覆盖订单 admin 注册、同一订单重复充值流水 DB 兜底、成功入账、重复回调幂等、金额不一致不入账、主动查单复用同一入账路径。
+  - `apps/api/tests.py`：覆盖微信/支付宝回调成功与重复回调幂等、mock 验签失败不入账、金额不一致不入账、开启 CSRF 检查时回调端点仍可被支付网关调用。
+  - 新增迁移 `apps/billing/migrations/0004_rechargeorder_and_more.py`，已应用到当前 MySQL。
+  - 同步更新 `.env.example`、`README.md`、`docs/00-ai-start-here.md`、`docs/03-tech-stack.md`、`docs/04-architecture.md`、`docs/api.md`、`docs/env.md`、`docs/06-tasks.md`、`docs/current-state.md`。
+- 验证：
+  - `./init.ps1`：开工前通过，依赖同步与 `manage.py check` 正常。
+  - `py -3.12 manage.py makemigrations billing`：生成 `billing.0004_rechargeorder_and_more`。
+  - `py -3.12 -m py_compile apps\billing\models.py apps\billing\admin.py apps\billing\services.py apps\billing\payment_gateways.py apps\billing\tests.py apps\api\views.py apps\api\urls.py apps\api\tests.py config\settings.py`：通过。
+  - `py -3.12 manage.py makemigrations --check`：通过，No changes detected。
+  - `py -3.12 manage.py migrate`：通过，应用 `billing.0004_rechargeorder_and_more`。
+  - `py -3.12 manage.py check`：通过，0 issues。
+  - `py -3.12 manage.py showmigrations billing`：通过，`billing.0001` ~ `0004` 均为 `[X]`。
+  - `py -3.12 manage.py test apps.billing apps.api --noinput --keepdb --verbosity 2`：通过，45 tests OK。
+  - `py -3.12 -m compileall apps config`：通过。
+  - `git diff --check`：通过，仅 Windows CRLF 提示。
+  - `py -3.12 manage.py test --noinput --keepdb --verbosity 2`：未作为绿灯；本轮跑到 65/73 后，远程 MySQL 连接超时导致 `BillingCoreModelTests.setUpClass` 失败，并引发并发测试 barrier 失败。
+  - `$env:MYSQL_CONNECT_TIMEOUT='90'; py -3.12 manage.py test apps.billing.tests.BillingCoreModelTests apps.billing.tests.ConcurrentDebitTests --noinput --keepdb --verbosity 2`：业务用例均跑过并显示 ok；最终测试库 flush 阶段仍遇到远程 MySQL 连接超时，因此命令整体未作为绿灯。
+- 阻塞：T-304 功能与相关测试无阻塞；完整测试仍被远程 MySQL `43.128.3.240:3306` 连接稳定性阻塞。生产真实支付还需要安装/配置微信、支付宝 SDK 与商户密钥/证书；当前 mock 仅用于本地/测试联调。
+- 决策：T-304 只做回调验签与幂等入账；扫码下单、订单状态查询、前端轮询留给 T-305。`PointsLedger.ref_order_id` 本轮仍保持数值引用，配合复合唯一约束兜底防重复充值流水。
+- 下一步：领取 T-305 扫码充值下单 + 轮询（create/status）。