package com.jeesharp.business.modules.member.service;

import com.jeesharp.business.modules.member.entity.Member;
import com.jeesharp.business.modules.member.entity.MemberOauth;
import com.jeesharp.business.modules.member.vo.MemberOauthQueryVO;
import com.jeesharp.framework.mybatis.core.service.BaseInterface;

/**
 * 会员第三方 OAuth 绑定
 *
 * @author jeesharp
 * @version 2026-03-19
 */
public interface MemberOauthService extends BaseInterface<MemberOauth, MemberOauthQueryVO> {

    /**
     * 按平台 + 应用类型 + appId + openid 查询（多小程序维度）
     */
    MemberOauth getByPlatformAppTypeAppIdOpenid(String platform, String appType, String appId, String openid);

    /**
     * 按平台 + unionid 查询一条（用于微信等同开放平台下关联账号）
     */
    MemberOauth getFirstByPlatformAndUnionid(String platform, String unionid);

    /**
     * 微信小程序：写入/更新 {@code app_member_oauth} 绑定行
     *
     * @param memberId 会员ID
     * @param appId      请求头 X-App-Id，可为空串
     * @param openid     微信 openid
     * @param unionid    微信 unionid，可空
     */
    void upsertWechatMiniBinding(String memberId, String appId, String openid, String unionid);

    /**
     * 按会员ID + 小程序 appId 查询微信小程序 openid。
     * 优先命中指定 appId，未命中时兼容历史空 app_id 绑定。
     */
    String getWechatMiniOpenidByMemberIdAppId(String memberId, String appId);

    /**
     * 微信小程序登录：仅根据 {@code app_member_oauth} 解析已存在会员；不存在则返回 null。
     *
     * @param oauthAppIdKey 当前请求上下文应用标识（如 AppID）
     * @param openId        微信 mini openid
     * @param unionId       微信 unionid，可空
     * @return 已存在会员，或 null
     */
    Member resolveMemberForWechatMini(String oauthAppIdKey, String openId, String unionId);

    /**
     * JustAuth 授权源：仅根据 {@code app_member_oauth} 解析会员（先 unionid 再 openid）。
     *
     * @param justAuthSource {@link com.jeesharp.business.modules.member.constants.MobileAuthConstants} 中 JUSTAUTH_* 键
     * @param unionId        平台 unionId，可空
     * @param openId         平台 openId，可空（部分渠道可为空则无法写入绑定）
     * @param oauthAppId     应用维度 appId：请求头 X-App-Id 或与当前 JustAuth 渠道一致的 client-id；可空则按空串参与查询（并兼容历史空 app_id 行）
     * @return 会员或 null
     */
    Member resolveMemberForJustAuthSource(String justAuthSource, String unionId, String openId, String oauthAppId);

    /**
     * 登录成功后写入/更新当前渠道在 {@code app_member_oauth} 中的绑定（与 {@link #resolveMemberForJustAuthSource} 使用相同 source 映射）。
     *
     * @param memberId       会员ID
     * @param justAuthSource JUSTAUTH_* 键
     * @param unionId        unionId，可空
     * @param openId         openId，必填（无则跳过）
     * @param oauthAppId     写入 {@code app_id}；建议传 JustAuth 对应渠道的 client-id 或 X-App-Id
     */
    void upsertJustAuthBinding(String memberId, String justAuthSource, String unionId, String openId, String oauthAppId);
}
