Skip to content

CLAUDE.md

Latest commit

 

History

History
124 lines (94 loc) · 6.92 KB

CLAUDE.md

File metadata and controls

124 lines (94 loc) · 6.92 KB

HT_SC_ — نظام تسجيل ومراقبة رحلات الحج والعمرة

هيكل المشروع

  • main.py — القائمة التفاعلية الرئيسية (7 خيارات تشغيل)
  • scripts/ — السكربتات: معالجة واتساب، تقارير، مدير ملفات، أدوات قاعدة البيانات، مراقبة
  • scripts/common.py — الدوال المشتركة بين كل السكربتات (عرض، تفاعل، تحليل واتساب، قراءة إكسل)
  • scripts/logger_config.py — نظام التسجيل (7 جداول في قاعدة منفصلة)
  • db/ — طبقة قاعدة البيانات: هيكل الجداول، استعلامات، استيراد، مزامنة
  • db/constants.py — الثوابت المشتركة (لا تُكرّر في ملفات أخرى)
  • db/helpers.py — الدوال المشتركة: safe_str, safe_int, build_records_insert_sql, build_record_2026_insert_sql
  • monitor_v2/ — مراقب واتساب (جافاسكربت/نود) — 5 طبقات: core, orchestrator, transport, storage, utils
  • tests/ — اختبارات الوحدة (pytest)
  • docs/ — التوثيق والدروس المستفادة
  • python-3.14-docs-text/ — وثائق بايثون 3.14 المحلية (534 ملف نصي)

أوامر التشغيل والاختبار

# تشغيل النظام
python main.py

# تشغيل الاختبارات
python -m pytest tests/ -v

# فحص الكود
ruff check scripts/ db/

# تشغيل المراقب
cd monitor_v2 && node index.js

قواعد كتابة الكود

الثوابت والدوال المشتركة — لا تكررها

  • db/constants.py يحتوي: MAX_TRIPS, TRIP_FIELDS, TRIP_FIELD_NAMES_AR
  • db/helpers.py يحتوي: safe_str, safe_int, build_records_insert_sql, build_record_2026_insert_sql
  • عند الحاجة لهذه القيم في أي ملف: استورد من المصدر — لا تُعرّف نسخة محلية

نمط الاستيراد

  • ملفات db/ تستورد نسبياً: from constants import ...، from helpers import ...
  • ملفات scripts/ تستورد بالمسار الكامل: from db.constants import ...
  • ترتيب الاستيرادات: مكتبة قياسية، خارجية، محلية

التنسيق

  • ruff يعمل تلقائياً عبر خطّاف .claude/hooks/ruff_hook.py
  • الحد الأقصى لطول السطر: 99 حرفاً (حسب ruff.toml)

أنماط محظورة

  • وسائط افتراضية قابلة للتغيير — استخدم None
  • مقارنة None بـ == — استخدم is
  • استيراد شامل بـ * — حدّد الأسماء صراحة
  • except مجردة — التقط استثناءات محددة
  • type() لفحص النوع — استخدم isinstance

قواعد البيانات الثلاث

  1. db/ht_sc.db — القاعدة الرئيسية (11 جدول)

    • رحلات، رسائل، مرسلين، مخالفات، تسجيل يومي، مقارنات
    • بايثون يقرأ ويكتب. المراقب يكتب المخالفات فيها.

  2. db/ht_sc_new.db — قاعدة 2026

    • جدول record_2026 + جداول مرجعية + إحصائيات النوبات
    • المراقب يكتب فيها مباشرة. write_excel_from_db.py يقرأ ويصدّر للإكسل.

  3. logs/ht_sc_logs.db — سجلات النظام

    • 7 جداول: أحداث نظام، تفاعلات، ملفات، جودة بيانات، معالجة، عمليات قاعدة، أخطاء
    • بايثون والمراقب يكتبان فيها.

كل القواعد تستخدم WAL + busy_timeout = 5000ms للوصول المتزامن.

العلاقة بين بايثون وجافاسكربت

  • المراقب (monitor_v2/) مكتوب بجافاسكربت ويعمل بنود
  • يتصل بالنظام البايثوني عبر القواعد الثلاث المشتركة
  • يتبادل الحالة عبر ملفات في monitor_v2/state/
  • scripts/monitor_v2_tool.py يدير تشغيل وإيقاف المراقب من القائمة الرئيسية

ملفات مرجعية

  • ARCHITECTURE.md — تحليل معماري شامل: طبقات، اعتماديات، كود مكرر، توصيات
  • REFACTOR_BASELINE.md — خط أساس إعادة الهيكلة
  • docs/LESSONS.md — 50 درساً مستفاداً من تطوير المشروع
  • docs/HANDOFF_2026-03-14.md — وثيقة تسليم شاملة: الملفات الجديدة والمحدّثة والمحذوفة و6 مهام معلّقة

المرجع التقني — وثائق بايثون

مجلد python-3.14-docs-text/ يحتوي وثائق بايثون 3.14 كاملة. ابحث فيه قبل أي قرار تقني:

  • وحدة معينة: library/<module>.txt (مثلاً library/sqlite3.txt)
  • الدوال المدمجة: library/functions.txt
  • الأنواع المدمجة: library/stdtypes.txt
  • نموذج البيانات: reference/datamodel.txt
  • تلميحات الأنواع: library/typing.txt

القيود

  • اسأل ولا تخمّن — عند مواجهة أمر غير واضح وجّه سؤالاً فوراً
  • الوثائق هي المرجع — ابحث في python-3.14-docs-text/ قبل كل تنفيذ
  • رشّد التوكنز — ردود موجزة، لا حشو، لا وكلاء ذكاء اصطناعي، لا مهارات
  • لا تحذف قاعدة البيانات — ممنوع حذف أو إعادة بناء ht_sc.db أو ht_sc_new.db
  • لا تغيّر هيكل الإكسل — بنية المجلدات والملفات ثابتة
  • اللغة العربية — الشرح والتعليقات بالعربية. الإنجليزية داخل الكود فقط.

بيانات العمل الثابتة

القواعد التفصيلية وبيانات العمل (ناقلات جوية، أنواع الفيزا، المشرفين، النوبات، صالات السفر) موجودة في: .claude/rules/AI_RULES.md

تعليمات الضغط

عند ضغط المحادثة احتفظ دائماً بـ:

  • قائمة الملفات التي عُدّلت في هذه الجلسة
  • أي قرارات تصميمية اتُّخذت
  • أي أخطاء اكتُشفت ولم تُحل بعد
  • آخر نتيجة اختبارات
  • المهمة الحالية التي نعمل عليها

الذاكرة التلقائية (إلزامي)

في بداية كل جلسة: اقرأ الملفات الثلاثة. بعد كل رد: حدّثها فوراً — المستخدم قد يُغلق بالـ X بدون /exit.

  • @.claude/memory/MEMORY.md — السياق والقرارات التقنية
  • @.claude/memory/LESSONS.md — الدروس والأخطاء
  • @.claude/memory/PROGRESS.md — المُنجز والمعلّق
  • @.claude/rules/auto_memory.md — قاعدة التحديث الإلزامي