koishi-plugin-bind-bot 2.0.0

package/lib/export-utils.d.ts

@@ -0,0 +1,49 @@
+import { Session, Context } from 'koishi';
+import { LoggerService } from './utils/logger';
+import { MCIDBINDRepository } from './repositories/mcidbind.repository';
+export declare class GroupExporter {
+    private logger;
+    private ctx;
+    private mcidbindRepo;
+    constructor(ctx: Context, logger: LoggerService, mcidbindRepo: MCIDBINDRepository);
+    /**
+     * 获取群成员列表
+     */
+    private getGroupMembers;
+    /**
+     * 翻译群角色
+     */
+    private translateRole;
+    /**
+     * 获取所有绑定信息
+     */
+    private getAllBindings;
+    /**
+     * 格式化时间戳
+     */
+    private formatTimestamp;
+    /**
+     * 合并群成员信息和绑定信息
+     */
+    private mergeData;
+    /**
+     * 生成Excel文件
+     */
+    private generateExcelFile;
+    /**
+     * 导出群数据
+     */
+    exportGroupData(session: Session, groupId: string): Promise<Buffer>;
+    /**
+     * 获取导出文件名
+     */
+    getExportFileName(groupId: string): string;
+    /**
+     * 保存Excel文件到临时目录并返回文件路径
+     */
+    saveExcelFile(excelBuffer: Buffer, fileName: string): Promise<string>;
+    /**
+     * 清理过期的临时文件（可选）
+     */
+    cleanupOldFiles(maxAgeHours?: number): Promise<void>;
+}

package/lib/export-utils.js

