مزامنة جهات اتصال الهاتف في FiveM: أنظمة جهات اتصال عبر الأجهزة

تحدي بيانات الهاتف في FiveM

بناء نظام هاتف لـ FiveM يتطلب أكثر بكثير من عرض واجهة مستخدم جميلة على شاشة اللاعب. التحدي الهندسي الحقيقي هو إدارة البيانات المستمرة عبر الجلسات: جهات الاتصال، محادثات الرسائل، سجلات المكالمات، الصور، وإعدادات التطبيقات كلها تحتاج إلى البقاء بعد إعادة تشغيل الخادم، تبديل الشخصيات، وبيئات الشخصيات المتعددة. تم تصميم Agency Phone من الألف إلى الياء مع سلامة البيانات كمبدأ أساسي. كل قطعة بيانات تمر عبر خط أنابيب موثوق من الخادم حيث يطلب العميل الإجراءات ويقوم الخادم بالتحقق، المعالجة، والحفظ قبل التأكيد للعميل. تكشف هذه المقالة كيف يتعامل Agency Phone مع مزامنة جهات الاتصال، تخزين الرسائل، مشاركة الصور، تسجيل المكالمات، والخصوصية حسب التصميم حتى يفهم المطورون ومالكو الخوادم البنية وراء المنتج.

هيكل تخزين جهات الاتصال

يتم تخزين جهات الاتصال في Agency Phone لكل شخصية، وليس لكل لاعب. هذا التمييز مهم لأن اللاعب قد يكون لديه ثلاث شخصيات على نفس الخادم، كل منها بدوائر اجتماعية مختلفة تمامًا. يستخدم جدول جهات الاتصال مفتاحًا مركبًا من رقم هاتف المالك ورقم هاتف جهة الاتصال، مع حقول إضافية لاسم العرض، رابط الصورة الرمزية، وعلم المفضلة. عندما يفتح اللاعب تطبيق جهات الاتصال، يرسل العميل طلبًا واحدًا إلى الخادم، الذي يستعلم قاعدة البيانات ويعيد قائمة جهات الاتصال كاملة دفعة واحدة. هذا يتجنب نمط الشلال حيث كل جهة اتصال تطلق استعلام قاعدة بيانات خاص بها، مما سيكون مدمرًا على خادم به لاعبين لديهم مئات جهات الاتصال.

-- How contacts are structured internally
-- Each contact belongs to a specific phone number (character)
local contactSchema = {
    owner_number = 'string',    -- the character's phone number
    contact_number = 'string',  -- the saved contact's number
    display_name = 'string',    -- custom name set by player
    avatar = 'string|nil',      -- optional avatar URL
    is_favorite = 'boolean',    -- pinned to top of list
    created_at = 'timestamp',   -- when contact was added
}

-- Server: fetch all contacts for a character
lib.callback.register('phone:contacts:getAll', function(source)
    local phoneNumber = GetPlayerPhoneNumber(source)
    if not phoneNumber then return {} end

    local contacts = MySQL.query.await([[
        SELECT contact_number, display_name, avatar, is_favorite
        FROM phone_contacts
        WHERE owner_number = ?
        ORDER BY is_favorite DESC, display_name ASC
    ]], { phoneNumber })

    return contacts or {}
end)

مزامنة جهات الاتصال في الوقت الحقيقي

عندما يضيف اللاعب أو يعدل أو يحذف جهة اتصال، يجب أن ينعكس التغيير فوراً على جهازه ويُحفظ في قاعدة البيانات. يستخدم Agency Phone نمط تحديث متفائل: يقوم العميل بتحديث حالته المحلية فوراً لتوفير رد فعل فوري، بينما يرسل التغيير إلى الخادم في نفس الوقت. إذا رفض الخادم التغيير بسبب فشل التحقق، يعود العميل إلى الحالة السابقة ويعرض خطأ. هذا يخلق تجربة مستخدم سريعة تبدو طبيعية مع الحفاظ على سلطة الخادم على البيانات. كما يبث الخادم التغييرات ذات الصلة إلى العملاء المتصلين الآخرين عند الضرورة، مثل عندما يحدث اللاعب اسمه في ملفه الشخصي الذي يظهر في قوائم جهات اتصال اللاعبين الآخرين.

