Waafir
هذه الصفحة ترجمة آلية في انتظار المراجعة البشرية. قد تحتوي على أخطاء.

فحص أخطاء الإخفاق الجزئي بعد الاستيراد

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

عند وصول الحالة partial / failed

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

  • partial — نجح صف واحد على الأقل وأخفق صف واحد على الأقل. وصلت الصفوف الصالحة؛ ويمكن الاستعلام عن غير الصالحة عبر هذه الوصفة.
  • failed — لم ينجح أي صف. فإما أن كل الصفوف كانت غير صالحة، أو أن الاستيراد واجه خطأً فادحًا (NDJSON مشوّه، أو فشل في قراءة الملف، أو استثناء في العامل)؛ وفي هذه الحالة يحمل errorSummary خطأً بالبنية الفادحة.

في كلتا الحالتين النهائيتين، الوصفة أدناه هي الأداة المناسبة للتعمّق.

بنية واجهة الأخطاء

تُعيد نقطة نهاية الحالة (GET /api/v1/monitoring/loan/imports/{id}) حقل errorSummary ببنيتين بحسب ما حدث:

  • أخطاء على مستوى الصف (الحالة الشائعة في partial ومعظم عمليات failed): يكون errorSummary هو { samples, totals }. تحمل المصفوفة samples الأخطاء العشرة الأولى بالشكل { rowNumber, errorCode, errorMessage, rawRow }. ويعرض الحقل totals عددًا إجماليًا.
  • أخطاء فادحة (استيراد توقف قبل معالجة أي صف): يكون errorSummary هو { fatal } — خطأ واحد يصف الإخفاق على مستوى العامل.

لأكثر من الأخطاء العشرة الأولى، استخدم وضع الأخطاء المقسّمة إلى صفحات: GET /api/v1/monitoring/loan/imports/{id}?errors=true&limit=&offset=.

الوصفة

# curl — inspect a partial / failed import's errors
set -euo pipefail

PAT="${WAAFIR_PAT}"
BASE_URL="${WAAFIR_BASE_URL:-https://app.waafir.io}"
IMPORT_ID="${1:?supply the import id}"

# Step 1 — fetch the terminal status, see the error summary.
STATUS=$(curl -fsS "${BASE_URL}/api/v1/monitoring/loan/imports/${IMPORT_ID}" \
  -H "Authorization: Bearer ${PAT}")

echo "status:" && echo "$STATUS" | jq '{status, rowCountProcessed, rowCountSucceeded, rowCountFailed}'
echo "first ten errors (sampled):"
echo "$STATUS" | jq '.errorSummary'

# Step 2 — page through every row error. Limit/offset are bounded
# (limit max 100; default 20).
LIMIT=100
OFFSET=0
TOTAL_FAILED=$(echo "$STATUS" | jq -r .rowCountFailed)

while [ "${OFFSET}" -lt "${TOTAL_FAILED}" ]; do
  PAGE=$(curl -fsS \
    "${BASE_URL}/api/v1/monitoring/loan/imports/${IMPORT_ID}?errors=true&limit=${LIMIT}&offset=${OFFSET}" \
    -H "Authorization: Bearer ${PAT}")
  echo "$PAGE" | jq -c '.items[] | {rowNumber, errorCode, errorMessage}'
  OFFSET=$((OFFSET + LIMIT))
done
// TypeScript — inspect a partial / failed import's errors
const PAT = process.env.WAAFIR_PAT!;
const BASE_URL = process.env.WAAFIR_BASE_URL ?? "https://app.waafir.io";
const importId = process.argv[2];
if (!importId) throw new Error("usage: ts-node inspect.ts <importId>");

const auth = { Authorization: `Bearer ${PAT}` };

