رصيد HyoNova والإيداعات المباشرة

يحتاج الشحن إلى ربط إيداع Binance المباشر لدى HyoNova؛ ولا يمكن سحب الرصيد أو تحويله.

رصيد HyoNova جزء من فوترة المنصة: أموال شركة يحتفظ بها HyoNova. لا يلمس مالية الشركة (المخطط company) أبداً، ولا يختلط بالسعات (credit_lots وcredit_operations) التي تبقى دفتر وحدات الخدمة.

الدفتر (migration 068)#

ثوابت تفرضها قاعدة البيانات: العمليات والقيود للإضافة فقط (Trigger وسحب صلاحيات UPDATE/DELETE)؛ لا يقل رصيد العميل عن صفر (CHECK)؛ لا يتغير الرصيد إلا داخل Trigger القيد (أي UPDATE … balance_micros مباشر مرفوض)؛ كل عملية متوازنة وتحدد مبلغ العميل (Trigger مؤجل)؛ الكتابة من مستوى المنصة فقط؛ حركات المشغّل تحمل المنفّذ والسبب؛ الإيداع يموّل عملية واحدة كحد أقصى، والدفعة لها عملية واحدة، والاسترداد يعود مرة واحدة (فهارس فريدة). وأمان الصفوف يحصر كل شركة في صفوفها.

packages/database/billing/balance.ts (postJournal) هو الكاتب الوحيد. يقفل صف حساب العميل، ويعيد العملية السابقة عند تكرار المفتاح (ويرفض المفتاح نفسه لعملية مختلفة)، ويرفض السحب الزائد قبل الكتابة، ثم يُدخل العملية وقيديها.

أنواع العمليات: CRYPTO_TOPUP وLATE_CRYPTO_TOPUP وMANUAL_DEPOSIT_ASSIGNMENT وINVOICE_PAYMENT وREFUND_CREDIT وOPERATOR_CREDIT وOPERATOR_DEBIT.

الدقة#

تُحسب قيمة المحفظة بـmicros: الدولار = 1,000,000. والأسعار بالسنت (= 10,000 micros). لـUSDT ست خانات عشرية، فتتطابق الوحدات الذرية مع micros وفق السياسة المعلنة USDT_USD_PARITY (1:1) المحفوظة مع كل عملية مع الأصل والشبكة والمبلغ الذري والوقت. كل الحساب بـbigint؛ وتُقرأ مبالغ المزوّد من نصوصها العشرية (parseAtomic يرفض الإشارات والأسس والخانات الزائدة عن دقة الأصل). ويسدد الرصيد الفواتير بالسنت الكامل فتبقى كسور السنت في الرصيد.

الإيراد#

الشحن التزام. فقط التخصيص لفاتورة ينشئ سجل دفعة (بطريقة رصيد HyoNova)، وهو ما تحسبه مؤشرات الإيراد. شحن 100$ ثم فاتورة 20$ يعني 20$ إيراداً و80$ التزاماً.

طبقة التخصيص#

balance-payments.ts ← applyBalanceToInvoice يكتب في معاملة المستدعي: صف الدفعة، وعملية INVOICE_PAYMENT، وapplyInvoicePayment (مع السماح بالجزئي)، والخط الزمني والإشعار، وعند السداد الكامل إكمال الـcheckout وactivateFromInvoice أو grantPurchase. وpayWithBalance يحدد ما يُشترى بالمحلل نفسه الذي يستخدمه الـcheckout (resolveCheckoutTarget)، ويصدر الفاتورة الأصلية للمشتريات الجديدة، ويدفع full (الكل أو لا شيء) أو partial (بموافقة صريحة؛ واختيارياً نية دفع رقمية بالباقي بالضبط). وrenewFromBalance يسدد فواتير التجديد فقط إذا غطّاها الرصيد. واسترداد دفعات الرصيد يعود عبر REFUND_CREDIT.

عقد مزوّدي الإيداع المباشر#

المزوّد الذي يعلن القدرة direct_deposit ينفّذ دالتين اختياريتين في المحوّل (packages/payments/core/provider.ts):

• depositTarget() — الأصل والشبكة واسمها والعنوان والـTag وخانات الأصل والمهلة (≤ 15 دقيقة) وأيام الحجر وحدود الشحن وتواتر الاستعلام وفاصل فحص الحساب؛ من الإعدادات فقط.
• listDeposits({ startTime, endTime, offset, limit }) — سجل إيداعات الحساب مصنّفاً pending | confirming | final | rejected والمبالغ بنصوص المزوّد العشرية.

