dukang/server/dukang-api/src/integrations/wechat/wechat.interface.ts

import type { WechatJssdkConfig, WechatJsapiPrepayParams } from '@dukang/shared-types';

export type WechatCodeSession = {
  openId: string;
  unionId?: string;
  sessionKey?: string;
  accessToken?: string;
};

export type WechatOAuthSession = {
  openId: string;
  unionId?: string;
  accessToken?: string;
  refreshToken?: string;
};

export type WechatOAuthUserInfo = {
  openId: string;
  nickname?: string;
  headImgUrl?: string;
  unionId?: string;
};

export type WechatPayNotifyResult = {
  transactionId: string;
  outTradeNo: string;
  tradeState: string;
  amountFen: number;
};

export type WechatWxaCodeUnlimitedInput = {
  /** 最大 32 可见字符，扫码后小程序 onLaunch.options.scene */
  scene: string;
  /** 小程序页面路径，如 pages/home/index（不要前导 /） */
  page?: string;
  width?: number;
  checkPath?: boolean;
  envVersion?: 'release' | 'trial' | 'develop';
  isHyaline?: boolean;
};

/** 小程序发货信息管理 — 发货信息录入 */
export type WechatUploadShippingInfoInput = {
  /** 1=商户单号；2=微信支付单号 */
  orderNumberType: 1 | 2;
  transactionId?: string;
  mchId?: string;
  outTradeNo?: string;
  /** 1 快递 2 同城 3 虚拟 4 自提 */
  logisticsType: 1 | 2 | 3 | 4;
  /** 1 统一发货 2 分拆发货 */
  deliveryMode?: 1 | 2;
  shippingList: Array<{
    trackingNo?: string;
    /** 微信运力 ID，如 SF / STO */
    expressCompany?: string;
    itemDesc: string;
    contact?: {
      consignorContact?: string;
      receiverContact?: string;
    };
  }>;
  uploadTime: string;
  payerOpenId: string;
};

export type WechatUploadShippingInfoResult = {
  errcode: number;
  errmsg: string;
};

export type WechatOrderShippingQueryResult = {
  errcode: number;
  errmsg: string;
  /** 1待发货 2已发货 3确认收货 4交易完成 5已退款 */
  orderState?: number;
  transactionId?: string;
  merchantTradeNo?: string;
  finishShipping?: boolean;
};

export type WechatDeliveryCompany = {
  deliveryId: string;
  deliveryName: string;
};

export interface IWechatProvider {
  isEnabled(): boolean;

  /** 是否为 preV1 Mock 实现（登录时可回落到演示账号） */
  isMock(): boolean;

  /** 微信支付是否已配置（商户号 + 证书） */
  isPayEnabled(): boolean;

  /** 当前商户号（用于日志/排查） */
  getMchId(): string;

  /** 小程序 code2session */
  code2Session(code: string, actorRef?: { refType: string; refId: bigint }): Promise<WechatCodeSession>;

  /** 公众号 H5 OAuth code 换 openId */
  oauth2AccessToken(code: string, actorRef?: { refType: string; refId: bigint }): Promise<WechatOAuthSession>;

  /** 公众号 OAuth access_token 拉取用户昵称头像（snsapi_userinfo） */
  fetchOAuthUserInfo(
    accessToken: string,
    openId: string,
    actorRef?: { refType: string; refId: bigint },
  ): Promise<WechatOAuthUserInfo>;

  /** JSSDK 签名配置 */
  createJssdkConfig(url: string, actorRef?: { refType: string; refId: bigint }): Promise<WechatJssdkConfig>;

  /** 构建公众号 OAuth 授权 URL */
  buildOAuthUrl(redirectUri: string, state: string, scope?: string): string;

  /** 小程序手机号 code 解密（或调用微信 getPhoneNumber 接口） */
  getPhoneNumberByCode(
    code: string,
    platform: 'mini' | 'h5',
    actorRef?: { refType: string; refId: bigint },
  ): Promise<string>;

  /** 创建 JSAPI 预支付参数（使用 WX_MCH_ID 统一下单） */
  createJsapiPrepay(params: {
    orderNo: string;
    description: string;
    amountFen: number;
    openId: string;
    notifyUrl: string;
    platform?: 'h5' | 'mini';
  }): Promise<WechatJsapiPrepayParams>;

  /** 解析并验签支付回调通知 */
  parsePayNotification(
    headers: Record<string, string | string[] | undefined>,
    rawBody: string,
  ): Promise<WechatPayNotifyResult>;

  /** 获取不限制的小程序码（PNG Buffer），须服务端调用 */
  getWxaCodeUnlimited(input: WechatWxaCodeUnlimitedInput): Promise<Buffer>;

  /**
   * 小程序发货信息录入（交易资金解冻前置）
   * @see https://developers.weixin.qq.com/miniprogram/dev/server/API/order_shipping/api_uploadshippinginfo.html
   */
  uploadShippingInfo(input: WechatUploadShippingInfoInput): Promise<WechatUploadShippingInfoResult>;

  /** 查询支付单发货/确认收货状态 */
  getOrderShippingInfo(input: {
    transactionId?: string;
    mchId?: string;
    outTradeNo?: string;
  }): Promise<WechatOrderShippingQueryResult>;

  /** 获取运力公司列表（快递公司 delivery_id） */
  getDeliveryList(): Promise<WechatDeliveryCompany[]>;
}