zhijiayun-pharmacy/zhijiayun-user/src/main/java/com/xuekairui/user/service/ExternalUserSyncService.java

package com.xuekairui.user.service;

import lombok.Data;

import java.util.List;
import java.util.Map;

/**
 * 外部用户系统（小程序后台）同步接口
 * <p>
 * 用于与外部小程序后台系统进行用户数据同步。
 * 默认提供基于 HTTP 的实现（{@link com.xuekairui.user.service.impl.ExternalUserSyncServiceImpl}），
 * 后续可替换为 RPC、MQ 等方式。
 * <p>
 * 设计原则：
 * <ul>
 *   <li>所有方法应具备容错能力，外部系统不可用时不应阻塞本地登录流程</li>
 *   <li>返回值使用 Optional 语义（null 表示不存在或查询失败）</li>
 * </ul>
 *
 * @author ProPrice Team
 * @since 2026-07-06
 */
public interface ExternalUserSyncService {

    /**
     * 检查用户是否存在于外部系统
     *
     * @param unionId 微信 UnionID
     * @return true=存在, false=不存在或外部系统不可用
     */
    boolean userExists(String unionId);

    /**
     * 在外部系统注册新用户
     *
     * @param userInfo 用户信息
     * @return 外部系统用户ID，失败返回 null
     */
    String registerUser(ExternalUserInfo userInfo);

    /**
     * 从外部系统拉取用户证书数据
     *
     * @param unionId 微信 UnionID
     * @return 证书数据列表，无证书或失败返回空列表
     */
    List<CertificateData> getCertificates(String unionId);

    /**
     * 外部系统用户信息
     */
    @Data
    class ExternalUserInfo {
        /** 微信 UnionID */
        private String unionId;
        /** 小程序 OpenID */
        private String miniProgramOpenId;
        /** 手机号 */
        private String phone;
        /** 昵称 */
        private String nickname;
        /** 头像 */
        private String avatar;
    }

    /**
     * 外部系统证书数据
     */
    @Data
    class CertificateData {
        /** 证书类型：BUSINESS_LICENSE / PHARMACY_LICENSE / MEDICAL_DEVICE_FILING */
        private String type;
        /** 外部系统记录ID */
        private String externalId;
        /** 证书字段数据（key 为字段名，value 为字段值） */
        private Map<String, Object> data;
    }
}