📋 توثيق تقني شامل 📋 Full Technical Documentation

النظام المحاسبي
دليل المطور الشامل Accounting System
Developer Reference

توثيق كامل لهيكل الملفات وقاعدة البيانات والجداول المحاسبية للنظام المالي Complete documentation for file structure, database schema, and accounting tables of the financial system

9جداول قاعدة البياناتDB Tables
12ملف APIAPI Files
40+صفحة في المشروعPages
7حسابات محاسبية أساسيةCore Accounts
⚡
خريطة التعديل السريع
Quick Edit Map
أين تعدّل حسب نوع الطلب؟
Where to edit based on request type
نموذج القبضReceipt Form
  • admin.php — الواجهة — UI
  • assets/js/app.js — المنطق — Logic
  • api/income.php — الحفظ — Save
  • pages/receipts/receipt-income.php — الطباعة — Print
نموذج الصرفExpense Form
  • admin.php
  • assets/js/app.js
  • api/expense.php
  • pages/receipts/receipt-expense.php
  • pages/receipts/receipt-cheque.php
نموذج الإيداعDeposit Form
  • admin.php
  • assets/js/app.js
  • api/deposit.php
  • pages/receipts/receipt-deposit-entry.php
السلفLoans
  • pages/loans/loans-management.php
  • assets/js/app.js
  • api/loan-accounting.php
  • api/loans.php
  • pages/loans/loan-reports/*
التقاريرReports
  • assets/js/app.js
  • api/reports.php
  • pages/reports/*
المستخدمين والصلاحياتUsers & Permissions
  • pages/admin/admin-panel.php
  • assets/js/users.js
  • api/auth.php
الألوان والثيمTheme & Colors
  • assets/js/theme.js
  • assets/js/login.js
  • assets/css/styles.css
قاعدة البياناتDatabase
  • database.sql
  • migrations/*
📁
هيكل الملفات
File Structure
وظيفة كل ملف في المشروع
Role of every file in the project
الملفFileالوظيفةPurpose
admin.phpالصفحة الرئيسية — النماذج والتقارير داخل التبويباتMain page — forms and reports inside tabs
index.phpتحويل تلقائي إلى شاشة تسجيل الدخولAuto-redirect to login screen
login.phpواجهة تسجيل الدخول + عرض اللوجو والملاحظاتLogin interface + logo and screen notes display
database.sql قاعدة البيانات + الجداول Database schema + tables + seed data
DOCUMENTATION.mdتوثيق سابق للمشروعPrevious project documentation
الملفFileالوظيفةPurpose
api/auth.phpتسجيل الدخول / الخروج / الجلسة / إدارة المستخدمينLogin / logout / session / user management & password
api/income.phpحفظ عمليات القبض وربطها بقيود اليوميةSave income transactions and link to journal entries
api/deposit.phpحفظ عمليات الإيداع وربطها بقيود اليوميةSave deposit operations and link to journal entries
api/expense.phpحفظ عمليات الصرف وربطها بقيود اليوميةSave expense operations and link to journal entries
api/loan-accounting.phpالمعالجة المحاسبية للسلف (منح / سداد / تعديل / إلغاء)Loan accounting processing (grant / repay / adjust / cancel)
api/loans.phpCRUD بيانات السلف التفصيلية وأقساطهاCRUD for detailed loan data and installments
api/receipts.phpحفظ وتحديث وصل المقبوضاتSave and update receipt vouchers
api/payments.phpحفظ وتحديث سندات الصرف والإيداعSave and update expense and deposit vouchers
api/reports.phpAPIs التقارير: دفتر اليومية، كشف البنك، ميزان المراجعةReport APIs: journal book, bank statement, trial balance, loans
api/state-read.phpقراءة حالة النظام من SQL وإرجاعها للواجهةRead system state from SQL and return to UI uniformly
api/state-sync.phpمزامنة الحالة القديمة إلى SQL (انتقالي)Sync legacy state to SQL (transitional)
api/storage.phpتخزين إعدادات عامة بمفتاح/قيمةStore general settings as key/value pairs
assets/js/
الملفFileالوظيفةPurpose
app.jsأكبر ملف منطق — النماذج، الجداول، APIs، الطباعة، التقارير، السلفCore logic file — forms, tables, API calls, printing, reports, loans
login.jsمنطق صفحة تسجيل الدخول + ألوان الواجهةLogin page logic + UI color application
users.jsتحميل المستخدم الحالي + إدارة قائمة المستخدمين + auth APILoad current user + manage user list + auth API calls
idle-timeout.jsتسجيل خروج تلقائي + Loader + تحسينات الجداول والتصديرAuto logout + loader + table improvements & export
theme.jsتطبيق وتخزين الثيم المختارApply and store the selected theme
employee.jsمنطق بوابة الموظف — عرض سلفه وتفاصيلهEmployee portal logic — display loans and details
general-ledger-sql.jsمنطق صفحات الأستاذ العام على بيانات SQLGeneral ledger pages logic built on SQL data
assets/css/
الملفFileالوظيفةPurpose
styles.cssملف التنسيق الرئيسي — ألوان، جداول، أزرار، طباعة، responsiveMain stylesheet — colors, tables, buttons, print, responsive
pages/receipts/
الملفFileالوظيفةPurpose
receipt-income.phpطباعة إيصال القبضPrint income receipt
receipt-expense.phpطباعة سند الصرفPrint expense voucher
receipt-cheque.phpطباعة الشيكPrint cheque
receipt-deposit-entry.phpطباعة مستند قيد الإيداعPrint deposit entry document
receipt-template.phpقالب عام / معاينة لقوالب الطباعةGeneric template / print preview
pages/loans/
الملفFileالوظيفةPurpose
loans-management.phpإدارة السلف — إضافة / تعديل / حذف / سدادLoan management — add / edit / delete / repay
loans-reports.phpصفحة تقارير السلفLoan reports page
loan-employee-record.phpسجل تفصيلي لموظف معيّن في السلفDetailed loan record for a specific employee
loan-schedule-details.phpتفاصيل جدول الأقساط لسلفة محددةInstallment schedule details for a specific loan
loan-reports/index.phpDashboard السلف — المؤشرات والملخصاتLoans dashboard — KPIs and summaries
loan-reports/by-employee.phpتقرير السلف للموظفينLoans report by employee
loan-reports/by-department.phpتقرير السلف حسب الأقسامLoans report by department
loan-reports/upcoming-installments.phpتقرير الأقساط القادمةUpcoming installments report
loan-reports/aging-report.phpتقرير أعمار السلف والتأخيرLoan aging & overdue report
pages/reports/
الملفFileالوظيفةPurpose
reports-trial-balance.phpميزان المراجعةTrial balance
reports-balance-sheet.phpالميزانية العموميةBalance sheet
reports-income-statement.phpقائمة الدخلIncome statement
reports-account-movements.phpحركة الحساباتAccount movements
reports-journal.phpدفتر اليوميةJournal book
reports-bank-statement.phpكشف حساب البنكBank statement
reports-income-log.phpسجل المقبوضاتReceipts log
reports-expense-log.phpسجل المصروفاتExpenses log
reports-expense-employees.phpسجل مصروفات الموظفينEmployee expenses log
reports-deposit-log.phpسجل الإيداعاتDeposits log
reports-loans-log.phpسجل السلفLoans log
pages/general-ledger/
الملفFileالوظيفةPurpose
index.phpبوابة الأستاذ العام — قائمة الحساباتGeneral ledger gateway — chart of accounts
cashbox.phpحساب الصندوقCash box account
bank-ahli.phpحساب البنك الأهليAhli Bank account
loans.phpحساب السلفLoans account
monitoring.phpحساب مساهمة مراقباتMonitoring contribution account
rewards.phpحساب المكافآتRewards account
interest.phpحساب إيرادات الفوائدInterest revenue account
trusts.phpحساب الأماناتTrusts / deposits account
pages/admin/
الملفFileالوظيفةPurpose
admin-panel.phpلوحة الأدمن — المستخدمين، الإعدادات، التدقيق، تخصيص الواجهةAdmin panel — users, settings, audit, UI customization
admin-profile.phpالملف الشخصي + تغيير كلمة المرورUser profile + change password
transactions.phpصفحة "معاملاتي" المستقلةStandalone "My Transactions" page
config/
الملفFileالوظيفةPurpose
database.phpإعدادات الاتصال بقاعدة البياناتDatabase connection settings (host / user / pass / db)
db.phpدوال الاتصال (PDO) المعتمدة من كل ملفات APIPDO connection functions used by all API files
migrations/
الملفFileالوظيفةPurpose
2026-04-13-add-is-adjustment.sqlترقية تضيف حقل is_adjustment لتمييز قيود التسوياتMigration adding is_adjustment field to distinguish adjustment entries
🗄️
جداول قاعدة البيانات
Database Tables
شرح كل جدول وحقوله التفصيلية
Detailed breakdown of each table and its fields
users
مستخدمو النظام
System users
إدارةAdmin
idBIGINT PKالرقم الداخليInternal ID
employee_noVARCHAR(50)الرقم الوظيفي — فريدEmployee number — unique
usernameVARCHAR(100)اسم الدخول — فريدLogin username — unique
password_hashVARCHAR(255)كلمة المرور مشفرةHashed password
full_nameVARCHAR(200)الاسم الكاملFull name
roleENUMadmin / finance / employee
permissions_jsonJSONnullable صلاحيات مخصصةCustom permissions
is_activeTINYINT(1)1 فعال / 0 معطل1 active / 0 disabled
accounts
شجرة الحسابات
Chart of accounts
محاسبةAccounting
idBIGINT PKالرقم الداخليInternal ID
codeVARCHAR(30)رقم الحساب — فريدAccount code — unique
nameVARCHAR(150)اسم الحسابAccount name
categoryENUMasset / liability / equity / revenue / expense
parent_idBIGINT FKnullable الحساب الأبParent account
is_activeTINYINT(1)هل الحساب فعالAccount active flag
receipts
سندات القبض
Income receipts
قبضIncome
idBIGINT PKالرقم الداخليInternal ID
external_idVARCHAR(64)معرف خارجي — فريدExternal identifier — unique
receipt_noBIGINTرقم الوصل — فريدSequential receipt number — unique
receipt_typeENUMincome / loan_payment
payer_nameVARCHAR(200)اسم الجهة الدافعةPayer name
amountDECIMAL(18,3)مبلغ القبضReceipt amount
cheque_noVARCHAR(100)nullable رقم الشيكCheque number
is_cancelledTINYINT(1)هل ملغىCancelled flag
payments
حركات الصرف والإيداع
Expense & deposit movements
صرفExpense
idBIGINT PKالرقم الداخليInternal ID
voucher_noBIGINTرقم المستندVoucher number
payment_typeENUMexpense / loan_grant / deposit_transfer
payee_nameVARCHAR(200)اسم المستفيدPayee name
amount_grossDECIMAL(18,3)المبلغ الإجماليGross amount
stamp_amountDECIMAL(18,3)الطوابع/الاقتطاعاتStamp / deductions
amount_netDECIMAL(18,3)صافي المبلغNet amount
is_cancelledTINYINT(1)هل ملغىCancelled flag
loans
بيانات السلف
Loan data
سلفLoans
idBIGINT PKالرقم الداخليInternal ID
employee_noVARCHAR(50)الرقم الوظيفيEmployee number
employee_nameVARCHAR(200)اسم الموظفEmployee name
loan_typeVARCHAR(120)نوع السلفةLoan type (personal/travel/etc.)
loan_amountDECIMAL(18,3)المبلغ الأصليOriginal loan amount
monthsINT UNSIGNEDعدد أشهر التقسيطNumber of installment months
remainingDECIMAL(18,3)الرصيد المتبقيRemaining balance
statusENUMactive / closed / cancelled
loan_payments
تسديدات أقساط السلف
Loan installment payments
سلفLoans
idBIGINT PKالرقم الداخليInternal ID
loan_idBIGINT FKمرتبط بـ loans.idLinked to loans.id
payment_dateDATEتاريخ التسديدPayment date
amountDECIMAL(18,3)مبلغ التسديدPayment amount
month_noINTnullable رقم الشهرInstallment month number
is_deferredTINYINT(1)هل القسط مؤجلDeferred installment flag
journal_entries
رأس القيد اليومي
Journal entry header
يوميةJournal
idBIGINT PKالرقم الداخليInternal ID
entry_noBIGINTرقم اليومية — فريدJournal number — unique
entry_dateDATEتاريخ القيدEntry date
ref_typeENUMreceipt / payment / manual
is_postedTINYINT(1)هل مرحّلPosted / approved flag
is_adjustmentTINYINT(1)هل قيد تسويةAdjustment entry flag
is_cancelledTINYINT(1)هل ملغىCancelled flag
journal_lines
سطور القيد التفصيلية
Journal entry lines (debit/credit)
يوميةJournal
idBIGINT PKالرقم الداخليInternal ID
journal_entry_idBIGINT FKمرتبط بـ journal_entriesLinked to journal_entries
line_noINTترتيب السطرLine order within entry
account_idBIGINT FKمرتبط بـ accounts.idLinked to accounts.id
debitDECIMAL(18,3)قيمة الطرف المدينDebit amount
creditDECIMAL(18,3)قيمة الطرف الدائنCredit amount
activity_logs
سجل التدقيق
Audit log
تدقيقAudit
idBIGINT PKالرقم الداخليInternal ID
user_idBIGINT FKالمستخدم المنفّذActing user
actionVARCHAR(120)اسم العمليةAction name
entity_typeVARCHAR(80)نوع العنصر المتأثرAffected entity type
before_dataJSONnullable البيانات قبل التعديلData before change
after_dataJSONnullable البيانات بعد التعديلData after change
ip_addressVARCHAR(64)nullable IP address
🔗
العلاقات بين الجداول
Table Relationships
Foreign Keys والروابط الرئيسية
Foreign keys and main links
جدول المصدرSource Table الحقلField جدول الهدفTarget Table الحقلField الوصفDescription
receiptscreated_by→usersidمنشئ وصل القبضReceipt creator
receiptscancelled_by→usersidملغي وصل القبضReceipt canceller
paymentscreated_by→usersidمنشئ حركة الصرفPayment creator
paymentscancelled_by→usersidملغي حركة الصرفPayment canceller
loanscreated_by→usersidمنشئ السلفةLoan creator
loanscancelled_by→usersidملغي السلفةLoan canceller
loan_paymentsloan_id→loansidالتسديد مرتبط بسلفة — CASCADE DELETEPayment linked to loan — CASCADE DELETE
journal_entriescreated_by→usersidمنشئ القيدEntry creator
journal_linesjournal_entry_id→journal_entriesidسطور القيد مرتبطة برأس القيدLines linked to parent entry
journal_linesaccount_id→accountsidكل سطر مرتبط بحساب محاسبيEach line linked to an account
accountsparent_id→accountsidشجرة الحسابات — SET NULL عند الحذفAccount tree — SET NULL on delete
activity_logsuser_id→usersidسجل التدقيق مرتبط بالمستخدمAudit log linked to user
⚡
الفهارس
Indexes
لتسريع الاستعلامات
For query performance
🔍
idx_receipts_date
receipts
تسريع البحث حسب تاريخ القبض
Speed up queries by receipt date
🔍
idx_payments_date
payments
تسريع البحث حسب تاريخ الصرف
Speed up queries by payment date
🔍
idx_journal_entries_date
journal_entries
تسريع تقارير دفتر اليومية
Speed up journal date queries
🔍
idx_journal_lines_account
journal_lines
تسريع تقارير الأستاذ العام
Speed up general ledger reports
🔍
idx_activity_logs_created_at
activity_logs
تسريع سجل التدقيق حسب التاريخ
Speed up audit log date queries
🔍
idx_loans_employee
loans
تسريع البحث عن سلف موظف معين
Speed up employee loan lookups
🔍
idx_loans_date
loans
تسريع تقارير السلف حسب التاريخ
Speed up loan date reports
🔍
idx_loan_payments_date
loan_payments
تسريع تقارير تسديدات السلف
Speed up installment date reports
💰
الحسابات المحاسبية الأساسية
Core Accounting Accounts
البذور المزروعة في قاعدة البيانات
Seed data pre-loaded in the database
1101
الصندوق
Cash Box
asset
1102
البنك الأهلي
Ahli Bank
asset
1103
السلف
Loans
asset
2101
الأمانات
Trusts
liability
4101
مساهمة المراقبات
Monitoring Contrib.
revenue
4102
إيرادات فوائد
Interest Revenue
revenue
5101
مصروف المكافآت
Rewards Expense
expense
⚠️
ملاحظات محاسبية مهمة
Important Accounting Notes
قواعد يجب مراعاتها قبل أي تعديل
Rules to follow before any modification

🔄 أي تعديل محاسبي ينعكس على 4 مستويات🔄 Any accounting change affects 4 levels

الإدخال (Form) ← الحفظ (API) ← التقارير ← الطباعةInput (Form) → Save (API) → Reports → Print templates

🗄️ لا تعدّل database.sql مباشرة🗄️ Don't edit database.sql directly

إذا كان النظام شغال على بيئة موجودة، أضف ترقية داخل migrations/If the system is running on an existing environment, add a migration inside migrations/ instead.

📊 التقارير الدقيقة تعتمد على journal_entries📊 Accurate reports rely on journal_entries

يجب أن تعتمد على journal_entries و journal_lines لأنها تمثل دفتر اليومية والأستاذ العام.Always rely on journal_entries and journal_lines — they represent the full journal and general ledger.

💳 كل حركة = سجل + قيد + سطور💳 Every transaction = record + entry + lines

أي حركة مالية صحيحة يجب أن يكون لها سجل في جدول الحركة المناسب + قيد + سطور تفصيلية.Any valid financial movement must have a record in the appropriate table + a journal entry + detail lines.

⚖️ قاعدة المدين والدائن⚖️ Debit / Credit rule

كل سطر في journal_lines يجب أن يكون إما مدين فقط أو دائن فقط — لا يمكن أن يكون الطرفان أكبر من صفر معاً.Each journal_lines row must be either debit-only or credit-only — both sides cannot be greater than zero simultaneously.

📦 app_storage جدول انتقالي📦 app_storage is a transitional table

ما زال موجوداً للتوافق مع إعدادات النظام — وليس بديلاً عن الجداول المحاسبية الأساسية.Kept for compatibility with system settings — not a substitute for the core accounting tables.