توثيق تقنِكس لنقاط البيع

التطبيق للمقاهي والمتاجر والمطاعم التي تعمل على أودو 19، وللمُركِّبين الذين يجهّزون أودو لعملائهم. الترخيص لشركة واحدة: على المُركِّب أن يشتري نسخة لكل شركة عميلة (الفصل 30).

الصور في هذا الدليل من متجر تجريبي اسمه Harbor Café & Market (بالدولار الأمريكي، العنوان 1200 Harbor Walk, Dearborn MI). فيه نقطتا بيع:

• المتجر الرئيسي: تجزئة ومقهى. الأسعار المعروضة شاملة الضريبة، وتقريب النقد 0.05 على الدفع النقدي، وبرنامج الولاء «مكافآت هاربر»، وكود الخصم SUMMER10.
• مطعم هاربر: طابقان هما «الطابق الأرضي» و«التراس»، وطابعتان للمطبخ والبار. الأسعار المعروضة دون الضريبة.

أمين الصندوق في الصور هو Tom Becker، وهو مستخدم عادي لنقطة البيع. عنوان أودو الظاهر في الصور خادم تجريبي محلي؛ عندك سيكون عنوان أودو الخاص بشركتك.

أودو علامة تجارية لشركة Odoo S.A. وهذا المنتج لم تصنعه Odoo S.A. ولم تعتمده.

التقنية: Next.js 16 وReact 19 وTypeScript وTailwind CSS 4. البيانات المحلية في IndexedDB عبر Dexie، وحالة الواجهة في Zustand، والتحقق من البيانات بـ Zod.

الخيار 1: تطبيق الويب الجاهز للتشغيل

لا شيء لتثبيته ولا لبنائه.

1. ثبّت Node.js 20.9 أو أحدث من nodejs.org (الأمر node -v يعرض الإصدار الذي عندك).
2. فُكّ ضغط الحزمة، ثم فُكّ ضغط الملف taqnix-pos-terminal-webapp.zip الذي فيها. المجلد taqnix-pos-terminal-webapp هو التطبيق الجاهز.
3. افتح نافذة أوامر (موجّه الأوامر في ويندوز) داخل هذا المجلد وشغّل التطبيق مع عنوان أودو: sh start.sh https://erp.example.com على ماك ولينكس، وstart.bat https://erp.example.com على ويندوز.
4. افتح http://localhost:3000 في Chrome أو Edge واربط الجهاز بأودو (الفصل 6). لإيقافه اضغط Ctrl+C.

# macOS and Linux, in the folder taqnix-pos-terminal-webapp
sh start.sh https://erp.example.com
# Windows (Command Prompt, or double-click start.bat)
start.bat https://erp.example.com
# another port; every option
sh start.sh https://erp.example.com --port 3100
sh start.sh --help
# the same without the launcher script
node run.cjs https://erp.example.com

ملف التشغيل يتحقق من إصدار Node.js، ويضيف عنوان أودو الذي تكتبه إلى POS_ALLOWED_ORIGINS، ويقرأ الملف .env (انسخ .env.example إلى .env لتحفظ إعداداتك)، وينبّهك إذا كان المنفذ مشغولًا. وفي المجلد أيضًا ملف README.txt خاص به.

يستمع التطبيق على هذا الحاسوب فقط (127.0.0.1) ما لم تطلب غير ذلك. وهذا يكفي للتجربة ولجهاز بيع على الحاسوب نفسه: العنوان http://localhost يُعدّ آمنًا في المتصفح، فيُثبَّت التطبيق ويعمل دون اتصال. لأجهزة بيع على أجهزة أخرى شغّله بالخيار --host 0.0.0.0 (أو POS_HOST=0.0.0.0) وضع أمامه HTTPS (أدناه). ولتشغيله مع الحاسوب وإعادة تشغيله بعد أي توقف شغّل node run.cjs بمدير عمليات تستخدمه عندك (systemd أو pm2 أو مجدول مهام ويندوز).

الخيار 2: البناء من الشيفرة المصدرية

لمن يعدّل التطبيق أو يريد بناءه على خادمه.

1. فُكّ ضغط الحزمة ثم الملف taqnix-pos-terminal.zip وادخل إلى المجلد src/pos-terminal (الذي فيه الملف package.json).
2. ثبّت الاعتماديات بالأمر npm ci.
3. انسخ الملف .env.example إلى .env واكتب فيه عنوان أودو في POS_ALLOWED_ORIGINS.
4. ابنِ التطبيق بالأمر npm run build. ينتج عنه نسخة الإنتاج وملف الـ service worker وملف التراخيص.
5. شغّله بالأمر npm start. المنفذ الافتراضي 3000، ويُغيَّر بالخيار -p.
6. افتح عنوان التطبيق من متصفح جهاز البيع (القسم الأخير من هذا الفصل).

npm ci
npm run dev            # development server on http://localhost:3000 (permissive proxy defaults)
npm run build          # production build + service worker (scripts/make-sw.mjs) + licences file
npm start              # production server (NODE_ENV=production), port 3000 (-p to change)
POS_STANDALONE=1 npm run build   # .next/standalone, used by the Dockerfile
npm run pack:webapp    # after that build: a ready-to-run folder in webapp-dist/, like the one in the package
docker compose up -d   # build + run with the settings of .env (copy .env.example)

متغيرات البيئة

تُكتب في الملف .env (أو في بيئة الحاوية). في وضع التطوير (npm run dev) يُسمح بأي عنوان أودو وبالعناوين الخاصة.

POS_ALLOWED_ORIGINS=https://erp.example.com
# POS_ALLOW_ANY_ORIGIN=1
# POS_ALLOW_PRIVATE=1
# POS_CONNECT_SRC=https://erp.example.com
# POS_TRUST_PROXY=1
# POS_DISABLE_JSONRPC=1
# POS_HOST=127.0.0.1
# PORT=3000

Docker

يأتي مع الحزمة ملفا Dockerfile وdocker-compose.yml. الأمر docker compose up -d يبني الصورة ويشغّلها بإعدادات الملف .env.

# docker-compose.yml
services:
  pos:
    build: .
    restart: unless-stopped
    ports:
      - "3000:3000"
    env_file: .env

# without compose (header of the Dockerfile)
docker build -t taqnix-pos . && docker run -p 3000:3000 --env-file .env taqnix-pos

واجهة HTTPS بـ nginx

المثال deploy/nginx.conf.example يضع TLS أمام التطبيق. النقاط المهمة فيه:

• شغّل التطبيق مع POS_TRUST_PROXY=1 لأن nginx هو الذي يكتب ترويسات X-Forwarded-*.
• الملف /sw.js لا يُخزَّن مؤقتًا أبدًا، لا في nginx ولا في أي CDN، وإلا لن تصل التحديثات.
• client_max_body_size 26m: يقبل الوسيط حتى 25 ميغابايت (طلبات فيها بنود كثيرة، وصور).
• العنوان العام يحتاج إلى حماية: VPN أو SSO أو قائمة عناوين مسموحة (الفصل 25).

# TLS front for the terminal (a PWA can only be installed from https:// or http://localhost).
# Run the app with POS_TRUST_PROXY=1 behind this proxy (it writes the X-Forwarded-* headers below).
# Internet-facing? /api/odoo has no login of its own: restrict who reaches it (VPN, SSO / identity-aware
# proxy, or an IP allow-list like the commented `allow`/`deny` lines below).
server {
  listen 443 ssl http2;
  server_name pos.example.com;
  ssl_certificate     /etc/letsencrypt/live/pos.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/pos.example.com/privkey.pem;

  client_max_body_size 26m;          # the proxy accepts up to 25 MB (orders with many lines, images)

  # allow 203.0.113.0/24;           # the shop's public address(es)
  # deny all;

  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    # overwrite (never append) what the client sent: the app trusts these only with POS_TRUST_PROXY=1
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 70s;          # the proxy gives Odoo 60 s
  }

  # The service worker must never be cached by a CDN or by nginx
  location = /sw.js {
    proxy_pass http://127.0.0.1:3000;
    add_header Cache-Control "no-cache, no-store, must-revalidate" always;
  }
}

