تجميع فاتورة بسيطة

تجميع فاتورة بسيطة — Build a Simple Invoice Calculator

بعد المتغيرات والنصوص والتحكم في التدفق والدوال، نحتاج تمريناً يربطها في شيء يشبه كود العمل اليومي: حساب فاتورة بسيطة. في هذا الـ walkthrough سنبني الفاتورة خطوة بخطوة — كل خطوة تضيف طبقة فوق السابقة.

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

انتبه: هذا الـ walkthrough يستخدم float للتبسيط التعليمي. في الأنظمة الإنتاجية الحقيقية نُفضّل تمثيل الأموال بأعداد صحيحة (هللات) لتجنب مشاكل الأرقام العشرية. لكن الآن نركز على البنية والدوال والقراءة.

الخطوة 1: احسب إجمالي صنف واحد

نبدأ بأبسط شيء — حساب إجمالي صنف بسعره وكميته:

main.go

# الخطوة 1: إجمالي صنف واحد — Step 1: single item subtotal
# البيانات — Data
item_name = "كتاب Python"
unit_price = 85.0   # السعر لكل وحدة — Price per unit
quantity = 3        # الكمية — Quantity

# الحساب — Calculate
item_total = unit_price * quantity

print(f"الصنف: {item_name}")
print(f"السعر: {unit_price:.2f} ريال")
print(f"الكمية: {quantity}")
print(f"الإجمالي: {item_total:.2f} ريال")

Output:

لاحظ أننا استخدمنا :.2f في f-string للحصول على رقمين بعد الفاصلة. الفواتير دائماً تحتاج هذا التنسيق لأن المال يُعرض بدقة ثابتة.

تحدي — Challenge

# احسب إجمالي الصنف — Calculate item total
# قلم حبر: 12.0 ريال × 20 قطعة
# Ink pen: 12.0 SAR × 20 pieces

item_name = "قلم حبر"
unit_price = 12.0
quantity = 20

# احسب item_total واطبع: "إجمالي الصنف: 240.00 ريال"
# Calculate item_total and print: "إجمالي الصنف: 240.00 ريال"

الخطوة 2: أضف ضريبة القيمة المضافة (15%)

الآن ننقل الحساب إلى دوال ونضيف ضريبة القيمة المضافة:

main.go

# الخطوة 2: دوال + ضريبة — Step 2: functions + VAT
def item_subtotal(price, qty):
    """احسب إجمالي صنف — Calculate item subtotal."""
    return price * qty

def add_vat(amount, rate=0.15):
    """أضف الضريبة وارجع الإجمالي — Add VAT and return total."""
    return amount * (1 + rate)

# بيانات — Data
price = 85.0
qty = 3

subtotal = item_subtotal(price, qty)
total = add_vat(subtotal)
vat_amount = total - subtotal

print(f"الإجمالي قبل الضريبة: {subtotal:.2f} ريال")
print(f"الضريبة (15%): {vat_amount:.2f} ريال")
print(f"الإجمالي مع الضريبة: {total:.2f} ريال")

Output:

لماذا نضع الحسابات في دوال بدلاً من كتابتها مباشرة؟ لأن الدالة تُسمّي النية. add_vat(subtotal) أوضح من subtotal * 1.15. وإذا تغيرت نسبة الضريبة ستعدّل في مكان واحد فقط.

تحدي — Challenge

# عرّف دالة add_vat وطبّقها — Define add_vat and apply it
# الإجمالي الجزئي 250.0 ريال، الضريبة 15%
# Subtotal 250.0 SAR, VAT 15%

subtotal = 250.0

# عرّف add_vat(amount, rate=0.15) — Define add_vat(amount, rate=0.15)
# احسب total وvat_amount
# اطبع: "الضريبة: 37.50 ريال" ثم "الإجمالي: 287.50 ريال"

الخطوة 3: نسّق سطر الفاتورة

الفاتورة ليست مجرد أرقام — يجب أن تكون قابلة للقراءة:

main.go

# الخطوة 3: تنسيق السطور — Step 3: format invoice lines
def format_item_line(name, price, qty):
    """نسّق سطر الصنف — Format an item line."""
    total = price * qty
    return f"  {name:<25} {qty:>3} × {price:>7.2f} = {total:>9.2f} ريال"

def format_summary_line(label, amount):
    """نسّق سطر الملخص — Format a summary line."""
    return f"  {label:<28} {amount:>9.2f} ريال"

# اطبع سطور — Print lines
print("=" * 50)
print("           فاتورة المشتريات")
print("=" * 50)
print(format_item_line("كتاب Python للمبتدئين", 85.0, 3))
print(format_item_line("قلم حبر أسود", 3.5, 10))
print("-" * 50)

subtotal = 85.0 * 3 + 3.5 * 10
vat = subtotal * 0.15
total = subtotal + vat

print(format_summary_line("الإجمالي الجزئي", subtotal))
print(format_summary_line("ضريبة القيمة المضافة (15%)", vat))
print("=" * 50)
print(format_summary_line("الإجمالي النهائي", total))
print("=" * 50)

Output:

تنسيق f-string المستخدم هنا:

:<25 — نص محاذى لليسار بعرض 25
:>9.2f — رقم عشري محاذى لليمين بعرض 9 ورقمين عشريين

تحدي — Challenge

