From c083880cbcd008d11c99183399eace5aeb2ccd45 Mon Sep 17 00:00:00 2001
From: erio <asakifeng@gmail.com>
Date: Mon, 2 Mar 2026 04:17:51 +0800
Subject: [PATCH] =?UTF-8?q?docs+feat:=20=E5=AE=8C=E5=96=84=20README=20?=
 =?UTF-8?q?=E5=B8=AE=E5=8A=A9=E5=86=85=E5=AE=B9=E9=85=8D=E7=BD=AE=E8=AF=B4?=
 =?UTF-8?q?=E6=98=8E=EF=BC=8C=E6=94=AF=E6=8C=81=E5=A4=9A=E8=A1=8C=E6=96=87?=
 =?UTF-8?q?=E5=AD=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- README (中/英) 修正 NEXT_PUBLIC_PAY_HELP_* → PAY_HELP_*
- 新增 PAYMENT_PROVIDERS 配置说明（两步配置服务商+渠道）
- 说明帮助图片支持外部 URL 或本地 uploads/ 两种方式
- PAY_HELP_TEXT 支持 \n 换行，渲染为多行段落
---
 README.en.md         | 43 ++++++++++++++++++++++++++++++++++++++-----
 README.md            | 43 ++++++++++++++++++++++++++++++++++++++-----
 src/app/pay/page.tsx |  8 +++++---
 3 files changed, 81 insertions(+), 13 deletions(-)

diff --git a/README.en.md b/README.en.md
index e6d43f2..c54b1d4 100644
--- a/README.en.md
+++ b/README.en.md
@@ -94,12 +94,24 @@ See [`.env.example`](./.env.example) for the full template.
 
 > `DATABASE_URL` is automatically injected by Docker Compose when using the bundled database.
 
-### Payment Methods
+### Payment Providers & Methods
 
-Control which payment methods are enabled via `ENABLED_PAYMENT_TYPES` (comma-separated):
+**Step 1**: Declare which payment providers to load via `PAYMENT_PROVIDERS` (comma-separated):
 
 ```env
-ENABLED_PAYMENT_TYPES=alipay,wxpay,stripe
+# EasyPay only
+PAYMENT_PROVIDERS=easypay
+# Stripe only
+PAYMENT_PROVIDERS=stripe
+# Both
+PAYMENT_PROVIDERS=easypay,stripe
+```
+
+**Step 2**: Control which channels are shown to users via `ENABLED_PAYMENT_TYPES`:
+
+```env
+# EasyPay supports: alipay, wxpay  |  Stripe supports: stripe
+ENABLED_PAYMENT_TYPES=alipay,wxpay
 ```
 
 #### EasyPay (Alipay / WeChat Pay)
@@ -137,10 +149,31 @@ ENABLED_PAYMENT_TYPES=alipay,wxpay,stripe
 
 ### UI Customization (Optional)
 
+Display a support contact image and description on the right side of the payment page.
+
 | Variable | Description |
 |----------|-------------|
-| `NEXT_PUBLIC_PAY_HELP_IMAGE_URL` | Help image URL (e.g. customer service QR code) |
-| `NEXT_PUBLIC_PAY_HELP_TEXT` | Help text displayed on payment page |
+| `PAY_HELP_IMAGE_URL` | Help image URL — external URL or local path (see below) |
+| `PAY_HELP_TEXT` | Help text; use `\n` for line breaks, e.g. `Scan to add WeChat\nMon–Fri 9am–6pm` |
+
+**Two ways to provide the image:**
+
+- **External URL** (recommended — no Compose changes needed): any publicly accessible image link (CDN, OSS, image hosting).
+  ```env
+  PAY_HELP_IMAGE_URL=https://cdn.example.com/help-qr.jpg
+  ```
+
+- **Local file**: place the image in `./uploads/` and reference it as `/uploads/<filename>`.
+  The directory must be mounted in `docker-compose.app.yml` (included by default):
+  ```yaml
+  volumes:
+    - ./uploads:/app/public/uploads:ro
+  ```
+  ```env
+  PAY_HELP_IMAGE_URL=/uploads/help-qr.jpg
+  ```
+
+> Clicking the help image opens it full-screen in the center of the screen.
 
 ### Docker Compose Variables
 