التثبيت على جهاز البيع

1. افتح عنوان التطبيق https://... في Chrome أو Edge.
2. اضغط زر التثبيت في المتصفح. وعندما يسمح المتصفح يعرض التطبيق أيضًا شريطًا صغيرًا فيه الرسالة «ثبّت التطبيق على هذا الجهاز لاستخدامه بملء الشاشة وتشغيله أسرع.» وزرّا تثبيت وتجاهل.
3. شغّل التطبيق المثبّت من قائمة التطبيقات أو من سطح المكتب. تجد حالة التثبيت أيضًا في الإعدادات ثم حول.

1. أنشئ لكل جهاز (أو لكل أمين صندوق) مستخدمًا في أودو: مستخدم داخلي مع المجموعة نقطة البيع / مستخدم فقط.
2. من تفضيلات هذا المستخدم افتح أمان الحساب وأنشئ مفتاح API جديد بالنطاق rpc. انسخ المفتاح فورًا: لا يعرضه أودو مرة ثانية. استعمل المفتاح بدل كلمة المرور في شاشة الإعداد.
3. اضبط نقطة البيع في أودو: طرق الدفع (طريقة نقدية واحدة لكل نقطة بيع)، ومراقبة النقد إن أردت عدّ الدرج عند الفتح والإغلاق، ودفتر اليومية الذي تصدر منه الفواتير إذا أردت استعمال خيار فاتورة.
4. اضغط اختبار الاتصال في التطبيق (الفصل 6). التقرير يقول لك ما ينقص هذا المستخدم.

صلاحيات اختيارية

المستخدم العادي لنقطة البيع لا يملك بعض الصلاحيات في أودو 19. لا يمنعه ذلك من البيع، لكن بعض الميزات تحتاج إليها:

الضرائب والأوضاع المالية

اربط في كل وضع مالي كل ضريبة صراحةً بضريبة أخرى، ولو كانت ضريبة نسبتها 0 %. الوضع المالي بلا أسطر ضرائب يتصرف في أودو 19 نفسه تصرفًا غير متسق: عميل أودو يُبقي الضرائب والخادم يحذفها، فلا تتطابق قيود الجلسة مع الطلبات (الفصل 23). لا يستطيع التطبيق التمييز بين هذا الوضع ووضع لا يُحوّل شيئًا.

للمطعم

الطوابق والطاولات وطابعات الطلبات وفئات المطبخ ومنتج الإكرامية وأنواع الخدمة تُضبط كلها في أودو، من نقطة البيع ثم الإعدادات ثم مخططات الصالة. مستخدم نقطة البيع يقرأ الطاولات فقط. عدّل المخطط في أودو ثم اضغط تنزيل البيانات الآن في شاشة المزامنة (الفصل 15).

في أعلى الشاشة شريحتان لاختيار اللغة (العربية وEnglish) والمظهر (فاتح وداكن ومحيط وغابة وغروب). يمكنك تغييرهما قبل الاتصال وبعده.

إعدادات متقدمة

اختبار الاتصال

الزر اختبار الاتصال يتحقق بالترتيب من أن العنوان خادم أودو، ومن قاعدة البيانات، ومن الدخول، ثم من صلاحية نقطة البيع. ويعرض تقريرًا:

الزر حفظ ومتابعة يعمل بعد أن تكتمل الحقول الأربعة ولا يكون في التقرير خطأ. إن لم تختبر الاتصال قبل ذلك فإنه يختبره أولًا، ثم يحفظ الاتصال على هذا الجهاز وينقلك إلى اختيار نقطة البيع.

أشهر المشكلات

بقية الرسائل وحلولها في الفصل 28.

تعرض كل بطاقة اسم نقطة البيع ونوعها (تجزئة أو مطعم)، وشارة مراقبة النقد إذا كانت نقطة البيع تعدّ النقد، وحالة الجلسة:

الزر تغيير الخادم في الأعلى يعيدك إلى شاشة الإعداد. إذا كانت على الجهاز طلبات لم تُرسل إلى الخادم السابق يرفض الجهاز الانتقال إلى خادم آخر ويقول «طلبات الخادم السابق لم تُرسل بعد. أرسلها قبل تغيير الخادم.»

النقد الافتتاحي

تفتح النافذة النقد الافتتاحي عندما تختار نقطة بيع لا جلسة مفتوحة لها. اختر طريقة الإدخال:

• عدّ الأوراق والعملات: فئات الأوراق والعملات تأتي من أودو، ولكل فئة عدّاد. الإجمالي يُحسب لك.
• إدخال المبلغ: تكتب مبلغ الدرج الإجمالي في الحقل النقد في الدرج.

اكتب عند الحاجة ملاحظة الافتتاح ثم اضغط فتح الجلسة. إن لم تكن نقطة البيع تعدّ النقد عند الافتتاح تظهر العبارة «نقطة البيع هذه لا تعدّ النقد عند الافتتاح.»

المنتجات

• ابحث بالاسم أو المرجع أو الباركود: البحث يبدأ بعد توقف الكتابة لحظة قصيرة، ويغطي الاسم والمرجع الداخلي والباركود. الضغط على Enter يضيف المنتج إذا كان الباركود أو المرجع مطابقًا تمامًا أو إذا بقيت نتيجة واحدة.
• الفئات: شرائح بألوان نقطة البيع في الصف الأول، وبعضها يحوي فئات فرعية. الكل يعرض كل المنتجات، والمفضلة ما علّمته مفضلًا في أودو.
• بطاقة المنتج: صورة (أو حرفان من الاسم) والاسم والسعر. المنتج الذي له خيارات تظهر عليه الشارة خيارات، والكومبو الشارة كومبو.
• لمسة واحدة تضيف المنتج إلى الطلب. المنتج نفسه بالخيارات نفسها والسعر نفسه يُدمج في بند واحد وتزيد كميته، كما تفعل نقطة بيع أودو.
• الزر «...» على البطاقة، أو الضغط المطوّل عليها نحو نصف ثانية، يفتح نافذة الخيارات (الكمية والملاحظة وخيارات المنتج، الفصل 9).
• إذا كان الكتالوج كبيرًا جدًا تتوقف الشبكة عند 1,200 بطاقة وتقول «ابحث أو اختر فئة لعرض بقية المنتجات.»

لوحة الطلب

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

لوحة الأرقام لها ثلاثة أوضاع لتعديل البند المحدد: الكمية وخصم % والسعر. اضغط الوضع ثم اكتب الرقم. لا يمكن تغيير سعر عنصر داخل كومبو.

على الجهاز اللوحي الرأسي (768×1024) تنطوي لوحة الطلب في شريط سفلي فيه الزر مراجعة الطلب مع عدد البنود والإجمالي والزر الدفع.

ماسح الباركود

يعمل الماسح كلوحة مفاتيح: يكتب الرمز بسرعة كبيرة ثم Enter. يتعرّف الجهاز على المسح من سرعة الأحرف (أقل من 35 ملّي ثانية بين حرف وآخر افتراضيًا، وثلاثة أحرف على الأقل). تُضبط المهلة وأقصر باركود في الإعدادات ثم الجهاز. ويقرأ الجهاز الأنواع حسب قواعد أودو الافتراضية للباركود:

الرمز غير المعروف يعطي «باركود غير معروف» مع الرمز. أثناء الكتابة داخل حقل نص عادي (مثل حقل ملاحظة) لا يُعدّ ما تكتب مسحًا.

