@alipay/alipay-aipay 1.0.2 → 1.2.2

package/skill/references/onboarding/modules/product-sign.md

@@ -1,7 +1,7 @@
 # 产品签约模块
 
 > 本文档定义产品签约的完整流程、参数规范和状态判断逻辑。
-> 被引用文档：`SKILL.md` → Step 5 入驻推进 - 签约部分
+> 被引用文档：`onboarding/flow.md` → Step 3.1 签约查询 + Step 5.1 签约提交
 > 本文档位于 `references/onboarding/modules/`，文中的 `scripts/...` 路径相对本目录；从技能包根目录执行时对应 `references/onboarding/modules/scripts/...`。
 
 ---
@@ -12,7 +12,7 @@
 
 本模块采用 `ar-sign.apply` **外部直调 / 静态参数模式**：由 `scripts/ar_sign_apply.sh` 基于当前已确认的产品类型、MCC 和资料字段直接构造 `businessProperty` 后提交申请。它不走 `previewFormView` 动态 schema 收集循环，因此只覆盖本文档明确列出的字段和产品。
 
-**触发条件：** Step 3.1 授权后处理中，签约状态为 NOT_SIGNED 时触发。
+**使用条件：** Step 3.1 始终使用本模块的签约状态查询规则；只有查询结果为 `NOT_SIGNED` 时，才使用本模块的签约申请提交规则。`SIGNED_EFFECTIVE`、`SIGN_SUBMITTED`、查询失败或其他状态均禁止提交签约申请。
 
 ---
 
@@ -42,8 +42,8 @@
 | 返回结果 | 状态判定 | 说明 |
 |----------|----------|------|
 | `resultObj.arInfoList` 为空数组 `[]` | `NOT_SIGNED` | 未签约 |
-| `resultObj.arInfoList` 不为空，且存在 `arStatus` 为 `"02"` 的记录 | `SIGNED_EFFECTIVE` | 签约已生效，跳过资料采集 |
-| `resultObj.arInfoList` 不为空，且存在 `arStatus` 为 `"01"` 的记录 | `SIGN_SUBMITTED` | 已提交签约（待生效），跳过资料采集与重复签约提交 |
+| `resultObj.arInfoList` 不为空，且存在 `arStatus` 为 `"02"` 的记录 | `SIGNED_EFFECTIVE` | 签约已生效，跳过签约材料采集，仍在 Step 4 处理应用/服务决策 |
+| `resultObj.arInfoList` 不为空，且存在 `arStatus` 为 `"01"` 的记录 | `SIGN_SUBMITTED` | 已提交签约（待生效），跳过签约材料和重复签约提交，仍在 Step 4 处理应用/服务决策 |
 
 ### 判断逻辑
 
@@ -53,22 +53,22 @@
 
 | 签约状态 | 产品类型 | FLOW 信号 | 后续流程 |
 |----------|----------|-----------|----------|