# نسّق سطر الصنف التالي — Format this item line:
# دفتر ملاحظات، السعر 8.0 ريال، الكمية 10
# Notebook, price 8.0 SAR, quantity 10

name = "دفتر ملاحظات"
price = 8.0
qty = 10

# المتوقع: "  دفتر ملاحظات          10 ×    8.00 =     80.00 ريال"
# اكتب الكود هنا

الخطوة 4: تعامل مع القائمة الفارغة

برنامج قوي يتعامل مع الحالات الاستثنائية. ماذا لو كانت قائمة الأصناف فارغة؟

main.go

# الخطوة 4: معالجة القائمة الفارغة — Step 4: handle empty list
def calculate_invoice_total(items):
    """
    احسب إجمالي الفاتورة.
    items: قائمة من (name, price, qty)
    يرجع: (subtotal, vat, total)
    """
    if not items:
        return 0.0, 0.0, 0.0   # القائمة فارغة — Empty list

    subtotal = 0.0
    for name, price, qty in items:
        subtotal += price * qty

    vat = subtotal * 0.15
    total = subtotal + vat
    return subtotal, vat, total

# اختبار مع أصناف — Test with items
order1 = [
    ("كتاب Python", 85.0, 2),
    ("قلم", 3.5, 5),
]

subtotal, vat, total = calculate_invoice_total(order1)
print(f"طلب عادي — Subtotal: {subtotal:.2f}, VAT: {vat:.2f}, Total: {total:.2f}")

# اختبار مع قائمة فارغة — Test with empty list
empty_order = []
s, v, t = calculate_invoice_total(empty_order)
print(f"طلب فارغ — Subtotal: {s:.2f}, VAT: {v:.2f}, Total: {t:.2f}")

Output:

if not items: في Python يعني “إذا كانت القائمة فارغة” — فارغة تعادل False في Python. هذا أنظف من if len(items) == 0.

تحدي — Challenge

# تعامل مع الفاتورة الفارغة — Handle empty invoice
# عرّف دالة print_invoice_total(items) تطبع:
# - إذا كانت القائمة فارغة: "الإجمالي: 0.00 ريال" ثم "لا توجد أصناف في الفاتورة"
# - وإلا: "الإجمالي: XX.XX ريال"

def print_invoice_total(items):
    # اكتب الكود هنا — Write your code here
    pass

# اختبر مع قائمة فارغة — Test with empty list
print_invoice_total([])

الخطوة 5: التكامل الكامل

الآن ندمج كل شيء في برنامج كامل يطبع فاتورة احترافية:

main.go

# الخطوة 5: الفاتورة الكاملة — Step 5: full invoice
def item_line(name, price, qty):
    """سطر الصنف منسقاً — Formatted item line."""
    return f"  {name:<25} {qty:>3} × {price:>7.2f} = {price*qty:>9.2f} ريال"

def summary_line(label, amount):
    """سطر الملخص منسقاً — Formatted summary line."""
    return f"  {label:<28} {amount:>9.2f} ريال"

def print_invoice(customer, items, vat_rate=0.15):
    """
    اطبع فاتورة كاملة.
    customer: اسم العميل
    items: قائمة من (name, price, qty)
    vat_rate: نسبة الضريبة، الافتراضي 15%
    """
    if not items:
        print("لا يمكن طباعة فاتورة فارغة")
        return

    subtotal = sum(price * qty for name, price, qty in items)
    vat = subtotal * vat_rate
    total = subtotal + vat

    border = "=" * 50
    print(border)
    print(f"  فاتورة العميل: {customer}")
    print(border)

    for name, price, qty in items:
        print(item_line(name, price, qty))

    print("-" * 50)
    print(summary_line("الإجمالي الجزئي", subtotal))
    print(summary_line(f"الضريبة ({vat_rate*100:.0f}%)", vat))
    print(border)
    print(summary_line("الإجمالي النهائي", total))
    print(border)

# استخدام الدالة — Use the function
order = [
    ("كتاب Python للمبتدئين", 85.0, 2),
    ("قلم حبر أسود", 3.5, 10),
    ("دفتر ملاحظات A5", 8.0, 5),
]

print_invoice("أحمد العمري", order)

Output:

ما تعلمناه من هذا الـ Walkthrough

كل خطوة بنينا فيها طبقة جديدة:

بيانات + حساب مباشر — أبسط شكل للكود
دوال صغيرة — كل حساب له اسم يشرح نيّته
تنسيق النص — f-strings مع تنسيق الأعمدة
معالجة الحالات الاستثنائية — القائمة الفارغة
التكامل — دالة رئيسية تُنسّق الكل وتُفوّض الحسابات لدوال أصغر

هذا هو النمط الأساسي في الكود الاحترافي: قسّم المشكلة إلى قطع صغيرة، أعطِ كل قطعة دالة باسم واضح، ثم اجمعها في دالة رئيسية تعكس المنطق الكلي للبرنامج.

عندما تقرأ كودك بعد الانتهاء يجب أن تستطيع شرح كل سطر بجملة بسيطة: “احسب إجمالي الصنف”، “أضف الضريبة”، “نسّق السطر”، “اطبع الفاتورة”. إذا احتجت فقرة كاملة لشرح سطر واحد فهذه إشارة لإعادة التنظيم.