feat: add advanced troubleshooting docs [DV-4240]

.vitepress/locales.ts

@@ -85,6 +85,14 @@ regions.forEach((region: RegionsType) => {
         { text: "KuCoin", link: `/${region.slug}/exchanges/kucoin.md` }
       ],
     },
+    {
+      text: tHandler(region.slug, "Advanced Troubleshooting"),
+      collapsible: true,
+      collapsed: false,
+      items: [
+        { text: tHandler(region.slug, "Re-reading a Block from Blockchain"), link: `/${region.slug}/advanced-troubleshooting/re-reading-block-from-blockchain.md` },
+      ],
+    },
     {
       text: tHandler(region.slug, "API Integration"),
       collapsible: true,

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## [Unreleased]
 
 - fix: remove unnecessary translations from the connecting-payment-form-without-api page [DV-4160]
+- feat: add Advanced Troubleshooting section and “Re-reading a Block from Blockchain” page (all locales) [DV-4240]
 
 ## [0.0.20]
 

src/ar/advanced-troubleshooting/re-reading-block-from-blockchain.md

@@ -0,0 +1,97 @@
+# إعادة قراءة كتلة من البلوكشين
+
+> ⚠️ **للمستخدمين المتقدمين فقط.** تتم جميع الإجراءات على مسؤوليتك الخاصة. قد تؤدي التغييرات الخاطئة في قاعدة البيانات إلى فقدان أو تكرار المعاملات. تأكد من فهم كل خطوة قبل المتابعة.
+
+## المشكلة
+
+بسبب إعادة تنظيم الكتل في شبكة إيثريوم، قد تكون المعاملة المؤكدة على البلوكشين مفقودة من النظام. يحدث هذا عندما تعالج المعالجة كتلة من فرع سلسلة مؤقت (مُهمَل) وتتخطى الكتلة المقابلة من السلسلة الرئيسية. لاستعادة الحالة الصحيحة، تحتاج إلى تشغيل إعادة قراءة الكتلة المطلوبة يدويًا.
+
+## الحل
+
+### 1. إنشاء نسخة احتياطية من قاعدة البيانات
+
+```bash
+sudo -u postgres pg_dump dv-processing > /tmp/dv-processing_backup_$(date +%Y%m%d_%H%M%S).sql
+```
+
+تحقق من إنشاء الملف وأنه غير فارغ:
+
+```bash
+ls -lh /tmp/dv-processing_backup_*.sql
+```
+### 2. (!مهم — في طرفية منفصلة) إيقاف المعالجة
+
+```bash
+sudo systemctl stop dv-processing
+```
+### 3. (في الطرفية الرئيسية) التبديل إلى مستخدم قاعدة البيانات
+
+```bash
+sudo su
+sudo su - postgres
+```
+### 4. (في الطرفية الرئيسية) تشغيل psql
+
+```bash
+psql
+```
+
+أو
+
+```bash
+/home/dv/embedded/usr/local/pgsql/bin/psql -p 5433
+```
+### 5. (في الطرفية الرئيسية) الاتصال بقاعدة بيانات dv-processing
+
+```sql
+\c dv-processing
+```
+### 6. (في الطرفية الرئيسية) قراءة حالة التحليل الحالية
+
+```sql
+select number from processed_blocks where blockchain = 'bsc';
+```
+
+> !مهم — تذكر النتيجة:
+> ```
+>   number
+> ----------
+>  81923203
+> (1 row)
+> ```
+### 7. (في الطرفية الرئيسية) تحديث القيمة إلى الكتلة -1 من معاملتك
+
+مثال للمعاملة `0xffe238ba2c1e028a8ec1c467cef53fa59112e2ccc922dc64345817f9da0f4e71` — الكتلة `81921203`:
+
+```sql
+update processed_blocks set number = 81921203 where blockchain = 'bsc';
+```
+### 8. (!مهم — في طرفية منفصلة) تشغيل المعالجة
+
+```bash
+sudo systemctl start dv-processing
+```
+### 9. (في الطرفية الرئيسية) بعد دقيقتين، تحقق من تقدم الكتل
+
+يجب أن تزداد القيمة بعشرات أو مئات من `81921203` — وهذا يشير إلى إعادة قراءة ناجحة للكتلة.
+
+```sql
+select number from processed_blocks where blockchain = 'bsc';
+```
+### 10. (!مهم — في طرفية منفصلة) إيقاف المعالجة
+
+```bash
+sudo systemctl stop dv-processing
+```
+### 11. (في الطرفية الرئيسية) استعادة قيمة الكتلة إلى ما دونته في الخطوة 6
+
+```sql
+update processed_blocks set number = 81923203 where blockchain = 'bsc';
+```
+### 12. (!مهم — في طرفية منفصلة) تشغيل المعالجة
+
+```bash
+sudo systemctl start dv-processing
+```
+
+بعد ذلك، من المرجح أن تُلتقط المعاملة.

src/ar/t.json

@@ -64,6 +64,8 @@
   "Connecting a payment form without API": "ربط نموذج الدفع بدون API",
   "Connecting exchanges": "ربط البورصات",
   "Exchanges": "البورصات",
+  "Advanced Troubleshooting": "استكشاف الأخطاء المتقدم",
+  "Re-reading a Block from Blockchain": "إعادة قراءة كتلة من البلوكشين",
   "Exchanges integration": "البورصات",
   "Proxying requests to exchanges": "طلبات الوكيل إلى البورصات",
   "Security": "الأمن",

src/de/advanced-troubleshooting/re-reading-block-from-blockchain.md

@@ -0,0 +1,97 @@
+# Block erneut aus der Blockchain lesen
+
+> ⚠️ **Nur für fortgeschrittene Benutzer.** Alle Aktionen erfolgen auf eigenes Risiko. Falsche Änderungen an der Datenbank können zu Verlust oder Duplizierung von Transaktionen führen. Stellen Sie sicher, dass Sie jeden Schritt verstehen, bevor Sie fortfahren.
+
+## Problem
+
+Aufgrund der Block-Reorganisation im Ethereum-Netzwerk kann eine im Blockchain bestätigte Transaktion im System fehlen. Dies geschieht, wenn die Verarbeitung einen Block aus einem temporären (verworfenen) Chain-Zweig verarbeitet und den entsprechenden Block der Hauptkette übersprungen hat. Um den korrekten Zustand wiederherzustellen, müssen Sie das erneute Lesen des erforderlichen Blocks manuell auslösen.
+
+## Lösung
+
+### 1. Datenbanksicherung erstellen
+
+```bash
+sudo -u postgres pg_dump dv-processing > /tmp/dv-processing_backup_$(date +%Y%m%d_%H%M%S).sql
+```
+
+Überprüfen Sie, dass die Datei erstellt wurde und nicht leer ist:
+
+```bash
+ls -lh /tmp/dv-processing_backup_*.sql
+```
+### 2. (!WICHTIG — in einem separaten Terminal) Verarbeitung stoppen
+
+```bash
+sudo systemctl stop dv-processing
+```
+### 3. (im Hauptterminal) Zum Datenbankbenutzer wechseln
+
+```bash
+sudo su
+sudo su - postgres
+```
+### 4. (im Hauptterminal) psql starten
+
+```bash
+psql
+```
+
+oder
+
+```bash
+/home/dv/embedded/usr/local/pgsql/bin/psql -p 5433
+```
+### 5. (im Hauptterminal) Mit der dv-processing-Datenbank verbinden
+
+```sql
+\c dv-processing
+```
+### 6. (im Hauptterminal) Aktuellen Parsing-Zustand auslesen
+
+```sql
+select number from processed_blocks where blockchain = 'bsc';
+```
+
+> !WICHTIG — merken Sie sich das Ergebnis:
+> ```
+>   number
+> ----------
+>  81923203
+> (1 row)
+> ```
+### 7. (im Hauptterminal) Wert auf Block -1 Ihrer Transaktion setzen
+
+Beispiel für Transaktion `0xffe238ba2c1e028a8ec1c467cef53fa59112e2ccc922dc64345817f9da0f4e71` — Block `81921203`:
+
+```sql
+update processed_blocks set number = 81921203 where blockchain = 'bsc';
+```
+### 8. (!WICHTIG — in einem separaten Terminal) Verarbeitung starten
+
+```bash
+sudo systemctl start dv-processing
+```
+### 9. (im Hauptterminal) Nach ein paar Minuten prüfen, ob die Blöcke fortgeschritten sind
+
+Der Wert sollte um mehrere Zehner oder Hunderte von `81921203` gestiegen sein — dies zeigt erfolgreiches erneutes Lesen des Blocks an.
+
+```sql
+select number from processed_blocks where blockchain = 'bsc';
+```
+### 10. (!WICHTIG — in einem separaten Terminal) Verarbeitung stoppen
+
+```bash
+sudo systemctl stop dv-processing
+```
+### 11. (im Hauptterminal) Blockwert auf den in Schritt 6 notierten Wert zurücksetzen
+
+```sql
+update processed_blocks set number = 81923203 where blockchain = 'bsc';
+```
+### 12. (!WICHTIG — in einem separaten Terminal) Verarbeitung starten
+
+```bash
+sudo systemctl start dv-processing
+```
+
+Danach wird die Transaktion mit hoher Wahrscheinlichkeit erfasst.

src/de/t.json

@@ -64,6 +64,8 @@
   "Connecting a payment form without API": "Einbindung eines Zahlungsformulars ohne API",
   "Connecting exchanges": "Börsen verbinden",
   "Exchanges": "Börsen",
+  "Advanced Troubleshooting": "Erweiterte Fehlerbehebung",
+  "Re-reading a Block from Blockchain": "Block erneut aus der Blockchain lesen",
   "Exchanges integration": "Integration der Börse",
   "Proxying requests to exchanges": "Proxy-Anfragen an Börsen",
   "Security": "Sicherheit",

src/en/advanced-troubleshooting/re-reading-block-from-blockchain.md

@@ -0,0 +1,97 @@
+# Re-reading a Block from Blockchain
+
+> ⚠️ **For advanced users only.** All actions are performed at your own risk. Incorrect changes to the database may result in loss or duplication of transactions. Make sure you understand each step before proceeding.
+
+## Problem
+
+Due to block reorganization in the Ethereum network, a transaction that is confirmed on the blockchain may be missing from the system. This happens when processing has handled a block from a temporary (discarded) chain branch and skipped the corresponding block from the main chain. To restore the correct state, you need to manually trigger re-reading of the required block.
+
+## Solution
+
+### 1. Create a database backup
+
+```bash
+sudo -u postgres pg_dump dv-processing > /tmp/dv-processing_backup_$(date +%Y%m%d_%H%M%S).sql
+```
+
+Verify that the file was created and is not empty:
+
+```bash
+ls -lh /tmp/dv-processing_backup_*.sql
+```
+### 2. (!IMPORTANT — in a separate terminal) Stop processing
+
+```bash
+sudo systemctl stop dv-processing
+```
+### 3. (in the main terminal) Switch to the database user
+
+```bash
+sudo su
+sudo su - postgres
+```
+### 4. (in the main terminal) Start psql
+
+```bash
+psql
+```
+
+or
+
+```bash
+/home/dv/embedded/usr/local/pgsql/bin/psql -p 5433
+```
+### 5. (in the main terminal) Connect to the dv-processing database
+
+```sql
+\c dv-processing
+```
+### 6. (in the main terminal) Read the current parsing state
+
+```sql
+select number from processed_blocks where blockchain = 'bsc';
+```
+
+> !IMPORTANT — remember the result:
+> ```
+>   number
+> ----------
+>  81923203
+> (1 row)
+> ```
+### 7. (in the main terminal) Update the value to block -1 of your transaction
+
+Example for transaction `0xffe238ba2c1e028a8ec1c467cef53fa59112e2ccc922dc64345817f9da0f4e71` — block `81921203`:
+
+```sql
+update processed_blocks set number = 81921203 where blockchain = 'bsc';
+```
+### 8. (!IMPORTANT — in a separate terminal) Start processing
+
+```bash
+sudo systemctl start dv-processing
+```
+### 9. (in the main terminal) After a couple of minutes, verify that blocks have advanced
+
+The value should have increased by several tens or hundreds from `81921203` — this indicates successful block re-reading.
+
+```sql
+select number from processed_blocks where blockchain = 'bsc';
+```
+### 10. (!IMPORTANT — in a separate terminal) Stop processing
+
+```bash
+sudo systemctl stop dv-processing
+```
+### 11. (in the main terminal) Restore the block value to what you noted in step 6
+
+```sql
+update processed_blocks set number = 81923203 where blockchain = 'bsc';
+```
+### 12. (!IMPORTANT — in a separate terminal) Start processing
+
+```bash
+sudo systemctl start dv-processing
+```
+
+After this, the transaction will most likely be picked up.

src/en/t.json

@@ -64,6 +64,8 @@
     "Connecting a payment form without API": "Connecting a payment form without API",
     "Connecting exchanges": "Connecting exchanges",
     "Exchanges": "Exchanges",
+    "Advanced Troubleshooting": "Advanced Troubleshooting",
+    "Re-reading a Block from Blockchain": "Re-reading a Block from Blockchain",
     "Exchanges integration": "Exchange Integration",
     "Proxying requests to exchanges": "Proxying requests to exchanges",
     "Security": "Security",