八字精算命理洞察

概述

八字-八字精算·命理洞察

触发条件

当用户需要从多个角度理解命局特点、比较不同阶段的运势，或希望获得五行、姻缘、财运等综合命理参考时，使用本 Skill。

接口

• 方法：POST
• 地址：https://api.shopbuy.top/api/agent/bazi/insight
• 请求体（JSON）：

{
  "name": "张三",
  "sex": "0",
  "type": "1",
  "bornDateTime": "199412031855",
  "sect": "1",
  "zhen": "2",
  "province": "北京市",
  "city": "北京",
  "lang": "zh-cn",
  "factor": "0"
}

• name（必填）：姓名
• sex（必填）：性别，0 男、1 女
• type（必填）：历类型，0 农历、1 公历
• bornDateTime（必填）：出生年月日时分，格式 yyyyMMddHHmm，例如 199412031855
• sect（可选）：流派，1 晚子时日柱算明天、2 晚子时日柱算当天，默认 1
• zhen（可选）：是否考虑真太阳时，1 考虑、2 不考虑，默认 2；考虑时 province 与 city 必传
• province（可选）：省，如 北京市
• city（可选）：市，如 北京
• lang（可选）：zh-cn（默认）、en-us、zh-tw
• factor（可选）：调整因子，0 不作调整、1 需要调整，默认 0

接口固定使用 HTTPS。该服务每次成功履约对应一次微信支付按量付费调用。

前置检查

进入支付流程前，Agent 必须先检查微信支付技能 weixinpay 是否已安装：

• 若未安装，提示用户执行 npx -y @tenpay/weixinpay-ai-installer 一键完成 weixinpay 插件安装，待安装完成后再继续，不要在缺少支付技能的情况下发起付费调用。
• 若已安装，直接进入下方支付流程。

支付流程

1. 首次请求不要携带 X-Out-Trade-No。
2. 服务会返回 HTTP 402，并在 WeixinPay-Required 响应头中返回支付触发标识（payment_code），同时在 X-Out-Trade-No 响应头中返回商户订单号。
3. 将完整的 WeixinPay-Required 交给微信支付技能 weixinpay_pay，向用户申请本次支付授权，不要修改、截断或放进请求体。买家侧首次使用需绑定微信支付 AI 专属卡。
4. 支付完成后，使用相同的请求参数重试，并添加请求头：X-Out-Trade-No: <商户订单号>。
5. 只有 HTTP 200 且响应中的 fulfillment_confirmed=true、Payment-Validation 存在时，才读取 data。

成功返回

{
  "code": 200,
  "resource_id": "api/agent/bazi",
  "trade_no": "微信支付交易号",
  "out_trade_no": "商户订单号",
  "already_fulfilled": false,
  "fulfillment_confirmed": true,
  "data": {
    "code": 200,
    "msg": "成功",
    "taskNo": "本次请求号",
    "charge": true,
    "data": {
      "base_info": {
        "sex": "乾造",
        "name": "张三",
        "gongli": "1994-12-03 18:55:00",
        "nongli": "一九九四年冬月初一日 酉时",
        "qiyun": "1年3个月20天后起运",
        "jiaoyun": "1996-03-23后交运",
        "shengxiao": "狗",
        "xingzuo": "射手",
        "zhengge": "伤官格",
        "xiyongshen": {
          "qiangruo": "八字偏弱",
          "xiyongshen": "金，水",
          "jishen": "水",
          "xiyongshen_desc": "身弱，需补助，避免克泄耗，喜用金补水，避木忌土火。"
        },
        "detail_info": {
          "dayun_info": [
            {
              "dayun_index": 1,
              "dayun_start_year": 1996,
              "dayun_start_ganzhi": "丙子",
              "dayun_shishen": "正财",
              "liunian_info": [],
              "dayun_shensha": "禄神 福星 天厨 桃花",
              "dayun_indication": {
                "shiye": "事业批示",
                "xueye": "学业批示",
                "yunshi": "运势批示",
                "yinyuan": "姻缘批示",
                "caiyun": "财运批示",
                "jiankang": "健康批示"
              }
            }
          ],
          "sizhu_info": {
            "year": { "tg": "甲", "dz": "戌", "ny": "山头火", "shensha": "天医 国印" },
            "month": { "tg": "乙", "dz": "亥", "ny": "山头火", "shensha": "空亡 天德" },
            "day": { "tg": "癸", "dz": "亥", "ny": "大海水", "shensha": "空亡 天罗" },
            "hour": { "tg": "辛", "dz": "酉", "ny": "石榴木", "shensha": "空亡 六厄" },
            "sizhu_indication": {
              "chenggu": { "total_weight": "3.8", "description": "称骨断命批示" },
              "yinyuan": { "sanshishu_yinyuan": "三世书姻缘批示" },
              "caiyun": { "sanshishu_caiyun": { "simple_desc": "简批", "detail_desc": "详批" } }
            }
          }
        }
      }
    }
  }
}

