fix: stabilize production payment flow

progress.md

@@ -1103,3 +1103,49 @@
   - `py -3.12 manage.py check`：通过，0 issues。
   - `py -3.12 manage.py test apps.billing.tests.BillingAdminTests.test_exchange_rate_changelist_renders_when_rates_exist --keepdb --noinput --verbosity 2`：通过，1 test OK；测试阶段仍有既有 allauth MySQL `models.W036` 警告。
 - 下一步：提交并部署后，在 VPS 上重启 `cmhub-web.service`，用 Django test client 或浏览器确认 `/admin/billing/exchangerate/` 已恢复 200。
+
+## 2026-07-04 Mock 支付二维码提示
+
+- 状态：DONE
+- 背景：线上 `PAYMENT_CALLBACK_MODE=mock` 时生成的微信二维码内容为 `weixin://wxpay/cmhub-mock...`，该票据只用于联调，不会进入微信真实支付页；用户用微信扫码可能看到空白，容易误认为生产支付异常。
+- 文档先行：
+  - `docs/api.md`：补充 mock 模式返回的是测试二维码票据，不能跳转真实微信/支付宝收银台；用户端充值页应展示醒目 mock 提示。
+  - `docs/04-architecture.md`：补充 `/recharge` 页面在 `PAYMENT_CALLBACK_MODE=mock` 时必须提示测试票据不可真实支付。
+- 代码：
+  - `apps/portal/views.py`：向充值页模板传入 `payment_callback_mode` 与 `is_mock_payment_mode`。
+  - `apps/portal/templates/portal/recharge.html`：待支付订单区域在 mock 模式下显示 warning 提示。
+  - `apps/portal/tests.py`：覆盖 mock 模式显示提示、sdk 模式不显示提示。
+- 验证：
+  - `py -3.12 -m py_compile apps\portal\views.py apps\portal\tests.py`：通过。
+  - `py -3.12 manage.py check`：通过，0 issues。
+  - `py -3.12 manage.py test apps.portal.tests.PortalAccountFlowTests.test_recharge_page_post_creates_pending_order_without_crediting_wallet_or_ledger apps.portal.tests.PortalAccountFlowTests.test_recharge_page_does_not_show_mock_notice_in_sdk_mode --keepdb --noinput --verbosity 2`：通过，2 tests OK；测试阶段仍有既有 allauth MySQL `models.W036` 警告。
+
+## 2026-07-04 临时隐藏用户端支付宝充值入口
+
+- 状态：DONE
+- 背景：线上支付宝 `trade.precreate` 返回 `isv.illegal-client-ip` / `当前调用IP不在可信名单中`，VPS 出口 IP 已确认为 `43.128.3.240`；在支付宝开放平台可信 IP 未配置前，用户端展示支付宝会持续创建失败订单。
+- 变更：
+  - `apps/portal/forms.py`：`RechargeCreateForm.pay_method` 暂时只保留微信选项，页面不再渲染支付宝 radio，手工提交 `pay_method=alipay` 也会被表单拒绝。
+  - `apps/portal/tests.py`：覆盖充值页不显示支付宝、超过上限仍按微信校验、隐藏支付宝提交不创建订单。
+  - `docs/current-state.md`：记录支付宝临时下线原因和恢复条件；底层 API / 回调 / SDK 路径保留。
+- 恢复条件：支付宝开放平台把 `43.128.3.240` 加入可信 IP 白名单并通过真实预下单 smoke 后，再把 `RechargeCreateForm` 的支付宝 choice 加回。
+
+## 2026-07-06 支付正式模式热修收敛
+
+- 状态：DONE
+- 背景：生产已切到 `PAYMENT_CALLBACK_MODE=sdk` 并配置微信 / 支付宝真实参数后，微信 1 元下单先后暴露两个 SDK 兼容问题；支付宝预下单返回业务错误 `isv.illegal-client-ip`。
+- 变更：
+  - `requirements.txt`：新增 `wechatpayv3` / `python-alipay-sdk`，并把 `cryptography` 上限放宽到 `<50`，对齐真实支付 SDK 依赖。
+  - `.gitignore`：忽略 `.secrets/` / `secrets/`，避免支付证书和私钥误入库。
+  - `apps/billing/payment_gateways.py`：微信 Native 下单显式传 `WeChatPayType.NATIVE`；兼容 `wechatpayv3` 返回 `(status_code, json_string)` 的 tuple 响应，统一解析 `code_url` 与查单结果。
+  - `apps/api/views.py`：pending 充值订单主动查单遇到支付网关运行时异常时不再让状态接口 500，而是记录 warning 并保持当前订单状态返回 200。
+  - `apps/portal/forms.py`：支付宝可信 IP 未配置前，用户端充值表单只保留微信；手工提交 `pay_method=alipay` 会被表单拒绝。
+  - `docs/api.md` / `docs/04-architecture.md` / `docs/current-state.md`：同步 mock 提示、微信正式下单热修、支付宝临时下线和恢复条件。
+- 验证：
+  - `py -3.12 -m py_compile apps\billing\payment_gateways.py apps\api\views.py apps\billing\tests.py apps\api\tests.py`：通过。
+  - `py -3.12 manage.py check`：通过，0 issues。
+  - `py -3.12 manage.py test apps.billing.tests.BillingServiceTests.test_wechat_sdk_native_order_passes_explicit_pay_type apps.billing.tests.BillingServiceTests.test_wechat_sdk_query_parses_tuple_json_response apps.api.tests.RechargeCreateStatusApiTests.test_recharge_status_keeps_pending_when_active_query_raises_unexpected_error --keepdb --noinput --verbosity 2`：通过，3 tests OK。
+  - `py -3.12 -m py_compile apps\portal\forms.py apps\portal\tests.py`：通过。
+  - `py -3.12 manage.py test apps.portal.tests.PortalAccountFlowTests.test_recharge_page_requires_login_and_shows_form apps.portal.tests.PortalAccountFlowTests.test_recharge_page_rejects_amount_above_configured_maximum apps.portal.tests.PortalAccountFlowTests.test_recharge_page_rejects_hidden_alipay_submit --keepdb --noinput --verbosity 2`：通过，3 tests OK。
+  - 线上：同步热修后 `python3.12 manage.py check` 通过，`cmhub-web` / `cmhub-generate` 重启后均为 `active`；修复后的微信 1 分诊断预支付请求返回 `weixin://wxpay/bizpayurl` 票据；用户端表单 choices 仅剩 `微信`，支付宝提交无效。
+- 后续：微信下单已通，但线上微信回调曾出现 `PaymentVerificationError`，仍需修复并做真实支付到账闭环；支付宝需在开放平台把 VPS 出口 IP `43.128.3.240` 加入可信 IP 后再恢复页面选项。