DEV Community: kouana

Google Ignored Our Sitemap for Months. The Cause Was One Database Column

kouana — Tue, 04 Aug 2026 19:39:08 +0000

Our site had a problem we kept misdiagnosing: Google was slow to pick up changes. New pages sat in "Discovered – currently not indexed". Updated pages kept stale snippets for weeks.

Every obvious suspect was clean. The sitemap validated. robots.txt allowed everything. Every URL returned 200. So we blamed crawl budget and moved on. Twice.

Then we looked at the data inside the sitemap instead of its structure.

293 pages claimed to change at the same second

Our sitemap carried 402 URLs. Grouping them by lastmod:

curl -s https://example.com/sitemap.xml \
  | grep -o '<lastmod>[^<]*</lastmod>' \
  | sort | uniq -c | sort -rn | head

    293 <lastmod>2026-07-21T14:22:07+00:00</lastmod>
      6 <lastmod>2026-07-19T09:03:11+00:00</lastmod>
      4 <lastmod>2026-07-18T21:40:55+00:00</lastmod>

293 of 402 pages shared one identical timestamp, down to the second. The whole file contained only 87 distinct dates.

The cause was mundane. Months earlier we ran a bulk update across the site. It rewrote post_modified on every row it touched. From then on our sitemap told Google that most of the site changed at the same instant and never changed again.

Put yourself on the crawler's side. A file claims three hundred unrelated pages were modified at 14:22:07 on the same day. That is not a signal, it is noise. The rational response is to stop trusting lastmod for that site and fall back to the existing crawl schedule. Which is what we were seeing.

Regenerating the sitemap fixes nothing

The bad value lives in the database, not in the file. Regeneration copies it faithfully.

Touching every post is worse. It stamps them all with a new identical timestamp and reproduces the problem with a fresher date.

What worked was deriving the date from the content itself. We compute a fingerprint of each page's rendered content and store the date that fingerprint last changed. That value, not post_modified, is what the sitemap publishes.

add_action('save_post', function ($post_id, $post) {
    if (wp_is_post_revision($post_id) || wp_is_post_autosave($post_id)) {
        return;
    }

    $fingerprint = md5($post->post_title . '|' . $post->post_content);
    $previous    = get_post_meta($post_id, '_content_fingerprint', true);

    if ($fingerprint === $previous) {
        return;                      // same content, so the date stands
    }

    update_post_meta($post_id, '_content_fingerprint', $fingerprint);
    update_post_meta($post_id, '_content_changed_at', current_time('mysql', true));
}, 10, 2);

Then expose it through the REST layer the front end reads:

register_rest_field('page', 'sitemap_lastmod', [
    'get_callback' => function ($post) {
        $changed = get_post_meta($post['id'], '_content_changed_at', true);
        return $changed ?: $post['modified_gmt'];   // fallback for legacy content
    },
]);

The property that matters is that it is honest by construction. A page whose content has not changed keeps its old date no matter how often you re-save it. A page whose content actually changed gets today's date. Nothing in the admin UI can inflate it.

The second half: your sitemap index is lying too

Most generators stamp index files with the generation time:

// ❌ every crawl sees a freshly modified index
lastModified: new Date(),

That tells Google every index changed on every crawl, which is another way of saying your dates carry no information. Report the newest real date among the children instead:

const newestOf = (items: { lastmod: string }[]) =>
  items.reduce((max, i) => (i.lastmod > max ? i.lastmod : max), items[0].lastmod);

export default function sitemapIndex() {
  return SECTIONS.map((section) => ({
    url: `${BASE}/sitemap/${section.slug}.xml`,
    lastModified: newestOf(section.items),
  }));
}

A trap we fell into ourselves while shipping this: we wrote newestOf, then forgot to use it in four of the entries. They kept emitting new Date(). Grep for your generator's date call after the change instead of trusting the diff.

Results

Metric	Before	After
Distinct `lastmod` values	87	337
Largest group sharing one timestamp	261	8
URLs in sitemap	402	402

Related: the pages that were never crawled at all

While investigating we checked the 41 URLs stuck in "Discovered – currently not indexed" and counted internal links pointing at each one. Eight had zero.