تعيد health() فحوصاً منظّمة checks. ويمكن للـmanifest أن يضبط enableRequiresHealthyTest: عند التفعيل يُجرى الاختبار على الإعداد المحفوظ ويُرفض أي نتيجة غير «متصل». وأُضيف تشخيصان: permission_unsafe وconfiguration_mismatch.

محوّل Binance#

packages/payments/providers/binance-deposit يستدعي GET /api/v3/time و/sapi/v1/account/apiRestrictions و/sapi/v1/capital/config/getall و/sapi/v1/capital/deposit/address و/sapi/v1/capital/deposit/hisrec على api.binance.com فقط، موقّعة بـHMAC-SHA256 مع recvWindow قدره 10 ثوانٍ، ويقيس فرق وقت الخادم ويعيد المزامنة عند الخطأ -1021. لا تعيد طبقة HTTP محاولة حدود الطلبات (429/418)، ويُحفظ Retry-After لتراجع النظام. حالة Binance رقم 1 نهائية؛ و0 و6 و8 غير نهائية؛ و2 و7 مرفوضة.

نوايا الدفع والبصمات (migration 069)#

يحفظ crypto_payment_intents الغرض (wallet_topup وinvoice_payment وpurchase_payment) والهدف والمبلغين الذريين الأساسي والمتوقع وقيمة المحفظة المطلوبة والحالة والمبالغ المستلمة/المضافة/المطبّقة، وexpires_at (قيد CHECK: 15 دقيقة كحد أقصى من الإنشاء) وgrace_until (+10 دقائق لتأخر الـAPI) وquarantine_until.

البصمة من 1 إلى 9999 وحدة ذرية تُضاف إلى الأساس (الأساس المحسوب من السنتات ينتهي دائماً بأربعة أصفار). في crypto_fingerprints صف لكل (نسخة، أصل، شبكة، عنوان، بصمة): الحجز يُدرج أو يستولي فقط على خانة انتهى reserved_until لها — والمفتاح الأساسي هو الضمان. إن لم تبقَ خانة حرة يُرفض الإنشاء (CRYPTO_CAPACITY) ويُرفع تنبيه.

المزامنة والمطابقة والإنهاء#

يستأجر النظام (deposits.ts ← directDepositWork في كل دورة) كل نسخة، ويعيد التحقق من الحساب دورياً، ويقرأ السجل من cursor − 30 دقيقة (دون تجاوز إيداع غير نهائي) بصفحات من 1000. الأخطاء تضبط تراجعاً (Retry-After لحدود الطلبات، وتراجعاً أُسياً لأخطاء 5xx، و5 دقائق لبيانات الاعتماد) وترفع تنبيهات عند التكرار. والسجلات المحسومة تُعدّ مرئية فقط.

processDeposit (معاملة واحدة بقفل الصف وUNIQUE(provider_instance_id, external_deposit_id)): فحص الهدف ← قراءة المبلغ ← المرشحون بالبصمة الذين غطّى حجزهم وقت الإيداع ← واحد، أو لا أحد (غير مطابق)، أو أكثر (مراجعة) ← فحص المعاملة المكررة ← غير نهائي: يُعلَّم مرصوداً ← نهائي: CRYPTO_TOPUP (أو LATE_CRYPTO_TOPUP بعد grace_until أو بعد الإلغاء)، ثم لدفعة فاتورة في وقتها يُطبَّق floor(المضاف) − المطبّق سنتاً حتى المستحق.

ملخص عدم التكرار#

مفتاح العملية لكل مؤسسة · عملية واحدة لكل إيداع/دفعة/استرداد · الإيداع فريد بمعرّف المزوّد · مفتاح النية لكل مؤسسة (topup:<key> وcheckout:<id>) · المفتاح الأساسي لخانة البصمة · مفتاح التخصيص invoice-payment:<source key> · إشعارات بلا تكرار لكل حدث.

إضافة مزوّد إيداع مباشر آخر#

اكتب وحدة بالقدرة direct_deposit مع depositTarget وlistDeposits وhealth يتحقق من القراءة فقط ومن العنوان، واضبط enableRequiresHealthyTest، وسجّلها في providers/index.ts وأضف نسخة معطّلة. لا تحتاج النواة ولا المخطط ولا الشاشات أي تغيير؛ ودعم الأصل هو سياسة التحويل في wallet-money.ts.

الحالة#