اختصارات لوحة المفاتيح

تعمل في شاشة البيع. زر اختصارات لوحة المفاتيح في الشريط العلوي، أو المفتاح ?، يعرض القائمة.

خيارات المنتج

تظهر لكل خاصية مجموعة أزرار. تأتي المجموعات من أودو بأحد أشكال العرض الثلاثة: شرائح للاختيار الواحد، وعيّنات ألوان للألوان، ومربعات متعددة الاختيار للإضافات. الزيادة في السعر تظهر بجانب كل خيار (مثل «+ 0.50»). الخيارات التي لا يسمح بها أودو معًا (الاستثناءات) تُعطَّل، والتركيبة غير المتاحة تعرض «هذه التركيبة غير متاحة.»

• أخرى (حدد) قيمة نصية حرة: يظهر حقل نص تكتب فيه ما تريد، ولا يُضاف المنتج قبل كتابته. حفظ هذه القيمة في أودو يحتاج صلاحية «المنتجات / الإنشاء» (الفصل 5)؛ بدونها يرفض أودو الطلب وتبقى المشكلة في شاشة المزامنة.
• ملاحظة: نص حر يبقى على البند، مثل «بدون بصل».
• العدّاد يحدد الكمية، والسعر الظاهر يتغير مع كل اختيار.
• الزر إضافة إلى الطلب يضيف البند. يظهر في الطلب اسم المنتج مع خياراته بين قوسين.

الكومبو

يعرض الكومبو بطاقة لكل مجموعة. عنوان المجموعة يبيّن ما اخترته وما هو مطلوب (مثل «1 من 1»)، والشارة «عنصر واحد مشمول» تعني أن عنصرًا واحدًا من المجموعة داخل سعر الكومبو. العناصر الإضافية لها سعر يظهر بجانبها، والعنصر المشمول يحمل الكلمة «مشمول». يكون الزر إضافة إلى الطلب معطّلًا إلى أن تكتمل كل المجموعات، ويعرض الإجمالي الجاري. إذا كان لعنصر خيارات (حجم مثلًا) فتُسأل عنها أيضًا.

في الطلب يظهر الكومبو كبند واحد تحته عناصره (كما في صورة الطلب في الفصل 8)، وعلى الإيصال تظهر العناصر تحت اسم الكومبو. حذف الكومبو أو تغيير كميته يشمل عناصره كلها، ويوزّع الجهاز سعر الكومبو على العناصر بالقاعدة التي تستعملها نقطة بيع أودو.

اختيار عميل للطلب

اضغط العميل في لوحة الطلب أو المفتاح F4. تنزلق لوحة فيها حقل بحث عن العملاء بالاسم أو الهاتف أو البريد أو الباركود (يُقبل الهاتف بأي صيغة، مثل +1 313 555 0111 أو 3135550111)، وزر جديد. اضغط النتيجة لتختارها. بعد الاختيار تظهر بطاقة العميل مع قائمة أسعاره ووضعه المالي، وفيها الزر إزالة لفصل العميل عن الطلب.

عند اختيار العميل ينتقل إلى الطلب ما يلي: قائمة أسعاره، ووضعه المالي (الذي يحوّل الضرائب). يعيد الجهاز حساب الإجماليات فورًا.

شاشة العملاء

في أعلاها العملاء وعدد العملاء الموجودين على هذا الجهاز، وزر عميل جديد. القائمة مرتبة أبجديًا مع فهرس للحروف. اضغط عميلًا لترى بطاقته: الهاتف والبريد والعنوان والرقم الضريبي والباركود، وقائمة الأسعار والوضع المالي، والطلبات الأخيرة على هذا الجهاز.

عميل جديد

الحقول: الاسم (مطلوب) وهذه شركة والهاتف والبريد الإلكتروني والشارع والمدينة والرمز البريدي والدولة والولاية / المنطقة والرقم الضريبي والباركود. اضغط إنشاء العميل. يُحفظ العميل على الجهاز فورًا ويمكن استعماله في الطلبات، ويظهر بالشارة «ستتم مزامنته». يُرسل إلى أودو عند الاتصال (أو فورًا إن كان متصلًا)، ثم يأخذ رقمه في أودو، ويتبعه ما كان ينتظره من طلبات.

1. اضغط طريقة دفع: يُضاف سطر دفع بالمبلغ المتبقي كله.
2. عدّل المبلغ بلوحة الأرقام، أو اضغط المبلغ المطلوب تمامًا ليأخذ السطر ما بقي، أو +10 و+20 و+50 لإضافة هذه المبالغ إلى السطر المحدد.
3. للدفع بأكثر من طريقة أضف سطرًا آخر بطريقة أخرى. اضغط أيقونة سلة المهملات على السطر لحذفه.
4. راقب المربع الرمادي: المتبقي بالبرتقالي إلى أن يُدفع الطلب، ثم الباقي بالأخضر إن زاد المدفوع.
5. اضغط تصديق (أو Enter). للعودة إلى الطلب اضغط السهم أو Esc.

المنتجات المتتبَّعة بالدفعة أو الرقم التسلسلي

عند إضافة منتج متتبَّع يفتح الجهاز نافذة لإدخال الأرقام: الأرقام التسلسلية (رقم واحد لكل وحدة، تكتبه أو تمسحه ثم تضيفه، ولا يُباع الرقم نفسه مرتين) أو الدفعة (اسم الدفعة والكمية المأخوذة منها، ودفعة أخرى تصبح بندًا جديدًا). يقبل أودو هذه الأرقام فقط من مستخدم له صلاحية «المخزون / مستخدم». بدونها يبقى الطلب في شاشة المزامنة مع الرسالة «صلاحية ناقصة» واسم المجموعة حتى تُمنح الصلاحية وتعيد المحاولة.

الإيصال

بعد تصديق تظهر بطاقة تم استلام الدفع مع الباقي وحالة الإرسال: على هذا الجهاز ثم بانتظار المزامنة أو جارٍ الإرسال إلى أودو… ثم في أودو (أو خطأ في المزامنة). تحتها اختيار عرض الورق 80 مم أو 58 مم، وزر طباعة، وزر طلب جديد.

يتألف الإيصال من: كتلة الشركة (الاسم والعنوان والرقم الضريبي والهاتف والبريد)، ورقم الإيصال والتاريخ واسم من خدمك ورقم الطلب، والعميل، والبنود وعلى كل بند حرف ضريبته (A وC...) ومعها خياراته وعناصر الكومبو، والإجمالي الفرعي، والضرائب لكل مجموعة ضريبية مع أساسها، والإجمالي، وطرق الدفع والباقي، وملاحظة العميل، ونص التذييل. في آخره باركود Code-128 لرقم الإيصال، ورمز QR فيه رابط بوابة أودو مع رمز الطلب: يمسحه العميل ليحصل على فاتورته.

الطباعة

• طباعة تفتح نافذة طباعة المتصفح وتطبع الإيصال وحده.
• الإعدادات ثم الجهاز: عرض ورق الإيصال (58 أو 80 مم) وطباعة الإيصال تلقائيًا (تفتح النافذة فور التصديق).
• الطباعة عبر المتصفح فقط. يعرض Chrome نافذة الطباعة في كل مرة إلا إذا شُغِّل بالخيار --kiosk-printing: عندها يطبع صامتًا على الطابعة الافتراضية للنظام.
• لا يتحدث الجهاز مع الطابعات بأوامر ESC/POS مباشرة، ولا يقود صندوق IoT. طابعات الإيصالات والمطبخ يجب أن يستطيع نظام التشغيل الطباعة عليها (الفصلان 21 و27).

ما يحفظه الجهاز