@@ -0,0 +1,305 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GroupExporter = void 0;
+const XLSX = __importStar(require("xlsx"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+class GroupExporter {
+    logger;
+    ctx;
+    mcidbindRepo;
+    constructor(ctx, logger, mcidbindRepo) {
+        this.ctx = ctx;
+        this.logger = logger;
+        this.mcidbindRepo = mcidbindRepo;
+    }
+    /**
+     * 获取群成员列表
+     */
+    async getGroupMembers(session, groupId) {
+        try {
+            this.logger.debug('群数据导出', `开始获取群 ${groupId} 的成员列表`);
+            if (!session.bot.internal) {
+                throw new Error('Bot不支持获取群成员列表');
+            }
+            const memberList = await session.bot.internal.getGroupMemberList(groupId);
+            this.logger.debug('群数据导出', `获取到 ${memberList.length} 个群成员`);
+            return memberList.map(member => ({
+                qqId: member.user_id.toString(),
+                nickname: member.nickname || '',
+                card: member.card || '',
+                role: this.translateRole(member.role),
+                join_time: member.join_time || 0,
+                last_sent_time: member.last_sent_time || 0
+            }));
+        }
+        catch (error) {
+            this.logger.error('群数据导出', `获取群成员列表失败: ${error.message}`);
+            throw new Error(`无法获取群 ${groupId} 的成员列表: ${error.message}`);
+        }
+    }
+    /**
+     * 翻译群角色
+     */
+    translateRole(role) {
+        switch (role) {
+            case 'owner': return '群主';
+            case 'admin': return '管理员';
+            case 'member': return '成员';
+            default: return role || '未知';
+        }
+    }
+    /**
+     * 获取所有绑定信息
+     */
+    async getAllBindings() {
+        try {
+            this.logger.debug('群数据导出', '开始获取数据库绑定信息');
+            const bindings = await this.mcidbindRepo.findAll();
+            this.logger.debug('群数据导出', `获取到 ${bindings.length} 条绑定记录`);
+            return bindings;
+        }
+        catch (error) {
+            this.logger.error('群数据导出', `获取绑定信息失败: ${error.message}`);
+            throw new Error(`无法获取绑定信息: ${error.message}`);
+        }
+    }
+    /**
+     * 格式化时间戳
+     */
+    formatTimestamp(timestamp) {
+        if (!timestamp)
+            return '未知';
+        let date;
+        if (timestamp instanceof Date) {
+            date = timestamp;
+        }
+        else if (typeof timestamp === 'number') {
+            // 如果是秒级时间戳，转换为毫秒
+            date = new Date(timestamp < 10000000000 ? timestamp * 1000 : timestamp);
+        }
+        else {
+            return '未知';
+        }
+        return date.toLocaleString('zh-CN', {
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit'
+        });
+    }
+    /**
+     * 合并群成员信息和绑定信息
+     */
+    mergeData(members, bindings) {
+        this.logger.debug('群数据导出', '开始合并群成员和绑定信息');
+        // 创建绑定信息映射
+        const bindingMap = new Map();
+        bindings.forEach(binding => {
+            bindingMap.set(binding.qqId, binding);
+        });
+        return members.map(member => {
+            const binding = bindingMap.get(member.qqId);
+            // 判断绑定状态
+            let bindingStatus = '未绑定';
+            if (binding) {
+                const hasMc = binding.mcUsername && !binding.mcUsername.startsWith('_temp_');
+                const hasBuid = binding.buidUid;
+                if (hasMc && hasBuid) {
+                    bindingStatus = '完全绑定';
+                }
+                else if (hasMc) {
+                    bindingStatus = '仅MC绑定';
+                }
+                else if (hasBuid) {
+                    bindingStatus = '仅B站绑定';
+                }
+                else {
+                    bindingStatus = '未绑定';
+                }
+            }
+            return {
+                QQ号: member.qqId,
+                群昵称: member.card || member.nickname,
+                用户昵称: member.nickname,
+                角色: member.role,
+                加群时间: this.formatTimestamp(member.join_time),
+                最后发言: this.formatTimestamp(member.last_sent_time),
+                MC用户名: binding?.mcUsername && !binding.mcUsername.startsWith('_temp_') ? binding.mcUsername : '',
+                MC_UUID: binding?.mcUuid || '',
+                B站UID: binding?.buidUid || '',
+                B站用户名: binding?.buidUsername || '',
+                舰长等级: binding?.guardLevelText || '',
+                粉丝牌名称: binding?.medalName || '',
+                粉丝牌等级: binding?.medalLevel ? binding.medalLevel.toString() : '',
+                荣耀等级: binding?.wealthMedalLevel ? binding.wealthMedalLevel.toString() : '',
+                绑定状态: bindingStatus,
+                最后修改时间: this.formatTimestamp(binding?.lastModified)
+            };
+        });
+    }
+    /**
+     * 生成Excel文件
+     */
+    generateExcelFile(allData, groupId) {
+        this.logger.debug('群数据导出', '开始生成Excel文件');
+        // 分类数据
+        const boundData = allData.filter(row => row.绑定状态 !== '未绑定');
+        const unboundData = allData.filter(row => row.绑定状态 === '未绑定');
+        // 创建工作簿
+        const workbook = XLSX.utils.book_new();
+        // Sheet1: 所有成员
+        const allSheet = XLSX.utils.json_to_sheet(allData);
+        XLSX.utils.book_append_sheet(workbook, allSheet, '所有成员');
+        // Sheet2: 已绑定成员
+        const boundSheet = XLSX.utils.json_to_sheet(boundData);
+        XLSX.utils.book_append_sheet(workbook, boundSheet, '已绑定成员');
+        // Sheet3: 未绑定成员
+        const unboundSheet = XLSX.utils.json_to_sheet(unboundData);
+        XLSX.utils.book_append_sheet(workbook, unboundSheet, '未绑定成员');
+        // 设置列宽
+        const colWidths = [
+            { wch: 12 }, // QQ号
+            { wch: 20 }, // 群昵称
+            { wch: 15 }, // 用户昵称
+            { wch: 8 }, // 角色
+            { wch: 18 }, // 加群时间
+            { wch: 18 }, // 最后发言
+            { wch: 16 }, // MC用户名
+            { wch: 36 }, // MC_UUID
+            { wch: 12 }, // B站UID
+            { wch: 20 }, // B站用户名
+            { wch: 10 }, // 舰长等级
+            { wch: 12 }, // 粉丝牌名称
+            { wch: 10 }, // 粉丝牌等级
+            { wch: 8 }, // 荣耀等级
+            { wch: 12 }, // 绑定状态
+            { wch: 18 } // 最后修改时间
+        ];
+        // 应用列宽到所有sheet
+        allSheet['!cols'] = colWidths;
+        boundSheet['!cols'] = colWidths;
+        unboundSheet['!cols'] = colWidths;
+        // 生成Excel文件
+        const excelBuffer = XLSX.write(workbook, {
+            type: 'buffer',
+            bookType: 'xlsx',
+            compression: true
+        });
+        this.logger.debug('群数据导出', 'Excel文件生成完成');
+        return excelBuffer;
+    }
+    /**
+     * 导出群数据
+     */
+    async exportGroupData(session, groupId) {
+        try {
+            this.logger.info('群数据导出', `开始导出群 ${groupId} 的数据`);
+            // 并行获取群成员和绑定信息
+            const [members, bindings] = await Promise.all([
+                this.getGroupMembers(session, groupId),
+                this.getAllBindings()
+            ]);
+            // 合并数据
+            const mergedData = this.mergeData(members, bindings);
+            // 生成Excel文件
+            const excelBuffer = this.generateExcelFile(mergedData, groupId);
+            this.logger.info('群数据导出', `群 ${groupId} 数据导出完成，共 ${members.length} 个成员，其中 ${mergedData.filter(d => d.绑定状态 !== '未绑定').length} 个已绑定`);
+            return excelBuffer;
+        }
+        catch (error) {
+            this.logger.error('群数据导出', `导出群数据失败`, error);
+            throw error;
+        }
+    }
+    /**
+     * 获取导出文件名
+     */
+    getExportFileName(groupId) {
+        const now = new Date();
+        const dateStr = now.toISOString().slice(0, 19).replace(/[:\-T]/g, '');
+        return `群${groupId}_绑定数据_${dateStr}.xlsx`;
+    }
+    /**
+     * 保存Excel文件到临时目录并返回文件路径
+     */
+    async saveExcelFile(excelBuffer, fileName) {
+        try {
+            // 创建临时目录
+            const tempDir = path.join(process.cwd(), 'temp', 'exports');
+            if (!fs.existsSync(tempDir)) {
+                fs.mkdirSync(tempDir, { recursive: true });
+            }
+            // 生成文件路径
+            const filePath = path.join(tempDir, fileName);
+            // 写入文件
+            fs.writeFileSync(filePath, excelBuffer);
+            this.logger.debug('群数据导出', `Excel文件已保存到: ${filePath}`);
+            return filePath;
+        }
+        catch (error) {
+            this.logger.error('群数据导出', `保存Excel文件失败: ${error.message}`);
+            throw new Error(`保存文件失败: ${error.message}`);
+        }
+    }
+    /**
+     * 清理过期的临时文件（可选）
+     */
+    async cleanupOldFiles(maxAgeHours = 24) {
+        try {
+            const tempDir = path.join(process.cwd(), 'temp', 'exports');
+            if (!fs.existsSync(tempDir))
+                return;
+            const files = fs.readdirSync(tempDir);
+            const now = Date.now();
+            const maxAge = maxAgeHours * 60 * 60 * 1000;
+            for (const file of files) {
+                const filePath = path.join(tempDir, file);
+                const stats = fs.statSync(filePath);
+                if (now - stats.mtime.getTime() > maxAge) {
+                    fs.unlinkSync(filePath);
+                    this.logger.debug('群数据导出', `已清理过期文件: ${file}`);
+                }
+            }
+        }
+        catch (error) {
+            this.logger.warn('群数据导出', `清理临时文件失败: ${error.message}`);
+        }
+    }
+}
+exports.GroupExporter = GroupExporter;

package/lib/force-bind-utils.d.ts

@@ -0,0 +1,40 @@
+import { LoggerService } from './utils/logger';
+import type { ForceBindConfig, EnhancedZminfoUser } from './types';
+export declare class ForceBinder {
+    private logger;
+    private config;
+    private cookieString;
+    constructor(config: ForceBindConfig, logger: LoggerService);
+    /**
+     * 处理cookie字符串，支持完整cookie或单独SESSDATA
+     */
+    private processCookie;
+    /**
+     * 检查B站登录状态
+     */
+    private checkBilibiliLoginStatus;
+    /**
+     * 获取用户的粉丝勋章信息（使用B站API）
+     */
+    private getBilibiliMedals;
+    /**
+     * 获取用户的基本信息（使用ZMINFO API）
+     */
+    private getZminfoUserInfo;
+    /**
+     * 检查是否拥有目标粉丝牌
+     */
+    private checkTargetMedal;
+    /**
+     * 强制绑定用户，获取完整信息包括目标粉丝牌数据
+     */
+    forceBindUser(uid: string): Promise<EnhancedZminfoUser>;
+    /**
+     * 转换为标准的ZminfoUser格式（用于数据库存储）
+     */
+    convertToZminfoUser(enhancedUser: EnhancedZminfoUser): any;
+    /**
+     * 获取目标粉丝牌的详细信息（用于显示）
+     */
+    getTargetMedalDetails(enhancedUser: EnhancedZminfoUser): string;
+}

package/lib/force-bind-utils.js

@@ -0,0 +1,242 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForceBinder = void 0;
+const axios_1 = __importDefault(require("axios"));
+class ForceBinder {
+    logger;
+    config;
+    cookieString;
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger;
+        this.cookieString = this.processCookie(config.SESSDATA);
+    }
+    /**
+     * 处理cookie字符串，支持完整cookie或单独SESSDATA
+     */
+    processCookie(input) {
+        if (!input || input.trim() === '') {
+            throw new Error('Cookie配置不能为空');
+        }
+        const trimmedInput = input.trim();
+        // 如果输入包含多个cookie字段（包含分号），则认为是完整cookie
+        if (trimmedInput.includes(';')) {
+            this.logger.debug('强制绑定', '检测到完整cookie字符串');
+            return trimmedInput;
+        }
+        // 如果输入只是SESSDATA值（不包含"SESSDATA="前缀）
+        if (!trimmedInput.startsWith('SESSDATA=')) {
+            this.logger.debug('强制绑定', '检测到SESSDATA值，添加前缀');
+            return `SESSDATA=${trimmedInput}`;
+        }
+        // 如果输入已经是"SESSDATA=xxx"格式
+        this.logger.debug('强制绑定', '检测到SESSDATA格式');
+        return trimmedInput;
+    }
+    /**
+     * 检查B站登录状态
+     */
+    async checkBilibiliLoginStatus() {
+        try {
+            // 使用一个简单的API来检查登录状态
+            const response = await axios_1.default.get('https://api.bilibili.com/x/web-interface/nav', {
+                headers: {
+                    Cookie: this.cookieString,
+                    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36'
+                },
+                timeout: 5000
+            });
+            this.logger.debug('强制绑定', `登录状态检查返回: ${response.data.code}`);
+            // code为0表示登录成功
+            if (response.data.code === 0) {
+                this.logger.debug('强制绑定', 'B站登录状态正常');
+                return true;
+            }
+            else {
+                this.logger.warn('强制绑定', `B站登录状态异常: ${response.data.message || '未知错误'}`);
+                return false;
+            }
+        }
+        catch (error) {
+            this.logger.warn('强制绑定', `检查B站登录状态失败: ${error.message}`);
+            return false;
+        }
+    }
+    /**
+     * 获取用户的粉丝勋章信息（使用B站API）
+     */
+    async getBilibiliMedals(uid) {
+        this.logger.debug('强制绑定', `开始获取用户 ${uid} 的粉丝勋章`);
+        try {
+            const url = 'https://api.live.bilibili.com/xlive/web-ucenter/user/MedalWall';
+            this.logger.debug('强制绑定', `API请求: ${url}?target_id=${uid}`);
+            const response = await axios_1.default.get(url, {
+                params: {
+                    target_id: uid
+                },
+                headers: {
+                    Cookie: this.cookieString,
+                    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36'
+                },
+                timeout: 10000
+            });
+            this.logger.debug('强制绑定', `B站API返回状态码: ${response.status}`);
+            if (this.config.debugMode) {
+                this.logger.debug('强制绑定', `B站API返回数据: ${JSON.stringify(response.data, null, 2)}`);
+            }
+            // 检查登录状态
+            if (response.data.code !== 0) {
+                if (response.data.message && response.data.message.includes('未登录')) {
+                    this.logger.warn('强制绑定', 'B站API返回未登录错误，SESSDATA可能无效或已过期');
+                    throw new Error('SESSDATA无效或已过期，无法获取粉丝勋章信息');
+                }
+                this.logger.warn('强制绑定', `B站API返回错误: ${response.data.message || '未知错误'}`);
+                throw new Error(`B站API错误: ${response.data.message || '未知错误'}`);
+            }
+            return response.data;
+        }
+        catch (error) {
+            this.logger.error('强制绑定', `获取B站粉丝勋章失败`, error);
+            throw error;
+        }
+    }
+    /**
+     * 获取用户的基本信息（使用ZMINFO API）
+     */
+    async getZminfoUserInfo(uid) {
+        this.logger.debug('强制绑定', `开始获取用户 ${uid} 的ZMINFO信息`);
+        try {
+            const response = await axios_1.default.get(`${this.config.zminfoApiUrl}/api/user/${uid}`, {
+                timeout: 10000,
+                headers: {
+                    'User-Agent': 'Koishi-MCID-Bot/1.0'
+                }
+            });
+            if (response.data.success && response.data.data && response.data.data.user) {
+                this.logger.debug('强制绑定', `ZMINFO API 用户信息获取成功: ${response.data.data.user.username}`);
+                return response.data.data.user;
+            }
+            else {
+                this.logger.warn('强制绑定', `ZMINFO API 返回失败: ${response.data.message}`);
+                return null;
+            }
+        }
+        catch (error) {
+            this.logger.error('强制绑定', `获取ZMINFO用户信息失败`, error);
+            throw new Error(`无法获取用户信息: ${error.message}`);
+        }
+    }
+    /**
+     * 检查是否拥有目标粉丝牌
+     */
+    checkTargetMedal(medalList) {
+        // 查找目标UP主的粉丝牌
+        const targetMedal = medalList.find(item => item.medal_info.target_id === this.config.targetUpUid &&
+            item.medal_info.medal_name === this.config.targetMedalName);
+        if (targetMedal) {
+            this.logger.info('强制绑定', `找到目标粉丝牌: ${targetMedal.medal_info.medal_name} LV.${targetMedal.medal_info.level}`);
+            return {
+                found: true,
+                name: targetMedal.medal_info.medal_name,
+                level: targetMedal.medal_info.level,
+                guard_level: targetMedal.medal_info.guard_level,
+                wearing_status: targetMedal.medal_info.wearing_status
+            };
+        }
+        this.logger.debug('强制绑定', `未找到目标粉丝牌 ${this.config.targetMedalName}（UP主UID: ${this.config.targetUpUid}）`);
+        return { found: false };
+    }
+    /**
+     * 强制绑定用户，获取完整信息包括目标粉丝牌数据
+     */
+    async forceBindUser(uid) {
+        this.logger.info('强制绑定', `开始强制绑定用户 ${uid}`);
+        try {
+            // 首先检查B站登录状态
+            const isLoggedIn = await this.checkBilibiliLoginStatus();
+            if (!isLoggedIn) {
+                throw new Error('B站登录状态异常，无法进行绑定，请检查Cookie配置');
+            }
+            this.logger.debug('强制绑定', 'B站登录状态正常，开始通过B站API获取用户信息');
+            // 强制绑定模式仅使用B站API，不再尝试ZMINFO（避免404错误）
+            const medalData = await this.getBilibiliMedals(uid);
+            // 验证B站API返回结果
+            if (medalData.code !== 0 || !medalData.data) {
+                const errorMsg = medalData.message || 'B站API未返回有效数据';
+                this.logger.error('强制绑定', `获取B站用户信息失败: ${errorMsg}`);
+                throw new Error(`无法获取用户 ${uid} 的信息: ${errorMsg}`);
+            }
+            // 从B站API构建用户信息
+            const userInfo = {
+                uid: uid,
+                username: medalData.data.name || `B站用户${uid}`,
+                avatar_url: medalData.data.icon || '',
+                guard_level: 0,
+                guard_level_text: '',
+                max_guard_level: 0,
+                max_guard_level_text: '',
+                medal: null,
+                wealthMedalLevel: 0,
+                last_active_time: new Date().toISOString()
+            };
+            this.logger.debug('强制绑定', `成功从B站API获取用户信息: ${userInfo.username}`);
+            // 处理粉丝勋章信息
+            let targetMedalInfo = { found: false };
+            let enhancedUserInfo = {
+                ...userInfo,
+                targetMedal: targetMedalInfo
+            };
+            // 检查目标粉丝牌
+            if (medalData.data && medalData.data.list) {
+                // 检查目标粉丝牌
+                targetMedalInfo = this.checkTargetMedal(medalData.data.list);
+                enhancedUserInfo.targetMedal = targetMedalInfo;
+                this.logger.debug('强制绑定', `已检查目标粉丝牌，找到: ${targetMedalInfo.found}`);
+            }
+            else {
+                this.logger.warn('强制绑定', `B站API未返回粉丝勋章列表数据`);
+            }
+            this.logger.info('强制绑定', `强制绑定完成: 用户=${enhancedUserInfo.username}(${uid}), 目标粉丝牌=${targetMedalInfo.found ? '已找到' : '未找到'}`);
+            return enhancedUserInfo;
+        }
+        catch (error) {
+            this.logger.error('强制绑定', `强制绑定过程出错`, error);
+            throw error; // 直接重抛原始错误，不添加前缀
+        }
+    }
+    /**
+     * 转换为标准的ZminfoUser格式（用于数据库存储）
+     */
+    convertToZminfoUser(enhancedUser) {
+        const { targetMedal, ...standardUser } = enhancedUser;
+        return standardUser;
+    }
+    /**
+     * 获取目标粉丝牌的详细信息（用于显示）
+     */
+    getTargetMedalDetails(enhancedUser) {
+        // 检查是否有目标粉丝牌信息（即是否尝试了B站API调用）
+        if (!enhancedUser.targetMedal) {
+            return `ℹ️ 未检查粉丝牌信息（B站登录状态异常，请检查SESSDATA配置）`;
+        }
+        if (!enhancedUser.targetMedal.found) {
+            return `未找到目标粉丝牌"${this.config.targetMedalName}"（UP主UID: ${this.config.targetUpUid}）`;
+        }
+        const medal = enhancedUser.targetMedal;
+        let details = `🎯 目标粉丝牌: ${medal.name} LV.${medal.level}`;
+        if (medal.guard_level && medal.guard_level > 0) {
+            const guardText = medal.guard_level === 1 ? '总督' :
+                medal.guard_level === 2 ? '提督' :
+                    medal.guard_level === 3 ? '舰长' : '未知';
+            details += ` (${guardText})`;
+        }
+        if (medal.wearing_status === 1) {
+            details += ' 【已佩戴】';
+        }
+        return details;
+    }
+}
+exports.ForceBinder = ForceBinder;