pay-interface.ts

/**
 * 支付套餐信息（面向前端消费的统一结构）。
 * 用于套餐列表展示、下单前校验、套餐配置管理等场景。
 */
export interface IRenewPackageInfo {
  /**
   * 套餐唯一ID（后端主键或业务唯一标识）。
   */
  packageId: string;
  /**
   * 套餐编码（对外稳定标识，常用于下单与查询）。
   */
  packageCode: string;
  /**
   * 套餐类型。
   * 典型取值见 PaymentPackageTypeValue。
   */
  pkgType?: number;
  /**
   * 套餐展示名称。
   */
  displayName: string;
  /**
   * 套餐有效期（天）。
   */
  durationDays?: number;
  /**
   * 套餐价格（分）。
   */
  amountCents?: number;
  /**
   * 货币代码，例如 CNY、USD。
   */
  currency?: string;
  /**
   * 服务应用 AppID（用于多应用场景隔离套餐）。
   */
  serviceAppid?: string;
  /**
   * 业务场景标识，如 AI_MODEL_CALL、APP_PUBLISH。
   */
  scene?: string;
  /**
   * 套餐关联的主题标识。
   */
  theme?: string;
  /**
   * 套餐关联的主题作者标识。
   */
  themeAuthor?: string;
  /**
   * 套餐关联的主题 AppID。
   */
  themeAppid?: string;
  /**
   * AI 应用 AppID（AI 套餐相关）。
   */
  aiAppid?: string;
  /**
   * AI 作者标识（AI 套餐相关）。
   */
  aiAuthor?: string;
  /**
   * AI 主题标识（AI 套餐相关）。
   */
  aiTheme?: string;
  /**
   * AI 模型名称（AI 套餐相关）。
   */
  aiModel?: string;
  /**
   * 套餐权益配置。
   * 可能是对象（结构化权益）或字符串（后端透传配置）。
   */
  pkgRights?: Record<string, any> | string;
  /**
   * 管理端业务描述。
   */
  bussdesc?: string;
  /**
   * 管理端图片列表（通常为 URL 拼接字符串）。
   */
  imglist?: string;
  /**
   * 审核状态。
   * 0=未审核/待审核，1=待审核，2=审核通过，3=审核被拒（以服务端最终定义为准）。
   */
  checkStatus?: number;
  /**
   * 审核备注/驳回原因。
   */
  checkReason?: string;
  /**
   * 被替换的旧套餐ID（修改套餐时使用）。
   */
  replacesPkgId?: number;
  /**
   * 审核时间（服务端返回的时间字符串）。
   */
  checkTime?: string;
  /**
   * 创建时间（服务端返回的时间字符串）。
   */
  createTime?: string;
  /**
   * 链上套餐ID（链路追踪或链上关联字段）。
   */
  chainPkgId?: number;
  /**
   * 扩展空间大小（通常单位为 GB，具体以业务约定为准）。
   */
  spaceSize?: number;
  /**
   * 备注信息
   */
  remark?: string;
  /** 是否仅限该应用下首次付款用户；推荐套餐会自动启用。 */
  firstPayOnly?: boolean;
  /** 是否必须通过推荐人购买；推荐套餐仅限本应用未购买且未绑定推荐人的用户。 */
  requireRecommender?: boolean;
  /** 推荐人的最低等级要求，0 表示公开套餐。 */
  requireRecommenderLevel?: number;
}

/**
 * 套餐类型常量定义。
 */
export enum PaymentPackageTypeValue {
  /**
   * 模型调用会员套餐。
   */
  SERVICECALL_MEMBER = 1,
  /**
   * 应用发布套餐。
   */
  APP_PUBLISH = 2,
  /**
   * 存储扩容套餐。
   */
  STORAGE_PURCHASE = 3,
  /**
   * 平台 SVIP 套餐。
   */
  PLATFORM_SVIP = 4,
  /**
   * 自由定价套餐。
   */
  FLEXIBLE_PRICING = 5,
}

/**
 * 套餐类型联合类型。
 * 约束调用方只能使用定义内的合法套餐类型值。
 */
export type PaymentPackageType =
  | PaymentPackageTypeValue.SERVICECALL_MEMBER // 模型调用会员套餐
  | PaymentPackageTypeValue.APP_PUBLISH // 应用发布套餐
  | PaymentPackageTypeValue.STORAGE_PURCHASE // 存储扩容套餐
  | PaymentPackageTypeValue.PLATFORM_SVIP // 平台 SVIP 套餐
  | PaymentPackageTypeValue.FLEXIBLE_PRICING; // 自由定价套餐