في IndexedDB داخل المتصفح: المنتجات ومتغيراتها والكومبو والعملاء والضرائب والأوضاع المالية وقوائم الأسعار وبرامج الولاء وإعدادات نقطة البيع، والطلبات المفتوحة والمدفوعة التي لم تُرسل. يبدأ الجهاز دون شبكة منذ أول زيارة ناجحة لأن ملفات التطبيق نفسها محفوظة عند الجهاز بواسطة الـ service worker (الفصل 4).

الشريط العلوي يوضح الحالة: متصل، أو غير متصل، أو «غير متصل · طلبان بانتظار الإرسال» (يتغير الرقم). الضغط عليه يفتح شاشة المزامنة. عند التصديق دون اتصال يقول الإيصال: «حُفظ على هذا الجهاز. سيُرسل إلى أودو تلقائيًا.»

قائمة الانتظار

• تُرسل الطلبات واحدًا واحدًا، الأقدم أولًا. لا يُرسل طلب قبل أن يكتمل السابق.
• كل طلب يُرسل مرة واحدة: لكل طلب معرّف فريد، وإذا ضاع رد أودو ثم أعاد الجهاز الإرسال فإن أودو يتعرّف على الطلب بمعرّفه ولا ينشئ نسخة ثانية.
• العملاء الذين أُنشئوا دون اتصال يُرسلون قبل الطلبات التي تنتظرهم، وتأخذ الطلبات رقم العميل في أودو بعد إنشائه.
• متى يحاول الجهاز؟ عند عودة الاتصال، وعند العودة إلى نافذة التطبيق، ومرة كل 30 ثانية ما دام في الانتظار شيء، وعند الضغط على مزامنة الآن. وإذا بقي المتصفح «متصلًا» بينما أودو أو التطبيق متوقف، يفحص الجهاز أودو بطلب خفيف ويرسل حالما يجيب.

التنزيل من أودو

بعد التنزيل الكامل الأول يطلب الجهاز التغييرات فقط (المنتجات والأسعار والعملاء...) كل 5 دقائق أثناء الاتصال (من الإعدادات ثم البيانات)، وعند الضغط على تنزيل البيانات الآن. إذا تغيّرت ضريبة بعد أن بِعتَ طلبًا فإن الجهاز يسجّل ذلك في سجل الأحداث ويرسل الطلب كما سُجّل وقت البيع، لأن العميل دفع هذا المبلغ. إذا فتحت التطبيق في تبويبين من المتصفح نفسه فإنهما يتشاركان البيانات، ويرسل واحد منهما فقط في كل مرة.

ما الذي قد يسوء

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

في تفاصيل الطلب: حالته (مدفوع أو مُرحّل أو ملغى أو مسودة أو حجز بعربون أو استرداد) وحالة إرساله (تمت المزامنة أو بانتظار الإرسال أو إعادة المحاولة أو خطأ في المزامنة...)، والعميل، ورقم الإيصال ورقم التتبع والفاتورة، والبنود، والإجماليات، والمدفوعات، وسجل المزامنة (متى أُنشئ الطلب على الجهاز ومتى أكّده أودو وبأي اسم).

الاسترداد

اضغط استرداد على طلب أكّده أودو. تفتح نافذة فيها كل بند مع عدّاد، وتحت كل بند «المُباع» و«المُسترد». اضغط استرداد الكل أو اختر البنود والكميات، ويظهر «المبلغ المُعاد». يحسب الجهاز ما سُبق استرداده من هذا الجهاز فلا تتجاوز الكمية ما بقي. ثم متابعة الاسترداد: تفتح شاشة الدفع بمبالغ سالبة لتردّ المبلغ للعميل بطريقة الدفع المناسبة (الفصل 11). في الإعدادات يمكنك طلب رمز المدير قبل الاسترداد.

الأزرار في الأعلى: مزامنة الآن (إرسال ما ينتظر)، وتنزيل البيانات الآن (جلب تغييرات أودو)، وإغلاق الجلسة (الفصل 20)، وتصدير التشخيص (ملف للدعم، بلا كلمات مرور ولا مفاتيح: لا يحوي من الطلبات إلا هويتها وحالة مزامنتها، ولا بنودها ولا عملاءها). الزران الأولان يعملان أثناء الاتصال فقط.

قائمة الانتظار

تعرض الطلبات والتغييرات الأخرى في طريقها إلى أودو (عميل جديد وتعديل عميل ونقاط الولاء وإلغاء طلب الطاولة في أودو وإيداع / سحب نقدي وإغلاق الجلسة)، المشكلات أولًا ثم الأقدم. لكل عنصر حالته وعدد محاولاته وموعد المحاولة التالية («المحاولة التالية خلال ...») وآخر خطأ مع طريقة إصلاحه. إعادة المحاولة الآن أو إعادة محاولة الكل ترسل في الحال. إذا كانت الرسالة تقول «لن يُرسل مجددًا» فالطلب لن يُرسل ثانية فراجعه في أودو (مثل طلب حفظه أودو دون أن يتحقق من دفعه).

سجل الأحداث

آخر الأحداث بمرشحات الكل والتحذيرات والأخطاء. يحتفظ الجهاز بآخر 500 حدث. أسطر السجل تُحفظ بالإنجليزية.

الاتصال والبيانات والتخزين

مخطط الصالة

افتح الطاولات من الشريط الجانبي. في الأعلى تبويب لكل طابق (الطابق الأرضي والتراس) وعليه عدد الطاولات المفتوحة، وشرائح بعدد الطاولات في كل حالة: شاغرة ومشغولة وبانتظار الدفع، وزر دمج. الطاولات تظهر في مواضعها وأشكالها وأحجامها من أودو (مربعة أو دائرية)، والمخطط يتكيّف مع الشاشة. في الواجهة العربية لا ينعكس المخطط: المواضع مواضع فعلية في القاعة، والباقي هو الذي ينعكس.

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

طلب الطاولة

اضغط طاولة: تفتح شاشة البيع وطلب هذه الطاولة (طلب جديد إن كانت شاغرة). تضاف إلى لوحة الطلب شريحة الطاولة بعدد الضيوف، وزر اطلب، وعلى كل بند علامة: في المطبخ (وصل إلى المطبخ) أو لم يُرسل (جديد) أو «+1 للإرسال» أو «1 للإلغاء» عند تغيير الكمية بعد الإرسال.

الضغط على شريحة الطاولة يفتح لوحة فيها:

• الضيوف: عدّاد عدد الضيوف.
• نوع الخدمة: أنواع الخدمة المعرّفة في أودو (مثل تناول الطعام في المطعم أو السفري أو التوصيل). تغييره يغيّر قائمة أسعار الطلب ووضعه المالي كما في أودو.
• تقسيم الفاتورة والفاتورة ونقل وفك الدمج ومخطط الصالة (للعودة إلى المخطط).
• المطبخ: ما سيُرسل الآن، وزر اطلب، ومعاينة التذكرة، وإعادة الطباعة، وسجل عدد التذاكر المطبوعة.

إرسال الطلب إلى المطبخ

الزر اطلب يرسل ما تغيّر فقط منذ آخر إرسال. الرقم على الزر هو عدد التغييرات (إرسال 3 تغييرات إلى المطبخ). يطبع الجهاز تذكرة لكل طابعة مطبخ، فيذهب كل صنف إلى الطابعة التي تحوي فئته في أودو. الأصناف التي لا تأخذها أي طابعة تُطبع على محطة افتراضية اسمها أصناف أخرى، وإذا لم تُضبط أي طابعة طلبات تُطبع كلها هناك. التذكرة مقسّمة إلى أقسام: جديد وتعديل (يُكتب +1 أو -1 مع «الكمية الآن») وملغى. وفي رأسها الطاولة والطابق ونوع الخدمة ومرجع الطلب وعدد الضيوف والنادل (النادل) والوقت، ومعها ملاحظات الأصناف والملاحظة الداخلية وملاحظة العميل وخيارات الصنف، وعناصر الكومبو تحت اسم الكومبو. لا تُرسل إلى المطبخ الإكراميات ولا الخصومات ولا المكافآت.