说明：

• base_info 为基本盘信息，包含 xiyongshen（喜用神）、五行旺度、命卦、星宿等字段。
• detail_info.dayun_info 为大运信息，每项包含该大运的 liunian_info（流年信息）与 dayun_indication（大运批示）。
• detail_info.sizhu_info 为四柱信息（年/月/日/时柱）与 sizhu_indication（四柱批示，含称骨、姻缘、财运等）。

服务端支付安全实现

本 Skill 对应的服务端已实现完整的微信支付按量付费闭环；客户端或 Agent 只需要按照“支付流程”发送和重试请求，不能自行跳过服务端验付。

订单持久化

服务端在返回 HTTP 402 之前，先持久化微信支付订单。订单至少保存：out_trade_no、total_amount、api_product=bazi_precise、resource_id=api/agent/bazi、pay_before、status=PENDING_PAYMENT、fulfillment_status=UNFULFILLED。

X-Out-Trade-No 验付

携带 X-Out-Trade-No 重试时，服务端会以该订单号调用微信支付「按商户订单号查单」接口，确认本次微信支付已成功：

微信支付「按商户订单号查单」

服务端以 X-Out-Trade-No 作为微信支付商户订单号 out_trade_no 查单，只有在下列条件全部满足时才允许履约：

1. 微信支付返回 trade_state=SUCCESS。
2. 查单返回的 out_trade_no 与本地订单一致。
3. 查单返回的 amount.total 与本地订单金额一致。
4. 本地订单的 resource_id 与当前资源 api/agent/bazi 一致。
5. 查单返回的 transaction_id 未被其他订单使用。
6. 本地订单未取消、首次履约尚未超过 pay_before，且状态允许履约。

任一校验失败时，服务端不会返回八字数据。

幂等履约与履约确认

服务端用数据库事务锁定订单，先将首次有效支付原子更新为 PENDING_CONFIRM，并保存微信支付交易单号（写入 trade_no），从而防止同一订单或同一微信支付交易被重复交付。

数据生成后，服务端保存结果快照，并将订单标记为已履约：

本地履约确认（微信支付已完成收款，无需再次调用支付接口）

付款成功后，订单更新为 fulfillment_status=FULFILLED 并向 Agent 返回 HTTP 200、资源数据和 Payment-Validation。

若资源已生成但履约确认暂时失败，订单保留 PENDING_CONFIRM 和结果快照；Agent 必须携带同一个 X-Out-Trade-No 重试，服务端不会再次查询或再次收费。已完成订单的重复请求直接返回已保存的同一结果，不重复调用数据源。

失败处理

• 400：必填参数缺失或格式错误（姓名、性别、历类型、出生日期时间格式等）。
• 402：支付凭证缺失、失效或订单不匹配，继续使用微信支付流程。
• 502：第三方请求或履约确认暂时失败，使用同一个 X-Out-Trade-No 重试。
• 503：服务端微信支付配置不完整或暂时不可用，不要重复扣款。