-- Server: add a new contact with validation
lib.callback.register('phone:contacts:add', function(source, data)
    local phoneNumber = GetPlayerPhoneNumber(source)
    if not phoneNumber then return { success = false, error = 'NO_PHONE' } end

    -- Validate the contact number exists in the system
    local numberExists = MySQL.scalar.await(
        'SELECT COUNT(*) FROM phone_numbers WHERE number = ?',
        { data.contact_number }
    )
    if numberExists == 0 then
        return { success = false, error = 'NUMBER_NOT_FOUND' }
    end

    -- Prevent duplicate contacts
    local existing = MySQL.scalar.await(
        'SELECT COUNT(*) FROM phone_contacts WHERE owner_number = ? AND contact_number = ?',
        { phoneNumber, data.contact_number }
    )
    if existing > 0 then
        return { success = false, error = 'ALREADY_EXISTS' }
    end

    -- Insert the contact
    MySQL.insert.await([[
        INSERT INTO phone_contacts (owner_number, contact_number, display_name, avatar)
        VALUES (?, ?, ?, ?)
    ]], { phoneNumber, data.contact_number, data.display_name, data.avatar })

    return { success = true }
end)

تخزين الرسائل وتنظيم المحادثات

الرسائل هي أكثر ميزات نظام الهاتف استهلاكًا للبيانات. ينظم Agency Phone الرسائل في خيوط محادثة يتم تحديدها بواسطة زوج مرتب من أرقام الهواتف. هذا يعني أن المحادثة بين الرقم A والرقم B دائمًا ما ترتبط بنفس الخيط بغض النظر عن من بدأها. تُخزن الرسائل داخل الخيط بترتيب زمني مع تحديد المرسل، حالة القراءة، والمرفقات الاختيارية. يدعم نموذج الخيوط أيضًا الرسائل الجماعية حيث يشارك ثلاثة أرقام أو أكثر في محادثة مشتركة. تستخدم خيوط المجموعات معرفًا منفصلًا يتم إنشاؤه عند إنشاء المجموعة، ويحافظ كل عضو على مؤشر قراءة خاص به بحيث تكون أعداد الرسائل غير المقروءة دقيقة لكل مشارك.

-- Message thread resolution
-- Ensures A->B and B->A map to the same conversation
local function GetThreadId(number1, number2)
    -- Sort numbers to create a deterministic thread ID
    local sorted = { number1, number2 }
    table.sort(sorted)
    return sorted[1] .. ':' .. sorted[2]
end

-- Server: send a message
lib.callback.register('phone:messages:send', function(source, data)
    local senderNumber = GetPlayerPhoneNumber(source)
    if not senderNumber then return { success = false } end

    local threadId = GetThreadId(senderNumber, data.to)

    local messageId = MySQL.insert.await([[
        INSERT INTO phone_messages (thread_id, sender_number, recipient_number, content, attachment, sent_at)
        VALUES (?, ?, ?, ?, ?, NOW())
    ]], { threadId, senderNumber, data.to, data.content, data.attachment })

    -- Notify recipient if online
    local recipientSource = GetPlayerByPhoneNumber(data.to)
    if recipientSource then
        TriggerClientEvent('phone:messages:receive', recipientSource, {
            id = messageId,
            thread_id = threadId,
            sender = senderNumber,
            sender_name = GetContactName(data.to, senderNumber),
            content = data.content,
            attachment = data.attachment,
            sent_at = os.time()
        })
    end

    return { success = true, id = messageId }
end)

مشاركة الصور والتعامل مع الوسائط

تتطلب مشاركة الصور في هاتف FiveM نهجًا مختلفًا عن تطبيقات الويب التقليدية لأنك لا تستطيع الوصول مباشرة إلى نظام ملفات اللاعب. يتعامل Agency Phone مع الصور من خلال آليتين: لقطات شاشة داخل اللعبة تُلتقط باستخدام وظيفة لقطة الشاشة في GTA، وصور تعتمد على URL يلصقها اللاعبون من خدمات استضافة الصور الخارجية. تُلتقط لقطات الشاشة داخل اللعبة باستخدام واجهة برمجة التطبيقات الأصلية للقطات الشاشة، تُحول إلى عنوان URL للبيانات، وتُرفع إلى خلفية تخزين قابلة للتكوين. يتحقق الخادم من حدود حجم الملف ونوع المحتوى قبل حفظ URL. عند مشاركة الصور في الرسائل، يُخزن فقط مرجع URL في سجل الرسالة، مما يحافظ على جدول الرسائل خفيفًا. تعيش بيانات الصورة الفعلية في خلفية تخزين الوسائط، التي يمكن تكوينها لاستخدام القرص المحلي، تخزين متوافق مع S3، أو CDN صور خارجي حسب بنية مالك الخادم.

