Odoo to PostgreSQL Sync Backend — Python, SQLAlchemy, Docker

[Mohammad77416]

توضیح مختصر راه‌حل

این پروژه یک Backend با Python پیاده‌سازی می‌کند که اطلاعات Contacts،
Products، Sale Orders و Sale Order Lines را از Odoo (از طریق XML-RPC)
دریافت کرده، به مدل داخلی تبدیل می‌کند، و در PostgreSQL ذخیره می‌کند.

معماری به‌صورت لایه‌ای طراحی شده:
سیستم کاملاً Idempotent است (اجرای مکرر داده‌ی تکراری نمی‌سازد)، خطای هر
رکورد به‌صورت مجزا مدیریت می‌شود (بدون توقف کل فرآیند)، و شامل Retry
Mechanism، Structured Logging (Database + File + Standard Output)،
Incremental Sync و Graceful Shutdown است.

نحوه اجرای پروژه

راهنمای کامل و قدم‌به‌قدم (شامل روش Docker و روش دستی) در
docs/USER_DOCUMENTATION.md موجود است.

خلاصه:

docker compose up -d --build

سپس یک دیتابیس Odoo (نام: sync_test) از طریق http://localhost:8069
ساخته و اپ Sales نصب می‌شود (این تنها مرحله‌ی دستی است، چون Odoo تازه‌نصب‌شده
هیچ دیتابیسی ندارد). سپس:

cp .env.example .env      # و تنظیم ODOO_PASSWORD
docker compose exec app python odoo/init_data.py   # ساخت داده‌ی تستی
docker compose exec app python -m src.main          # اجرای Sync

نحوه اجرای تست‌ها

docker compose exec app pytest -v

۲۴ Unit Test (Mapper، Repository، Service Layer، Retry) با استفاده از
pytest و unittest.mock نوشته شده که بدون نیاز به Odoo یا PostgreSQL
واقعی اجرا می‌شوند (از SQLite در حافظه استفاده می‌کنند). برای مشاهده‌ی
Test Coverage:

docker compose exec app pytest --cov=src --cov-report=term-missing

تصمیمات مهم معماری

جزئیات کامل در docs/TECHNICAL_DOCUMENTATION.md
موجود است. مهم‌ترین تصمیمات:

• Repository Pattern: جداسازی منطق تجاری از جزئیات SQLAlchemy/دیتابیس.
• Idempotency در دو لایه: چک odoo_id قبل از insert (سطح اپلیکیشن) +
  UNIQUE constraint روی odoo_id (سطح دیتابیس).
• مدیریت خطا با SAVEPOINT (session.begin_nested()): خطای یک رکورد
  فقط تغییرات همان رکورد را rollback می‌کند، نه کل Transaction — پردازش
  رکوردهای بعدی ادامه پیدا می‌کند.
• Dependency Injection: Session و OdooClient از بیرون به
  Repository/Service تزریق می‌شوند؛ این امر تست‌نویسی با Mock را ساده کرده.
• Abstract Base Classes: BaseMapper, BaseRepository,
  BaseSyncService قرارداد مشترک تعریف می‌کنند و افزودن Entity جدید را
  ساده می‌کنند.
• Retry با تفکیک نوع خطا: خطاهای شبکه‌ای (ConnectionError, OSError)
  با Exponential Backoff تلاش مجدد می‌شوند؛ خطاهای منطقی/برنامه‌نویسی
  (ValueError, TypeError, ...) هرگز retry نمی‌شوند.
• Incremental Sync: بر پایه‌ی فیلتر write_date در Odoo و آخرین
  زمان Sync موفق ثبت‌شده در جدول sync_runs.

محدودیت‌های شناخته‌شده

• Sync یک‌طرفه است (فقط Odoo → PostgreSQL).
• حذف رکورد در Odoo باعث حذف آن در PostgreSQL نمی‌شود (فقط Create/Update
  پشتیبانی می‌شود).
• ساخت دیتابیس اولیه‌ی Odoo یک مرحله‌ی دستی است (طبق سناریوی آزمون مجاز
  دانسته شده) و به همین دلیل با تنها یک docker compose up به‌طور کامل
  خودکار نمی‌شود؛ سرویس app پس از بالا آمدن، Migration را خودکار اجرا
  می‌کند و برای اجرای Sync واقعی از docker compose exec app ... استفاده
  می‌شود.
• در صورت اجرای هم‌زمان چند نمونه از برنامه، احتمال Race Condition جزئی
  وجود دارد (برای اجرای تکی/زمان‌بندی‌شده مشکلی ایجاد نمی‌کند).
• تست‌ها صرفاً Unit Test هستند؛ Integration Test رسمی (اتصال به Odoo/DB
  واقعی در پایپ‌لاین CI) به دلیل محدودیت زمانی نوشته نشده و اسکریپت‌های
  scripts/test_*.py این نقش را به‌صورت دستی ایفا می‌کنند.