-| `NOT_SIGNED` | 网站支付 | `FLOW:PC_WEB_NOT_SIGNED` | 进入 Step 4 资料采集（3张网站截图）→ Step 5 签约 + 应用发布 |
-| `NOT_SIGNED` | APP支付 | `FLOW:APP_NOT_SIGNED` | 进入 Step 4 资料采集（APP名称 + 3张APP界面截图）→ Step 5 签约 + 应用发布 |
-| `NOT_SIGNED` | 按量付费 | `FLOW:AI_PAY_NOT_SIGNED` | 跳过 Step 4，进入 Step 5.1 签约，再继续服务注册 + 应用发布 |
-| `SIGNED_EFFECTIVE` | 网站支付 | `FLOW:PC_WEB_SIGNED` | 跳过签约提交，直接执行应用发布 |
-| `SIGNED_EFFECTIVE` | APP支付 | `FLOW:APP_SIGNED` | 跳过签约提交，直接执行应用发布 |
-| `SIGNED_EFFECTIVE` | 按量付费 | `FLOW:AI_PAY_SIGNED` | 跳过签约提交，直接执行服务注册 + 应用发布 |
-| `SIGN_SUBMITTED` | 网站支付 | `FLOW:PC_WEB_SIGNED` | 跳过重复签约提交，直接执行应用发布 |
-| `SIGN_SUBMITTED` | APP支付 | `FLOW:APP_SIGNED` | 跳过重复签约提交，直接执行应用发布 |
-| `SIGN_SUBMITTED` | 按量付费 | `FLOW:AI_PAY_SIGNED` | 跳过重复签约提交，直接执行服务注册 + 应用发布 |
-
-**⚠️ 按量付费 无需前置资料采集：**
+| `NOT_SIGNED` | 网站支付 | `FLOW:PC_WEB_NOT_SIGNED` | 进入 Step 4 一次性资料与资源决策（3张网站截图 + 应用决策/条件资料）→ Step 5 签约 + 应用发布 |
+| `NOT_SIGNED` | APP支付 | `FLOW:APP_NOT_SIGNED` | 进入 Step 4 一次性资料与资源决策（APP名称 + 3张APP界面截图 + 应用决策/条件资料）→ Step 5 签约 + 应用发布 |
+| `NOT_SIGNED` | 按量付费 | `FLOW:AI_PAY_NOT_SIGNED` | Step 4 无需收集页面图片，但一次完成服务/应用决策和条件资料；再进入 Step 5.1 签约 |
+| `SIGNED_EFFECTIVE` | 网站支付 | `FLOW:PC_WEB_SIGNED` | Step 4 完成应用决策后，跳过签约提交并执行应用发布 |
+| `SIGNED_EFFECTIVE` | APP支付 | `FLOW:APP_SIGNED` | Step 4 完成应用决策后，跳过签约提交并执行应用发布 |
+| `SIGNED_EFFECTIVE` | 按量付费 | `FLOW:AI_PAY_SIGNED` | Step 4 完成服务/应用决策后，跳过签约提交并执行服务注册 + 应用发布 |
+| `SIGN_SUBMITTED` | 网站支付 | `FLOW:PC_WEB_SIGNED` | Step 4 完成应用决策后，跳过重复签约提交并执行应用发布 |
+| `SIGN_SUBMITTED` | APP支付 | `FLOW:APP_SIGNED` | Step 4 完成应用决策后，跳过重复签约提交并执行应用发布 |
+| `SIGN_SUBMITTED` | 按量付费 | `FLOW:AI_PAY_SIGNED` | Step 4 完成服务/应用决策后，跳过重复签约提交并执行服务注册 + 应用发布 |
+
+**⚠️ 按量付费无需签约材料：**
 ```
 ✅ 网站支付未签约：需先采集 3 张网站截图，再进入 Step 5 签约
 ✅ APP支付未签约：需先采集 APP 名称和 3 张APP界面截图，再进入 Step 5 签约
-✅ 按量付费 未签约：跳过 Step 4，进入 Step 5.1 签约，再继续服务注册 + 应用发布
-❌ 禁止：按量付费 在 Step 4 收集服务注册信息（服务信息在 Step 5 服务注册时交互式收集）
+✅ 按量付费 未签约：Step 4 无需签约页面图片，但前置完成服务/应用决策和条件资料；Step 5 仍先提交签约
+✅ 按量付费在 Step 4 基于已查询的服务候选，一次收集新建/修改分支的完整五项服务资料；Step 5.2 才执行写操作
 ```
 
 **按量付费签约后的必要后续动作：**
@@ -188,8 +188,8 @@ bash scripts/ar_sign_apply.sh --product apppay --sales-code "I108030000100004131
 | `mccCode` | Step 2 方案规划 | 运行时变量，格式 `Axxxx_Bxxxx`，不持久化到状态文件 |
 | `channelCode` | 固定值 | `"B_SK_SH_RPC"` |
 | `orderType` | 固定值 | `"NEW_SIGN"` |
