t-comm/lib/bump-service/types.d.ts

专业、稳定、纯粹的工具库

/**
 * bump-service —— 碰一碰业务编排层类型定义
 *
 * 与 bluetooth-bump（纯蓝牙层）配合使用：
 *   bluetooth-bump 负责：蓝牙广播/扫描/RSSI 判定/去重
 *   bump-service   负责：状态机/API 调用/缓存/重试/事件派发
 */
/** 碰一碰阶段 */
export declare enum BumpPhase {
    /** 空闲 */
    Idle = "idle",
    /** 正在启动（调 BumpStart 拿 tempId） */
    Starting = "starting",
    /** 扫描中（蓝牙已启动，等待用户碰） */
    Scanning = "scanning",
    /** 上报中（正在调 BumpReport） */
    Reporting = "reporting",
    /** 已匹配成功 */
    Matched = "matched",
    /** 失败（蓝牙/网络硬错误） */
    Failed = "failed"
}
/** 后台撮合状态（BumpReport 返回） */
export declare enum BumpMatchStatus {
    Unknown = 0,
    Waiting = 1,
    Matched = 2,
    Loser = 3
}
/** BumpStart 请求参数 */
export interface BumpStartReq {
    act_id?: string;
    [key: string]: any;
}
/** BumpStart 响应 */
export interface BumpStartRsp {
    temp_id?: string;
    tempId?: string;
    expire_at?: number;
    expireAt?: number;
    [key: string]: any;
}
/** BumpReport 请求参数 */
export interface BumpReportReq {
    act_id?: string;
    my_temp_id: string;
    peer_temp_id: string;
    rssi?: number;
    ts?: number;
    [key: string]: any;
}
/** BumpReport 响应 */
export interface BumpReportRsp {
    status?: number;
    match_id?: string;
    matchId?: string;
    err_msg?: string;
    [key: string]: any;
}
/** BumpReward 请求参数 */
export interface BumpRewardReq {
    act_id?: string;
    match_id: string;
    [key: string]: any;
}
/** BumpReward 响应 */
export interface BumpRewardRsp {
    egg_result_list?: any[];
    reward_type?: string;
    reward_amount?: number;
    [key: string]: any;
}
/** GetPetByTempId 请求参数 */
export interface GetPeerByTempIdReq {
    temp_id: string;
    [key: string]: any;
}
/** GetPetByTempId 响应 */
export interface GetPeerByTempIdRsp {
    user_nick?: string;
    pet_id?: string;
    pet?: {
        nick?: string;
        [key: string]: any;
    };
    user_head?: string;
    [key: string]: any;
}
/** 附近设备缓存项 */
export interface NearbyPeer {
    /** 对端 tempId（BLE payload 解析得到） */
    peerTempId: string;
    /** 对端设备 ID（BLE 物理层稳定标识） */
    deviceId: string;
    /** 最后发现时间戳 */
    lastSeenAt: number;
    /** 首次发现时间戳 */
    firstSeenAt: number;
    /** 信号强度 */
    rssi: number;
    /** 对端用户昵称（通过 getPeerByTempId 获取） */
    nick?: string;
    /** 对端头像 */
    userHead?: string;
    /** 对端 petId（用于去重） */
    petId?: string;
}
/** BumpService 配置选项 */
export interface BumpServiceOptions {
    /** API 调用适配器（必传，由业务方注入具体的 HTTP 实现） */
    api: BumpApiAdapter;
    /** 事件总线适配器（可选，用于派发/订阅事件） */
    eventBus?: BumpEventBus;
    /** 本地存储适配器（可选，用于缓存持久化） */
    storage?: BumpStorage;
    /** 日志适配器（可选） */
    logger?: BumpLogger;
    /** 活动 ID（可选，每次 start 时也可传入） */
    actId?: string;
    /** tempId 刷新间隔（毫秒），默认 150000（2.5 分钟，3 分钟过期前刷新） */
    tempIdRefreshMs?: number;
    /** 附近设备缓存 TTL（毫秒），默认 30 分钟 */
    peerCacheTtlMs?: number;
}
/** BumpService 启动选项 */
export interface BumpStartOptions {
    /** 活动 ID（覆盖构造时的 actId） */
    actId?: string;
    /** 额外传给 BumpStart 接口的字段 */
    extra?: Record<string, any>;
}
/** bumpPeer 的返回结果 */
export interface BumpPeerResult {
    success: boolean;
    /** 匹配成功时的奖励信息 */
    reward?: BumpRewardRsp;
    /** 匹配 ID */
    matchId?: string;
    /** 失败时的错误文案 */
    error?: string;
    /** 后台错误码 */
    ret?: number;
    /** 正在等待对方上报 */
    waiting?: boolean;
}
/**
 * API 适配器 —— 由业务方实现，注入到 BumpService
 *
 * 这是唯一与后端交互的接口，只要后端提供这 4 个接口，
 * 任何业务都可以复用 BumpService。
 */
export interface BumpApiAdapter {
    /** 发起碰一碰，获取 tempId */
    bumpStart(req: BumpStartReq): Promise<BumpStartRsp>;
    /** 上报撮合 */
    bumpReport(req: BumpReportReq): Promise<BumpReportRsp>;
    /** 领取奖励 */
    bumpReward(req: BumpRewardReq): Promise<BumpRewardRsp>;
    /** 通过 tempId 获取对端信息 */
    getPeerByTempId(req: GetPeerByTempIdReq): Promise<GetPeerByTempIdRsp>;
}
/** 事件总线适配器 */
export interface BumpEventBus {
    emit(event: string, data?: any): void;
    on(event: string, handler: (...args: any[]) => void): void;
    off(event: string, handler: (...args: any[]) => void): void;
}
/** 本地存储适配器 */
export interface BumpStorage {
    get(key: string): string | null;
    set(key: string, value: string): void;
    remove(key: string): void;
}
/** 日志适配器 */
export interface BumpLogger {
    info(msg: string, ...args: any[]): void;
    warn(msg: string, ...args: any[]): void;
    error(msg: string, ...args: any[]): void;
}
/** BumpService 派发的事件名 */
export declare const BumpEvent: {
    /** 阶段变化 */
    readonly PhaseChanged: "bump:phase-changed";
    /** 发现附近设备 */
    readonly PeerFound: "bump:peer-found";
    /** 设备离开 */
    readonly PeerLost: "bump:peer-lost";
    /** 碰蛋成功（含奖励） */
    readonly Matched: "bump:matched";
    /** 软失败（可继续选下一只） */
    readonly SoftFail: "bump:soft-fail";
    /** 硬失败（会话中断） */
    readonly Failed: "bump:failed";
    /** tempId 已刷新 */
    readonly TempIdRefreshed: "bump:tempid-refreshed";
};