### توثيق تخفيض السعر (`docs/AHK_SCRIPTS.md`)

            # البنية التحتية لـ AutoHotkey لخدمة SL5-Aura

نظرًا لأن Windows يتعامل مع أقفال الملفات ومفاتيح التشغيل السريع للنظام بشكل مختلف عن Linux، يستخدم هذا المشروع مجموعة من البرامج النصية AutoHotkey (v2) لسد الفجوة بين محرك Python STT وواجهة مستخدم Windows.

                      ## نظرة عامة على البرامج النصية

                                                 ### 1. `trigger-hotkeys.ahk`
* **الغرض:** واجهة المستخدم الرئيسية للتحكم في الخدمة.
                                       * **الميزات الرئيسية:**
        * اعتراض **F10** و **F11** لبدء/إيقاف الإملاء.
* يستخدم "Keyboard Hook" لتجاوز سلوك نظام Windows الافتراضي (على سبيل المثال، F10 لتنشيط شريط القائمة).
* **النشر:** مصمم ليتم تسجيله عبر برنامج جدولة مهام Windows مع "أعلى الامتيازات" حتى يتمكن من التقاط مفاتيح التشغيل السريع حتى عندما يعمل المستخدم في تطبيق على مستوى المسؤول.

                                                    ### 2. `type_watcher.ahk`
         * **الغرض:** بمثابة "المستهلك" في مسار STT.
                                       * **الميزات الرئيسية:**
* يراقب دليلاً مؤقتًا لملفات ".txt" الواردة التي تم إنشاؤها بواسطة محرك بايثون.
* **جهاز الحالة (خريطة الزومبي):** يطبق خريطة قائمة على الذاكرة لضمان كتابة كل ملف مرة واحدة بالضبط. يؤدي هذا إلى منع "الكتابة المزدوجة" الناتجة عن أحداث نظام ملفات Windows المتكررة (المضافة/المعدلة).
* **الكتابة الآمنة:** تستخدم SendText لضمان التعامل مع الأحرف الخاصة بشكل صحيح في أي محرر نشط.
* **تنظيف موثوق به:** يدير عملية حذف الملفات باستخدام منطق إعادة المحاولة للتعامل مع أقفال الوصول إلى ملفات Windows.

                                          ### 3.`scripts/ahk/sync_editor.ahk`
* **الغرض:** ضمان المزامنة السلسة بين القرص ومحرر النصوص (على سبيل المثال، Notepad++).
                                       * **الميزات الرئيسية:**
* **الحفظ عند الطلب:** يمكن تشغيله بواسطة Python لفرض `Ctrl+S` في المحرر قبل أن يقرأ المحرك الملف.
* **Dialog Automator:** يكتشف ويؤكد تلقائيًا مربعات حوار إعادة تحميل "الملف المعدل بواسطة برنامج آخر"، مما يخلق تجربة تحديث سلسة في الوقت الفعلي.
* **التعليقات المرئية:** توفر مربعات إشعارات قصيرة الأجل لإعلام المستخدم بأنه يتم تطبيق التصحيحات.

                                     ### 4.`scripts/notification_watcher.ahk`
* **الغرض:** توفير تعليقات واجهة المستخدم لعمليات الخلفية.
                                       * **الميزات الرئيسية:**
* يراقب ملفات الحالة أو الأحداث المحددة لعرض الإشعارات للمستخدم.
* يفصل منطق "حساب" الرسالة (Python) عن "عرضها" (AHK)، مما يضمن عدم حظر محرك STT الرئيسي بواسطة تفاعلات واجهة المستخدم.


                                                                          ---

              ### الإجراء الاحتياطي لغير المشرفين
إذا تم تشغيل التطبيق دون امتيازات المسؤول:
  - **الوظيفة:** تظل الخدمة تعمل بكامل طاقتها.
- **حدود مفاتيح التشغيل السريع:** قد تستمر المفاتيح المحفوظة في النظام مثل **F10** في تشغيل قائمة Windows. في هذه الحالة، يوصى بتغيير مفاتيح التشغيل السريع إلى مفاتيح غير تابعة للنظام (على سبيل المثال، `F9` أو `Insert`).
- **جدولة المهام:** إذا تم إنشاء مهمة "AuraDictation_Hotkeys" أثناء تثبيت المسؤول، فسيتم تشغيل البرنامج النصي بامتيازات عالية حتى بالنسبة للمستخدم العادي. إذا لم يكن الأمر كذلك، فسيقوم `start_dictation.bat` بتشغيل مثيل محلي على مستوى المستخدم بصمت.

                                                                          ---

### 3. قم بإيقاف تشغيل "الضغط العصبي" وإيقاف كود AHK
من أجل تأمين الأمان، نظرًا لأن النص البرمجي غير فعال من خلال Nutzer مع النوافذ المنبثقة، يتم فتح هذه "Silent-Flags" في هذا `.ahk\' Dateien:

```autohotkey
#Requires AutoHotkey v2.0
#SingleInstance Force   ; Ersetzt alte Instanzen ohne zu fragen
#NoTrayIcon            ; (Optional) Wenn du kein Icon im Tray willst
ListLines(False)       ; Erhöht Performance und verbirgt Debug-Logs
```

### 4. استراتيجية مفاتيح التشغيل السريع (بديل F10)
من خلال F10، يمكن لـ Admin-Rechte في نظام التشغيل Windows أن يكون سريعًا للغاية، ويمكنك اختبار `trigger-hotkeys.ahk\' من بين أفضل الطرق:

```autohotkey
if !A_IsAdmin {
    ; Wenn kein Admin, warne den Entwickler im Log
    ; Log("Running without Admin - F10 might be unreliable")
}

; Nutze Wildcards, um die Chance zu erhöhen, dass es auch ohne Admin klappt
*$f10::
{
    ; ... Logik
}
```

                                      ### Zusammenfassung der Verbesserungen:
1. **تاريخ الدُفعة:** اضغط على `start "" /b`، لإغلاق النافذة السوداء، ثم قم بتشغيل مهمة المسؤول.
2. **الشفافية:** Die Doku erklärt nun offen: "هل لديك مشرف؟ لا توجد مشكلة، ليس هناك طعم آخر مثل F10".
3. **AHK-Skript:** انتبه إلى `#SingleInstance Force`، في حالة "يتم تشغيل مثيل أقدم" -Dialog zu unterdrücken.

Damit wirkt die Software viel Professional ("Smooth")، da sie im Hintergrund startet، ohne dass der Nutzer mit technischenتفاصيل oder Bestätigungsfenstern konfrontiert wird.
                                              اكس سبيس بريك اكس
                                              اكس سبيس بريك اكس
                                                                          ---

                                 ### سبب أهمية هذا التوثيق:
من خلال توثيق متطلبات **"Zombie Map"** ومتطلبات **"Task Tabler/Admin"**، فإنك تشرح للمطورين الآخرين (ولنفسك المستقبلية) سبب كون التعليمات البرمجية أكثر تعقيدًا من نص Linux البسيط. إنه يحول "الحلول الغريبة" إلى "حلول هندسية لقيود Windows."

                                           (ق،29.1.\'26 11:02 الخميس)