/**
 * 应用开发者提交套餐申请/修改时的请求体。
 */
export interface IPackageApplyRequest {
  /**
   * 套餐类型。
   */
  pkgType: number;
  /**
   * 业务场景标识。
   */
  scene?: string;
  /**
   * 套餐业务描述。
   */
  bussdesc?: string;
  /**
   * 套餐展示图列表。
   */
  imglist?: string;
  /**
   * 套餐名称。
   */
  pkgName: string;
  /**
   * 语言标识，如 zh、en。
   */
  lang?: string;
  /**
   * 金额（分）。
   */
  amount: number;
  /**
   * 货币代码，默认 CNY。
   */
  currency?: string;
  /**
   * 有效期（天）。
   */
  validDays?: number;
  /**
   * 权益配置，支持对象或字符串。
   */
  pkgRights?: Record<string, any> | string;
  /**
   * 主题标识（按业务场景可选）。
   */
  theme?: string;
  /**
   * 主题作者标识（按业务场景可选）。
   */
  themeAuthor?: string;
  /**
   * 主题 AppID（按业务场景可选）。
   */
  themeAppid?: string;
  /**
   * 服务 AppID（按业务场景可选）。
   */
  serviceAppid?: string;
  /**
   * 被替换的旧套餐ID（修改套餐时使用）。
   */
  replacesPkgId?: number;
  /**
   * 链上套餐ID（链路追踪或链上关联字段）。
   */
  chainPkgId?: number;
  /**
   * 扩展空间大小（通常用于存储类套餐）。
   */
  spaceSize?: number;
  /**
   * 备注信息
   */
  remark?: string;
  /** 是否仅限该应用下首次付款用户；推荐套餐会自动启用。 */
  firstPayOnly?: boolean;
  /** 是否必须通过推荐人购买；推荐套餐仅限本应用未购买且未绑定推荐人的用户。 */
  requireRecommender?: boolean;
  /** 推荐人的最低等级要求，0 表示公开套餐。 */
  requireRecommenderLevel?: number;
}

/**
 * 套餐配置查询过滤条件。
 */
export interface IPackageConfigFilter {
  /**
   * 页码（从 1 开始）。
   */
  pageNum?: number;
  /**
   * 每页数量。
   */
  pageSize?: number;
  /**
   * 套餐类型，-1 表示所有类型。
   */
  pkgType?: number;
  /**
   * 审核状态，0 表示所有，1 待审核，2 审核通过，3 审核被拒。
   */
  checkStatus?: number;
  /**
   * 仅按 AppID 过滤。
   */
  appid?: string;
}

/**
 * 套餐配置列表查询结果。
 */
export interface IPackageConfigListResult {
  /**
   * 当前页数据。
   */
  list: IRenewPackageInfo[];
  /**
   * 总记录数。
   */
  total: number;
}

/** 应用内的一条推广奖励比例策略。 */
export interface IRecommenderAppPolicy {
  id: number;
  serviceAppid: string;
  /** 非空表示单个推荐人的特殊覆盖策略。 */
  recommenderPubkey: string;
  /** 大于 0 表示应用的对应等级策略；特殊推荐人覆盖时为 0。 */
  recommenderLevel: number;
  hasFirstPayRatio: boolean;
  firstPayRatio: number;
  hasSubsequentPayRatio: boolean;
  subsequentPayRatio: number;
  remark: string;
  createTime: string;
  updateTime: string;
}

/** 支付网关应用管理中维护的推荐人等级定义。 */
export interface IRecommenderLevelDefinition {
  id: number;
  level: number;
  name: string;
  description: string;
  remark: string;
  createTime: string;
  updateTime: string;
}

/** 可管理某个应用推广比例的授权用户。 */
export interface IRecommenderAppManager {
  id: number;
  serviceAppid: string;
  managerPubkey: string;
  grantedBy: string;
  grantedByType: "admin" | "owner" | string;
  remark: string;
  createTime: string;
  updateTime: string;
}

/** 当前签名用户在应用推广配置中的权限。 */
export interface IRecommenderAppPolicyAccess {
  role: "owner" | "manager" | string;
  canManagePolicy: boolean;
  canManageManagers: boolean;
  ownerPubkey: string;
  signerPubkey: string;
}