The correlation was exact. Every city page linked from its category hub was indexed. Every one omitted from that hub was stuck. Google found them in the sitemap, recorded them, then assigned them near-zero crawl priority because nothing on the site pointed at them.

We added the missing links to the hubs. Seven of nine pages got indexed with no manual indexing request at all. For comparison, manual requests in Search Console are capped at roughly ten per day. Internal links have no cap and fix the cause rather than the symptom.

What to check on your own site

Export your sitemap and count distinct lastmod values. If that number is far below your URL count, your dates are noise and Google has probably stopped reading them.
Check whether your sitemap index carries the generation timestamp rather than a real content date.
Never run a bulk update that touches modification dates. The cost stays invisible for months, then it is your entire crawl behaviour.

The full write-up with the complete implementation is on our blog. It is in Arabic, but the code and the tables read the same in any language.

سلة واحدة وطلبات متعددة: الخطأ الذي يقتل أي متجر متعدد التجار

kouana — Tue, 04 Aug 2026 16:15:07 +0000

بنينا سوقًا متعدد التجار: تاجر يفتح متجره ويوثَّق، ودليل متاجر، ومشترٍ يضع في سلة واحدة منتجات من بائعين مختلفين. المنصة تشرف على الجودة والشحن والاسترجاع.

الخطأ الذي يقع فيه أغلب من يبني هذا النوع يظهر في أول أسبوع تشغيل: طلب واحد يحمل منتجات من ثلاثة تجار. يبدو منطقيًا، لأن المشتري اشترى مرة واحدة ودفع مرة واحدة. ثم يصل أول سؤال من التشغيل: أحد التجار شحن والثاني تأخر والثالث نفد مخزونه. ما حالة هذا الطلب؟

لا جواب. الحالة الواحدة لا تصف ثلاثة مسارات مستقلة.

المشتري يشتري مرة، والتنفيذ يحدث مرات

النموذج الذهني للمشتري: عملية شراء واحدة. النموذج التشغيلي: عدد من الطلبات بعدد التجار، لكل واحد شحنته وحالته ومهلته وسياسة إرجاعه.

الحل ألا تختار بينهما، بل تمثّل الاثنين:

checkout (عملية الشراء)
├── order  #1  → التاجر A   (شحن، حالة، تتبع مستقل)
├── order  #2  → التاجر B
└── order  #3  → التاجر C

Schema::create('checkouts', function (Blueprint $t) {
    $t->foreignId('customer_id')->constrained();
    $t->string('payment_reference');    // عملية دفع واحدة
    $t->unsignedInteger('grand_total'); // بالهللات، عدد صحيح
    $t->timestamps();
});

Schema::create('orders', function (Blueprint $t) {
    $t->foreignId('checkout_id')->constrained();
    $t->foreignId('vendor_id')->constrained();
    $t->string('status');               // حالة مستقلة لكل تاجر
    $t->unsignedInteger('items_total');
    $t->unsignedInteger('shipping_total');
    $t->string('tracking_number')->nullable();
});

الدفع يرتبط بـcheckout، والتنفيذ يرتبط بـorder. من هنا يصير كل سؤال لاحق قابلًا للإجابة.

ولاحظ unsignedInteger للمبالغ: خزّن المال بأصغر وحدة كعدد صحيح. الأعداد العشرية في قواعد البيانات تُنتج فروق كسور تظهر عند جمع عمولات آلاف الطلبات.

الحالة المعروضة للعميل مشتقة لا مخزَّنة

بعد الفصل يبقى سؤال الواجهة: ماذا نعرض للمشتري في صفحة "طلباتي"؟

لا تخزّن حالة موحّدة في checkouts، لأنها ستتعارض مع الحالات الفرعية عند أول تحديث. اشتقها:

public function displayStatus(): string
{
    $statuses = $this->orders->pluck('status');

    if ($statuses->every(fn ($s) => $s === 'delivered'))  return 'مكتمل';
    if ($statuses->every(fn ($s) => $s === 'cancelled'))  return 'ملغى';
    if ($statuses->contains('shipped'))                   return 'جزء منه في الطريق';
    return 'قيد التجهيز';
}