-| `screenshot` | Step 4 资料采集 | **仅网站支付/APP支付需要**（3个上传后的图片引用值），按量付费 无需此项 |
-| `appName` | Step 4 资料采集 | **仅APP支付需要**；脚本参数仍为 `--app-name`，提交到 MCP 时映射为 `nativeAppDTO.name` |
+| `screenshot` | Step 4 一次性资料与资源决策 | **仅未签约的网站支付/APP支付需要**（3个上传后的图片引用值），按量付费无需此项 |
+| `appName` | Step 4 一次性资料与资源决策 | **仅未签约的 APP支付需要**；脚本参数仍为 `--app-name`，提交到 MCP 时映射为 `nativeAppDTO.name` |
 | `appStatus` | 固定值 | **仅APP支付需要**，本次固定为 `OFFLINE` |
 
 ### 按量付费接入产物映射
@@ -209,8 +209,11 @@ bash scripts/ar_sign_apply.sh --product apppay --sales-code "I108030000100004131
 ✅ 网站支付未签约 → 需要 3 张网站截图（首页、商品页、支付页）
 ✅ APP支付未签约 → 需要 APP 名称和 3 张APP界面截图（首页、商品页、支付页），签约状态固定按 OFFLINE 提交
 ✅ 按量付费 未签约 → 无需截图，直接签约
+✅ 网站支付/APP支付缺少支付页或支付能力 → 不提交签约；先进入/回到集成流程完成实现，再回来上传图片
+✅ 网站支付/APP支付页面和支付能力已存在、仅缺三张页面图片 → 保留在 onboarding Step 4 收集和上传，不进入集成流程
 ❌ 禁止：按量付费 签约时传入 screenshot 字段
 ❌ 禁止：网站支付/APP支付 签约时省略 screenshot 字段