export interface IRecommenderAppPolicyInput {
  serviceAppid: string;
  recommenderPubkey?: string;
  recommenderLevel?: number;
  hasFirstPayRatio: boolean;
  firstPayRatio?: number;
  hasSubsequentPayRatio: boolean;
  subsequentPayRatio?: number;
  remark?: string;
}

export interface IRecommenderAppManagerInput {
  serviceAppid: string;
  managerPubkey: string;
  remark?: string;
}

/**
 * 支付网关场景标识。
 * 由业务方定义具体字符串值。
 */
export type PaymentGatewayScene = string;

/**
 * 待支付网关订单的本地暂存信息。
 * 常用于跳转支付页前后恢复支付上下文。
 */
export interface IPendingGatewayPayment {
  /**
   * 支付场景标识。
   */
  scene: PaymentGatewayScene;
  /**
   * 商户订单号（可能在创建前为空）。
   */
  outTradeNo?: string;
  /**
   * 套餐编码。
   */
  packageCode: string;
  /**
   * 套餐ID。
   */
  packageId?: string;
  /**
   * 套餐名称。
   */
  packageName: string;
  /**
   * 订单金额（分）。
   */
  amountCents: number;
  /**
   * 自由定价套餐使用的价格明细 key。
   */
  priceKey?: string;
  /**
   * 套餐时长（天）。
   */
  durationDays?: number;
  /**
   * 业务透传字段。
   */
  payload?: Record<string, any>;
  /**
   * 创建时间戳（毫秒）。
   */
  createdAt: number;
}

/**
 * 支付订单记录。
 * 来自支付系统查询结果，用于订单列表和状态展示。
 */
export interface IPaymentOrderRecord {
  /**
   * 商户订单号。
   */
  outTradeNo: string;
  /**
   * 用户账号标识。
   */
  account: string;
  /**
   * 应用ID。
   */
  dappid: string;
  /**
   * 套餐ID。
   */
  packageId: string;
  /**
   * 套餐名称。
   */
  packageName: string;
  /**
   * 套餐编码。
   */
  packageCode: string;
  /**
   * 订单金额（分）。
   */
  amountCents: number;
  /**
   * 自由定价套餐使用的价格明细 key。
   */
  priceKey?: string;
  /**
   * 支付状态码。
   */
  payStatus: number;
  /**
   * 支付状态文本。
   */
  payStatusText: string;
  /**
   * 交易状态码。
   */
  tradeState: string;
  /**
   * 交易状态文本。
   */
  tradeStateText: string;
  /**
   * 交易类型，如 JSAPI、NATIVE。
   */
  tradeType: string;
  /**
   * 第三方支付平台交易号。
   */
  transactionId: string;
  /**
   * 支付成功时间。
   */
  successTime: string;
  /**
   * 订单创建时间。
   */
  createdAt: string;
  /**
   * 支付场景，无法识别时为 UNKNOWN。
   */
  scene: PaymentGatewayScene | "UNKNOWN";
}

/**
 * 支付模块对外操作接口。
 */
export interface IPayOperations {
  /**
   * 配置服务端地址信息
   * @param options 支付网关及支付能力相关地址配置
   */
  config(options: {
    /**
     * 支付 Peer 服务地址。
     */
    payPeerUrl?: string;
    /**
     * 托管支付页地址（Hosted Checkout）。
     */
    hostedPayBaseUrl?: string;
    /**
     * 支付 API 基础地址。
     */
    payApiBaseUrl?: string;
  }): void;

  /**
   * 查询支付订单列表。
   * @param options 查询条件
   * @returns 订单记录数组
   */
  listPaymentOrders(options: {
    /**
     * 账号标识（必填）。
     */
    account: string;
    /**
     * 应用ID（可选）。
     */
    dappid?: string;
    /**
     * 页码。
     */
    pageNum?: number;
    /**
     * 每页大小。
     */
    pageSize?: number;
    /**
     * 是否跳过账单补偿检查。
     */
    skipBillCheck?: boolean;
  }): Promise<IPaymentOrderRecord[]>;