وأظهر التفصيل تحتها: كل تاجر بحالته ورقم تتبعه. المشتري الذي يرى "شُحن جزء منك من متجر كذا" لا يفتح تذكرة دعم. الذي يرى "قيد التجهيز" منذ أربعة أيام يفتحها.

الشحن لا يُجمع ولا يُقسم بالتساوي

كل تاجر يشحن من موقعه بسياسته. جمع تكلفة الشحن في رقم واحد على مستوى checkout يجعل الاسترجاع الجزئي مستحيلًا: لو أُلغي طلب تاجر واحد، كم تُعيد من الشحن؟

احسب الشحن على مستوى order وخزّنه هناك، والمجموع مشتق:

$shipping = $ordersByVendor->map(fn ($o) => $o->vendor
    ->shippingRuleFor($customerAddress)
    ->quote($o->weight, $o->items_total));

القاعدة العامة: أي مبلغ قد يُسترجَع وحده يجب أن يُخزَّن في المستوى الذي يُسترجَع عنده.

العمولة تُجمَّد لحظة البيع

المنصة تأخذ نسبة. الإغراء أن تحسبها عند العرض من vendors.commission_rate.

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

$t->unsignedInteger('commission_rate_bps');  // نقاط أساس: 250 = 2.5%
$t->unsignedInteger('commission_amount');    // المبلغ كما احتُسب يومها
$t->unsignedInteger('vendor_payout');

خزّن النسبة المطبَّقة والمبلغ الناتج داخل الطلب نفسه. الجدول المرجعي يخدم الطلبات القادمة فقط. المبدأ نفسه ينطبق على الضريبة وعلى أي تعريفة متغيرة.

المنتج الواحد عند تجار مختلفين

في السوق المتعدد يبيع أكثر من تاجر المنتج ذاته بسعر ومخزون مختلفين. إن جعلت السعر والمخزون حقلين في جدول products، فأنت تفترض بائعًا واحدًا، وستعيد بناء الجدول لاحقًا.

افصل التعريف عن العرض:

products            # التعريف: اسم، وصف، صور، تصنيف، باركود
└── vendor_offers   # العرض: تاجر + سعر + مخزون + مدة تجهيز

صفحة المنتج تعرض التعريف مرة واحدة، وتحته قائمة العروض. السلة تشير إلى vendor_offer_id لا إلى product_id، وإلا لم تعرف من الذي يشحن.

توثيق التاجر قرار مسجَّل لا علم منطقي

المنصة تضمن الجودة، ومعنى ذلك أن انضمام تاجر يمر بمراجعة. خانة is_verified تجيب عن "هل هو موثق" ولا تجيب عن "من وثّقه ومتى ولماذا سُحب التوثيق".

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

الاسترجاع الجزئي: الاختبار الذي يكشف النموذج كله

هنا تُقاس صحة كل ما سبق. المشتري دفع مبلغًا واحدًا بعملية واحدة عند البوابة، ثم أراد إرجاع صنف واحد من تاجر واحد.

بوابة الدفع تعرف عملية واحدة برقم واحد. أنت تحتاج أن تسترجع جزءًا منها، وأن تعرف من أي تاجر يُخصم، وكم من الشحن يُعاد، وكم عمولة تتنازل عنها المنصة.

الاسترجاع يصبح ممكنًا لأن كل رقم مخزَّن في مستواه الصحيح:

$refund = [
    'items'      => $line->unit_price * $qty,
    'shipping'   => $order->refundableShipping($qty),   // من مستوى الطلب
    'commission' => $line->commission_amount_share($qty), // مجمَّدة وقت البيع
];
$refund['customer_total'] = $refund['items'] + $refund['shipping'];
$refund['vendor_debit']   = $refund['customer_total'] - $refund['commission'];

$gateway->refund($checkout->payment_reference, $refund['customer_total']);

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

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

مصيدة الحجز عند الدفع

بين لحظة الضغط على "ادفع" ولحظة تأكيد بوابة الدفع تمر ثوانٍ. إن خصمت المخزون بعد التأكيد فقط، فمشترٍ آخر قد يأخذ آخر قطعة أثناءها.