معاينة التذكرة تعرض التذاكر قبل الإرسال، وإعادة الطباعة تعيد طباعة آخر تذكرة وتحمل الشارة نسخة مكررة. كل تذكرة مهمة طباعة مستقلة من المتصفح (الفصل 11)؛ يعرض Chrome نافذة الطباعة لكل تذكرة إلا إذا شُغِّل بالخيار --kiosk-printing. لا يقود التطبيق صندوق IoT ولا طابعات Epson ePOS الشبكية المضبوطة في أودو: كل محطة مطبخ تحتاج إلى طابعة يستطيع نظام التشغيل الطباعة عليها، أو إلى متصفح ثانٍ عند المحطة (الفصل 27).

تقسيم الفاتورة

اضغط تقسيم الفاتورة (من لوحة الطاولة أو من المزيد). لكل بند عدّاد بالكمية التي ستنتقل إلى الفاتورة الجديدة، وزر الكل. الأداة حصة متساوية: اكتب عدد الضيوف ثم اضغط «تحديد حصة من 4 حصص» فيحدد الجهاز جزءًا من كل بند (وحدات كاملة)، وتعدّل بعده ما تشاء، ومسح يمسح الاختيار. تعرض النافذة الفاتورة الجديدة وما يبقى على الطاولة. ثم اختر إبقاؤها مفتوحة أو دفع هذه الفاتورة.

الفاتورة والإكرامية

الفاتورة تفتح معاينة الفاتورة: فاتورة مبدئية عنوانها «فاتورة - ليست إيصال دفع». لإضافة الإكرامية اختر بلا إكرامية أو 5% أو 10% أو 15% أو 20% من قيمة الفاتورة، أو اكتب مبلغ آخر واضغط تطبيق. تصبح الإكرامية بندًا بمنتج الإكرامية المضبوط في أودو، وتُستبدل إذا غيّرتها وتُحذف إذا اخترت بلا إكرامية. طباعة الفاتورة تطبع الفاتورة المبدئية وتصبح الطاولة «بانتظار الدفع»، والدفع ينقلك إلى شاشة الدفع (الفصل 11).

النقل والدمج

نقل في لوحة الطاولة ينقلك إلى المخطط مع الرسالة «نقل {الطلب}: اضغط على الطاولة الجديدة». إذا كانت الطاولة الجديدة شاغرة تتغير الطاولة فقط. وإذا كانت مشغولة تنضم الأصناف إلى طلبها (الأصناف المتطابقة تجتمع) ثم يُلغى طلب الطاولة القديمة. وللدمج اضغط دمج على المخطط: اختر الطاولة التي تريد نقلها («دمج الطاولات: اضغط على الطاولة المراد نقلها») ثم الطاولة الهدف. وللتراجع اضغط فك الدمج داخل الطلب: تعود الأصناف القادمة من طاولة أخرى إلى طلب جديد على تلك الطاولة، بشرط أن تكون شاغرة. حفظ الوجهة يسبق إلغاء المصدر، فلو انقطع التطبيق في اللحظة بينهما بقيت الأصناف في الطلبين ولا تضيع.

مصدر الأرقام: أرقام أودو للفترة المختارة، مضافًا إليها طلبات هذا الجهاز التي لم تُرسل بعد (فلا يضيع منها شيء ولا يُحسب شيء مرتين). تحت العنوان وقت الحساب «حتى 02:51 م» وعدد الطلبات المنتظرة المشمولة. دون اتصال تعرض اللوحة آخر إجابة محفوظة للفترة نفسها مع طلبات الجهاز، وتكتب «نتيجة محفوظة من ... (دون اتصال)» أو «هذا الجهاز فقط (دون اتصال)».

اكتب في حقل ابحث عن منتج الاسم أو المرجع أو الباركود، واختر النتيجة. تظهر لكل مستودع الأعمدة: المتوفر والمحجوز والمتاح والوارد. مستودع نقطة البيع الحالية يأتي أولًا بالشارة هذا المتجر. الكمية المنخفضة (أقل من 5) تُظهر الشارة «مخزون منخفض»، والكمية 0 أو أقل «نفد من المخزون»، وكلاهما مظلل. حسب الموقع يفتح الكميات لكل موقع داخل المستودع. المنتج الذي له متغيرات يظهر بعدد متغيراته.

دون اتصال يعرض الجهاز آخر نتيجة سبق أن استعلمت عنها لهذا المنتج مع وقتها، ويقول «دون اتصال: هذه آخر نتيجة من أودو وليست المخزون الحالي.» ومن لم يُستعلم عنه من قبل يقول «دون اتصال ولم يُستعلم عنه على هذا الجهاز من قبل.» لا تظهر الكميات على بطاقات المنتجات في شاشة البيع.

شروط الحجز، وإلا يرفضه الجهاز برسالة:

1. حدّد العميل وأضف المنتجات، ثم اضغط الدفع.
2. أضف دفعة العربون بطريقة الدفع (دون باقٍ).
3. في لوحة الحجز بعربون ترى المدفوع والمبلغ المتبقي. اضغط إبقاء الطلب مفتوحًا بعربون.
4. يظهر إيصال إيصال العربون (عنوانه «حجز - عربون»، وفي ذيله «احتفظ بهذا الإيصال لاستلام طلبك.») فسلّمه للعميل.

يُرسل الطلب إلى أودو مسودةً مع دفعات العربون. الدفعة التي أُخذت لا تُعدَّل ولا تُحذف من شاشة الدفع، ولا يمكن إلغاء الطلب من الجهاز («سبق استلام عربون على هذا الطلب: حصّل المبلغ المتبقي أو أعد العربون في أودو بدلًا من إلغائه.»).

تحصيل الباقي

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

اختر عميلًا ثم افتح المزيد وبعدها المكافآت وكود الخصم. وتظهر شريحة النقاط في لوحة الطلب برصيد العميل بعد هذا الطلب. إذا لم يكن للعميل بطاقة تقول اللوحة إن بطاقة جديدة ستُنشأ مع الطلب. دون عميل تقول «اختر عميلًا لكسب النقاط واستخدامها.»

ما يدعمه الجهاز وما لا يدعمه

• المنتجان «Gift Card» و«Top-up eWallet» في أودو يختفيان من الكتالوج ومن البحث بالباركود إذا كانا مرتبطين ببرنامج بطاقة هدايا أو محفظة مفعّل، لأن الجهاز لا يستطيع إنشاء البطاقة أو شحنها. إن لم يكن المنتج مرتبطًا ببرنامج مفعّل فهو منتج عادي كما في أودو.
• استعمال نقاط البطاقة يحتاج إلى اتصال: يتحقق الجهاز من أودو أولًا. دون اتصال تظهر «استخدام النقاط يحتاج إلى اتصال». إذا رفض أودو تظهر «رفض أودو: النقاط غير كافية.»
• تُؤكَّد النقاط في أودو بعد إرسال الطلب (عنصر نقاط الولاء في قائمة انتظار المزامنة). والنقاط التي أنفقتها طلبات لم يؤكدها أودو بعد تُخصم من رصيد البطاقة قبل عرض أي مكافأة.
• المكافآت المطبَّقة تتبع الطلب: تُعاد حساباتها بعد كل تغيير، وما لم يعد صالحًا يُزال مع رسالة. إذا أوقفت الميزة والطلب مفتوح تُزال بيانات الولاء منه فورًا.

افتح إغلاق الجلسة من قائمة الجلسة في الشريط العلوي، أو من زر إغلاق الجلسة في شاشة المزامنة، أو من الإعدادات ثم هوية الجهاز.