  /**
   * 按应用维度查询订单（商品管理 / 统计分析用）。
   * 返回该应用下所有买家的订单，因此网关要求调用者是应用 owner
   * 或配置的统计管理员。订单由支付网关写入，此接口只读。
   * @param options 查询条件（dappid / 分页 / 商品 / 状态 / 时间过滤）
   * @returns 订单记录数组
   */
  listOrdersByDappid(options: {
    /**
     * 应用ID（可选，缺省用当前应用）。
     */
    dappid?: string;
    /**
     * 页码。
     */
    pageNum?: number;
    /**
     * 每页大小。
     */
    pageSize?: number;
    /**
     * 商品价格 key（可选）。
     */
    priceKey?: string;
    /** 推荐人 pubkey；不传时 SDK 自动读取当前 URL 或本地已保存值。 */
    recommender?: string;
    /**
     * 套餐/商品 ID（可选）。
     */
    pkgId?: number;
    /**
     * 支付状态（可选）。
     */
    payStatus?: number;
    /**
     * 起始时间（毫秒时间戳，可选）。
     */
    startTime?: number;
    /**
     * 结束时间（毫秒时间戳，左闭右开，可选）。
     */
    endTime?: number;
  }): Promise<IPaymentOrderRecord[]>;

  /**
   * 按应用维度分页查询订单，返回总数供分页 UI 使用。
   * 过滤条件与 listOrdersByDappid 一致。
   */
  listOrdersByDappidPage(options: {
    dappid?: string;
    pageNum?: number;
    pageSize?: number;
    priceKey?: string;
    pkgId?: number;
    payStatus?: number;
    startTime?: number;
    endTime?: number;
  }): Promise<{
    list: IPaymentOrderRecord[];
    total: number;
    pageNum: number;
    pageSize: number;
  }>;

  /**
   * 按应用维度统计订单（笔数/已支付笔数/已支付金额）。
   * 与列表同过滤条件同口径，金额只统计已支付订单。
   */
  statsOrdersByDappid(options: {
    dappid?: string;
    priceKey?: string;
    pkgId?: number;
    payStatus?: number;
    startTime?: number;
    endTime?: number;
  }): Promise<{
    totalOrders: number;
    paidOrders: number;
    paidAmount: number;
  }>;

  /**
   * 创建支付订单。
   * @param options 下单参数
   * @returns 商户订单号 outTradeNo
   */
  createPayOrder(options: {
    /**
     * 账号标识。
     */
    account: string;
    /**
     * 套餐ID。
     */
    packageId: string;
    /**
     * 套餐名称。
     */
    packageName: string;
    /**
     * 金额（分）。
     */
    amountCents: number;
    /**
     * 支付透传参数。
     */
    attach: string;
    /**
     * 应用ID（可选）。
     */
    dappid?: string;
    /**
     * 是否续费订单。
     */
    isRenew?: boolean;
    /**
     * 续费时指定的原订单 NO（仅续费时有效）。
     */
    oldNo?: number;
    /**
     * 自由定价套餐金额明细 key（可选）。
     */
    priceKey?: string;
  }): Promise<string>;

  /**
   * 获取 NATIVE 支付二维码链接。
   * @param outTradeNo 商户订单号
   * @returns 支付链接（通常可用于生成二维码）
   */
  getNativePrepayCodeUrl(outTradeNo: string): Promise<string>;

  /**
   * 查询订单支付结果。
   * @param outTradeNo 商户订单号
   * @returns 是否支付成功
   */
  queryPaymentResult(outTradeNo: string): Promise<boolean>;

  /**
   * 拉取续费/购买套餐列表。
   * @param pkgType 套餐类型
   * @param serviceAppid 服务应用 AppID（可选）
   * @param scene 业务场景（可选）
   */
  listRenewPackages(
    pkgType: PaymentPackageType,
    serviceAppid?: string,
    scene?: string,
    recommender?: string,
  ): Promise<IRenewPackageInfo[]>;

  /**
   * 查询指定推荐人在某应用下可推广的套餐。
   * 该目录按推荐人等级筛选，不应用买家侧的自荐和首次付款校验。
   */
  listPromotablePackages(
    pkgType: PaymentPackageType | 0,
    serviceAppid: string,
    scene?: string,
    recommender?: string,
  ): Promise<IRenewPackageInfo[]>;

  /**
   * 按编码获取指定套餐信息。
   * @param packageCode 套餐编码
   * @param pkgType 套餐类型
   * @param serviceAppid 服务应用 AppID（可选）
   * @param scene 业务场景（可选）
   */
  getPackageInfo(
    packageCode: string,
    pkgType: PaymentPackageType,
    serviceAppid?: string,
    scene?: string,
  ): Promise<IRenewPackageInfo>;

  /**
   * 获取指定套餐续费时长（天）。
   * @param packageCode 套餐编码
   * @param targetType 套餐类型
   * @param serviceAppid 服务应用 AppID（可选）
   * @param scene 业务场景（可选）
   */
  getRenewalDays(
    packageCode: string,
    targetType: PaymentPackageType,
    serviceAppid?: string,
    scene?: string,
  ): Promise<number>;