احجز المخزون قبل استدعاء البوابة، بعملية شرطية ذرية تفشل بوضوح:

$reserved = VendorOffer::where('id', $offerId)
    ->where('stock', '>=', $qty)
    ->decrement('stock', $qty);

if ($reserved === 0) {
    throw new OutOfStock($offerId);
}

وأطلِق مهمة مجدولة تعيد المحجوز إن لم يكتمل الدفع خلال مهلة. الحجز بلا انتهاء صلاحية يحوّل السلال المهجورة إلى مخزون مجمَّد.

الخلاصة

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

نبني في رؤية أنظمة تصميم متجر الكتروني ومتاجر متعددة التجار، والدرس الذي يتكرر في كل مشروع: ارسم دورة حياة الطلب كاملة على ورقة، من الإضافة إلى السلة حتى الاسترجاع بعد شهر، قبل أن تكتب أول ترحيل.

تطبيق طلب سيارات: خمسة قرارات معمارية تُحسم قبل أول سطر كود

kouana — Tue, 04 Aug 2026 16:05:53 +0000

بنينا منصة نقل ركاب كاملة: تطبيق للراكب، وتطبيق للسائق، ولوحة تحكم، وواجهة برمجية من أربعين مسارًا. الخلفية على Laravel مع لوحة Filament، والتطبيقان بـFlutter، والاتصال اللحظي عبر Firebase. ستة عشر نموذج بيانات وعشرون ترحيلًا وتسع شاشات إدارة.

الجزء الصعب لم يكن أي تقنية بعينها. الصعوبة أن ثلاثة أنظمة تعمل في اللحظة نفسها: راكب ينتظر، وسائق يقرر خلال ثوانٍ، ولوحة تراقب وتسعّر وتوثّق. تأخير ثانيتين في وصول عرض الرحلة يعني رحلة ضائعة، لا تجربة أبطأ.

هذه القرارات الخمسة حسمناها قبل الكتابة، وكل واحد منها كان سيكلّف إعادة بناء لو أجّلناه.

1. مصدران للحقيقة، لكل منهما وظيفة مختلفة

موقع السائق يتغير كل ثانية أو ثانيتين. لو كتبنا كل تحديث في جدول علاقي، لصار جدول المواقع أثقل من قاعدة البيانات كلها خلال أسابيع، بلا فائدة تُذكر من التاريخ الكامل.

في المقابل، الأجرة وحالة الرحلة لا تحتمل قاعدة بلا معاملات. مبلغ يُحتسب مرتين أو حالة تنتقل من اتجاهين في وقت واحد يعني نزاعًا ماليًا.

فصلنا الاثنين حسب طبيعتهما:

البيانات	المكان	السبب
موقع السائق، حالة الاتصال، إشعار العرض	Firebase	تحديث كثيف قصير العمر، يصل فورًا
الرحلة، الأجرة وبنودها، السائق، الوثائق	Laravel + قاعدة علاقية	معاملات، قيود، تدقيق

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

2. الأجرة تُخزَّن بنودًا لا رقمًا واحدًا

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

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

// الشكل العام: بنود منفصلة، والإجمالي مشتق منها لا مخزَّن بدلًا عنها
$fare = [
    'base'     => $tariff->base_fare,
    'distance' => round($km * $tariff->per_km, 2),
    'time'     => round($minutes * $tariff->per_minute, 2),
];
$fare['subtotal'] = array_sum($fare);
$fare['tax']      = round($fare['subtotal'] * $tariff->tax_rate, 2);
$fare['total']    = $fare['subtotal'] + $fare['tax'];

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

3. الرحلة آلة حالات، وكل شيء آخر يتفرع منها

أربعون مسارًا في الواجهة البرمجية تبدو كثيرة حتى ترسم دورة حياة الرحلة، فتجد أغلبها انتقالات مشروعة بين حالتين.

requested → offered → accepted → arrived → started → completed
     ↘ cancelled_by_rider          ↘ cancelled_by_driver

اجعل الانتقال المسموح بيانات لا شروطًا متناثرة في المتحكمات:

