trustbase-seller-backend 0.1.5

package/.agents/skills/wechatpay-payment-integration/references//346/216/245/345/205/245/350/264/250/351/207/217/346/243/200/346/237/245/346/270/205/345/215/225.md

@@ -0,0 +1,70 @@
+# 微信支付接入质量检查清单（通用）
+
+> **检索入口**：本清单是 `SKILL.md` 核心工作流中意图「接入质量评估」的配套规则。进入质检前仍须走 `SKILL.md` 的检索循环：先用 CLI 定位到产品「开发指引」，再提取其中「注意事项」与本清单合并扫描。
+>
+> **适用范围**：所有微信支付业务的通用质检框架——境内基础支付、合单支付、境外微信支付、医保支付、委托代扣、微信支付分、商品券、商家券、刷脸支付等。
+
+## 角色设定：金融支付系统技术专家
+
+> ‼️ **本节角色、铁律和问题雷达是质检的全部驱动力，必须内化后再审代码。**
+
+你是金融支付系统技术专家，全栈工程师出身，亲手写过从前端收银台到后端交易引擎的全链路代码。你主导过千万级用户规模的国民级支付系统架构设计，从零搭建过高并发交易平台。你熟悉主流支付平台的接入规范与安全体系，对 API 签名验签机制、异步回调通知处理、资金流对账有丰富的实战经验。你对代码质量有极强的直觉，尤其对资金链路上的异常处理缺失高度警觉。
+
+你对支付系统的要求极高：接口交互必须有完善的异常处理和兜底方案，资金操作必须可追溯、可对账，所有外部输入必须经过校验才能进入业务逻辑。
+
+## 铁律
+
+### 铁律一：高可用（99.9999%）
+
+**要求**：系统可用性 99.9999%（六个 9），即每一百万次请求中最多允许一次失败。资金链路上不允许单点故障，每一个外部调用都必须有超时、重试和降级方案。
+
+**检查直觉**：
+
+- 调用微信支付 API 超时了，代码会自动重试还是直接报错？
+- 重试时会不会导致重复操作？
+- 微信异步通知一直没来，系统有没有定时主动查询服务端状态？
+- 用户快速点击两次提交，会不会创建两笔业务单？
+
+### 铁律二：资金安全（一分钱都不能错）
+
+**要求**：金额计算必须使用整数（单位：分），杜绝浮点精度丢失。每一笔资金变动（支付、退款、分账、扣款、出款）都必须有据可查，系统必须主动通过对账机制发现差异。
+
+**检查直觉**：
+
+- 金额字段的类型是 `int`/`long` 还是 `double`/`float`？
+- 涉及金额累加 / 累减的地方，有没有用本地账本校验上限？
+- 系统有没有每天自动拉取微信账单和本地业务流水做比对？
+
+### 铁律三：零信任（不信任任何未经验证的外部数据）
+
+**要求**：微信异步通知、前端 / 客户端传入的参数、缓存中的数据，在进入业务逻辑前必须经过验证；未验证的输入一律视为不可信。
+
+**检查直觉**：
+
+- 收到异步通知后，代码是先验签还是直接解析 body 处理业务？
+- 写入微信 API 的金额 / 商户号 / 用户标识等关键字段，是后端查的还是直接用前端传值？
+- 通知中的关键字段有没有和本地数据做比对？
+- 私钥是通过环境变量加载的，还是硬编码在代码里？
+
+---
+
+## 检查方法
+
+1. **扫代码** — 快速扫描代码，按问题雷达定位高风险区域
+2. **追链路** — 沿业务流完整走一遍：发起请求 → 服务端处理 → 异步通知 → 主动查询 → 后续操作 → 对账，任何断点都是事故点
+3. **做预演** — 对每个关键节点问"如果这里故障了 / 超时了 / 被攻击了 / 来了两次，会怎样？"
+
+**输出要求**：发现问题必须给出修复方向，不能只说"有风险"；必须基于代码事实，不基于猜测；结果按 🔴🟡🟠 分级，致命问题置顶。
+
+## 通用问题雷达
+
+| 模块 | 检查项 | 必要性 | 说明 |
+| --- | --- | --- | --- |
+| **签名** | 异步通知先验签再处理业务 | 🔴 致命 | 收到通知时代码是先 `verify_sign(headers, body)` 还是直接 `JSON.parse(body)`？验签失败必须立即 return，禁止继续业务逻辑 |
+| **签名** | 验签失败必须返回 4xx/5xx，并正确处理 SIGNTEST 探测流量 | 🔴 致命 | 验签失败返回 200 等于"通知成功"，微信不会重试；微信会下发签名错误的**探测流量**（前缀 `WECHATPAY/SIGNTEST/`）测试商户是否正确验签，返回 200 即视为安全隐患 |
+| **安全** | 客户端 / APP / H5 禁出现 API 私钥 / 证书 / APIv3 密钥 | 🔴 致命 | grep 私钥文件名 / 商户号 / APIv3 密钥是否出现在前端 JS、APK 反编译产物、H5 / 小程序页面里；私钥应从环境变量或 KMS 加载 |
+| **安全** | 资金 / 关键字段一律以后端为准，禁信前端传值 | 🔴 致命 | 调用微信 API 的金额、商户号、用户标识、业务类型等关键字段必须从可信后端数据源读取；前端传入仅作为引导，不能直接落库或入参 |
+| **安全** | 敏感字段（姓名 / 身份证 / 手机号 / 邮箱 / 银行账号）用平台公钥加密 | 🔴 致命 | 进件、开户意愿、订单转账、用户信息上报等业务的敏感字段必须用微信支付公钥加密，并在 Header 携带 `Wechatpay-Serial`；明文上送即合规风险 |
+| **幂等** | 调用重试 + 异步通知都必须做业务幂等 | 🟡 必须 | 同一笔业务被多次触达时结果必须一致：① 调微信 API 网络异常重试时复用原业务单号幂等；② 异步通知多次收到时以业务单号 + 状态机锁保证幂等。避免重复操作 / 重复出资金 |
+| **兜底** | 异步通知缺失时有主动查询兜底 | 🟡 必须 | 关键链路（支付、退款、扣款、分账等）必须有定时任务主动查询服务端状态作为兜底，禁止仅依赖异步通知 |
+| **打印日志** | 关键链路打印 Request-Id | 🟠 建议 | 调微信 API 时把响应 Header 中的 `Request-Id` 写入业务日志，回调 / 报错时凭 Request-Id 可让微信侧快速定位到服务日志，是排障最高效的线索 |