قبل الإغلاق

تعرض الشاشة قائمة فحوص. لا يتقدم الإغلاق إلا إذا تحققت:

عدّ النقد

في النقد في الدرج اختر عدّ الأوراق والعملات أو إدخال الإجمالي. تظهر النقد المعدود والمتوقع والمعدود والفرق بحالته: «لا يوجد فرق» أو «أكثر من المتوقع» أو «أقل من المتوقع». في طرق الدفع الأخرى اكتب إجمالي جهاز البطاقات إذا اختلف عن أودو؛ يُرحَّل الفرق عند الإغلاق. وتحتها ملخص الجلسة: الطلبات والمبيعات والنقد والمدفوعات من أودو، والضرائب وأكثر المنتجات مبيعًا من طلبات هذا الجهاز. وملاحظة الإغلاق ملاحظة للمدير تُحفظ على الجلسة في أودو.

إذا كان الفرق أكبر من الحد المضبوط في الإعدادات ثم الأمان (فرق النقد الذي يتطلب تأكيدًا، والقيمة الافتراضية 5) فتظهر عبارة تنبّهك، وعند الإغلاق يُطلب منك كتابة اسم الجلسة للتأكيد.

الإغلاق

1. اضغط إغلاق الجلسة (الزر الأحمر).
2. اقرأ نافذة التأكيد «إغلاق ...؟»: يتوقف أودو عن قبول الطلبات ويرحّل القيود، ولا يمكن التراجع من الجهاز.
3. إذا كان الفرق فوق الحد اكتب اسم الجلسة.
4. تظهر نافذة أُغلقت الجلسة و«أغلق أودو الجلسة.» وفيها تقرير الإغلاق.

طباعة تقرير الإغلاق يطبع التقرير ليوقّعه المسؤول. فتح جلسة جديدة يعيدك إلى اختيار نقطة البيع، وتسجيل الخروج يخرج من هذا الجهاز.

تقرير Z الكامل في أودو («تفاصيل المبيعات»، من نقطة البيع ثم التقارير) يحتاج إلى صلاحيات محاسبية لا يملكها أمين الصندوق العادي: يطبعه المدير في أودو. أما ملخص الجلسة في هذه الشاشة فيعرض ما يستطيع الجهاز قراءته من أودو ومن طلباته.

القائمة الجانبية فيها الأقسام: المظهر والجهاز والطباعة والبيانات والأمان والميزات وملف الإعدادات وهوية الجهاز وحول.

المظهر

الجهاز

الطباعة

تُطبع الإيصالات عبر المتصفح على الطابعة التي تختارها. يفتح الجهاز نافذة الطباعة في النظام: اختر طابعة الإيصالات مرة واحدة ويتذكرها المتصفح؛ واضبط الهوامش على «بلا» وحجم الورق على عرض اللفافة؛ والتطبيق المثبّت يطبع دون ترويسة شريط العنوان. الزر طباعة صفحة اختبار يطبع صفحة فيها عرض الورق ونصًا عربيًا للتجربة. طابعات المطبخ والبار قائمة للقراءة فقط تأتي من أودو، وإن لم تُضبط طابعة تقول «لا توجد طابعة طلبات مضبوطة لنقطة البيع هذه.» التطبيق يطبع تذاكره عبر المتصفح، وطباعة IoT Box وEpson ePOS لا يقودها هذا الجهاز (الفصل 27).

البيانات

قسم الأمان في الفصل 25.

الميزات

تشغّل المفاتيح الميزات الاختيارية لهذا الجهاز أو توقفها. الميزة التي تحتاج وحدة غير مثبتة في أودو تظهر بالعبارة «تتطلب ... في أودو» ولا يُحمَّل شيء منها. المطعم يظهر هنا لنقطة بيع المطعم. اللوحة والمخزون يعملان أثناء الاتصال وتبقى آخر نتيجة مقروءة دونه.

ملف الإعدادات

تصدير الإعدادات ينزّل ملف JSON بإعدادات هذا الجهاز. استيراد الإعدادات يقرأ ملفًا ويعرض جدولًا بما سيتغير (الإعداد والآن وبعد الاستيراد) قبل أن تضغط تطبيق. لا يحتوي الملف على اتصال أودو ولا المفاتيح ولا كلمات المرور ولا الرموز. الملف من إصدار أحدث من الجهاز يُرفض: حدّث الجهاز أولًا. إذا كان الاستيراد يوقف حماية برمز المدير فيُطلب رمز المدير.

هوية الجهاز

تعرض كيف يعرف أودو هذا الجهاز: معرّف الجهاز وخادم أودو وقاعدة البيانات واسم الدخول ومستخدم أودو والاتصال ونقطة البيع والجلسة، وزر إغلاق الجلسة.

حول

كيف تعمل المظاهر

كل لون ونصف قطر وحجم في الواجهة متغير CSS اسمه يبدأ بـ --pos- على العنصر :root[data-theme=...] في الملف src/app/globals.css. أهمها: --pos-bg و--pos-surface و--pos-surface-2 و--pos-border و--pos-fg و--pos-muted و--pos-primary و--pos-primary-fg و--pos-accent و--pos-success و--pos-warning و--pos-danger. تربط الكتلة @theme inline فئات Tailwind بهذه المتغيرات (مثل bg-surface وtext-fg وbg-primary)، فتغيير المظهر يغيّر المتغيرات فقط. الألوان التي لا يحددها مظهر تأتي من :root (المظهر الفاتح).

إضافة مظهر

هذه خمسة مواضع، والمثال هو المظهر «محيط» الحقيقي:

/* 1. src/app/globals.css: one block of variables per theme (the tokens a theme does not set come from :root) */
:root[data-theme="ocean"] {
  --pos-bg: #eaf3f9;
  --pos-surface: #ffffff;
  --pos-surface-2: #dcebf4;
  --pos-border: #c4dbe9;
  --pos-fg: #0e2433;
  --pos-muted: #516c7e;
  --pos-primary: #0a6595;
  --pos-primary-fg: #ffffff;
  --pos-accent: #06687f;
}

/* 2. src/lib/theme/prefs.ts: the list of names */
export const THEMES = ['light', 'dark', 'ocean', 'forest', 'sunset'] as const

/* 3. src/lib/theme/themes.ts: the colours of the small theme chips (a test keeps them equal to the stylesheet) */
ocean: { bg: '#eaf3f9', surface: '#ffffff', primary: '#0a6595', accent: '#06687f' },

/* 4. src/app/layout.tsx: the boot script, so there is no flash of the wrong theme */
var T=['light','dark','ocean','forest','sunset'];

/* 5. src/lib/i18n/en/core.ts and ar/core.ts: the name shown on the chip */
'theme.ocean': 'Ocean',

الاختبار src/lib/theme/contrast-themes.test.ts يقيس تباين كل زوج ألوان يستعمله النص في كل مظهر ويفشل إن نزل عن 4.5:1، ويتأكد من أن ألوان الشرائح الصغيرة تطابق الملف globals.css. شغّله بعد إضافة المظهر: npx vitest run src/lib/theme.

لون العلامة التجارية (الإعدادات ثم المظهر) يغيّر --pos-primary وحده، ويختار الجهاز لون النص فوقه تلقائيًا بالتباين الأفضل. لا يحتاج إلى مظهر جديد.

اتجاه الصفحة (RTL)

الاتجاه يتبع اللغة: يكتب التطبيق dir على العنصر html (rtl للعربية). الأنماط تستعمل خصائص منطقية (مثل ms-* وps-* وtext-start) بدل اليمين واليسار، فتنقلب الواجهة وحدها. المبالغ تُعزل لتبقى بالاتجاه من اليسار إلى اليمين. مخطط صالة المطعم لا ينقلب لأن مواضع الطاولات مواضع فعلية.