private const ALLOWED = [
    'requested' => ['offered', 'cancelled_by_rider'],
    'offered'   => ['accepted', 'cancelled_by_rider', 'expired'],
    'accepted'  => ['arrived', 'cancelled_by_rider', 'cancelled_by_driver'],
    'arrived'   => ['started', 'cancelled_by_driver'],
    'started'   => ['completed'],
];

public function moveTo(Trip $trip, string $next): void
{
    if (!in_array($next, self::ALLOWED[$trip->status] ?? [], true)) {
        throw new InvalidTransition($trip->status, $next);
    }
    // ...
}

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

سباق القبول: سائقان يضغطان في اللحظة نفسها

العرض يصل إلى أكثر من سائق. اثنان يقبلان بفارق أجزاء من الثانية. الكود الساذج يقرأ ثم يكتب:

$trip = Trip::find($id);
if ($trip->status === 'offered') {      // كلاهما يقرأ 'offered'
    $trip->update(['status' => 'accepted', 'driver_id' => $driverId]);
}

كلا الطلبين يمر، والثاني يدهس الأول. الراكب يرى سائقًا، وسائق آخر يقود إليه بلا رحلة.

اجعل الشرط جزءًا من الكتابة نفسها، واقرأ عدد الصفوف المتأثرة:

$claimed = Trip::where('id', $id)
    ->where('status', 'offered')          // الشرط داخل UPDATE
    ->update(['status' => 'accepted', 'driver_id' => $driverId]);

if ($claimed === 0) {
    return response()->json(['error' => 'trip_already_taken'], 409);
}

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

4. تطبيقان منفصلان، لا تطبيق واحد بوضعين

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

بنيناهما تطبيقين مستقلين. الأسباب عملية لا نظرية:

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

المنطق المشترك يعيش في حزمة داخلية يستوردها الاثنان:

packages/core/       # النماذج، عميل الواجهة البرمجية، التحقق، الخرائط
apps/rider/
apps/driver/

5. المراجعة البشرية جزء من التصميم لا من سياسة الدعم

شكوى متكررة أخرى في هذا المجال: حظر آلي بلا تفسير ولا مسار مراجعة. عالجناها في البنية: وثائق السائق ورخصته وتأمينه تُرفع، وتُراجَع من لوحة التحكم، والقرار يُسجَّل بصاحبه وسببه ووقته.

الفرق أن حالة السائق ليست علمًا منطقيًا is_active، بل سجل قرارات:

Schema::create('driver_reviews', function (Blueprint $t) {
    $t->foreignId('driver_id')->constrained();
    $t->foreignId('reviewer_id')->constrained('users');
    $t->enum('decision', ['approved', 'rejected', 'suspended']);
    $t->string('reason');
    $t->timestamps();
});

الحالة الحالية مشتقة من آخر قرار. تكلفة هذا التصميم جدول إضافي، ومقابله أنك تستطيع الإجابة عن "لماذا أُوقف هذا السائق ومن أوقفه" بعد ستة أشهر.

مصيدتان صغيرتان كلّفتانا وقتًا

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

المسافة المدفوعة ليست خطًا مستقيمًا بين نقطتين. خزّن مسار الرحلة نقاطًا واحسب الطول التراكمي. الفارق بين الخط المستقيم والمسار الفعلي في مدينة مزدحمة كبير بما يكفي لتحويل كل رحلة إلى شكوى.

الخلاصة

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

نعمل في رؤية على تصميم تطبيقات الجوال وأنظمتها الخلفية، وهذا المشروع كان أوضح مثال على أن الوقت المدفوع في نمذجة البيانات يُوفَّر مضاعفًا في الشهر الثالث.

لعبة ثلاثية الأبعاد داخل صفحة ويب عادية: سبع مصائد لم يذكرها أي درس

kouana — Tue, 04 Aug 2026 15:54:05 +0000