  /**
   * 应用开发者：申请创建/修改支付套餐（提交审核）
   * @param request 套餐申请内容
   */
  applyBusinessPackage(request: IPackageApplyRequest): Promise<boolean>;

  /**
   * 应用开发者：查询自己应用下的所有套餐配置列表（含审核状态）
   * @param filter 查询过滤条件
   */
  getAllPackagesConfig(
    filter: IPackageConfigFilter,
  ): Promise<IPackageConfigListResult>;

  /**
   * 应用开发者：删除自己应用下的支付套餐配置
   * @param packageId 套餐ID
   */
  deleteBusinessPackage(packageId: string): Promise<boolean>;

  /** 查询当前账号是否可管理指定应用的推广比例。 */
  getRecommenderAppPolicyAccess(
    serviceAppid: string,
  ): Promise<IRecommenderAppPolicyAccess>;

  /** 查询指定应用的推广奖励比例配置。 */
  listRecommenderAppPolicies(options: {
    serviceAppid: string;
    recommenderPubkey?: string;
    recommenderLevel?: number;
    pageNum?: number;
    pageSize?: number;
  }): Promise<{ list: IRecommenderAppPolicy[]; total: number }>;

  /** 查询应用奖励策略可引用的推荐人等级目录。 */
  listRecommenderLevelDefinitions(options: {
    serviceAppid: string;
    pageNum?: number;
    pageSize?: number;
  }): Promise<{ list: IRecommenderLevelDefinition[]; total: number }>;

  /** Owner 或授权用户新增、更新指定应用的推广奖励比例。 */
  upsertRecommenderAppPolicy(
    input: IRecommenderAppPolicyInput,
  ): Promise<boolean>;

  /** Owner 或授权用户删除指定应用的推广奖励比例。 */
  deleteRecommenderAppPolicy(
    serviceAppid: string,
    recommenderPubkey?: string,
    recommenderLevel?: number,
  ): Promise<boolean>;

  /** Owner 查询指定应用的推广比例授权用户。 */
  listRecommenderAppManagers(options: {
    serviceAppid: string;
    managerPubkey?: string;
    pageNum?: number;
    pageSize?: number;
  }): Promise<{ list: IRecommenderAppManager[]; total: number }>;

  /** Owner 为指定应用新增、更新推广比例授权用户。 */
  upsertRecommenderAppManager(
    input: IRecommenderAppManagerInput,
  ): Promise<boolean>;

  /** Owner 取消指定用户的推广比例管理权限。 */
  deleteRecommenderAppManager(
    serviceAppid: string,
    managerPubkey: string,
  ): Promise<boolean>;

  /**
   * 将当前页面标记为支付回跳页。
   * @param scene 支付场景
   * @returns 标记后的 URL
   */
  markCurrentUrlAsPayReturn(scene?: PaymentGatewayScene): string;

  /**
   * 判断当前 URL 是否为支付回跳页。
   * @param scene 支付场景
   */
  isPayReturnUrl(scene?: PaymentGatewayScene): boolean;

  /**
   * 清理 URL 中支付回跳相关参数。
   */
  clearPayReturnUrlParams(): void;

  /**
   * 构建托管收银台 URL。
   * @param options 收银台参数
   * @returns 可直接跳转的支付 URL
   */
  buildHostedCheckoutUrl(options: {
    /**
     * 账号标识。
     */
    account: string;
    /**
     * 套餐编码。
     */
    packageCode: string;
    /**
     * 套餐名称。
     */
    packageName: string;
    /**
     * 金额（分）。
     */
    amountCents: number;
    /**
     * 支付完成后回跳地址。
     */
    returnUrl: string;
    /**
     * 透传字段。
     */
    attach?: string;
    /**
     * 商户订单号（不传则由服务端生成）。
     */
    outTradeNo?: string;
    /**
     * 自由定价套餐金额明细 key（可选）。
     */
    priceKey?: string;
    /**
     * 收银台展示标题。
     */
    title?: string;
  }): string;

  /**
   * 暂存待支付信息。
   */
  markPendingGatewayPayment(info: IPendingGatewayPayment): void;

  /**
   * 获取暂存的待支付信息。
   */
  getPendingGatewayPayment(): IPendingGatewayPayment | null;

  /**
   * 清除暂存的待支付信息。
   */
  clearPendingGatewayPayment(): void;
}