إضافة لغة

لكل لغة مجلد src/lib/i18n/<lang>/ فيه الملفات نفسها التي في src/lib/i18n/en/ (close وcore وcustomers وlock وorders وpayment وpro وrestaurant وscreens وsell وsettings وsetup وsync)، وبالمفاتيح نفسها. الاختبار في src/lib/i18n/ يفشل إن نقص مفتاح أو متغير نصي في الترجمة. الرسائل التي فيها عدد تحتاج أشكال الجمع التي تتطلبها اللغة: في الإنجليزية شكلان، وفي العربية ستة (zero وone وtwo وfew وmany وother). المصطلحات المعتمدة في src/lib/i18n/GLOSSARY.md.

اللغتان الحاليتان مكتوبتان صراحة في الشيفرة، فلإضافة لغة ثالثة عدّل أيضًا:

• src/lib/theme/prefs.ts: النوع Lang والقائمة LANGS والتحقق من القيمة المحفوظة.
• src/lib/i18n/index.ts (دالة dirOf للاتجاه) وformat.ts (رمز اللغة للأرقام والتواريخ) وplural.ts (قواعد الجمع).
• src/app/layout.tsx: سكربت الإقلاع الذي يضبط اللغة والاتجاه قبل الرسم.
• src/components/setup/prefs-chips.tsx: شرائح اختيار اللغة.
• تسجيل الرسائل بـ registerMessages في src/lib/i18n/messages.ts وsrc/lib/screens/messages.ts وملف تسجيل الميزات في src/components/extensions/.

المحرك مكتوب بـ TypeScript ومنقول من شيفرة أودو 19: ملف الضرائب account_tax.js وقواعد نقطة البيع (قوائم الأسعار والأوضاع المالية والكومبو والمتغيرات وتقريب النقد والخصم العام). يدعم تقريب الضريبة لكل بند ولكل الطلب (round_per_line وround_globally). ملفات المحرك في src/lib/engine/ ومذكورة في الملف NOTICE وتبقى تحت رخصة LGPL-3.0 (نصها في LICENSE-LGPL-3.0.txt)، والمسموح لك تعديلها وإعادة توزيعها بتلك الرخصة.

كيف فُحص

أين يختلف أودو عن نفسه

في الحالات التالية يختلف عميل أودو (جافاسكربت نقطة البيع) عن خادمه (بايثون). الجهاز يحسب كما تحسب نقطة بيع أودو، لأن هذا ما يُرسَل ويُحفظ:

وللجهاز اختلافان مقصودان عن عميل أودو: يصفّي عناصر قائمة الأسعار بتواريخها وقت البيع أيضًا (نقطة البيع تصفّيها عند التحميل فقط، فجهاز يعمل أيامًا يُبقي عروضًا منتهية)، ويقرّب إجماليات البنود إلى العملة.

ما لا يدعمه المحرك

• الضرائب المحسوبة بشيفرة بايثون (النوع code): يقول الجهاز «لا يمكن حساب إحدى ضرائب هذا المنتج دون اتصال. اطلب من المدير مراجعة إعداد الضرائب.»
• قوائم الأسعار بعملة غير عملة نقطة البيع، وتحويل وحدات القياس في قوائم الأسعار: تُتجاهل، كما تفعل نقطة بيع أودو.
• الخصم العام في نقطة بيع عملتها غير عملة الشركة: تُترك مبالغ عملة الشركة في بيانات الضريبة الإضافية ويحسبها الخادم.
• الدولة المالية البرتغالية (PT) فُحصت بأدوات بايثون فقط.
• الضريبة المجهولة على بند (من شركة أخرى أو محذوفة) تُسقط ويرفض الخادم مزامنة هذا البند.
• نقاط الولاء لا يحسبها المحرك: تعاملها طبقة الولاء (الفصل 19).

الأجزاء

خارج src/: المجلد deploy/ (أمثلة nginx، وdeploy/webapp/ وفيه ملف التشغيل وREADME للتطبيق الجاهز للتشغيل) والمجلد scripts/ (مولّدا service worker وملف التراخيص، وscripts/pack-webapp.mjs الذي يجمّع المجلد الجاهز للتشغيل من نسخة البناء المستقلة بالأمر npm run pack:webapp).

البيانات المحلية

في IndexedDB جدول لكل نموذج أودو، باسم النموذج مع استبدال النقطة بـ «_» (مثل product_product وres_partner وaccount_tax وloyalty_program وrestaurant_table)، ومفتاحه id. وجداول الجهاز: orders (مفتاحها uuid)، وops (قائمة العمليات غير الطلبات: عميل جديد، حركة نقد، إغلاق جلسة، نقاط ولاء، إلغاء طلب طاولة)، وimages (صور المنتجات)، وlog (سجل الأحداث، 500 حدث)، وmeta (الاتصال والهوية والجلسة والوحدات المثبتة وعلامة آخر تنزيل...).

من أودو وإليه

• التنزيل بمحمّل أودو نفسه pos.session.load_data لكل شيء عدا المنتجات، وهي تُنزَّل صفحات بـ product.template.load_product_from_pos بحقول أودو وقواعده. التنزيل التراكمي يعتمد علامة وقت الخادم، ويراجع الحذف بـ pos.session.filter_local_data.
• الطلبات: pos.order.sync_from_ui طلبًا واحدًا في كل استدعاء، وفريد بمعرّف الطلب. المسودات (الطاولات والحجز) تُرسل بحالة draft.
• الخطأ يُصنَّف: خطأ شبكة (يُعاد) أو خطأ عمل (يتوقف ويبقى للمراجعة).

سجل الميزات وإضافة ميزة احترافية

كل شاشة اختيارية ميزة تسجّل نفسها بالدالة registerFeature: معرّف، وفئة، وما تحتاجه من وحدات أودو أو اتصال، وموضعها في الشريط الجانبي، ودالة تحمّل شاشتها. الميزة التي تنقصها وحدة لا تُحمَّل شيفرتها ولا تظهر. خطوات إضافة ميزة اسمها «giftcards» مثلًا:

1. المنطق في src/lib/pro/giftcards/: دوال صرفة مع اختباراتها. الشبكة عبر getOdooCaller() فقط (تعيد null دون اتصال) والتحقق من كل جواب بـ Zod.
2. ما يجب أن يبقى مقروءًا دون اتصال يُخزَّن بـ readCache وwriteCache (مفتاح pro.giftcards.* في meta).
3. الواجهة في src/components/pro/giftcards/: شاشة بتصدير افتراضي و/أو شريحة داخل شاشة أخرى (تُحمَّل بـ lazy()).
4. الرسائل: مفاتيح pro.giftcards.* في src/lib/i18n/en/pro.ts وفي ar/pro.ts (الاختبار يفشل إن نقص مفتاح عربي).
5. التسجيل في ملف الميزات الاحترافية في src/components/extensions/ (المثال أدناه).
6. أضف المعرّف إلى PRO_FEATURE_IDS في src/lib/pro/features.ts ونصّي pro.feature.giftcards وpro.feature.giftcards_desc: فيكون له مفتاح في الإعدادات ثم الميزات (مفعّل افتراضيًا).
7. لا تستورد شيفرة الميزة استيرادًا مباشرًا من ملف التسجيل: الميزة المعطّلة أو الوحدة الناقصة يجب ألا تحمّل شيئًا.

// the registration file of the Pro features (src/components/extensions/): one call per feature
registerFeature({
  id: 'giftcards',
  title: 'Gift cards',
  tier: 'pro',
  requires: { modules: ['pos_loyalty'] },
  nav: { icon: 'gift', labelKey: 'pro.giftcards.title', order: 65 },   // place in the left rail (stock is 60, sync is 70)
  screen: () => import('@/components/pro/giftcards/giftcards-screen'), // loaded only when the feature is on
  // optional: cartSlot, paymentSlot, orderActions, settingsPanel
})