-- Server: handle photo upload from in-game camera
lib.callback.register('phone:photos:upload', function(source, imageData)
    local phoneNumber = GetPlayerPhoneNumber(source)
    if not phoneNumber then return { success = false } end

    -- Validate size (max 2MB base64)
    if #imageData > 2 * 1024 * 1024 * 1.37 then
        return { success = false, error = 'FILE_TOO_LARGE' }
    end

    -- Generate unique filename
    local filename = ('%s_%s.jpg'):format(phoneNumber, os.time())

    -- Store via configured backend (webhook, local, S3)
    local url = StorageBackend:upload(filename, imageData)
    if not url then
        return { success = false, error = 'UPLOAD_FAILED' }
    end

    -- Save photo reference in gallery
    MySQL.insert.await([[
        INSERT INTO phone_photos (owner_number, url, created_at)
        VALUES (?, ?, NOW())
    ]], { phoneNumber, url })

    return { success = true, url = url }
end)

سجلات المكالمات والتاريخ

تسجل سجلات المكالمات كل مكالمة واردة، صادرة، ومفقودة مع الطوابع الزمنية والمدة. عندما يبدأ اللاعب مكالمة، يتم إنشاء سجل مكالمة بحالة "الاتصال". إذا أجاب المستلم، تتغير الحالة إلى "نشط" ويتم تسجيل طابع زمني للبداية. عند انتهاء المكالمة، يتم حساب المدة ويتم إنهاء السجل. تحدث المكالمات الفائتة عندما لا يرد المستلم خلال فترة المهلة أو يرفض صراحة. يتم عرض سجل المكالمات في تبويب المكالمات الحديثة بالهاتف مع مؤشرات بصرية لاتجاه المكالمة وحالتها. يمكن للاعبين النقر على إدخال مكالمة فائتة للاتصال فوراً، أو الضغط المطول لإضافة الرقم إلى جهات الاتصال. يقوم الخادم بحذف سجلات المكالمات الأقدم من فترة الاحتفاظ القابلة للتكوين، الافتراضية 30 يومًا، لمنع نمو الجدول بلا حدود على الخوادم طويلة التشغيل.

-- Server: create and manage call records
local activeCalls = {}

function StartCallRecord(callerNumber, receiverNumber)
    local callId = MySQL.insert.await([[
        INSERT INTO phone_calls (caller_number, receiver_number, status, started_at)
        VALUES (?, ?, 'dialing', NOW())
    ]], { callerNumber, receiverNumber })

    activeCalls[callId] = {
        caller = callerNumber,
        receiver = receiverNumber,
        answeredAt = nil
    }
    return callId
end

function AnswerCall(callId)
    if not activeCalls[callId] then return end
    activeCalls[callId].answeredAt = os.time()
    MySQL.update.await(
        'UPDATE phone_calls SET status = ?, answered_at = NOW() WHERE id = ?',
        { 'active', callId }
    )
end

function EndCall(callId)
    local call = activeCalls[callId]
    if not call then return end

    local duration = call.answeredAt and (os.time() - call.answeredAt) or 0
    local status = call.answeredAt and 'completed' or 'missed'

    MySQL.update.await(
        'UPDATE phone_calls SET status = ?, duration = ?, ended_at = NOW() WHERE id = ?',
        { status, duration, callId }
    )
    activeCalls[callId] = nil
end

الخصوصية حسب التصميم

Agency Phone follows privacy-by-design principles throughout its architecture. Phone numbers are generated randomly and are not tied to any real-world identifier. Message content is stored in the database but is only accessible to the sender and recipient through validated server callbacks. There is no global message search that an admin could use to read private conversations without explicit database access. Contact lists are strictly per-character with no cross-character data leakage. When a character is deleted, all associated phone data including contacts, messages, call logs, and photos are cascade-deleted from the database, ensuring no orphaned personal data remains. The photo upload system strips EXIF metadata before storage to prevent unintentional location or device information leaks, though this is more of a best practice than a practical concern in a game environment.

الأداء على نطاق واسع

Agency Phone is tested and optimized for servers with 200 or more concurrent players. The key performance strategies include lazy loading message threads so only the most recent conversations are fetched on phone open, with older threads loaded on scroll. Contact lists are cached client-side after the initial fetch and only refreshed when a mutation occurs. Database queries use proper indexes on phone numbers and timestamps to ensure sub-millisecond lookups even on tables with millions of rows. The server maintains an in-memory map of online player phone numbers for instant recipient lookups without database hits. All NUI communication is batched where possible, so opening the messages app triggers one server request that returns threads with their latest message preview rather than making separate requests for each thread. These optimizations ensure the phone remains responsive even during peak server hours when dozens of players are simultaneously sending messages and making calls.