package/.agents/skills/wechatpay-payment-integration/references//346/226/207/346/241/243/346/243/200/347/264/242/344/270/216/351/227/256/347/255/224.md

@@ -0,0 +1,99 @@
+# 文档检索与问答
+
+本文件说明**怎么查、怎么读、怎么答**：先用 CLI 线索定方向，再在知识库的 `.md` 文件里 `Grep` **探路**、按命中与用户语义 **缩小范围**、`Read` **精读**，最后作答。查哪棵目录由 `SKILL.md` [意图细则](../SKILL.md#意图细则) 决定；默认「答疑与排障」查 `<SKILL目录>/assets/微信支付官网文档/` 全库。
+
+回答正文须来自已 `Read` 的知识库文档；知识库没有时，再按[链接与联网](#链接与联网)取官方页。
+
+## 规则
+
+### 硬性约束
+
+1. **先探路再锁定**：可依据已有线索（CLI search 返回的定位信息、用户给出的 URL/路径）做定向 `Grep`；**没有这类依据时**须在当前意图的检索路径上 `Grep`（答疑与排障为全树），不得在未看命中分布的情况下仅凭知识库索引猜测并锁定单一前缀。
+2. **路径即判据**：文件名和目录已包含中文标题，路径明显相关时直接精读，**不要**批量读 `front matter` 做筛选。
+3. **检索词忠实**：`Grep` 的 `pattern` 须保留用户原文中的 URL、接口路径、错误码、字段名等。
+4. **精读节制**：按需精读与问题**直接相关**的文档（一般 3～5 篇，复杂 / 对比类可更多），**不要大面积无关扫描**、不要整篇通读；缩小范围后的 `Grep`/`Read` 应落在第三步确定的前缀或少数候选前缀内。
+5. **禁止编造**：接口、字段、错误码须来自知识库 `Read` 结果，不凭模型记忆编造。
+6. **检索有上限，未覆盖如实告知**：换方向找 **3 次**仍无相关命中即停止，明确告知用户该问题超出当前知识库覆盖范围，禁止用弱相关文档硬凑答案。
+7. **简洁作答**：答案只含直接回答用户问题所需的信息；用户未问的不展开，不堆砌无关内容。
+
+### 链接与联网
+
+正文中遇到的链接按以下方式处理：
+
+| 域名 | 处理 |
+|---|---|
+| `pay.weixin.qq.com` | **优先**在 `<SKILL目录>/assets/微信支付官网文档/` 内用 `Grep`（URL 路径片段、文档标题、`doc` 路径、文档 ID 等）定位对应 `.md` 再 `Read`；知识库内**未找到**对应或等价文档时，可对该 URL 使用 `WebFetch` |
+
+其他外链先询问用户是否联网。
+
+---
+
+## 检索与作答流程（必须按顺序）
+
+> 建议顺序：**读索引、拟检索词** → **Grep 探路** → **缩小范围** → **聚焦 `Grep` / `Read`** → **作答**。
+
+### 第一步：读索引、拟定检索词
+
+1. 知识库结构以已加载的 `<SKILL目录>/assets/wechatpay-docs-guide.md` 为准，未在上下文则再 `Read`。
+2. 沿用核心工作流已产出的意图、理解后的问题、角色与 API 版本；未定时按 [如何理解用户问题](./如何理解用户问题.md) 处理，需澄清则停在本轮。
+3. 抽出 **1～3 个**探路 `pattern`：优先原文中的 URL、接口路径、错误码、字段名、产品官方名；给了官网链接或文档 ID 时取纯数字 `doc_id`。要具体可命中，避免单独搜「支付」这类过宽词。
+
+### 第二步：Grep 探路
+
+用已有 CLI 线索（及用户给出的 URL / 路径）校准 `Grep` 前缀；CLI 没给线索时在当前意图的检索路径上搜（答疑与排障为全树）。固定入口文件直接 `Read`。看路径与文件名是否对题、片段是否覆盖所问、落在哪些角色 / 版本分支：
+
+- **足够 → 第三步**：至少 1 篇（对比类每分支各 ≥1 篇）值得精读，不为凑数继续搜。
+- **不够 / 没搜到**：先在当前前缀换 `pattern`，或回退到意图起点再搜。
+- **换方向**：路径明显不对题、或换词与回退仍无相关命中，就换检索目标（另一产品 / 角色 / 版本分支）重新 `Grep`。次数按 [硬性约束](#硬性约束) 第 6 条。
+
+### 第三步：缩小范围
+
+把第二步命中收到最相关的若干篇（一般 3～5 篇），再进第四步精读。路径明显相关即可，不必先读 `front matter`；命中分散时可用知识库指南目录树辅助，与 Grep 冲突时以更贴题的命中文件为准。角色与版本按 [如何理解用户问题](./如何理解用户问题.md#角色与-api-版本判定) 收敛，跨多侧则停下询问（对比类各侧都保留）。
+
+仍不够则回第二步：先换词或回退起点，再不行才换方向。
+
+### 第四步：聚焦 `Grep` / `Read`
+
+方向已定，只在当前范围内缩小与精读。
+
+1. 在第三步确定的前缀下，用更精确的 `pattern` 做聚焦 `Grep`。
+2. `Read` 最相关的若干篇 `.md`（一般 3～5 篇），只读与问题相关的段落。
+3. 同一文档 ID 可能存在请求示例副本，接口说明以**主文件**为准；示例代码文件仅在需要代码示例时 `Read`。
+
+> **对比类问题**：每个分支至少各取 1 篇，篇数按分支数量按需增加，只读相关的、别大面积无关扫描。
+
+### 第五步：作答
+
+按 `SKILL.md` 当前意图的细则组织答案。默认答疑格式如下：
+
+- **极简**：只答用户所问，先给结论或做法，再补必要细节；不扩背景、不复述检索、不贴文档原文。
+- **可溯源**：每条结论都对应到已 `Read` 的知识库文件，或知识库未收录时经 `WebFetch` 取得的 `pay.weixin.qq.com` 正文（须在答案中注明来源 URL）。
+- **「⚠️ 注意事项」**：仅直接踩坑风险时输出，无则省略整个段落。
+- **「📋 相关文档」**（必须）：只列实际引用过的知识库文档，一般 3～5 条。列之前读这些文件的 `front matter`，标题和链接原样取 `title_display` / `url_display`，不改写、不拼接。
+
+需查单时走动态排障。
+
+#### 作答格式
+
+```markdown
+## [简短答案，直接回答用户问题]
+
+### 📋 相关文档
+- **{front matter title_display}**：{front matter url_display}
+- ...（一般 3～5 条）
+
+### ⚠️ 注意事项
+- [注意点]
+```
+
+## 示例
+
+**用户**：「合作伙伴 `APIv3` 合单 JSAPI 下单里 `sub_mchid` 怎么传？」
+
+前提：`SKILL.md` 核心工作流已完成理解（角色「合作伙伴」、版本 `APIv3`、意图「答疑与排障」）与本轮 CLI search，拿到线索（产品「合单支付」、商户类型「服务商」、版本 `v3`）。以下都在本地完成。
+
+1. 第一步：索引已在前置加载；沿用理解后的检索词 `sub_mchid`、`合单`、`JSAPI`。
+2. 第二步：用 CLI search 的线索在 `APIv3/合作伙伴/` 下定向 `Grep`，观察命中路径（如 `APIv3/合作伙伴/支付产品/JSAPI合单支付/...`）是否覆盖 `sub_mchid`；不够就同前缀换更细或更宽的 `pattern`。
+3. 第三步：结合已识别的角色 / 版本与命中分布，将精读范围收敛到 `APIv3/合作伙伴/支付产品`。
+4. 第四步：在该前缀下聚焦 `Grep`，`Read` 最相关的若干篇 `.md`（按需）。
+5. 第五步：按 `front matter` 的 `title_display` / `url_display` 生成回答。

package/.agents/skills/wechatpay-payment-integration/scripts/bash/extract_and_sign.sh

@@ -0,0 +1,231 @@
+#!/bin/bash
+#
+# 微信支付 APIv3 - P12 证书信息提取与签名工具
+#
+# 用法（推荐，签名时刻生成 TIMESTAMP / NONCE_STR）:
+#   bash extract_and_sign.sh --filePath <P12> [--password <密码>] \
+#     --method GET --url '/v3/pay/transactions/id/xxx?mchid=yyy'
+#
+# 用法（可选，自行提供时间戳与随机串）:
+#   bash extract_and_sign.sh --filePath <P12> --method GET --url '...' \
+#     --timestamp <秒级时间戳> --nonce_str <32位随机串>
+#
+# 用法（兼容，传入完整待签名串）:
+#   bash extract_and_sign.sh --filePath <P12> --signString 'GET\n/...\n...\n\n'
+
+set -euo pipefail
+
+P12_FILE=""
+P12_PASSWORD=""
+HTTP_METHOD=""
+REQUEST_URL=""
+TIMESTAMP_IN=""
+NONCE_IN=""
+SIGN_STRING=""
+
+usage() {
+    echo "用法: bash extract_and_sign.sh --filePath <P12文件路径> [--password <P12密码>] \\"
+    echo "        (--method <HTTP方法> --url '<请求URL路径+query>') | --signString '<待签名串>'"
+    echo ""
+    echo "参数说明:"
+    echo "  --filePath      apiclient_cert.p12 文件路径（支持 file:///... 或 @/path/...）"
+    echo "  --password      P12 密码（可选；未传时可能从 URL 中的 mchid/sp_mchid 尝试）"
+    echo "  --method        HTTP 方法，如 GET（与 --url 搭配使用）"
+    echo "  --url           请求 URL（含 path 与 query，以 / 开头）"
+    echo "  --timestamp     秒级时间戳（可选；未传则在签名时自动生成）"
+    echo "  --nonce_str     随机串（可选；未传则在签名时自动生成）"
+    echo "  --signString    完整待签名串（兼容旧用法；含 \\\\n 转义换行）"
+    exit 1
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --filePath)
+      P12_FILE="${2:-}"
+      shift 2
+      ;;
+    --password)
+      P12_PASSWORD="${2:-}"
+      shift 2
+      ;;
+    --method)
+      HTTP_METHOD="${2:-}"
+      shift 2
+      ;;
+    --url)
+      REQUEST_URL="${2:-}"
+      shift 2
+      ;;
+    --timestamp)
+      TIMESTAMP_IN="${2:-}"
+      shift 2
+      ;;
+    --nonce_str)
+      NONCE_IN="${2:-}"
+      shift 2
+      ;;
+    --signString)
+      SIGN_STRING="${2:-}"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      ;;
+    *)
+      echo "错误: 未知参数: $1"
+      usage
+      ;;
+  esac
+done
+
+if [ -z "$P12_FILE" ]; then
+    usage
+fi
+
+if [ -z "$SIGN_STRING" ]; then
+    if [ -z "$HTTP_METHOD" ] || [ -z "$REQUEST_URL" ]; then
+        echo "错误: 请提供 --method 与 --url，或提供 --signString"
+        usage
+    fi
+    if [[ "$REQUEST_URL" != /* ]]; then
+        echo "错误: --url 必须以 / 开头（path + query）"
+        exit 1
+    fi
+    if [ -z "$TIMESTAMP_IN" ]; then
+        TIMESTAMP_IN="$(date +%s)"
+    fi
+    if [ -z "$NONCE_IN" ]; then
+        NONCE_IN="$(openssl rand -hex 16 | tr '[:lower:]' '[:upper:]')"
+    fi
+    SIGN_STRING="${HTTP_METHOD}"$'\n'"${REQUEST_URL}"$'\n'"${TIMESTAMP_IN}"$'\n'"${NONCE_IN}"$'\n\n'
+elif [ -z "$TIMESTAMP_IN" ] || [ -z "$NONCE_IN" ]; then
+  # 从完整待签名串解析时间戳与随机串（第 3、4 行）
+  [ -z "$TIMESTAMP_IN" ] && TIMESTAMP_IN=$(printf '%b' "$SIGN_STRING" | sed -n '3p')
+  [ -z "$NONCE_IN" ] && NONCE_IN=$(printf '%b' "$SIGN_STRING" | sed -n '4p')
+fi
+
+# 兼容 file:/// file: @ 前缀
+if [[ "$P12_FILE" == file://* ]]; then
+    P12_FILE="${P12_FILE#file://}"
+    if [[ "$P12_FILE" != /* ]]; then
+        P12_FILE="/$P12_FILE"
+    fi
+elif [[ "$P12_FILE" == file:* ]]; then
+    P12_FILE="${P12_FILE#file:}"
+fi
+if [[ "$P12_FILE" == @* ]]; then
+    P12_FILE="${P12_FILE#@}"
+fi
+
+if [[ "$P12_FILE" == "/path/to/"* ]] || [[ "$P12_FILE" == *"\\path\\to\\"* ]] || [[ "$P12_FILE" == *":\\path\\to\\"* ]]; then
+    echo "错误: 请将 --filePath 参数替换为你本地 P12 证书的真实路径"
+    exit 1
+fi
+
+if [ ! -f "$P12_FILE" ]; then
+    echo "错误: P12 文件不存在: $P12_FILE"
+    exit 1
+fi
+
+_is_pem_like_file() {
+    local file="$1"
+    local ext first
+    ext="${file##*.}"
+    ext=$(printf '%s' "$ext" | tr '[:upper:]' '[:lower:]')
+    case "$ext" in
+        pem|crt|cer|key) return 0 ;;
+    esac
+    first=$(head -n 1 "$file" 2>/dev/null || true)
+    [[ "$first" == -----BEGIN* ]]
+}
+
+_fail_wrong_cert_format() {
+    local file="$1"
+    echo "错误: --filePath 指向的是 PEM/证书文件（$(basename "$file")），本脚本仅支持 PKCS#12 格式的 apiclient_cert.p12"
+    echo "提示: 请将 --filePath 改为你本地的 apiclient_cert.p12 路径（证书压缩包内通常同时提供 .p12 与 .pem，请选用 .p12）"
+    exit 1
+}
+
+if _is_pem_like_file "$P12_FILE"; then
+    _fail_wrong_cert_format "$P12_FILE"
+fi
+
+_guess_p12_password() {
+    local hint="$1"
+    local pwd
+    pwd=$(printf '%s' "$hint" | sed -n 's/.*[?&]mchid=\([^&]*\).*/\1/p' | head -n 1)
+    if [ -z "$pwd" ]; then
+        pwd=$(printf '%s' "$hint" | sed -n 's/.*[?&]sp_mchid=\([^&]*\).*/\1/p' | head -n 1)
+    fi
+    printf '%s' "$pwd"
+}
+
+# 密码候选：优先从 URL 提取 mchid / sp_mchid
+PWD_HINT="${REQUEST_URL:-$SIGN_STRING}"
+
+LEGACY_FLAG=""
+PASSIN="pass:$P12_PASSWORD"
+
+if openssl pkcs12 -in "$P12_FILE" -clcerts -nokeys -passin "$PASSIN" -legacy >/dev/null 2>&1; then
+    LEGACY_FLAG="-legacy"
+elif ! openssl pkcs12 -in "$P12_FILE" -clcerts -nokeys -passin "$PASSIN" >/dev/null 2>&1; then
+    if [ -z "$P12_PASSWORD" ]; then
+        CAND_PWD="$(_guess_p12_password "$PWD_HINT")"
+        if [ -n "$CAND_PWD" ]; then
+            P12_PASSWORD="$CAND_PWD"
+            PASSIN="pass:$P12_PASSWORD"
+            if openssl pkcs12 -in "$P12_FILE" -clcerts -nokeys -passin "$PASSIN" -legacy >/dev/null 2>&1; then
+                LEGACY_FLAG="-legacy"
+            elif ! openssl pkcs12 -in "$P12_FILE" -clcerts -nokeys -passin "$PASSIN" >/dev/null 2>&1; then
+                echo "错误: 无法读取 P12 文件。可能需要 P12 密码，请在命令中追加: --password \"<P12密码>\"（常见为商户号）"
+                exit 1
+            fi
+        else
+            echo "错误: 无法读取 P12 文件。可能需要 P12 密码，请在命令中追加: --password \"<P12密码>\"（常见为商户号）"
+            exit 1
+        fi
+    else
+        if _is_pem_like_file "$P12_FILE"; then
+            _fail_wrong_cert_format "$P12_FILE"
+        fi
+        echo "错误: 无法读取 P12 文件，请检查 --password 是否为 P12 密码（常见为商户号）"
+        exit 1
+    fi
+fi
+
+CERT_PEM=$(openssl pkcs12 -in "$P12_FILE" -clcerts -nokeys -passin "$PASSIN" $LEGACY_FLAG 2>/dev/null)
+
+SERIAL=$(echo "$CERT_PEM" | openssl x509 -serial -noout 2>/dev/null | sed 's/serial=//')
+if [ -z "$SERIAL" ]; then
+    echo "错误: 无法提取证书序列号"
+    exit 1
+fi
+
+SUBJECT=$(echo "$CERT_PEM" | openssl x509 -subject -noout -nameopt RFC2253 2>/dev/null)
+MCHID=$(echo "$SUBJECT" | sed -n 's/.*CN=\([^,]*\).*/\1/p')
+if [ -z "$MCHID" ]; then
+    MCHID="（无法从证书 CN 字段提取，请手动确认）"
+fi
+
+PRIVKEY=$(openssl pkcs12 -in "$P12_FILE" -nocerts -nodes -passin "$PASSIN" $LEGACY_FLAG 2>/dev/null)
+if [ -z "$PRIVKEY" ]; then
+    echo "错误: 无法提取私钥"
+    exit 1
+fi
+
+SIGNATURE=$(printf "%b" "$SIGN_STRING" | \
+    openssl dgst -sha256 -sign <(echo "$PRIVKEY") 2>/dev/null | \
+    openssl base64 -A)
+
+if [ -z "$SIGNATURE" ]; then
+    echo "错误: 签名失败"
+    exit 1
+fi
+
+echo "---------- 签名结果开始 ----------"
+echo "API 证书序列号（serial_no）: $SERIAL"
+echo "时间戳（timestamp）: $TIMESTAMP_IN"
+echo "随机串（nonce_str）: $NONCE_IN"
+echo "API 证书中的商户号: $MCHID"
+echo "签名值（signature）: $SIGNATURE"
+echo "---------- 签名结果结束 ----------"

package/.agents/skills/wechatpay-payment-integration/scripts/powershell/extract_and_sign.ps1

@@ -0,0 +1,199 @@
+#
+# 微信支付 APIv3 - P12 证书信息提取与签名工具 (Windows PowerShell 版)
+#
+# 推荐用法（签名时刻生成 TIMESTAMP / NONCE_STR）:
+#   powershell -ExecutionPolicy Bypass -File extract_and_sign.ps1 `
+#     -FilePath "apiclient_cert.p12" -Method GET -Url "/v3/pay/transactions/id/xxx?mchid=yyy"
+#
+
+param(
+    [Parameter(Mandatory=$true, HelpMessage="Path to apiclient_cert.p12")]
+    [string]$FilePath,
+
+    [Parameter(Mandatory=$false, HelpMessage="P12 password (optional)")]
+    [string]$Password = "",
+
+    [Parameter(Mandatory=$false, HelpMessage="HTTP method, e.g. GET")]
+    [string]$Method = "",
+
+    [Parameter(Mandatory=$false, HelpMessage="Request URL path+query, starts with /")]
+    [string]$Url = "",
+
+    [Parameter(Mandatory=$false, HelpMessage="Unix timestamp seconds (optional)")]
+    [string]$Timestamp = "",
+
+    [Parameter(Mandatory=$false, HelpMessage="Nonce string (optional)")]
+    [string]$NonceStr = "",
+
+    [Parameter(Mandatory=$false, HelpMessage="Full sign string; use \\n for newlines")]
+    [string]$SignString = ""
+)
+
+$ErrorActionPreference = "Stop"
+
+function Get-MchidFromHint([string]$hint) {
+    if ($hint -match '[\?&]mchid=([^&\\n]+)') { return $Matches[1] }
+    if ($hint -match '[\?&]sp_mchid=([^&\\n]+)') { return $Matches[1] }
+    return $null
+}
+
+if ([string]::IsNullOrEmpty($SignString)) {
+    if ([string]::IsNullOrEmpty($Method) -or [string]::IsNullOrEmpty($Url)) {
+        Write-Host "错误: 请提供 -Method 与 -Url，或提供 -SignString" -ForegroundColor Red
+        exit 1
+    }
+    if (-not $Url.StartsWith("/")) {
+        Write-Host "错误: -Url 必须以 / 开头（path + query）" -ForegroundColor Red
+        exit 1
+    }
+    if ([string]::IsNullOrEmpty($Timestamp)) {
+        $Timestamp = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds().ToString()
+    }
+    if ([string]::IsNullOrEmpty($NonceStr)) {
+        $bytes = New-Object byte[] 16
+        [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
+        $NonceStr = ([BitConverter]::ToString($bytes) -replace '-', '')
+    }
+    $SignString = "$Method`n$Url`n$Timestamp`n$NonceStr`n`n"
+} elseif ([string]::IsNullOrEmpty($Timestamp) -or [string]::IsNullOrEmpty($NonceStr)) {
+    $lines = ($SignString -replace '\\n', "`n") -split "`n"
+    if ($lines.Count -ge 4) {
+        if ([string]::IsNullOrEmpty($Timestamp)) { $Timestamp = $lines[2] }
+        if ([string]::IsNullOrEmpty($NonceStr)) { $NonceStr = $lines[3] }
+    }
+}
+
+if ($FilePath.StartsWith("file://")) {
+    $FilePath = $FilePath.Substring(7)
+    if (-not $FilePath.StartsWith("/")) { $FilePath = "/" + $FilePath }
+} elseif ($FilePath.StartsWith("file:")) {
+    $FilePath = $FilePath.Substring(5)
+}
+if ($FilePath.StartsWith("@")) { $FilePath = $FilePath.Substring(1) }
+
+if ($FilePath -like "/path/to/*" -or $FilePath -like "*\path\to\*" -or $FilePath -like "*:\path\to\*") {
+    Write-Host "错误: 请将 -FilePath 参数替换为你本地 P12 证书的真实路径" -ForegroundColor Red
+    exit 1
+}
+
+if (-not (Test-Path $FilePath)) {
+    Write-Host "错误: P12 文件不存在: $FilePath" -ForegroundColor Red
+    exit 1
+}
+
+function Test-PemLikeFile([string]$path) {
+    $ext = [System.IO.Path]::GetExtension($path).ToLowerInvariant()
+    if ($ext -in '.pem', '.crt', '.cer', '.key') { return $true }
+    $first = Get-Content -Path $path -TotalCount 1 -ErrorAction SilentlyContinue
+    return ($first -like '-----BEGIN*')
+}
+
+function Write-WrongCertFormatError([string]$path) {
+    $name = [System.IO.Path]::GetFileName($path)
+    Write-Host "错误: -FilePath 指向的是 PEM/证书文件（$name），本脚本仅支持 PKCS#12 格式的 apiclient_cert.p12" -ForegroundColor Red
+    Write-Host "提示: 请将 -FilePath 改为你本地的 apiclient_cert.p12 路径（证书压缩包内通常同时提供 .p12 与 .pem，请选用 .p12）" -ForegroundColor Yellow
+    exit 1
+}
+
+if (Test-PemLikeFile $FilePath) {
+    Write-WrongCertFormatError $FilePath
+}
+
+$P12FullPath = (Resolve-Path $FilePath).Path
+$pwdHint = "$Url$SignString"
+
+try {
+    $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2(
+        $P12FullPath, $Password,
+        [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::Exportable
+    )
+} catch {
+    if ([string]::IsNullOrEmpty($Password)) {
+        $cand = Get-MchidFromHint $pwdHint
+        if ($cand) {
+            try {
+                $cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2(
+                    $P12FullPath, $cand,
+                    [System.Security.Cryptography.X509Certificates.X509KeyStorageFlags]::Exportable
+                )
+                $Password = $cand
+            } catch {
+                Write-Host '错误: 无法加载 P12 文件。可能需要 P12 密码，请在命令中追加: -Password "你的P12密码"（常见为商户号）' -ForegroundColor Red
+                exit 1
+            }
+        } else {
+            Write-Host '错误: 无法加载 P12 文件。可能需要 P12 密码，请在命令中追加: -Password "你的P12密码"（常见为商户号）' -ForegroundColor Red
+            exit 1
+        }
+    } else {
+        if (Test-PemLikeFile $FilePath) {
+            Write-WrongCertFormatError $FilePath
+        }
+        Write-Host "错误: 无法加载 P12 文件，请检查 -Password 是否为 P12 密码（常见为商户号）" -ForegroundColor Red
+        exit 1
+    }
+}
+
+$serial = $cert.SerialNumber
+if ([string]::IsNullOrEmpty($serial)) {
+    Write-Host "错误: 无法提取证书序列号" -ForegroundColor Red
+    exit 1
+}
+
+$subject = $cert.Subject
+if ($subject -match 'CN=([^,]+)') { $mchid = $Matches[1].Trim() }
+else { $mchid = "（无法从证书 CN 字段提取，请手动确认）" }
+
+$signContent = $SignString -replace '\\n', "`n"
+$bytes = [System.Text.Encoding]::UTF8.GetBytes($signContent)
+$signatureBytes = $null
+
+# Windows PowerShell 5.1 / .NET Framework：使用 PrivateKey + SignHash
+$legacyRsa = $cert.PrivateKey
+if ($null -ne $legacyRsa) {
+    try {
+        $sha256 = New-Object System.Security.Cryptography.SHA256CryptoServiceProvider
+        $hash = $sha256.ComputeHash($bytes)
+        $oid = [System.Security.Cryptography.CryptoConfig]::MapNameToOID("SHA256")
+        $signatureBytes = $legacyRsa.SignHash($hash, $oid)
+    } catch {
+        $signatureBytes = $null
+    } finally {
+        if ($null -ne $sha256) { $sha256.Dispose() }
+    }
+}
+
+# PowerShell 7+ / .NET 4.6+：使用 RSACertificateExtensions::GetRSAPrivateKey
+if ($null -eq $signatureBytes) {
+    try {
+        $rsaType = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]
+        $rsa = $rsaType::GetRSAPrivateKey($cert)
+        if ($null -ne $rsa) {
+            $signatureBytes = $rsa.SignData($bytes,
+                [System.Security.Cryptography.HashAlgorithmName]::SHA256,
+                [System.Security.Cryptography.RSASignaturePadding]::Pkcs1)
+        }
+    } catch {
+        $signatureBytes = $null
+    }
+}
+
+if ($null -eq $signatureBytes) {
+    Write-Host "错误: 无法提取私钥或签名失败，请确认 P12 文件包含私钥" -ForegroundColor Red
+    exit 1
+}
+
+try {
+    $signature = [Convert]::ToBase64String($signatureBytes)
+} catch {
+    Write-Host "错误: 签名失败" -ForegroundColor Red
+    exit 1
+}
+
+Write-Host "---------- 签名结果开始 ----------" -ForegroundColor Green
+Write-Host "API 证书序列号（serial_no）: $serial"
+Write-Host "时间戳（timestamp）: $Timestamp"
+Write-Host "随机串（nonce_str）: $NonceStr"
+Write-Host "API 证书中的商户号: $mchid"
+Write-Host "签名值（signature）: $signature"
+Write-Host "---------- 签名结果结束 ----------" -ForegroundColor Green