الاختبارات

npm test               # Vitest: unit and integration tests (a fake Odoo inside the test process), engine tests
npm run typecheck      # TypeScript
npm run lint           # ESLint

الاختبارات الحيّة (أمام أودو 19 حقيقي) تُتخطّى ما لم تضبط هذه المتغيرات:

POS_TEST_URL=http://localhost:8069 POS_TEST_DB=mydb POS_TEST_LOGIN=cashier POS_TEST_SECRET=<api key> \
POS_TEST_ADMIN_SECRET=<admin api key> npx vitest run tests/live

إضافة إلى ذلك 66 اختبارًا حيًا تحتاج إلى أودو يعمل وتُتخطّى افتراضيًا.

مفتاح أودو على الجهاز

يحفظ المتصفح مفتاح API (أو كلمة المرور) في IndexedDB. مع رمز PIN للقفل يُشفَّر المفتاح بـ PBKDF2-SHA-256 (310,000 تكرار) وAES-GCM ويُطلب الرمز عند تشغيل الجهاز وبعد القفل التلقائي. الرمز من 6 إلى 12 رقمًا. من يملك نسخة من ملفات المتصفح يستطيع تجربة الرموز القصيرة دون اتصال، وعدّاد المحاولات في الملفات نفسها. لذلك:

• الرمز يحمي من الوصول العابر، لا من فحص القرص جنائيًا.
• استعمل مفتاح API واحدًا لكل جهاز، لمستخدم من مجموعة نقطة البيع فقط (الفصل 5).
• إذا ضاع الجهاز فألغِ مفتاحه في أودو (التفضيلات ثم أمان الحساب).

عندما يكون الجهاز مقفلًا تظهر الشاشة الجهاز مقفل. يمكنك فتح القفل بالرمز، أو تسجيل الخروج من هذا الجهاز دون رمز: يحذف الجهاز عندها بيانات الدخول إلى أودو والبيانات المنزّلة، وتبقى الطلبات التي لم تُرسل بعد على الجهاز وتُرسل بعد تسجيل الدخول التالي.

الوسيط /api/odoo

• يمرّر إلى أودو مسارات مسموحة فقط (/jsonrpc و/json/2/... وإصدار الخادم وصور المنتجات وقائمة القواعد)، ولا يتبع التحويلات، ولا يمرّر ملفات تعريف الارتباط من المتصفح ولا يعيد Set-Cookie.
• يفحص كل عنوان يُحَلّ إليه اسم خادم أودو. عناوين link-local وبيانات السحابة الوصفية مرفوضة دائمًا. والشبكات الخاصة مرفوضة إلا بـ POS_ALLOW_PRIVATE أو إذا ذُكر العنوان في POS_ALLOWED_ORIGINS.
• محاولات الدخول الفاشلة: 10 في 10 دقائق ثم الرد 429 مدة 10 دقائق. دون POS_TRUST_PROXY=1 يتشارك كل العملاء هذه الحصة لكل خادم أودو، فعشر محاولات فاشلة من أي جهة توقف الدخول والمزامنة لكل الأجهزة عشر دقائق.
• فحص المصدر نفسه (أن الطلب من الصفحة نفسها)، وحد 25 ميغابايت و60 ثانية، والسجلات بلا محتوى ولا مفاتيح.
• ترويسات سياسة الأمان (Content-Security-Policy وغيرها) في next.config.ts، ولا تسمح الصفحة بالاتصال إلا بنفسها (والعناوين المذكورة في POS_CONNECT_SRC).

الإجماليات

يحسب الجهاز الأسعار والضرائب والتقريب بمحرك منقول من شيفرة نقطة بيع أودو 19 (الفصل 23). فُحص مقابل أدوات بايثون في أودو نفسه على 667 سيناريو (يطابقها الجهاز كلها)، وأُرسل 447 منها إلى أودو بـ sync_from_ui وقُرئت ثانيةً. ومقابل جافاسكربت نقطة بيع أودو يطابق الجهاز 664 سيناريو من 667، والثلاثة الباقية استثناءات موثّقة. وأُعيد إنتاج 1,149 طلبًا بمسار البيع الحقيقي وأُرسلت إلى أودو بصفة أمين صندوق: يطابق الجهاز بايثون في كل طلب (حُفظ 1,085 ورفض أودو 64 بخطأ صلاحيات على منتجات الدفعة / الرقم التسلسلي).

في بضع حالات يختلف عميل أودو عن خادمه (وضع مالي بلا ربط ضريبي، وتقريب النقد على الطلب كله مع باقٍ، وسعر سالب مع التقريب الشامل). الجهاز يتبع عميل أودو. الجدول في الفصل 23، وأهمها: لا تترك وضعًا ماليًا بلا ربط ضريبي صريح.

ضمانات العمل دون اتصال

ما قيس وأين

الاختبارات

الأمر npm test ينجح بـ 3,336 اختبارًا (Vitest)، ويتخطى 66 اختبارًا حيًا تحتاج إلى أودو 19 يعمل. تفصيلها في الفصل 24.

ما لم يُفحص

• الطابعات (الإيصالات والمطبخ) والماسحات وأدراج النقد وأجهزة الدفع على أجهزة حقيقية.
• Safari وFirefox. الفحص على Chrome وEdge.
• أودو Enterprise، وإصدارات أودو غير 19.
• صورة Docker: الملفات مرفقة والصورة لم تُبنَ ولم تُختبر هنا.
• أداء الأجهزة اللوحية.

أثناء الاتصال والإعداد

الرسائل الست الأولى في الفصل 6. هذه بقيتها:

أثناء البيع

طلبات لم تصل إلى أودو

تجدها في الطلبات ثم الأخطاء، وفي شاشة المزامنة. الرسالة تحت الطلب تقول السبب:

تحديث الخادم

1. احتفظ بنسخة من الملف .env ومن أي ملفات عدّلتها.
2. التطبيق الجاهز للتشغيل: فُكّ ضغط الملف taqnix-pos-terminal-webapp.zip الجديد في مجلد جديد وانسخ ملف .env إليه، ثم أوقف الجهاز القديم وشغّل الجديد.
3. من الشيفرة المصدرية: استبدل ملفات التطبيق بملفات الإصدار الجديد، ونفّذ الأمرين أدناه ثم أعد تشغيل التطبيق (أو أعد بناء صورة Docker).

npm ci && npm run build

تحديثات الإصدار 1.x مشمولة بالشراء.

على جهاز البيع

عند فتح التطبيق ينزّل الـ service worker الإصدار الجديد في الخلفية. عندما يكتمل تظهر رسالة «إصدار جديد من الجهاز جاهز.» وزرّان: تحديث ولاحقًا. اضغط تحديث في وقت هادئ: يحفظ الجهاز الطلب المفتوح ثم يعيد التحميل. ما دمت لم تضغط فالجهاز يستمر على الإصدار القديم ولا يعيد التحميل وحده. وللسؤال بنفسك: الإعدادات ثم حول ثم التحقق من وجود تحديث.

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

النسخ الاحتياطي

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

اكتب في رسالتك: إصدار أودو، والمتصفح ونظام التشغيل، ولقطة للشاشة، وملف تصدير التشخيص من شاشة المزامنة. ملف التشخيص لا يحتوي مفاتيح ولا كلمات مرور، ولا بنود الطلبات ولا العملاء.

الترخيص باختصار

النص الكامل في الملف licensing/license.txt.

أودو علامة تجارية لشركة Odoo S.A. وهذا المنتج لم تصنعه Odoo S.A. ولم تعتمده.