// Step 1 — terminal status + error summary.
const statusRes = await fetch(`${BASE_URL}/api/v1/monitoring/loan/imports/${importId}`, {
    headers: auth,
});
type Status = {
    status: string;
    rowCountProcessed: number;
    rowCountSucceeded: number;
    rowCountFailed: number;
    errorSummary: unknown;
};
const status = (await statusRes.json()) as Status;
console.log("status:", {
    status: status.status,
    rowCountProcessed: status.rowCountProcessed,
    rowCountSucceeded: status.rowCountSucceeded,
    rowCountFailed: status.rowCountFailed,
});
console.log("error summary (first ten):", status.errorSummary);

// Step 2 — page through every row error.
type RowError = {
    rowNumber: number;
    errorCode: string;
    errorMessage: string;
    rawRow: unknown;
    createdAt: string;
};
const limit = 100;
for (let offset = 0; offset < status.rowCountFailed; offset += limit) {
    const url = `${BASE_URL}/api/v1/monitoring/loan/imports/${importId}?errors=true&limit=${limit}&offset=${offset}`;
    const pageRes = await fetch(url, { headers: auth });
    const page = (await pageRes.json()) as { items: RowError[]; limit: number; offset: number };
    for (const error of page.items) {
        console.log({
            rowNumber: error.rowNumber,
            errorCode: error.errorCode,
            errorMessage: error.errorMessage,
        });
    }
}
# python — inspect a partial / failed import's errors
import os
import sys
import requests

PAT = os.environ["WAAFIR_PAT"]
BASE_URL = os.environ.get("WAAFIR_BASE_URL", "https://app.waafir.io")
import_id = sys.argv[1] if len(sys.argv) > 1 else None
if not import_id:
    raise SystemExit("usage: python inspect.py <importId>")

auth = {"Authorization": f"Bearer {PAT}"}

# Step 1 — terminal status + error summary.
status = requests.get(
    f"{BASE_URL}/api/v1/monitoring/loan/imports/{import_id}",
    headers=auth,
    timeout=30,
).json()
print("status:", {
    "status": status["status"],
    "rowCountProcessed": status["rowCountProcessed"],
    "rowCountSucceeded": status["rowCountSucceeded"],
    "rowCountFailed": status["rowCountFailed"],
})
print("error summary (first ten):", status.get("errorSummary"))

# Step 2 — page through every row error.
LIMIT = 100
offset = 0
total_failed = status["rowCountFailed"]
while offset < total_failed:
    page = requests.get(
        f"{BASE_URL}/api/v1/monitoring/loan/imports/{import_id}",
        params={"errors": "true", "limit": LIMIT, "offset": offset},
        headers=auth,
        timeout=30,
    ).json()
    for error in page["items"]:
        print({
            "rowNumber": error["rowNumber"],
            "errorCode": error["errorCode"],
            "errorMessage": error["errorMessage"],
        })
    offset += LIMIT

ما يجب التحقق منه

في استيراد partial، يساوي مجموع rowCountSucceeded وrowCountFailed القيمة rowCountProcessed، وتكون rowCountSucceeded غير صفرية. وفي استيراد failed، تكون rowCountSucceeded صفرًا — فإما أن كل صف أمكن الوصول إليه أخفق في التحقق، أو أن الحقل errorSummary.fatal يصف إخفاقًا على مستوى العامل.

الحقل rowNumber هو رقم السطر في ملف NDJSON مع البدء من الواحد. اربطه بصفوفك المصدرية للعثور على السجلات المخالفة، وأصلحها، ثم أعد إرسال الصفوف المصحّحة وحدها أو الملف بأكمله (استخدم مفتاح عدم تكرار جديدًا للنية الجديدة — راجع وصفة إعادة المحاولة).

يحمل الحقل rawRow الحمولة المحلَّلة كما استلمتها Waafir (لتتمكن من التحقق من أن بنية البيانات المُرسلة تطابق ما أنشأته شيفرتك)؛ ويمثّل errorCode معرّفًا ثابتًا لقاعدة التحقق التي انطلقت (لتتمكن من مطابقة مجموعات الأخطاء مع قائمة إصلاحات).