قررنا أن تكون صفحة خدمة الألعاب عندنا دليلًا لا وعدًا. بدل صور ثابتة لألعاب صنعناها، وضعنا في الصفحة لعبة تُلعب فعلًا: مشهد صحراوي بمحرك three.js، سلاح مُجهَّز بحركات إطلاق وإعادة تلقيم، أعداء يخرجون من الرمل ويطاردون اللاعب، وحلقة مهمة تنتهي عند خمسين هدفًا.

تشغيل مشهد WebGL داخل صفحة موقع قائمة يختلف عن تشغيله في صفحة فارغة. أغلب الدروس تفترض صفحة نظيفة فيها <canvas> وحده. أما نحن فأدخلناه وسط تخطيط فيه حركات وتحويلات ورأس ثابت ومحتوى تسويقي.

في كل مصيدة من السبع التالية، كانت رسالة الخطأ تشير إلى موضع غير الموضع الذي يجب إصلاحه.

1. `position: fixed` يتوقف عن كونه fixed

أول ما بنينا زر ملء الشاشة، ظهر المشهد داخل حدود القسم لا فوق الصفحة. راجعنا الـCSS مرارًا وكل شيء سليم ظاهريًا.

السبب ليس في العنصر نفسه بل في أحد آبائه. أي عنصر عليه transform أو filter أو perspective يصنع حاوية احتواء جديدة، فيصير position: fixed نسبيًا إليه لا إلى نافذة المتصفح. وتخطيط موقعنا مليء بعناصر عليها transform بسبب الحركات.

أخرِج المشهد من الشجرة كلها. مطاردة الأب المذنب حل مؤقت، لأن أي تعديل تصميم لاحق يعيد المشكلة:

import { createPortal } from "react-dom";

function FullscreenGame({ children }) {
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);
  if (!mounted) return null;
  return createPortal(
    <div style={{ position: "fixed", inset: 0, zIndex: 9999 }}>{children}</div>,
    document.body
  );
}

ضع أي طبقة تغطي الشاشة كاملة في document.body مباشرة، ولا تعتمد على fixed وحده داخل موقع حقيقي.

2. حاوية بمقاس صفر تُغرق الكونسول

بعد نقل المشهد إلى البورتال، امتلأ الكونسول بسطر واحد يتكرر بالآلاف:

GL_INVALID_FRAMEBUFFER_OPERATION: Framebuffer is incomplete

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

الحاوية تأخذ مقاسها بعد الرسم الأول لا قبله، ونحن نقرأه قبله. العلاج أن يكون للقراءة بديل مضمون:

const w = wrap.clientWidth || window.innerWidth;
const h = wrap.clientHeight || window.innerHeight;
renderer.setSize(w, h);
camera.aspect = w / h;
camera.updateProjectionMatrix();

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

3. طلب قفل المؤشر قد يُرفض، وأنت لا تتوقع ذلك

التحكم بالفأرة في لعبة منظور أول يحتاج requestPointerLock(). كتبناها كما تُكتب في كل الأمثلة:

canvas.addEventListener("click", () => canvas.requestPointerLock());

عملت على أجهزتنا. ثم بدأت تظهر شاشة خطأ حمراء من Next.js عند بعض المستخدمين وفي بيئات الاختبار الآلي. السبب أن هذه الدالة ترجع Promise في المتصفحات الحديثة، وهذا الوعد يُرفض إذا لم يعتبر المتصفح النقرة إيماءة مستخدم موثوقة، أو إذا كانت الصفحة داخل إطار مقيّد. الرفض غير الملتقَط يصير خطأ غير معالَج، وNext يعرضه فوق الصفحة.

canvas.addEventListener("click", () => {
  const req = canvas.requestPointerLock();
  if (req && typeof req.catch === "function") {
    req.catch(() => showHint("اضغط داخل الشاشة للتحكم"));
  }
});

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

4. المؤشر يختفي فوق قائمة تحتاج فأرة

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

المتصفح لا يفك القفل تلقائيًا عند ظهور عنصر جديد، لأنه لا يعرف شيئًا عن طبقاتك. اربط فك القفل بحالة الواجهة نفسها:

useEffect(() => {
  const overlayOpen = paused || dead || won;
  if (overlayOpen && document.pointerLockElement) {
    document.exitPointerLock();
  }
}, [paused, dead, won]);