+❌ 禁止：将“支付页”自行改口为“支付成功页”或要求用户提供文档未定义的页面
 ❌ 禁止：APP支付签约 MCP payload 中使用 webAppDTO、appDTO、appName、appType、placeType=APP、placeType=ONLINE_WEBAPP、placeType=ONLINE_NATIVEAPP 或 appType=PC_WEB
 ```
 
@@ -226,7 +229,7 @@ bash scripts/ar_sign_apply.sh --product apppay --sales-code "I108030000100004131
 
 > ⚠️ **签约提交成功后，无需等待签约审核通过，应立即继续推进后续步骤。**
 
-签约申请提交后，后端会异步审核，`arStatus` 为 `"01"`（已提交待生效）。应用创建和服务注册不依赖签约审核通过，可以并行推进。
+签约申请提交后，后端会异步审核，`arStatus` 为 `"01"`（已提交待生效）。应用创建和服务注册不依赖签约审核通过，可以继续推进。为减少用户交互，应用/服务列表查询及分支资料采集可在签约提交前完成；当前流程仍先提交签约，成功后才执行服务或应用写操作。
 
 ### FLOW 信号
 

package/skill/references/onboarding/modules/scripts/app.sh

@@ -2,7 +2,7 @@
 #=============================================================================
 # 脚本名称: app.sh
 # 功能描述: 应用发布全流程 - 查询/复用 + 创建 + 公钥设置 + 提交审核
-# 调用位置: Step 5.3 应用发布
+# 调用位置: list 用于 Step 3.1 前置资源查询；其他命令用于 Step 5.3 应用发布
 # 调用前置: 脚本通过 error_handler.sh 间接初始化 DEV_TOOL_NAME
 #          list/create 可传 --application-type，未传时按 --product-type/--sales-code 或兼容环境变量推断
 # 用法:
@@ -13,8 +13,8 @@
 #   app audit  <appId>                   - 提交应用审核
 #   app reuse  <appId>                   - 复用已有应用（查询安全密钥）
 # 返回值:
-#   list:   FLOW:CREATE_NEW | FLOW:SELECT | FLOW:ERROR
-#   create: 输出 APP_ID=xxx
+#   list:   FLOW:CREATE_NEW | FLOW:SELECT | FLOW:PENDING_APPLICATIONS | FLOW:ERROR
+#   create: 成功输出 APP_ID=xxx；失败 exit 1，返回结构异常时同时输出 FLOW:ERROR
 #   key:    输出 confirmPageUrl
 #   audit:  输出审核结果
 #   reuse:  FLOW:REUSE_SUCCESS | FLOW:REUSE_NO_KEY | FLOW:ERROR
@@ -31,7 +31,6 @@ else
 fi
 
 require_command jq || exit 1
-require_command alipay-cli || exit 1
 
 parse_app_context_args() {
   while [[ $# -gt 0 ]]; do
@@ -261,36 +260,54 @@ extract_application_status() {
   '
 }
 
-extract_rsa2_key_info() {
+extract_rsa2_application_key_info() {
   echo "$SECURITY_BUSINESS" | jq -c '
     (
-      (.resultObj.alipayKeyList // []) +
+      (.resultObj.securityConfigList // []) +
       (.resultObj.securityKeys // []) +
-      (.data.alipayKeyList // []) +
-      (.data.securityKeys // [])
-    ) | map(select(.signType == "RSA2")) | .[0] // {}
+      (.data.securityConfigList // []) +
+      (.data.securityKeys // []) +
+      (.resultObj.alipayKeyList // []) +
+      (.data.alipayKeyList // [])
+    ) |
+    map(select(
+      .signType == "RSA2" and
+      (
+        ((.partnerPublicKey // "") != "") or
+        ((.certInfoDTO | type) == "object" and ((.certInfoDTO.publicKey // "") != ""))
+      )
+    )) |
+    .[0] // {}
   '
 }
 
-extract_rsa2_security_config() {
+extract_rsa2_alipay_key_info() {
   echo "$SECURITY_BUSINESS" | jq -c '
     (
-      (.resultObj.securityConfigList // []) +
-      (.data.securityConfigList // [])
-    ) | map(select(.signType == "RSA2")) | .[0] // {}
+      (.resultObj.alipayKeyList // []) +
+      (.data.alipayKeyList // []) +
+      (.resultObj.securityKeys // []) +
+      (.data.securityKeys // [])
+    ) |
+    map(select(.signType == "RSA2" and ((.alipayPublicKey // "") != ""))) |
+    .[0] // {}
   '
 }
 
+extract_alipay_public_key() {
+  local RSA2_KEY_INFO="$1"
+  echo "$RSA2_KEY_INFO" | jq -r '.alipayPublicKey // empty'
+}
+
 is_rsa2_application_key_ready() {
   local RSA2_KEY_INFO="$1"
-  local RSA2_SECURITY_CONFIG="$2"
 
   echo "$RSA2_KEY_INFO" | jq -e '
-    ((.certInfoDTO.publicKey // .publicKey // .alipayPublicKey // "") != "")
-  ' >/dev/null 2>&1 && return 0
-
-  echo "$RSA2_SECURITY_CONFIG" | jq -e '
-    ((.partnerPublicKey // "") != "") and (.invalid != true)
+    ((.partnerPublicKey // "") != "") or
+    (
+      (.certInfoDTO | type) == "object" and
+      ((.certInfoDTO.publicKey // "") != "")
+    )
   ' >/dev/null 2>&1
 }
 
@@ -342,10 +359,9 @@ ensure_rsa2_application_key_ready() {
   while [ "$ATTEMPT" -le "$MAX_ATTEMPTS" ]; do
     query_security_key "$APP_ID" "$PUBLIC_KEY" || return 1
 
-    RSA2_KEY_INFO=$(extract_rsa2_key_info)
-    RSA2_SECURITY_CONFIG=$(extract_rsa2_security_config)
+    RSA2_KEY_INFO=$(extract_rsa2_application_key_info)
 
-    if is_rsa2_application_key_ready "$RSA2_KEY_INFO" "$RSA2_SECURITY_CONFIG"; then
+    if is_rsa2_application_key_ready "$RSA2_KEY_INFO"; then
       return 0
     fi
 
@@ -361,30 +377,35 @@ ensure_rsa2_application_key_ready() {
   return 1
 }
 
-ensure_alipay_public_key_exported() {
+verify_key_and_export_alipay_public_key() {
   local APP_ID="$1"
 
   query_security_key "$APP_ID" || return 1
 
-  RSA2_KEY_INFO=$(extract_rsa2_key_info)
-  RSA2_SECURITY_CONFIG=$(extract_rsa2_security_config)
-  ALIPAY_PUBLIC_KEY=$(echo "$RSA2_KEY_INFO" | jq -r '.alipayPublicKey // empty')
+  RSA2_KEY_INFO=$(extract_rsa2_application_key_info)
+  RSA2_ALIPAY_KEY_INFO=$(extract_rsa2_alipay_key_info)
+  ALIPAY_PUBLIC_KEY=$(extract_alipay_public_key "$RSA2_ALIPAY_KEY_INFO")
 
-  if ! is_rsa2_application_key_ready "$RSA2_KEY_INFO" "$RSA2_SECURITY_CONFIG"; then
+  if ! is_rsa2_application_key_ready "$RSA2_KEY_INFO"; then
     echo "❌ 应用公钥尚未确认，禁止提交应用审核"
     return 1
   fi
 
   if [ -z "$ALIPAY_PUBLIC_KEY" ]; then
-    echo "❌ 未获取到 RSA2 支付宝公钥，禁止提交应用审核"
+    echo "❌ 已确认应用公钥生效，但未获取到 RSA2 支付宝公钥，禁止提交应用审核"
     return 1
   fi
 
   if write_alipay_public_key "$APP_ID" "$ALIPAY_PUBLIC_KEY"; then
     echo "✅ 已确认应用公钥并导出支付宝公钥"
     echo "支付宝公钥保存路径: ~/.config/${APP_ID}-alipayPublicKey.keytext"
+    echo "ALIPAY_PUBLIC_KEY_EXPORT_STATUS=EXPORTED"
     echo "ALIPAY_PUBLIC_KEY_FILE=~/.config/${APP_ID}-alipayPublicKey.keytext"
+  else
+    echo "ALIPAY_PUBLIC_KEY_EXPORT_STATUS=MANUAL_CONFIGURATION_REQUIRED"
   fi
+
+  return 0
 }
 
 # ─── app list: 查询已有应用 ──────────────────────────────────────────────────
@@ -422,7 +443,7 @@ app_list() {
     elif (.resultObj | type) == "array" then
       .resultObj
     else
-      []
+      null
     end
   ' 2>/dev/null)
   if [ -z "$APP_LIST" ] || ! echo "$APP_LIST" | jq -e 'type == "array"' >/dev/null 2>&1; then
@@ -433,17 +454,32 @@ app_list() {
   APP_COUNT=$(echo "$APP_LIST" | jq 'length')
 
   if [ "$APP_COUNT" -eq 0 ]; then
-    echo "📋 暂无 ${APP_APPLICATION_TYPE} 应用，进入创建应用流程"
+    echo "📋 暂无 ${APP_APPLICATION_TYPE} 应用；记录新建候选分支，等待 Step 4 统一决策"
     echo "FLOW:CREATE_NEW"
   else
     # 实际返回的状态字段值是 "ON_LINE"（带下划线）
     ONLINE_APPS=$(echo "$APP_LIST" | jq -r '[.[] | select(.status == "ON_LINE")]')
+    NON_ONLINE_APPS=$(echo "$APP_LIST" | jq -r '[.[] | select(.status != "ON_LINE")]')
     ONLINE_COUNT=$(echo "$ONLINE_APPS" | jq 'length')
+    NON_ONLINE_COUNT=$(echo "$NON_ONLINE_APPS" | jq 'length')
     ONLINE_COUNT=${ONLINE_COUNT:-0}
+    NON_ONLINE_COUNT=${NON_ONLINE_COUNT:-0}
 
     if [ "$ONLINE_COUNT" -eq 0 ]; then
-      echo "📋 暂无上线 ${APP_APPLICATION_TYPE} 应用，进入创建应用流程"
-      echo "FLOW:CREATE_NEW"
+      echo "📋 当前已有以下尚未上线的 ${APP_APPLICATION_TYPE} 应用："
+      echo ""
+      echo "| 应用ID | 应用名称 | 实际状态 |"
+      echo "|--------|----------|----------|"
+      for i in $(seq 0 $((NON_ONLINE_COUNT-1))); do
+        APP=$(echo "$NON_ONLINE_APPS" | jq ".[$i]")
+        APP_ID=$(echo "$APP" | jq -r '.appId // "未知"')
+        APP_NAME=$(echo "$APP" | jq -r '.appName // "未知"')
+        APP_STATUS=$(echo "$APP" | jq -r '.status // "未知"')
+        echo "| $APP_ID | $APP_NAME | $APP_STATUS |"
+      done
+      echo ""
+      echo "以上应用当前不可复用。请等待应用上线，或在了解现有应用状态后明确选择新建。"
+      echo "FLOW:PENDING_APPLICATIONS"
     else
       echo "📋 发现您已有以下上线 ${APP_APPLICATION_TYPE} 应用："
       echo ""
@@ -457,6 +493,23 @@ app_list() {
         echo "| $((i+1)) | $APP_ID | $APP_NAME | 已上线 |"
       done
 
+      if [ "$NON_ONLINE_COUNT" -gt 0 ]; then
+        echo ""
+        echo "另有以下尚未上线的同类型应用，当前不可复用："
+        echo ""
+        echo "| 应用ID | 应用名称 | 实际状态 |"
+        echo "|--------|----------|----------|"
+        for i in $(seq 0 $((NON_ONLINE_COUNT-1))); do
+          APP=$(echo "$NON_ONLINE_APPS" | jq ".[$i]")
+          APP_ID=$(echo "$APP" | jq -r '.appId // "未知"')
+          APP_NAME=$(echo "$APP" | jq -r '.appName // "未知"')
+          APP_STATUS=$(echo "$APP" | jq -r '.status // "未知"')
+          echo "| $APP_ID | $APP_NAME | $APP_STATUS |"
+        done
+        echo ""
+        echo "新建前请结合以上状态避免重复创建。"
+      fi
+
       echo ""
       echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
       echo "  请选择操作："
@@ -499,6 +552,11 @@ app_create() {
 
   if [ "$SUCCESS" = "true" ]; then
     APP_ID=$(echo "$BUSINESS" | jq -r '.resultObj.appId // .data.appId // empty')
+    if [ -z "$APP_ID" ]; then
+      echo "❌ 应用创建返回成功，但未解析到 appId，禁止进入公钥设置流程"
+      echo "FLOW:ERROR"
+      exit 1
+    fi
     echo "✅ 应用创建成功"
     echo "APPLICATION_TYPE=$APP_APPLICATION_TYPE"
     echo "APP_ID=$APP_ID"
@@ -511,6 +569,12 @@ app_create() {
 
 # ─── app key: 设置应用公钥 ───────────────────────────────────────────────────
 app_key() {
+  if [ "$#" -ne 2 ] || [[ "${1:-}" == --* ]]; then
+    echo "❌ 参数格式错误：key 使用位置参数 <appId> <publicKey>，不支持 --app-id 等未定义选项"
+    echo "用法: bash app.sh key <appId> <publicKey>"
+    exit 1
+  fi
+
   APP_ID="$1"
   PUBLIC_KEY="$2"
 
@@ -546,7 +610,8 @@ app_key() {
       echo ""
       echo "请点击以下链接确认公钥设置："
       echo ""
-      echo "[点击确认公钥设置]($CONFIRM_PAGE_URL)（无法跳链时，请复制链接到网页浏览器打开）"
+      echo "提示：无法跳链时，请复制下方链接到网页浏览器打开。"
+      echo "[点击确认公钥设置]($CONFIRM_PAGE_URL)"
       echo ""
       echo "链接有效期为10分钟。"
       echo ""
@@ -564,6 +629,12 @@ app_key() {
 
 # ─── app audit: 提交应用审核 ─────────────────────────────────────────────────
 app_audit() {
+  if [ "$#" -ne 1 ] || [[ "${1:-}" == --* ]]; then
+    echo "❌ 参数格式错误：audit 使用位置参数 <appId>，不支持 --app-id 等未定义选项"
+    echo "用法: bash app.sh audit <appId>"
+    exit 1
+  fi
+
   APP_ID="$1"
 
   if [ -z "$APP_ID" ]; then
@@ -572,7 +643,7 @@ app_audit() {
     exit 1
   fi
 
-  ensure_alipay_public_key_exported "$APP_ID" || exit 1
+  verify_key_and_export_alipay_public_key "$APP_ID" || exit 1
 
   REQUEST_JSON=$(jq -n --arg appId "$APP_ID" '{request:{appId:$appId}}')
 
@@ -602,6 +673,12 @@ app_audit() {
 
 # ─── app verify-key: 确认应用公钥已设置 ─────────────────────────────────────
 app_verify_key() {
+  if [ "$#" -lt 1 ] || [ "$#" -gt 2 ] || [[ "${1:-}" == --* ]]; then
+    echo "❌ 参数格式错误：verify-key 使用位置参数 <appId> [publicKey]，不支持 --app-id 等未定义选项"
+    echo "用法: bash app.sh verify-key <appId> [publicKey]"
+    exit 1
+  fi
+
   APP_ID="$1"
   PUBLIC_KEY="${2:-}"
 
@@ -623,6 +700,12 @@ app_verify_key() {
 
 # ─── app reuse: 复用已有应用（查询安全密钥） ──────────────────────────────────
 app_reuse() {
+  if [ "$#" -ne 1 ] || [[ "${1:-}" == --* ]]; then
+    echo "❌ 参数格式错误：reuse 使用位置参数 <appId>，不支持 --app-id 等未定义选项"
+    echo "用法: bash app.sh reuse <appId>"
+    exit 1
+  fi
+
   APP_ID="$1"
 
   if [ -z "$APP_ID" ]; then
@@ -644,20 +727,29 @@ app_reuse() {
   fi
 
   if query_security_key "$APP_ID"; then
-    RSA2_KEY_INFO=$(extract_rsa2_key_info)
-    ALIPAY_PUBLIC_KEY=$(echo "$RSA2_KEY_INFO" | jq -r '.alipayPublicKey // empty')
+    RSA2_KEY_INFO=$(extract_rsa2_application_key_info)
+    RSA2_ALIPAY_KEY_INFO=$(extract_rsa2_alipay_key_info)
+    ALIPAY_PUBLIC_KEY=$(extract_alipay_public_key "$RSA2_ALIPAY_KEY_INFO")
 
-    if [ -n "$ALIPAY_PUBLIC_KEY" ]; then
+    if ! is_rsa2_application_key_ready "$RSA2_KEY_INFO"; then
+      echo "⚠️ 未确认到已生效的 RSA2 应用公钥"
+      echo "FLOW:REUSE_NO_KEY"
+      exit 1
+    elif [ -n "$ALIPAY_PUBLIC_KEY" ]; then
       if write_alipay_public_key "$APP_ID" "$ALIPAY_PUBLIC_KEY"; then
         echo "✅ 已获取支付宝公钥"
         echo "支付宝公钥保存路径: ~/.config/${APP_ID}-alipayPublicKey.keytext"
+        echo "ALIPAY_PUBLIC_KEY_EXPORT_STATUS=EXPORTED"
         echo "ALIPAY_PUBLIC_KEY_FILE=~/.config/${APP_ID}-alipayPublicKey.keytext"
+      else
+        echo "ALIPAY_PUBLIC_KEY_EXPORT_STATUS=MANUAL_CONFIGURATION_REQUIRED"
       fi
       echo "APP_ID=$APP_ID"
       echo "FLOW:REUSE_SUCCESS"
     else
-      echo "⚠️ 未找到 RSA2 公钥，请先设置应用公钥"
-      echo "FLOW:REUSE_NO_KEY"
+      echo "❌ 已确认应用公钥生效，但未获取到 RSA2 支付宝公钥"
+      echo "FLOW:ERROR"
+      exit 1
     fi
   else
     echo "FLOW:ERROR"
@@ -666,7 +758,14 @@ app_reuse() {
 }
 
 # ─── 入口分发 ────────────────────────────────────────────────────────────────
-case "${1:-}" in
+APP_COMMAND="${1:-}"
+case "$APP_COMMAND" in
+  list|create|key|verify-key|audit|reuse)
+    require_command alipay-cli || exit 1
+    ;;
+esac
+
+case "$APP_COMMAND" in
   list)
     shift
     app_list "$@"