diff --git a/README.md b/README.md
index 9ff8118..f090b14 100644
--- a/README.md
+++ b/README.md
@@ -94,12 +94,24 @@ docker compose up -d --build
 
 > `DATABASE_URL` 使用自带数据库时由 Compose 自动注入，无需手动填写。
 
-### 支付方式
+### 支付服务商与支付方式
 
-通过 `ENABLED_PAYMENT_TYPES` 控制开启哪些支付方式（逗号分隔）：
+**第一步**：通过 `PAYMENT_PROVIDERS` 声明启用哪些支付服务商（逗号分隔）：
 
 ```env
-ENABLED_PAYMENT_TYPES=alipay,wxpay,stripe
+# 仅易支付
+PAYMENT_PROVIDERS=easypay
+# 仅 Stripe
+PAYMENT_PROVIDERS=stripe
+# 两者都用
+PAYMENT_PROVIDERS=easypay,stripe
+```
+
+**第二步**：通过 `ENABLED_PAYMENT_TYPES` 控制向用户展示哪些支付渠道：
+
+```env
+# 易支付支持: alipay, wxpay；Stripe 支持: stripe
+ENABLED_PAYMENT_TYPES=alipay,wxpay
 ```
 
 #### EasyPay（支付宝 / 微信支付）
@@ -137,10 +149,31 @@ ENABLED_PAYMENT_TYPES=alipay,wxpay,stripe
 
 ### UI 定制（可选）
 
+在充值页面右侧可展示客服联系方式、说明图片等帮助内容。
+
 | 变量 | 说明 |
 |------|------|
-| `NEXT_PUBLIC_PAY_HELP_IMAGE_URL` | 帮助图片 URL（如客服二维码） |
-| `NEXT_PUBLIC_PAY_HELP_TEXT` | 帮助说明文字 |
+| `PAY_HELP_IMAGE_URL` | 帮助图片地址（支持外部 URL 或本地路径，见下方说明） |
+| `PAY_HELP_TEXT` | 帮助说明文字，用 `\n` 换行，如 `扫码加微信\n工作日 9-18 点在线` |
+
+**图片地址两种方式：**
+
+- **外部 URL**（推荐，无需改 Compose 配置）：直接填图片的公网地址，如 OSS / CDN / 图床链接。
+  ```env
+  PAY_HELP_IMAGE_URL=https://cdn.example.com/help-qr.jpg
+  ```
+
+- **本地文件**：将图片放到 `./uploads/` 目录，通过 `/uploads/文件名` 引用。
+  需在 `docker-compose.app.yml` 中挂载目录（默认已包含）：
+  ```yaml
+  volumes:
+    - ./uploads:/app/public/uploads:ro
+  ```
+  ```env
+  PAY_HELP_IMAGE_URL=/uploads/help-qr.jpg
+  ```
+
+> 点击帮助图片可在屏幕中央全屏放大查看。
 
 ### Docker Compose 专用
 
diff --git a/src/app/pay/page.tsx b/src/app/pay/page.tsx
index 5f8824e..e39bf1f 100644
--- a/src/app/pay/page.tsx
+++ b/src/app/pay/page.tsx
@@ -438,9 +438,11 @@ function PayContent() {
                       />
                     )}
                     {helpText && (
-                      <p className={['mt-3 text-sm leading-6', isDark ? 'text-slate-300' : 'text-slate-600'].join(' ')}>
-                        {helpText}
-                      </p>
+                      <div className={['mt-3 space-y-1 text-sm leading-6', isDark ? 'text-slate-300' : 'text-slate-600'].join(' ')}>
+                        {helpText.split('\\n').map((line, i) => (
+                          <p key={i}>{line}</p>
+                        ))}
+                      </div>
                     )}
                   </div>
                 )}