وأضفنا cursor: auto صريحًا على الطبقة، وشريحة تلميح تظهر حين يكون المؤشر غير مقفول. كل حالة تفتح واجهة يجب أن تحرر الفأرة، وإلا صار اللاعب أمام شاشة تبدو معطلة.

5. قبة السماء تظهر سوداء بالكامل

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

عند تحميلها ظهرت سوداء تمامًا. المشكلة أن الخامة الافتراضية MeshStandardMaterial خامة مضاءة، والوجه الداخلي العلوي للقبة لا يصله ضوء، فيُرسم أسود مهما رفعت شدة الإضاءة.

القبة ليست جسمًا في المشهد، هي لوحة. والحل أن تُعامَل كلوحة:

dome.traverse((o) => {
  if (!o.isMesh) return;
  o.material = new THREE.MeshBasicMaterial({
    map: o.material.map,
    side: THREE.BackSide,   // نرى الوجه الداخلي
    fog: false,             // الضباب لا يمس السماء
    toneMapped: false,      // بألوانها الأصلية
  });
});

// أعد مركز الصندوق المحيط إلى الأصل وإلا وقفت الكاميرا خارج القبة
const box = new THREE.Box3().setFromObject(dome);
dome.position.sub(box.getCenter(new THREE.Vector3()));

وأضفنا خلفية متدرجة على scene.background كضمانة أخيرة، حتى لو فشل تحميل النموذج لا يرى الزائر سوادًا.

6. نموذج بـ87 ميجابايت لا يُرسل إلى متصفح أحد

النموذج الرئيسي للشخصية جاء بحجم 87 ميجابايت. رقم مقبول في محرك ألعاب مثبَّت على الجهاز، ومستحيل في صفحة ويب.

خفّضناه إلى 3.1 ميجابايت بأمر واحد، مع الاحتفاظ بـ92 ألف مثلث وبحركة السكون كاملة و25 خامة:

npx @gltf-transform/cli optimize in.glb out.glb \
  --texture-compress webp \
  --texture-size 1024 \
  --compress draco

أغلب الوزن في الخامات لا في الأشكال. تحويل الصور إلى webp وتحديد حدها الأقصى عند 1024 بكسل يقتطع النصيب الأكبر، وضغط draco يتولى الهندسة. بعد التحويل يفتح المشهد على شبكة جوال عادية.

7. `next/dynamic` داخل مكوّن سيرفر لا يقسّم شيئًا

هذه لم تظهر في الألعاب وحدها، بل في الموقع كله، ولم ننتبه لها إلا عند قياس الحزمة.

كنا نستورد المحركات الثقيلة عبر next/dynamic ونظن أن كل صفحة تحمّل ما يخصها فقط. الأرقام قالت غير ذلك: أول تحميل لمسار الصفحات الداخلية كان 2.04 ميجابايت.

السبب أن next/dynamic داخل مكوّن سيرفر لا يقسّم إطلاقًا. التقسيم الفعلي يقوم على دلالات React.lazy، وهي لا تعمل إلا على حدود العميل. المكوّن السيرفري يجمع كل شيء في حزمة صفحة واحدة.

الحل أن يكون الموزّع نفسه مكوّن عميل:

"use client";
import dynamic from "next/dynamic";

const PAGES = {
  106: dynamic(() => import("./p106")),
  9443: dynamic(() => import("./p9443")),
};

export default function BespokePage({ id, content }) {
  const C = PAGES[id];
  return C ? <C content={content} /> : null;
}

ويبقى في السيرفر ملف أرقام فقط، لا يستورد أي مكوّن، ليقرر أي فرع يُسلك. النتيجة: أول تحميل نزل من 2.04 ميجابايت إلى 195 كيلوبايت، وعلى صفحة حية قِيس الجافاسكربت المرسل 2,012 كيلوبايت قبل، و209 كيلوبايت بعد.

كيف تتحقق من مشهد لا تستطيع تصويره

أدوات لقطة الشاشة الآلية كانت تفشل على صفحة اللعبة برسالة انتهاء مهلة. حلقة requestAnimationFrame لا تتوقف، فلا تجد الأداة لحظة سكون تلتقط فيها.

