fix: stabilize production payment flow

docs/api.md

@@ -37,7 +37,7 @@ T-502 已实现用户端 API Key 自助管理基线：`/apikeys` 走 Django sess
 
 T-503/T-505 已实现用户端个人中心 / 记录页基线：`/dashboard` 走 Django session，展示当前用户剩余点数、充值总额、入账点数、净消耗点数和最近记录；`/records/recharge` 分页展示当前登录用户的充值订单；`/records/usage` 分页展示当前登录用户的 `consume` / `refund` 点数流水并关联调用信息。页面只读，不写 `UserWallet.points_balance`。
 
-T-504/T-505 已实现用户端充值页基线：`/recharge` 走 Django session + CSRF，GET 展示余额、充值表单、当前订单和最近充值；POST 创建 pending 充值订单并用本地 static 自托管的 qrcode.js 展示支付二维码票据；浏览器轮询 `GET /api/v1/recharge/status`，订单 paid 后刷新页面重新读取余额。页面不直接加点，到账仍以支付回调或主动查单入账后的本地订单状态为准。
+T-504/T-505 已实现用户端充值页基线：`/recharge` 走 Django session + CSRF，GET 展示余额、充值表单、当前订单和最近充值；POST 创建 pending 充值订单并用本地 static 自托管的 qrcode.js 展示支付二维码票据；浏览器轮询 `GET /api/v1/recharge/status`，订单 paid 后刷新页面重新读取余额。页面不直接加点，到账仍以支付回调或主动查单入账后的本地订单状态为准。若当前 `PAYMENT_CALLBACK_MODE=mock`，页面必须明确提示二维码为测试票据、不能用微信/支付宝真实支付，避免用户把 mock 二维码当成生产收款码。当前因支付宝可信 IP 未配置，用户端 `/recharge` 表单暂只开放微信支付，底层 JSON API / 回调 / SDK 路径仍保留支付宝。
 
 通用错误响应：
 
@@ -265,7 +265,7 @@ query_and_apply_recharge_payment(order_no: str, query_func) -> RechargeResult
 - 微信走 `pay/transactions/native` 取 `code_url`；支付宝走 `trade.precreate` 取 `qr_code`；前端用 qrcode.js 渲染。
 - 走 **Web session** 鉴权（用户端流程），不同于对外 API Key；订单绑定发起用户，防充错账户。
 - T-504 的 `/recharge` 页面使用同一 `create_recharge_order()` 计费层入口创建订单；JSON API 仍保留给用户端脚本或后续前端调用。
-- 开发 / 测试 `PAYMENT_CALLBACK_MODE=mock` 时返回 mock 二维码票据；生产应使用 `sdk` 模式与真实商户配置。
+- 开发 / 测试 `PAYMENT_CALLBACK_MODE=mock` 时返回 mock 二维码票据（如 `weixin://wxpay/cmhub-mock...` / `https://qr.alipay.com/cmhub-mock...`），只用于联调订单创建、页面渲染和轮询，不会跳转到真实微信/支付宝收银台；用户端充值页应展示醒目 mock 提示。生产应使用 `sdk` 模式与真实商户配置。
 - 单笔金额超过 `RECHARGE_MAX_AMOUNT_CNY` 会返回 `bad_request`，不创建 `RechargeOrder`。
 
 ### `GET /api/v1/recharge/status?order_no=...`