From d643084ba958ba8ca077e82b805748dfeb5aa44d Mon Sep 17 00:00:00 2001
From: James ZHANG <1631685+TheNorthMemory@users.noreply.github.com>
Date: Fri, 15 Nov 2024 12:34:15 +0800
Subject: [PATCH] optim pay guideline (#2859)

---
 docs/.vitepress/config.ts |  5 +++++
 docs/src/6.x/pay/index.md | 36 +++++++++++++++++++++++-------------
 2 files changed, 28 insertions(+), 13 deletions(-)

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 5757468c8..8c15e4db2 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -142,6 +142,11 @@ export default {
     lightModeSwitchTitle: '浅色模式',
     darkModeSwitchTitle: '深色模式',
 
+    outline: {
+      level: [2, 3],
+      label: '页面导航',
+    },
+
     docFooter: {
       prev: '上一页',
       next: '下一页'
diff --git a/docs/src/6.x/pay/index.md b/docs/src/6.x/pay/index.md
index e2d81c751..bb191deda 100755
--- a/docs/src/6.x/pay/index.md
+++ b/docs/src/6.x/pay/index.md
@@ -2,7 +2,11 @@
 
 请仔细阅读并理解：[微信官方文档 - 微信支付](https://pay.weixin.qq.com/wiki/doc/apiv3/wxpay/pages/index.shtml)
 
-## 实例化
+> [!NOTE]
+> 2024年Q3，微信支付官方开启了「平台公钥」平替「平台证书」方案，初始化所需的参数仅需配置上 **平台公钥ID** 及 **平台公钥** 即完全兼容支持，CLI/API下载 **平台证书** 已不是一个必要步骤，可略过。
+> **平台公钥ID** 及 **平台公钥** 均可在 [微信支付商户平台](https://pay.weixin.qq.com/) -> 账户中心 -> API安全 查看及/或下载。
+
+## 实例化 {#init}
 
 ```php
 <?php
@@ -24,8 +28,13 @@ $config = [
     // 平台证书：微信支付 APIv3 平台证书，需要使用工具下载
     // 下载工具：https://github.com/wechatpay-apiv3/CertificateDownloader
     'platform_certs' => [
-        // 请使用绝对路径
+        // 如果是「平台证书」模式
+        //    可简写使用平台证书文件绝对路径
         // '/path/to/wechatpay/cert.pem',
+
+        // 如果是「平台公钥」模式
+        //    使用Key/Value结构， key为平台公钥ID，value为平台公钥文件绝对路径
+        // "{$pubKeyId}" => '/path/to/wechatpay/pubkey.pem',
     ],
 
     /**
@@ -35,18 +44,19 @@ $config = [
     'http' => [
         'throw'  => true, // 状态码非 200、300 时是否抛出异常，默认为开启
         'timeout' => 5.0,
-        // 'base_uri' => 'https://api.mch.weixin.qq.com/', // 如果你在国外想要覆盖默认的 url 的时候才使用，根据不同的模块配置不同的 uri
+        // 如果你在国外想要覆盖默认的 url 的时候才使用，根据不同的模块配置不同的 base_uri
+        // 'base_uri' => 'https://api.mch.weixin.qq.com/',
     ],
 ];
 
 $app = new Application($config);
 ```
 
-## API
+## API {#api}
 
 Application 就是一个工厂类，所有的模块都是从 `$app` 中访问，并且几乎都提供了协议和 setter 可自定义修改。
 
-### API Client
+### API Client {#client}
 
 封装了多种模式的 API 调用类，你可以选择自己喜欢的方式调用开放平台任意 API，默认自动处理了 access_token 相关的逻辑。
 
@@ -56,7 +66,7 @@ $app->getClient();
 
 :book: 更多说明请参阅：[API 调用](../client.md)
 
-### 工具
+### 工具 {#tools}
 
 为了方便开发者生成各种调起支付所需配置，你可以使用工具类：
 
@@ -66,7 +76,7 @@ $app->getUtils();
 
 :book: 更多说明请参阅：[工具](utils.md)
 
-### 配置
+### 配置 {#config}
 
 ```php
 $config = $app->getConfig();
@@ -74,7 +84,7 @@ $config = $app->getConfig();
 
 你可以轻松使用 `$config->get($key, $default)` 读取配置，或使用 `$config->set($key, $value)` 在调用前修改配置项。
 
-### 支付账户
+### 支付账户 {#merchant}
 
 支付账户类，提供一系列 API 获取支付的基本信息：
 
@@ -89,9 +99,9 @@ $account->getV2SecretKey();
 $account->getPlatformCerts();
 ```
 
-### 一些可能会用到的
+### 一些可能会用到的 {#others}
 
-#### 签名验证
+#### 签名验证 {#validation}
 
 按官方说法，建议在拿到**微信接口响应**和**接收到微信支付的回调通知**时，对通知的签名进行验证，以确保通知是微信支付发送的。
 
@@ -101,7 +111,7 @@ $account->getPlatformCerts();
 $app->getValidator();
 ```
 
-##### 推送消息的签名验证
+##### 推送消息的签名验证 {#webhook}
 
 ```php
 $server = $app->getServer();
@@ -124,7 +134,7 @@ $server->handlePaid(function (Message $message, \Closure $next) use ($app) {
 return $server->serve();
 ```
 
-##### API返回值的签名验证
+##### API返回值的签名验证 {#verify-response}
 
 ```php
 // API 请求示例
@@ -138,7 +148,7 @@ try{
 }
 ```
 
-#### 获取证书序列号
+#### 获取证书序列号 {#x509-serial-no}
 
 ```bash
 openssl x509 -in /path/to/merchant/apiclient_cert.pem -noout -serial | awk -F= '{print $2}'