المخرج أن نقرأ الإطار من بطاقة الرسوم مباشرة:

const gl = canvas.getContext("webgl2");
const px = new Uint8Array(gl.drawingBufferWidth * gl.drawingBufferHeight * 4);
gl.readPixels(0, 0, gl.drawingBufferWidth, gl.drawingBufferHeight,
              gl.RGBA, gl.UNSIGNED_BYTE, px);

ثم نصنّف الصفوف بنسبة البكسلات السوداء ومتوسط اللون. بعد إصلاح القبة صار المشهد صفر بالمئة سوادًا، ومتوسط اللون في الصفوف العليا [116, 174, 210]، أي سماء زرقاء. اختبار رقمي كهذا يعمل داخل خط النشر الآلي.

انتبه أن أصل الإحداثيات في readPixels أسفل اليسار لا أعلاه، فأي منطق يفترض العكس سيقرأ الأرض على أنها سماء.

الخلاصة

المصائد السبع تنبع كلها من موضع المشهد: داخل موقع حقيقي، لا في صفحة تجريبية معزولة. الأب صاحب الـtransform، والحاوية التي لم تأخذ مقاسها بعد، والحزمة التي جمعت كل الصفحات، لا وجود لأي منها في الدرس التعليمي.

بنينا هذا الديمو في شركة تصميم العاب رؤية ليكون جزءًا من صفحة الخدمة نفسها، فوقعنا في المصائد بالترتيب. إن كنت تخطط لشيء مشابه، قِس حزمة الجافاسكربت قبل أن تصدّق أن التقسيم يعمل، وابدأ باختبار المشهد داخل تخطيط موقعك لا في صفحة فارغة.

DEV Community: kouana

Google Ignored Our Sitemap for Months. The Cause Was One Database Column

293 pages claimed to change at the same second

Regenerating the sitemap fixes nothing

The second half: your sitemap index is lying too

Results

Related: the pages that were never crawled at all

What to check on your own site

سلة واحدة وطلبات متعددة: الخطأ الذي يقتل أي متجر متعدد التجار

المشتري يشتري مرة، والتنفيذ يحدث مرات

الحالة المعروضة للعميل مشتقة لا مخزَّنة

الشحن لا يُجمع ولا يُقسم بالتساوي

العمولة تُجمَّد لحظة البيع

المنتج الواحد عند تجار مختلفين

توثيق التاجر قرار مسجَّل لا علم منطقي

الاسترجاع الجزئي: الاختبار الذي يكشف النموذج كله

مصيدة الحجز عند الدفع

الخلاصة

تطبيق طلب سيارات: خمسة قرارات معمارية تُحسم قبل أول سطر كود

1. مصدران للحقيقة، لكل منهما وظيفة مختلفة

2. الأجرة تُخزَّن بنودًا لا رقمًا واحدًا

3. الرحلة آلة حالات، وكل شيء آخر يتفرع منها

سباق القبول: سائقان يضغطان في اللحظة نفسها

4. تطبيقان منفصلان، لا تطبيق واحد بوضعين

5. المراجعة البشرية جزء من التصميم لا من سياسة الدعم

مصيدتان صغيرتان كلّفتانا وقتًا

الخلاصة

لعبة ثلاثية الأبعاد داخل صفحة ويب عادية: سبع مصائد لم يذكرها أي درس

1. position: fixed يتوقف عن كونه fixed

2. حاوية بمقاس صفر تُغرق الكونسول

3. طلب قفل المؤشر قد يُرفض، وأنت لا تتوقع ذلك

4. المؤشر يختفي فوق قائمة تحتاج فأرة

5. قبة السماء تظهر سوداء بالكامل

6. نموذج بـ87 ميجابايت لا يُرسل إلى متصفح أحد

7. next/dynamic داخل مكوّن سيرفر لا يقسّم شيئًا

كيف تتحقق من مشهد لا تستطيع تصويره

الخلاصة

1. `position: fixed` يتوقف عن كونه fixed

7. `next/dynamic` داخل مكوّن سيرفر لا يقسّم شيئًا