<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Anas Amin</title>
    <description>The latest articles on DEV Community by Anas Amin (@anasamin22311).</description>
    <link>https://dev.to/anasamin22311</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F1673461%2F1ce850ad-7b8c-454a-9484-b0c7958f194f.jpg</url>
      <title>DEV Community: Anas Amin</title>
      <link>https://dev.to/anasamin22311</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/anasamin22311"/>
    <language>en</language>
    <item>
      <title>⁧أنظمة متعددة المستأجرين وكثيرة الصلاحيات: اجعل فحص الوصول مملًّا⁩</title>
      <dc:creator>Anas Amin</dc:creator>
      <pubDate>Thu, 19 Nov 2026 17:00:00 +0000</pubDate>
      <link>https://dev.to/anasamin22311/nzm-mtdd-lmstjryn-wkthyr-lslhyt-jl-fhs-lwswl-mmlanw-3k6h</link>
      <guid>https://dev.to/anasamin22311/nzm-mtdd-lmstjryn-wkthyr-lslhyt-jl-fhs-lwswl-mmlanw-3k6h</guid>
      <description>&lt;p&gt;&lt;em&gt;⁧الأنظمة كثيرة الصلاحيات تصبح خطرة حين تتوزع قواعد الوصول بين المتحكمات، وفحوص الواجهة، وفلاتر المستودعات، والمهام الخلفية. الهدف ليس إطار تفويض ذكيًا، بل مسار واحد للقواعد يصعب الالتفاف عليه. والأمثلة من Shield وZotic وCAS وQuestion Banking وAmlaak.⁩&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  ⁧ابدأ برباعية الوصول⁩
&lt;/h2&gt;

&lt;p&gt;⁧كل عملية محمية يمكن وصفها بأربع قيم: الفاعل، والمستأجر، والإجراء، والمورد. إن كانت إحداها مجهولة، فالنظام لا يملك بعد ما يكفي ليسمح بالعملية.⁩&lt;/p&gt;

&lt;p&gt;⁧هذه الرباعية البسيطة تمنع خطأً شائعًا: أن تتحقق من أن المستخدم يملك الصلاحية في مكان ما، ثم تحمّل موردًا يخص مستأجرًا آخر. الصلاحية والملكية تُقيَّمان معًا.⁩&lt;/p&gt;

&lt;p&gt;&lt;em&gt;⁧مدخلات القرار⁩&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;record&lt;/span&gt; &lt;span class="nc"&gt;AccessRequest&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="n"&gt;Guid&lt;/span&gt; &lt;span class="n"&gt;ActorId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;Guid&lt;/span&gt; &lt;span class="n"&gt;TenantId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;Action&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;ResourceType&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;Guid&lt;/span&gt;&lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;ResourceId&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  ⁧حدّد المستأجر من سياق موثوق⁩
&lt;/h2&gt;

&lt;p&gt;⁧معامل في المسار أو جسم الطلب قد يسمّي مستأجرًا، لكنه لا يثبت العضوية فيه. حدّد المستأجر النشط من العضوية بعد المصادقة، ثم قارن به أي معرّف مستأجر يأتي في الطلب.⁩&lt;/p&gt;

&lt;p&gt;⁧العمل الإداري الذي يعبر المستأجرين يحتاج مسارًا صريحًا بسياسة وقواعد تدقيق منفصلة. إخفاؤه داخل محلّل المستأجر العادي يجعل فهم الكود العادي أصعب بكثير.⁩&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;⁧أنشئ سياق مستأجر واحدًا لكل طلب بعد المصادقة.⁩&lt;/li&gt;
&lt;li&gt;⁧ارفض المستأجر المفقود أو الملتبس قبل أن يبدأ منطق العمل.⁩&lt;/li&gt;
&lt;li&gt;⁧مرّر معرّف المستأجر صراحةً إلى حدود التطبيق والوصول إلى البيانات.⁩&lt;/li&gt;
&lt;li&gt;⁧لا تقبل معرّف مستأجر من رسالة أو مهمة مجدولة دون أن تتحقق ممن أنشأ ذلك العمل.⁩&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  ⁧افصل الأدوار عن الصلاحيات⁩
&lt;/h2&gt;

&lt;p&gt;⁧الأدوار أداة إدارة، والصلاحيات هي الإجراءات التي يحميها التطبيق فعلًا. الكود الذي يسأل عن اسم دور تكثر فيه الاستثناءات، مثل «مدير أو مالك أو دعم فني». والكود الذي يسأل عن صلاحية يُبقي قرار العمل في مكان واحد.⁩&lt;/p&gt;

&lt;p&gt;⁧استخدم أسماء صلاحيات ثابتة تصف إجراءً، مثل invoice.read أو member.invite. واربط أدوار المستأجر بهذه الصلاحيات في الإعدادات أو في البيانات. التطبيق يفحص الصلاحية، وواجهة الإدارة تقرر أي الأدوار تنالها.⁩&lt;/p&gt;

&lt;p&gt;⁧في Shield خمسة أنواع من المستخدمين: الإدارة، والشركة، والمنشأة، والحارس، والأمن الوقائي. لكل نوع مجموعة صلاحيات خاصة به، وكل شركة جديدة تحصل على دور مسؤول خاص بها يحمل مجموعة صلاحيات الشركات.⁩&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;⁧&lt;strong&gt;السياسة العامة.&lt;/strong&gt; قواعد مثل حالة الحساب، والعضوية في المستأجر، ووصول فريق الدعم، تنطبق قبل تحميل أي مورد. في Amlaak يبقى الحساب مقيّدًا إن كان دوره يستطيع إدارة المستخدمين أو الأدوار أو التكاملات، أو تصدير بيانات شخصية، حتى يفعّل التحقق الثنائي TOTP.⁩&lt;/li&gt;
&lt;li&gt;⁧&lt;strong&gt;سياسة الصلاحية.&lt;/strong&gt; هل يجوز للفاعل أن يحاول هذا الإجراء في المستأجر النشط.⁩&lt;/li&gt;
&lt;li&gt;⁧&lt;strong&gt;سياسة المورد.&lt;/strong&gt; الملكية، أو الحالة، أو القسم، أو غيرها من الحقائق التي لا تُفحص إلا مقابل المورد نفسه. في Question Banking توصل صلاحية ReadQuestionBank الطلب إلى البنك فقط، ثم يقرر البنك: يدخل مالكه، ويدخل الجميع إن كان عامًا، ويدخل من يحمل مشاركة لم تنتهِ. وكل من عدا ذلك يتلقى «غير موجود».⁩&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  ⁧الاستعلامات جزء من حدود الأمان⁩
&lt;/h2&gt;

&lt;p&gt;⁧فحص الصلاحيات ثم استعلام غير مقيّد بالمستأجر ما زال تسريبًا للبيانات. ضع شرط المستأجر في استعلام قاعدة البيانات الذي يحمّل المورد أو يغيّره. وهذا يعالج أيضًا حالة معرّف مورد صحيح يخص مستأجرًا آخر.⁩&lt;/p&gt;

&lt;p&gt;⁧فلاتر الاستعلام العامة في Entity Framework Core تقلل التكرار، لكن لا ينبغي أن تصير سحرًا خفيًا. استعلامات SQL المباشرة، والمهام الخلفية، واستعلامات الإدارة، وتعطيل الفلاتر، كلها تحتاج مراجعة متعمدة. والكتابات الحساسة أسلم في دالة مستودع أو تطبيق تطلب معرّف المستأجر صراحةً، بدل أن تقرأه من قيمة ثابتة عامة.⁩&lt;/p&gt;

&lt;p&gt;⁧Zotic يُخرج تقييد المستأجر من الاستعلامات الفردية: فلتر استعلام واحد يُسجَّل لكل كيان يرث من صنفه الأساسي متعدد المستأجرين، ومعترض (interceptor) عند SaveChanges يكتب المستأجر على كل صف جديد. أما CAS فيحدد النطاق بالشخص لا بالمستأجر: قائمة دورات الطبيب لا تضم إلا الدورات التي يدرّسها، وقائمة موظف الاستقبال لا تضم إلا دورات الأطباء المسند إليهم.⁩&lt;/p&gt;

&lt;p&gt;&lt;em&gt;⁧حدّد نطاق المورد داخل الاستعلام⁩&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Orders&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SingleOrDefaultAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="n"&gt;x&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;x&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Id&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;OrderId&lt;/span&gt;
          &lt;span class="p"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="n"&gt;x&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;TenantId&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;tenant&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;cancellationToken&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  ⁧احمِ مسار الكتابة كله⁩
&lt;/h2&gt;

&lt;p&gt;⁧ما تُظهره الواجهة أو تخفيه ليس تفويضًا. إخفاء زر يساعد المستخدم على فهم المنتج، لكن القرار الأخير للواجهة البرمجية أو لمعالج الأمر. والقاعدة نفسها تنطبق على الاستيراد الجماعي، ومستهلكي الرسائل، والمهام المجدولة، والأدوات الداخلية.⁩&lt;/p&gt;

&lt;p&gt;⁧في المهام الخلفية، احفظ المستأجر ومن بدأ العمل مع المهمة. وعند التنفيذ، أعد بناء سياق تفويض محدود، أو استخدم هوية خدمة باسم واضح. لا تدع عاملًا يرث وصولًا واسعًا لمجرد أنه يعمل داخل الخادم.⁩&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;⁧حدّد الفاعل والمستأجر.⁩&lt;/li&gt;
&lt;li&gt;⁧افحص صلاحية الإجراء.⁩&lt;/li&gt;
&lt;li&gt;⁧حمّل المورد داخل حدود المستأجر.⁩&lt;/li&gt;
&lt;li&gt;⁧طبّق قواعد المورد نفسه.⁩&lt;/li&gt;
&lt;li&gt;⁧غيّر الحالة واكتب حدث التدقيق في عملية التطبيق نفسها.⁩&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  ⁧التخزين المؤقت للصلاحيات يحتاج خطة إبطال⁩
&lt;/h2&gt;

&lt;p&gt;⁧تخزين مجموعة الصلاحيات مؤقتًا يوفر قراءات متكررة من قاعدة البيانات، لكن مفتاحًا مبنيًا على معرّف المستخدم وحده غير آمن في نظام متعدد المستأجرين. أدخل في المفتاح المستأجر، ونسخة السياسة، أو نسخة إسناد الأدوار، أو أي قيمة أخرى تتغير حين يُعدَّل الوصول.⁩&lt;/p&gt;

&lt;p&gt;⁧قرّر كم يجب أن يكون سحب الصلاحية سريعًا. انتهاء قصير قد يكفي لقراءة قليلة المخاطر، أما الإجراءات الحساسة فقد تحتاج فحصًا جديدًا أو إبطالًا مباشرًا. هذا قرار منتج وأمان، لا مجرد إعداد للتخزين المؤقت.⁩&lt;/p&gt;

&lt;p&gt;⁧Amlaak يحفظ صلاحيات المستخدم في الذاكرة ثلاث دقائق، بمفتاح مكوّن من معرّف المستخدم وبصمة (hash) لختم الأمان (security stamp) في رمز دخوله. تغيير الدور يبدّل الختم، ورمز الدخول الذي يحمل ختمًا قديمًا يُرفض، فلا يقرأ رمز جديد مدخلًا قديمًا أبدًا.⁩&lt;/p&gt;

&lt;p&gt;&lt;em&gt;⁧شكل أكثر أمانًا لمفتاح التخزين المؤقت⁩&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;permissions:{tenantId}:{actorId}:{assignmentVersion}
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  ⁧دقّق القرارات المهمة⁩
&lt;/h2&gt;

&lt;p&gt;⁧حدث التدقيق المفيد يقول من حاول ماذا، وفي أي مستأجر، وعلى أي مورد، وهل سُمح له. ويسجل أيضًا السياسة أو الصلاحية المعنية. ولا ينسخ إلى السجلات رموز الدخول، ولا أجسام الطلبات، ولا الحقول الحساسة.⁩&lt;/p&gt;

&lt;p&gt;⁧محاولات الوصول المرفوضة قد تكون كثيرة، فاجمع الرفض الروتيني في أرقام، واحتفظ بسجلات مفصلة للعمليات الحساسة. فريق الدعم يحتاج سياقًا يكفي للتحقيق، دون أن يتسلم البيانات المحمية نفسها.⁩&lt;/p&gt;

&lt;p&gt;⁧Amlaak يضع على كل عملية يدققها وسمًا (attribute) يسمّي الإجراء، مثل User.Block أو Inquiry.Export. وطبقة في آخر مسار MediatR تكتب السجل بعد نجاح المعالج فقط، وتخفي قبل الحفظ أي حقل يوحي اسمه بكلمة مرور أو رمز دخول أو سر.⁩&lt;/p&gt;

&lt;h2&gt;
  
  
  ⁧اختبر الحدود، لا المسارات السعيدة فقط⁩
&lt;/h2&gt;

&lt;p&gt;⁧اختبارات التفويض يجب أن تثبت أن الحد يصمد حين تكون المعرّفات صحيحة لكنها تخص مكانًا آخر. والاختبار الذي لا يستخدم إلا معرّفات غير موجودة لا يكشف القراءة عبر المستأجرين.⁩&lt;/p&gt;

&lt;p&gt;&lt;em&gt;⁧الحد الأدنى من الحالات لعملية محمية⁩&lt;/em&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;⁧النتيجة المتوقعة⁩&lt;/th&gt;
&lt;th&gt;⁧الحالة⁩&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;⁧سماح⁩&lt;/td&gt;
&lt;td&gt;⁧عضو، في المستأجر الصحيح، بصلاحية مسموحة، على مورد يملكه⁩&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;⁧رفض دون تحميل بيانات محمية⁩&lt;/td&gt;
&lt;td&gt;⁧عضو، في المستأجر الصحيح، بلا الصلاحية⁩&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;⁧رفض أو «غير موجود»، بثبات⁩&lt;/td&gt;
&lt;td&gt;⁧عضو، من مستأجر آخر، بمعرّف مورد صحيح⁩&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;⁧رفض خلال مهلة السحب المتفق عليها⁩&lt;/td&gt;
&lt;td&gt;⁧سُحبت الصلاحية بعد إنشاء مدخل في التخزين المؤقت⁩&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;⁧اتباع سياسة الخدمة أو سياسة البادئ الموثقة⁩&lt;/td&gt;
&lt;td&gt;⁧مهمة خلفية أُزيل وصول من بدأها⁩&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;⁧رفض⁩&lt;/td&gt;
&lt;td&gt;⁧مسار الإدارة يُستخدم عبر نقطة مستأجر عادية⁩&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  ⁧المملّ هو الهدف⁩
&lt;/h2&gt;

&lt;p&gt;⁧نقطة API جديدة لا ينبغي أن تُلزم كاتبها باختراع تسلسل تفويض. أعطها سياق مستأجر واحدًا، واسم صلاحية واحدًا، واستعلام مورد واحدًا محصورًا بالمستأجر، ومكانًا واحدًا للقرار الأخير. عندها يبحث المراجعون عن خطوة ناقصة، بدل أن يفككوا نموذج أمان مختلفًا في كل ميزة.⁩&lt;/p&gt;

&lt;h2&gt;
  
  
  ⁧أين استخدمت هذا⁩
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;⁧Shield يعطي كل نوع من أنواع مستخدميه الخمسة (الإدارة، والشركة، والمنشأة، والحارس، والأمن الوقائي) مجموعة صلاحيات خاصة به، وكل شركة جديدة تحصل على دور مسؤول خاص بها. (&lt;a href="https://anasamin.dev/ar/work/shield/" rel="noopener noreferrer"&gt;دراسة حالة Shield&lt;/a&gt;)⁩&lt;/li&gt;
&lt;li&gt;⁧Zotic يقيّد كياناته متعددة المستأجرين بفلتر استعلام واحد في EF Core، ويكتب المستأجر على كل صف جديد عند SaveChanges، مع 82 صلاحية عبر لوحة المنظمين. (&lt;a href="https://anasamin.dev/ar/work/zotic/" rel="noopener noreferrer"&gt;دراسة حالة Zotic&lt;/a&gt;)⁩&lt;/li&gt;
&lt;li&gt;⁧CAS فيه 85 صلاحية عبر خمسة أدوار، ويقصر قائمة دورات كل طبيب وكل موظف استقبال على الدورات التي يدرّسها أو المسندة إليه. (&lt;a href="https://anasamin.dev/ar/work/cas/" rel="noopener noreferrer"&gt;دراسة حالة CAS&lt;/a&gt;)⁩&lt;/li&gt;
&lt;li&gt;⁧Question Banking يعير بنك الأسئلة عبر خمسة مستويات ظهور وثلاث درجات مشاركة (قراءة فقط، وقراءة وكتابة، ومسؤول)، ويمكن أن تحمل المشاركة تاريخ انتهاء يتحقق منه استعلام قاعدة البيانات نفسه. (&lt;a href="https://anasamin.dev/ar/work/question-banking/" rel="noopener noreferrer"&gt;دراسة حالة Question Banking&lt;/a&gt;)⁩&lt;/li&gt;
&lt;li&gt;⁧Amlaak يقيّد أي حساب يستطيع دوره إدارة المستخدمين أو الأدوار أو التكاملات، أو تصدير بيانات شخصية، حتى يفعّل التحقق الثنائي TOTP، ويربط ذاكرة الصلاحيات المؤقتة بختم الأمان في رمز الدخول. (&lt;a href="https://anasamin.dev/ar/work/amlaak/" rel="noopener noreferrer"&gt;دراسة حالة Amlaak&lt;/a&gt;)⁩&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;⁧نُشر أولًا على &lt;a href="https://anasamin.dev/ar/notes/permission-heavy-multi-tenant-dotnet/" rel="noopener noreferrer"&gt;anasamin.dev&lt;/a&gt;. أنا أنس أمين، مهندس برمجيات ⁦.NET⁩ ومؤسس &lt;a href="https://arkedia.dev/ar" rel="noopener noreferrer"&gt;أركيديا&lt;/a&gt;.⁩&lt;/em&gt;&lt;/p&gt;

</description>
      <category>dotnet</category>
      <category>authorization</category>
      <category>multitenancy</category>
      <category>arabic</category>
    </item>
    <item>
      <title>Staying hands-on while leading delivery</title>
      <dc:creator>Anas Amin</dc:creator>
      <pubDate>Tue, 17 Nov 2026 13:00:00 +0000</pubDate>
      <link>https://dev.to/anasamin22311/staying-hands-on-while-leading-delivery-bd2</link>
      <guid>https://dev.to/anasamin22311/staying-hands-on-while-leading-delivery-bd2</guid>
      <description>&lt;p&gt;&lt;em&gt;Hands-on leadership does not mean taking every difficult ticket. It means staying close enough to the code and production path to make sound decisions, while giving the team clear ownership of the work. The examples come from Zotic, Amlaak, Happy Ticket, Project Pavilion and Alreef.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Leadership and coding are one feedback loop
&lt;/h2&gt;

&lt;p&gt;Architecture, planning, review, and deployment are often treated as separate responsibilities. In practice, each one corrects the others. A deployment exposes operational constraints. Those constraints change an architecture decision. The decision changes how work should be sliced. Code review shows whether the slice was clear enough.&lt;/p&gt;

&lt;p&gt;A lead who never touches that loop can make decisions based on diagrams that no longer match the system. A lead who keeps all hard implementation work has the opposite problem: the team waits for one person and never gains ownership.&lt;/p&gt;

&lt;h2&gt;
  
  
  Write down the decision before the task list
&lt;/h2&gt;

&lt;p&gt;A short decision note is usually enough. State the problem, the constraints, the chosen approach, the alternatives that were considered, and what would cause the choice to be revisited. The purpose is not documentation volume. It is to stop the same argument from restarting inside every pull request.&lt;/p&gt;

&lt;p&gt;Keep the decision close to the codebase or delivery workspace. Link it from the work that implements it. If the implementation reveals a wrong assumption, update the decision instead of quietly drifting away from it.&lt;/p&gt;

&lt;p&gt;Amlaak keeps six of these in its repository, next to the code, from “Modular monolith, not microservices” to “Transactional outbox &amp;amp; Odoo adapter”. Some decisions come straight from a constraint: Happy Ticket runs on Blazor Server so a small team could ship fast.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;What user or operational problem are we solving?&lt;/li&gt;
&lt;li&gt;Which constraints are fixed, and which are only preferences?&lt;/li&gt;
&lt;li&gt;What is deliberately outside this change?&lt;/li&gt;
&lt;li&gt;How will we know the decision is wrong in production?&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Break work down by risk, not by technical layer
&lt;/h2&gt;

&lt;p&gt;Separate backend, frontend, database, and deployment tickets can look tidy while hiding the fact that nothing works until all four finish. A thin vertical slice gives the team an earlier integration point and makes unclear contracts visible.&lt;/p&gt;

&lt;p&gt;Start with the part that can invalidate the plan: an external API, a migration on real-shaped data, a permission boundary, a slow query, or an unfamiliar deployment target. Proving that boundary early is more useful than completing the easiest files first.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Name one user-visible or operator-visible outcome.&lt;/li&gt;
&lt;li&gt;Identify the riskiest assumption inside that outcome.&lt;/li&gt;
&lt;li&gt;Create the smallest vertical slice that can test it.&lt;/li&gt;
&lt;li&gt;Add acceptance notes, edge cases, and rollback needs before assignment.&lt;/li&gt;
&lt;li&gt;Give one person ownership of the slice while making dependencies explicit.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Choose hands-on work that improves the team
&lt;/h2&gt;

&lt;p&gt;The lead should not automatically take the most visible feature. Better hands-on work often sits at a boundary: the first implementation of a pattern, a risky integration, a production defect with unclear ownership, or tooling that removes repeated friction.&lt;/p&gt;

&lt;p&gt;After proving a pattern, leave an example and hand the next use to someone else. If only the lead can extend it, the code did not create leverage. It created another dependency.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Prototype the uncertain part.&lt;/strong&gt; Use a narrow branch or spike to prove feasibility, then turn the result into team-owned production work.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Build the first reference path.&lt;/strong&gt; Implement one complete example when the team needs a concrete pattern more than another document.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Debug across boundaries.&lt;/strong&gt; Step in when the failure crosses application, database, network, and deployment layers, then share the diagnosis.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;In practice.&lt;/strong&gt; On Zotic that meant writing the tenant isolation, the ticket encryption and the Telr integration; on Amlaak, the Odoo outbox and MFA enrolment; on Project Pavilion, the RAG path. Each one is a boundary where a mistake is expensive.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Review the contract before the style
&lt;/h2&gt;

&lt;p&gt;A useful review starts with behaviour. Does the change match the task? Does it preserve tenant and permission boundaries? What happens on retry, cancellation, or partial failure? Can it be deployed and rolled back safely?&lt;/p&gt;

&lt;p&gt;Style and naming still matter, but automated tools should handle mechanical rules where possible. Human review time is better spent on assumptions, domain behaviour, data changes, security, and operational cost.&lt;/p&gt;

&lt;p&gt;Amlaak keeps its review rules in the repository. Findings run from P0, a release blocker, to P3, optional, and each one has to name the file and lines, the behaviour it affects and a test that would prove it fixed.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Ask for a smaller pull request when unrelated decisions are mixed together.&lt;/li&gt;
&lt;li&gt;Write comments that explain the risk, not only the preferred edit.&lt;/li&gt;
&lt;li&gt;Separate blocking correctness issues from optional improvements.&lt;/li&gt;
&lt;li&gt;When a pattern repeats, improve the shared rule, test, or example instead of leaving the same comment again.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Keep deployment inside the definition of done
&lt;/h2&gt;

&lt;p&gt;A feature is not finished when it works on a developer machine. The work item should name configuration changes, migrations, health checks, logs, rollback steps, and any manual action needed in the target environment.&lt;/p&gt;

&lt;p&gt;The lead does not need to press every deployment button. The lead does need to make the path understandable and ensure more than one person can operate it. Pair on the first release of a new path, record the result, then rotate ownership.&lt;/p&gt;

&lt;p&gt;Amlaak’s deploy workflow waits for the new containers to report healthy, puts the previous images back if they do not, and ends with a smoke test against the public site. Alreef’s deploy script gives a new container two minutes to turn healthy, rolls back to the exact image that ran before, and moves the latest tag only after the new one passes.&lt;/p&gt;

&lt;h2&gt;
  
  
  A simple operating loop
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;One loop from decision to production learning&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Stage&lt;/th&gt;
&lt;th&gt;Concrete output&lt;/th&gt;
&lt;th&gt;Question to answer&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Decide&lt;/td&gt;
&lt;td&gt;Short decision note&lt;/td&gt;
&lt;td&gt;Why this approach under these constraints?&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Slice&lt;/td&gt;
&lt;td&gt;Small vertical work items&lt;/td&gt;
&lt;td&gt;What can be delivered and checked independently?&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Implement&lt;/td&gt;
&lt;td&gt;Reference path or owned feature slice&lt;/td&gt;
&lt;td&gt;Where is direct lead involvement most useful?&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Review&lt;/td&gt;
&lt;td&gt;Risk-focused feedback and tests&lt;/td&gt;
&lt;td&gt;Does the behaviour hold at its boundaries?&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Release&lt;/td&gt;
&lt;td&gt;Runbook, health signal, and rollback path&lt;/td&gt;
&lt;td&gt;Can the team operate this change safely?&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Learn&lt;/td&gt;
&lt;td&gt;Updated decision, task template, or shared pattern&lt;/td&gt;
&lt;td&gt;What should be easier next time?&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  Warning signs
&lt;/h2&gt;

&lt;p&gt;The balance is wrong when every technical question waits for the lead, pull requests remain open because one reviewer is overloaded, or the lead works on hidden emergency code that nobody else understands. It is also wrong when architecture decisions have no contact with production behaviour.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Move routine decisions into examples, tests, and short decision records.&lt;/li&gt;
&lt;li&gt;Give review ownership to the engineers closest to the area, with a clear escalation path.&lt;/li&gt;
&lt;li&gt;Keep a small amount of direct implementation work, chosen for learning and risk reduction.&lt;/li&gt;
&lt;li&gt;Review incidents and deployments with the team, then change the working system rather than relying on memory.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Where this runs
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;On Zotic I led architecture and delivery across the API, the organiser dashboard and the Flutter app, wrote the tenant isolation, the ticket encryption and the Telr integration myself, and ran code review and release. (&lt;a href="https://anasamin.dev/work/zotic/" rel="noopener noreferrer"&gt;Zotic case study&lt;/a&gt;)&lt;/li&gt;
&lt;li&gt;On Amlaak I set the architecture and its six decision records, wrote the Odoo outbox and the MFA enrolment, and owned the test strategy, CI and the Docker deployment. (&lt;a href="https://anasamin.dev/work/amlaak/" rel="noopener noreferrer"&gt;Amlaak case study&lt;/a&gt;)&lt;/li&gt;
&lt;li&gt;On Happy Ticket I chose Blazor Server so a small team could ship fast, then wrote the tenant isolation, the seat-inventory model and the Telr integration. (&lt;a href="https://anasamin.dev/work/happy-ticket/" rel="noopener noreferrer"&gt;Happy Ticket case study&lt;/a&gt;)&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://anasamin.dev/notes/hands-on-engineering-leadership/" rel="noopener noreferrer"&gt;anasamin.dev&lt;/a&gt;. I'm Anas Amin, a software engineer in .NET and the founder of &lt;a href="https://arkedia.dev" rel="noopener noreferrer"&gt;Arkedia&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>engineeringleadership</category>
      <category>delivery</category>
      <category>codereview</category>
      <category>dotnet</category>
    </item>
    <item>
      <title>⁧إرسال العملاء المحتملين إلى Odoo دون أن يضيع أحد: صندوق صادر معاملاتي في ASP.NET Core⁩</title>
      <dc:creator>Anas Amin</dc:creator>
      <pubDate>Sun, 15 Nov 2026 17:00:00 +0000</pubDate>
      <link>https://dev.to/anasamin22311/rsl-lml-lmhtmlyn-l-odoo-dwn-n-ydy-hd-sndwq-sdr-mmlty-fy-aspnet-core-5ecl</link>
      <guid>https://dev.to/anasamin22311/rsl-lml-lmhtmlyn-l-odoo-dwn-n-ydy-hd-sndwq-sdr-mmlty-fy-aspnet-core-5ecl</guid>
      <description>&lt;p&gt;&lt;em&gt;⁧عميل محتمل يصل إلى الموقع ولا يصل إلى فريق المبيعات أسوأ من ألا يكون هناك موقع أصلًا. سيتوقف نظام إدارة العملاء أحيانًا، والمهم أن ينتظر العميل المحتمل بدل أن يختفي.⁩&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  ⁧كتابتان، وإحداهما ستفشل⁩
&lt;/h2&gt;

&lt;p&gt;⁧أن تحفظ العميل المحتمل ثم تتصل بـOdoo يبدو سليمًا حتى يفشل الاتصال بعد الحفظ: العميل في قاعدة بياناتك، ولا أثر له عند المبيعات. وأن تتصل بـOdoo أولًا يفشل بالعكس، حين ينكسر الحفظ بعد أن صار السجل في النظام. وإعادة المحاولة داخل الطلب لا تفعل إلا أن تُبطئ الصفحة ما دام النظام متوقفًا.⁩&lt;/p&gt;

&lt;p&gt;⁧الصندوق الصادر يُخرج الكتابة الثانية من الطلب. السجل نفسه ورسالة تصفه يُحفظان في المعاملة نفسها، فإما أن يوجدا معًا أو لا يوجد أي منهما. وتسليم الرسالة يصير مهمة منفصلة تأخذ ما يحتاجه النظام من وقت.⁩&lt;/p&gt;

&lt;p&gt;&lt;em&gt;⁧حفظ واحد، ومعاملة SQL واحدة⁩&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="c1"&gt;// The enquiry and its outbox row commit together, or not at all.&lt;/span&gt;
&lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Inquiries&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;inquiry&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;OutboxMessages&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;OutboxMessage&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;Type&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"InquiryCreated"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;AggregateId&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;inquiry&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;PayloadJson&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;JsonSerializer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Serialize&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;InquiryPayload&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;From&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;inquiry&lt;/span&gt;&lt;span class="p"&gt;)),&lt;/span&gt;
    &lt;span class="n"&gt;OccurredUtc&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;now&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;Status&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;OutboxStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Pending&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;NextAttemptUtc&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;now&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SaveChangesAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  ⁧ماذا تحمل الرسالة⁩
&lt;/h2&gt;

&lt;p&gt;⁧اجعل السجل مملًّا وكاملًا. لا يجب أن يخمّن المُرسِل أبدًا ما هي الرسالة، ولمن هي، ولماذا فشلت آخر مرة.⁩&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;⁧&lt;strong&gt;النوع.&lt;/strong&gt; ما الذي حدث: استفسار جديد، أو مورد اعتُمد، أو بريد يجب إرساله.⁩&lt;/li&gt;
&lt;li&gt;⁧&lt;strong&gt;السجل والحمولة.&lt;/strong&gt; معرّف السجل الذي تخصه، ولقطة JSON بما يحتاجه الطرف الآخر.⁩&lt;/li&gt;
&lt;li&gt;⁧&lt;strong&gt;الحالة.&lt;/strong&gt; معلّقة، أو قيد المعالجة، أو مُعالَجة، أو ميتة. لا شيء بينها.⁩&lt;/li&gt;
&lt;li&gt;⁧&lt;strong&gt;المحاولات.&lt;/strong&gt; كم محاولة حتى الآن، ومتى موعد التالية.⁩&lt;/li&gt;
&lt;li&gt;⁧&lt;strong&gt;عقد الإيجار.&lt;/strong&gt; أي عامل يمسك الرسالة، وحتى متى.⁩&lt;/li&gt;
&lt;li&gt;⁧&lt;strong&gt;آخر خطأ.&lt;/strong&gt; رمز وسبب قصير، لا الحمولة ولا تتبع أخطاء مليء ببيانات شخصية.⁩&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  ⁧استلم كل رسالة بعقد إيجار مؤقت⁩
&lt;/h2&gt;

&lt;p&gt;⁧مهمة متكررة في Hangfire تعمل كل 30 ثانية وتمر على الرسائل المستحقة، الأقدم أولًا، لمدة 20 ثانية أو 500 رسالة على الأكثر. وتستلم سجلًا واحدًا في كل مرة بتحديث مشروط: لا ينتقل إلى قيد المعالجة إلا سجل معلّق حان موعده، أو سجل قيد المعالجة انتهى عقده، مع عقد مدته خمس دقائق ومعرّف العامل.⁩&lt;/p&gt;

&lt;p&gt;⁧إن لم يلمس التحديث أي سجل فقد سبقه عامل آخر، فينتقل إلى غيره. ولا يمكن وضع علامة النجاح أو الفشل إلا ما دام العامل يمسك العقد، فلا يكتب عامل تأخر بعد انتهاء عقده فوق عمل من استلم بعده. ورسالة عامل تعطّل تعود وحدها حين ينتهي العقد.⁩&lt;/p&gt;

&lt;p&gt;&lt;em&gt;⁧استلم، أو انتقل إلى غيرها⁩&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;claimed&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;OutboxMessages&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Where&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Id&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="p"&gt;&amp;amp;&amp;amp;&lt;/span&gt;
        &lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Status&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;OutboxStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Pending&lt;/span&gt; &lt;span class="p"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;NextAttemptUtc&lt;/span&gt; &lt;span class="p"&gt;&amp;lt;=&lt;/span&gt; &lt;span class="n"&gt;now&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;||&lt;/span&gt;
         &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Status&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;OutboxStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Processing&lt;/span&gt; &lt;span class="p"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;LeaseExpiresUtc&lt;/span&gt; &lt;span class="p"&gt;&amp;lt;&lt;/span&gt; &lt;span class="n"&gt;now&lt;/span&gt;&lt;span class="p"&gt;)))&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ExecuteUpdateAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;s&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;s&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SetProperty&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Status&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;OutboxStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Processing&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SetProperty&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;LeaseExpiresUtc&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;now&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;AddMinutes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;5&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SetProperty&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;LockedBy&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;workerId&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;claimed&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="m"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;continue&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// someone else has it&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  ⁧اجعل الكتابة في النظام آمنة إذا تكررت⁩
&lt;/h2&gt;

&lt;p&gt;⁧قد تُسلَّم الرسالة ثم يتعطل العامل قبل أن يسجل ذلك. المحاولة التالية يجب ألا تنشئ عميلًا محتملًا ثانيًا. لذلك يُكتب معرّف GUID الخاص بالسجل في حقل مخصص على العميل في Odoo، وكل تسليم يبحث به أولًا: يحدّث إن وجده، وينشئ إن لم يجده. وجدول للتسليمات بمفتاح فريد لكل مزوّد وعملية وسجل يُبقي صفًّا واحدًا لكل إرسال منطقي.⁩&lt;/p&gt;

&lt;p&gt;⁧لكن البحث ثم الإنشاء ما زالا اتصالين. إن جرت رسالتان للسجل نفسه في الوقت نفسه، قد لا تجد أي منهما شيئًا فتنشئ كلتاهما. عالج رسائل السجل الواحد بالترتيب، أو ضع قيدًا فريدًا على ذلك الحقل في Odoo؛ الحقل وحده لا يجعل العملية ذرية.⁩&lt;/p&gt;

&lt;h2&gt;
  
  
  ⁧أعد محاولة ما يمكن أن يُشفى، وأمِت ما لا يُشفى⁩
&lt;/h2&gt;

&lt;p&gt;⁧كل فشل يأتي من عميل Odoo يُصنَّف مرة واحدة في مكان حدوثه، فلا يحتاج المُرسِل إلا إلى قراءة الجواب.⁩&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;⁧أضف تفاوتًا عشوائيًا إلى فترات الانتظار، حتى لا تعيد دفعة من الإخفاقات المحاولة في الدقيقة نفسها.⁩&lt;/li&gt;
&lt;li&gt;⁧عامِل 408 و429 كأخطاء عابرة، واحترم Retry-After. من السهل تصنيفهما دائمين بالخطأ.⁩&lt;/li&gt;
&lt;li&gt;⁧اجعل إعادة المحاولة اليدوية تصفّر عدد المحاولات، وإلا نالت الرسالة الميتة محاولة واحدة ثم ماتت من جديد.⁩&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;em&gt;⁧أنواع الفشل، وما يفعله المُرسِل⁩&lt;/em&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;⁧ما يحدث⁩&lt;/th&gt;
&lt;th&gt;⁧النوع⁩&lt;/th&gt;
&lt;th&gt;⁧الفشل⁩&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;⁧إعادة بعد دقيقة، ثم 5 و15 و60 و360⁩&lt;/td&gt;
&lt;td&gt;⁧عابر⁩&lt;/td&gt;
&lt;td&gt;⁧انتهاء المهلة، خطأ شبكة، 5xx⁩&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;⁧رسالة ميتة فورًا، ويظهر على العميل أن مزامنته فشلت⁩&lt;/td&gt;
&lt;td&gt;⁧دائم⁩&lt;/td&gt;
&lt;td&gt;⁧401 و403 وأي 4xx آخر⁩&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;⁧رسالة ميتة فورًا⁩&lt;/td&gt;
&lt;td&gt;⁧دائم⁩&lt;/td&gt;
&lt;td&gt;⁧حمولة لا يمكن تحويلها⁩&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;⁧رسالة ميتة، وتنبيه للمسؤولين بالمعرّفات فقط⁩&lt;/td&gt;
&lt;td&gt;⁧استسلام⁩&lt;/td&gt;
&lt;td&gt;⁧المحاولة الفاشلة السادسة⁩&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  ⁧واجهتا Odoo خلف واجهة واحدة⁩
&lt;/h2&gt;

&lt;p&gt;⁧Odoo من 14 إلى 18 يتحدث JSON-RPC بجلسة، وOdoo 19 يضيف واجهة JSON-2 بمفتاح. واجهة واحدة تخفي الاثنتين، ومصنع يختار العميل عند التشغيل من إعداد صريح أو من فحص الإصدار، ويعود إلى JSON-RPC عند الشك. وحين يكون التكامل متوقفًا، يضع عميل لا يفعل شيئًا علامة «لا ينطبق» على الرسائل بدل أن يُفشلها.⁩&lt;/p&gt;

&lt;h2&gt;
  
  
  ⁧اجعل الطابور مرئيًا⁩
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;⁧مقاييس لعدد الرسائل الميتة ولعمر أقدم رسالة معلّقة، مع تنبيه لكل منهما. العمر يكشف مُرسِلًا عالقًا لا يكشفه العدد أبدًا.⁩&lt;/li&gt;
&lt;li&gt;⁧السجلات تحمل المعرّفات ورموز الأخطاء، لا الأسماء ولا أرقام الهواتف.⁩&lt;/li&gt;
&lt;li&gt;⁧يستطيع الفريق إعادة مزامنة عميل واحد من صندوق العملاء المحتملين. وإعادة أي رسالة تحتاج المصادقة الثنائية وتُسجَّل في سجل التدقيق.⁩&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  ⁧اختبره أمام شيء يفشل⁩
&lt;/h2&gt;

&lt;p&gt;⁧اختبارات التكامل تشغّل المُرسِل أمام حاوية SQL Server 2022 حقيقية وOdoo مزيف يمكن أن يُطلب منه الفشل. وإن لم تبدأ الحاوية تفشل الاختبارات بدل أن تُتخطّى.⁩&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;⁧الرسالة المسلَّمة تنتهي مُعالَجة، مع عميل محتمل واحد فقط في Odoo؛ وتشغيل المُرسِل مرة أخرى لا يغيّر شيئًا.⁩&lt;/li&gt;
&lt;li&gt;⁧الخطأ 500 يترك الرسالة معلّقة مع موعد لإعادة المحاولة، والخطأ 401 يجعلها ميتة.⁩&lt;/li&gt;
&lt;li&gt;⁧العقد المنتهي يُستعاد والعقد الساري يُترك؛ ولا يُرسل بريد مرتين بعد تعطّل.⁩&lt;/li&gt;
&lt;li&gt;⁧أربعة مُرسِلين يفرّغون عشرين رسالة يرسلون كل واحدة مرة واحدة فقط.⁩&lt;/li&gt;
&lt;li&gt;⁧اختبار حمل بـk6 وOdoo متوقف يفشل ما لم تنجح 99.5% من النماذج ويبقَ p95 تحت ثانية.⁩&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  ⁧قبل أن تثق به⁩
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;⁧هل يُحفظ السجل مع رسالته الصادرة في معاملة واحدة؟⁩&lt;/li&gt;
&lt;li&gt;⁧هل يمكن أن يرسل عاملان الرسالة نفسها، وهل يوجد اختبار بعدة عمّال؟⁩&lt;/li&gt;
&lt;li&gt;⁧هل تعود رسالة العامل المتعطل حين ينتهي عقده؟⁩&lt;/li&gt;
&lt;li&gt;⁧هل كل كتابة خارجية مرتبطة بمعرّفك أنت وآمنة إذا تكررت؟⁩&lt;/li&gt;
&lt;li&gt;⁧أي الأخطاء يُعاد، وأيها يموت، ومن يعلم حين تموت رسالة؟⁩&lt;/li&gt;
&lt;li&gt;⁧هل يستطيع أحد أن يرى عمر أقدم رسالة معلّقة؟⁩&lt;/li&gt;
&lt;li&gt;⁧الحمولة فيها بيانات شخصية: متى تُحذف؟ قرّر قبل الإطلاق، لا بعده.⁩&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  ⁧أين استخدمت هذا⁩
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;⁧Amlaak يرسل الاستفسارات والموردين المعتمدين إلى Odoo بهذه الطريقة، على ⁦.NET 10⁩ مع SQL Server وHangfire. واختبارات التكامل تشغّله على SQL Server وOdoo بديل داخل حاويات. (&lt;a href="https://anasamin.dev/ar/work/amlaak/" rel="noopener noreferrer"&gt;دراسة حالة Amlaak&lt;/a&gt;)⁩&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;⁧نُشر أولًا على &lt;a href="https://anasamin.dev/ar/notes/odoo-outbox-aspnet-core/" rel="noopener noreferrer"&gt;anasamin.dev&lt;/a&gt;. أنا أنس أمين، مهندس برمجيات ⁦.NET⁩ ومؤسس &lt;a href="https://arkedia.dev/ar" rel="noopener noreferrer"&gt;أركيديا&lt;/a&gt;.⁩&lt;/em&gt;&lt;/p&gt;

</description>
      <category>dotnet</category>
      <category>odoo</category>
      <category>integration</category>
      <category>arabic</category>
    </item>
    <item>
      <title>Arabic and English in one Angular app: direction, fonts and numbers</title>
      <dc:creator>Anas Amin</dc:creator>
      <pubDate>Fri, 13 Nov 2026 13:00:00 +0000</pubDate>
      <link>https://dev.to/anasamin22311/arabic-and-english-in-one-angular-app-direction-fonts-and-numbers-55bi</link>
      <guid>https://dev.to/anasamin22311/arabic-and-english-in-one-angular-app-direction-fonts-and-numbers-55bi</guid>
      <description>&lt;p&gt;&lt;em&gt;Translating the strings is the easy part. The hard part is everything around them: a page that flips before its words arrive, arrows that point the wrong way, a Hijri date nobody asked for, a page range that reads backwards. This is what three systems running in Arabic and English today taught me.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  The language goes in the URL, not the browser
&lt;/h2&gt;

&lt;p&gt;On public pages, make the language part of the address: /ar/... and /en/.... The URL is the single source of truth. Search engines see two separate pages, a shared link opens in its own language, and the language toggle takes you to the same page in the other language without jumping to the top.&lt;/p&gt;

&lt;p&gt;An unknown prefix redirects to the default language, and so does the bare home page. Keep localStorage for the admin and sign-in pages that search engines never need. And link the two versions with hreflang, plus an x-default.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;A route resolver: a known language, or a redirect&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;langResolver&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;ResolveFn&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;AppLang&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;async &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;route&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;translations&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;inject&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;TranslationCatalogService&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;router&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;inject&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;Router&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;lang&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;parseLang&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;route&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;paramMap&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;lang&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// Unknown locale: rewrite the first segment to the default one.&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;rest&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;url&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;split&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;/&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;rest&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nx"&gt;rest&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;DEFAULT_LANG&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="nx"&gt;rest&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;DEFAULT_LANG&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;RedirectCommand&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;router&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;parseUrl&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;`/&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;rest&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;/&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;replaceUrl&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;translations&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;switchTo&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;};&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Flip the direction after the words arrive
&lt;/h2&gt;

&lt;p&gt;Flip dir before the translation file has loaded and the user sees a mirrored layout in the old language for a moment. The right order: load the words, switch the language, then flip the direction. And when someone taps the toggle twice in a row, the newest request wins and the older one is dropped quietly.&lt;/p&gt;

&lt;p&gt;Set dir and lang on the html element through Renderer2 and the injected document, not the global document, so it works on the server too. Angular Material reads direction from the CDK’s Directionality, so replace it with a service that follows the app’s language, or menus and dialogs keep opening from the wrong side.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The words first, the direction last&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nf"&gt;switchTo&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;AppLang&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;boolean&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;latest&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ensure&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;                 &lt;span class="c1"&gt;// lazy-load the dictionary chunk&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;latest&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;  &lt;span class="c1"&gt;// a newer toggle won&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;firstValueFrom&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;translate&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;use&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
  &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;localization&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;setLanguage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="c1"&gt;// App root: one effect sets &amp;lt;html dir lang&amp;gt;, in the browser and on the server.&lt;/span&gt;
&lt;span class="nf"&gt;effect&lt;/span&gt;&lt;span class="p"&gt;(()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;lang&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;localization&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;language&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;root&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nb"&gt;document&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;documentElement&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;renderer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;setAttribute&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;root&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;dir&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;lang&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;ar&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;rtl&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;ltr&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;renderer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;setAttribute&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;root&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;lang&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Logical CSS properties first
&lt;/h2&gt;

&lt;p&gt;margin-inline-start instead of margin-left, padding-inline instead of padding-right, inset-inline-end instead of right. Then the layout flips with dir on its own, with no second stylesheet. Amlaak has about 153 logical properties to about 12 physical ones.&lt;/p&gt;

&lt;p&gt;Keep [dir=rtl] for what has no logical version: transform, transform-origin and animation. And one rule for icons: flip only the ones that point somewhere, like arrows and next and previous. A check mark, a play button and a search icon stay as they are.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;One class for icons that point a direction&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight css"&gt;&lt;code&gt;&lt;span class="o"&gt;[&lt;/span&gt;&lt;span class="nt"&gt;dir&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;'rtl'&lt;/span&gt;&lt;span class="o"&gt;]&lt;/span&gt; &lt;span class="nc"&gt;.flip-rtl&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;transform&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;scaleX&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;-1&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nc"&gt;.card-cta&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="py"&gt;margin-inline-start&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;auto&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c"&gt;/* right in English, left in Arabic */&lt;/span&gt;
  &lt;span class="py"&gt;padding-inline&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="m"&gt;1rem&lt;/span&gt; &lt;span class="m"&gt;0.75rem&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  An Arabic font that does not weigh down the English page
&lt;/h2&gt;

&lt;p&gt;Split the font with unicode-range into an Arabic subset and a Latin one, and the English page never downloads Arabic letters. Preload only the subset the first screen needs: Alreef preloads Tajawal because Arabic text is the biggest thing on its first paint, and Amlaak’s server sends different preload hints per language.&lt;/p&gt;

&lt;p&gt;A small one: write the other language’s name on the toggle in the system font, or that one button pulls the other font file into every page. And letter-spacing pulls joined Arabic letters apart, so turn it off on Arabic pages.&lt;/p&gt;

&lt;h2&gt;
  
  
  Numbers and dates
&lt;/h2&gt;

&lt;p&gt;ar-SA on its own gives you the Hijri calendar and Arabic-Indic digits in many browsers. If the business runs on the Gregorian calendar with Latin digits, ask for that explicitly, and set the time zone instead of trusting the user’s device.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Gregorian, Latin digits, Riyadh time&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;date&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nx"&gt;Intl&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;DateTimeFormat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;ar-SA-u-ca-gregory-nu-latn&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="na"&gt;dateStyle&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;medium&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;timeZone&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Asia/Riyadh&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}).&lt;/span&gt;&lt;span class="nf"&gt;format&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;());&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;compact&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nx"&gt;Intl&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;NumberFormat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;ar-u-nu-latn&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;notation&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;compact&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;}).&lt;/span&gt;&lt;span class="nf"&gt;format&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;1250000&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Mixed text
&lt;/h2&gt;

&lt;p&gt;A sentence that mixes Arabic, numbers and English follows the bidirectional algorithm, and the result can surprise you. Angular Material’s paginator builds its range label by gluing numbers to words, and in an Arabic interface it comes out scrambled. Alreef’s fix: translate the whole phrase as one template with placeholders instead of gluing numbers beside translated words.&lt;/p&gt;

&lt;p&gt;When users write the text themselves, as in chat, do not force the interface’s direction on it. In Project Pavilion each message takes its direction from the script most of its letters use, and the dir attribute survives HTML sanitizing so the direction is not lost on the way.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;A message’s direction from its own text&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;detectContentDirection&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;text&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;rtl&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;ltr&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;text&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;text&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;trim&lt;/span&gt;&lt;span class="p"&gt;())&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;arabic&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;text&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;match&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;ARABIC_G&lt;/span&gt;&lt;span class="p"&gt;)?.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;arabic&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;ltr&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;latin&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;text&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;match&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;LATIN_G&lt;/span&gt;&lt;span class="p"&gt;)?.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;arabic&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;=&lt;/span&gt; &lt;span class="nx"&gt;latin&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;rtl&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;ltr&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  With server-side rendering
&lt;/h2&gt;

&lt;p&gt;The server knows the language from the URL, so it should write the right dir and lang into the HTML from the start. Few things look worse than an Arabic page that draws from the left and then jumps.&lt;/p&gt;

&lt;p&gt;When pages are prerendered in one language, as Alreef’s are in Arabic, a visitor who chose English sees Arabic for a moment before everything switches. The fix there: a small inline script in index.html reads the saved choice and hides the page until it has rendered in English, with a three-second fallback, and the script’s hash pinned in the CSP. It is a workaround with a cost, a later first paint for those visitors; server rendering per language avoids it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Before you ship
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Does every public page have a URL in its own language, with hreflang between the two?&lt;/li&gt;
&lt;li&gt;Does the direction flip after the words arrive, and does the last tap on the toggle win?&lt;/li&gt;
&lt;li&gt;Do Material menus and dialogs open from the right side?&lt;/li&gt;
&lt;li&gt;Is there any margin-left or right left without a reason?&lt;/li&gt;
&lt;li&gt;Do only the arrows flip, not the check mark or the play button?&lt;/li&gt;
&lt;li&gt;Does the English page download the Arabic font? Open the network tab and check.&lt;/li&gt;
&lt;li&gt;Are dates Gregorian or Hijri on purpose, and in which digits?&lt;/li&gt;
&lt;li&gt;Do both languages have the same translation keys, and does the build fail when they do not?&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Where this runs
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Amlaak works this way: Angular with server-side rendering, the language in the URL (/ar and /en), and logical CSS properties almost everywhere. (&lt;a href="https://anasamin.dev/work/amlaak/" rel="noopener noreferrer"&gt;Amlaak case study&lt;/a&gt;)&lt;/li&gt;
&lt;li&gt;Alreef is Arabic first, prerendered in Arabic, with 736 translation keys per language that CI checks match. (&lt;a href="https://anasamin.dev/work/alreef/" rel="noopener noreferrer"&gt;Alreef case study&lt;/a&gt;)&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://anasamin.dev/notes/arabic-english-angular/" rel="noopener noreferrer"&gt;anasamin.dev&lt;/a&gt;. I'm Anas Amin, a software engineer in .NET and the founder of &lt;a href="https://arkedia.dev" rel="noopener noreferrer"&gt;Arkedia&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>angular</category>
      <category>rtl</category>
      <category>i18n</category>
      <category>dotnet</category>
    </item>
    <item>
      <title>⁧مدفوعات Telr في ASP.NET Core: ما لا تقوله الوثائق⁩</title>
      <dc:creator>Anas Amin</dc:creator>
      <pubDate>Thu, 12 Nov 2026 17:00:00 +0000</pubDate>
      <link>https://dev.to/anasamin22311/mdfwt-telr-fy-aspnet-core-m-l-tqwlh-lwthyq-e83</link>
      <guid>https://dev.to/anasamin22311/mdfwt-telr-fy-aspnet-core-m-l-tqwlh-lwthyq-e83</guid>
      <description>&lt;p&gt;&lt;em&gt;⁧ربط صفحة الدفع المستضافة من Telr يأخذ ساعات. العمل الحقيقي في كل ما حولها: إعادة توجيه لا تعود، ورد يصل مرتين، ودفعة تصل بعد أن حرّرت المقاعد.⁩&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  ⁧ثلاث إشارات، واحدة فقط موثوقة⁩
&lt;/h2&gt;

&lt;p&gt;⁧مع صفحة الدفع المستضافة لا تلمس واجهتك البرمجية بيانات البطاقة. تنشئ طلبًا لدى Telr، وترسل العميل إلى الصفحة التي يعيدها، ثم تنتظر النتيجة. والنتيجة تصلك بثلاث طرق لا تتساوى.⁩&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;⁧&lt;strong&gt;رابط العودة.&lt;/strong&gt; يعود المتصفح إلى صفحة القبول أو الرفض أو الإلغاء عندك. مفيد للمستخدم، وبلا قيمة كدليل: أي شخص يستطيع كتابة هذا الرابط، والتبويب المغلق لا يعود أصلًا.⁩&lt;/li&gt;
&lt;li&gt;⁧&lt;strong&gt;إشعار Telr.&lt;/strong&gt; يرسل Telr إلى خادمك إشعارًا موقّعًا بصيغة نموذج (ivp_update_url). دليل جيد بعد التحقق من التوقيع، لكنه قد يتأخر، أو يصل مرتين، أو يسبق المتصفح.⁩&lt;/li&gt;
&lt;li&gt;⁧&lt;strong&gt;order/check.&lt;/strong&gt; خادمك يسأل Telr عن الطلب بمرجعه. هذه هي الإجابة التي تبني عليها، وإليها ترجع كلما اختلفت الإشارتان الأخريان أو سكتتا.⁩&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  ⁧أنشئ الجلسة مرة واحدة⁩
&lt;/h2&gt;

&lt;p&gt;⁧نقرة مزدوجة على زر الدفع، أو إعادة محاولة من اتصال جوال ضعيف، أو تبويبان مفتوحان: كلها تطلب جلسة دفع ثانية للطلب نفسه. وجلستان حيّتان تعنيان أن العميل قد يدفع مرتين. اقفل صف الطلب، وأعد استخدام الجلسة إن كانت محفوظة، واحفظ المرجع والرابط الجديدين في المعاملة نفسها التي أنشأتهما.⁩&lt;/p&gt;

&lt;p&gt;⁧أعد محاولة عمل قاعدة البيانات كما تشاء. لا تعد محاولة الاتصال بالبوابة أبدًا. إن فشل الاتصال بعد خروج الطلب فأنت لا تعرف هل فتح Telr جلسة أم لا، فيوضع الطلب في الانتظار ويُطلب من العميل ألا يبدأ دفعة أخرى. أما الرفض الصريح من Telr فشيء آخر: احذف الطلب وحرّر المقاعد. وضع مهلة قصيرة لاتصال Telr، لأن صف الطلب يبقى مقفولًا وأنت تنتظر.⁩&lt;/p&gt;

&lt;p&gt;⁧تفصيل مهم: مرجع الصفحة المستضافة يُستهلك عند أول تحميل لها. إذا عاد العميل نفسه لاحقًا ليدفع السلة نفسها، فاسأل Telr عن الجلسة القديمة أولًا، واستبدلها فقط إن كانت ما زالت معلّقة.⁩&lt;/p&gt;

&lt;p&gt;&lt;em&gt;⁧جلسة دفع مستضافة واحدة لكل طلب (EF Core وSQL Server)⁩&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;var&lt;/span&gt; &lt;span class="n"&gt;tx&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Database&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;BeginTransactionAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;IsolationLevel&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Serializable&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="c1"&gt;// UPDLOCK: two requests cannot both reach Telr before one has saved its session.&lt;/span&gt;
&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Orders&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;FromSqlInterpolated&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;$"SELECT * FROM Orders WITH (UPDLOCK, HOLDLOCK) WHERE Id = &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;orderId&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;AsTracking&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SingleAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentUrl&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="n"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt; &lt;span class="p"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentOrderRef&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="n"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;PaymentSession&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentUrl&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentOrderRef&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;try&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;session&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;telr&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;CreateSessionAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="c1"&gt;// method: "create"&lt;/span&gt;
    &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentUrl&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Url&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentOrderRef&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Ref&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SaveChangesAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;CommitAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;session&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;Exception&lt;/span&gt; &lt;span class="n"&gt;ex&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;when&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ex&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="n"&gt;not&lt;/span&gt; &lt;span class="n"&gt;GatewayRejectedException&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// The request may have reached Telr: hold the order, never open a second session.&lt;/span&gt;
    &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;PaymentSessionUncertainException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ex&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  ⁧المبالغ نصوص، والإعدادات الإقليمية تخدعك⁩
&lt;/h2&gt;

&lt;p&gt;⁧يستقبل Telr المبلغ نصًا. يبدو ToString("F2") آمنًا حتى يعمل الخادم بإعدادات إقليمية تكتب الفاصلة العشرية فاصلة، فيصبح المبلغ شيئًا غير السعر الذي قصدته. نسّق بالثقافة الثابتة (InvariantCulture)، واحتفظ باختبار وحدة يغيّر ثقافة الخيط إلى fr-FR ليثبت ذلك.⁩&lt;/p&gt;

&lt;p&gt;⁧قرّب حيث يُحسم المال، لا في النهاية. ضريبة تُقرَّب لكل تذكرة بعيدًا عن الصفر، وإجمالي الطلب هو مجموع البنود المقرّبة، يعني أن الرقم الذي ترسله هو نفسه الرقم في قاعدة بياناتك. نسختنا الأولى حسبت الضريبة بـdouble، والآن decimal في كل مكان.⁩&lt;/p&gt;

&lt;p&gt;&lt;em&gt;⁧المبلغ الذي يراه Telr، والإجمالي الذي يجب أن يطابقه⁩&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;foreach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;item&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Items&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;TaxAmount&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Round&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Price&lt;/span&gt; &lt;span class="p"&gt;*&lt;/span&gt; &lt;span class="n"&gt;taxRate&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="m"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;MidpointRounding&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;AwayFromZero&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;TotalAmount&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Items&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Sum&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;i&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Price&lt;/span&gt; &lt;span class="p"&gt;+&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;TaxAmount&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;amount&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;TotalAmount&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToString&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"F2"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;CultureInfo&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;InvariantCulture&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="c1"&gt;// "11.50", never "11,50"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  ⁧ثق في order/check، لا في إعادة التوجيه⁩
&lt;/h2&gt;

&lt;p&gt;⁧صفحة العودة لا تقرر شيئًا. تقرأ رقم الطلب من رابطها وتطلب من واجهتك البرمجية التحقق، عدة مرات، بفاصل ثانيتين تقريبًا. تتأكد الواجهة أن الطلب يخص المستخدم المسجّل، وتستدعي order/check بالمرجع المحفوظ، ثم تقارن وتطبّق.⁩&lt;/p&gt;

&lt;p&gt;⁧قارن كل ما تستطيع: المرجع، ورقم السلة، والمبلغ، والعملة، وعلامة الاختبار. إجابة من وضع الاختبار تصل إلى بيئة الإنتاج، أو دفعة بعملة خاطئة، خطأ في الإعدادات يجب أن يفشل بصوت عالٍ، لا أن يحوّل الطلب إلى مدفوع.⁩&lt;/p&gt;

&lt;p&gt;&lt;em&gt;⁧حالة الطلب في Telr، وما يصبح عليه الطلب عندك⁩&lt;/em&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;⁧حالة الطلب⁩&lt;/th&gt;
&lt;th&gt;⁧المعنى⁩&lt;/th&gt;
&lt;th&gt;⁧order/check⁩&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;⁧مقبول: نفّذ الطلب⁩&lt;/td&gt;
&lt;td&gt;⁧مدفوع⁩&lt;/td&gt;
&lt;td&gt;⁧3، والمعاملة A، بيع أو تحصيل⁩&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;⁧في الانتظار⁩&lt;/td&gt;
&lt;td&gt;⁧مفوَّض، لم يُحصَّل⁩&lt;/td&gt;
&lt;td&gt;⁧2⁩&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;⁧معلّق: اسأل لاحقًا⁩&lt;/td&gt;
&lt;td&gt;⁧معلّق⁩&lt;/td&gt;
&lt;td&gt;⁧1⁩&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;⁧ملغى⁩&lt;/td&gt;
&lt;td&gt;⁧منتهٍ أو ملغى⁩&lt;/td&gt;
&lt;td&gt;⁧⁦-1⁩ أو ⁦-2⁩⁩&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;⁧مرفوض⁩&lt;/td&gt;
&lt;td&gt;⁧مرفوض⁩&lt;/td&gt;
&lt;td&gt;⁧⁦-3⁩⁩&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;⁧خطأ، وتنبيه⁩&lt;/td&gt;
&lt;td&gt;⁧غير معروف⁩&lt;/td&gt;
&lt;td&gt;⁧غير ذلك⁩&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  ⁧إشعار Telr: تحقق منه، ثم أجب دائمًا بـ200⁩
&lt;/h2&gt;

&lt;p&gt;⁧يرسل Telr الإشعار بصيغة نموذج، فاستقبله كنموذج. يوقّع مفتاحك السري وأربعة عشر حقلًا من حقوله بـSHA1، تفصل بينها نقطتان، والمفتاح أولًا. تحقق من رقم المتجر وعلامة الاختبار والعملة مقابل إعداداتك قبل أن تحسب أي توقيع، وقارن التوقيع في زمن ثابت.⁩&lt;/p&gt;

&lt;p&gt;⁧ثم أجب بـ200، مهما حدث. التوقيع الخاطئ، أو الطلب غير المعروف، أو المبلغ غير المطابق يُسجَّل، والمبلغ غير المطابق كخطأ حرج، لكن رد الخطأ لا يفعل إلا أن يخبر الغريب بما تتحقق منه، ويستدعي إعادة محاولات لن تنجح أبدًا.⁩&lt;/p&gt;

&lt;p&gt;&lt;em&gt;⁧التحقق من إشعار المعاملة⁩&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_store&lt;/span&gt; &lt;span class="p"&gt;!=&lt;/span&gt; &lt;span class="n"&gt;settings&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;StoreId&lt;/span&gt; &lt;span class="p"&gt;||&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_test&lt;/span&gt; &lt;span class="p"&gt;!=&lt;/span&gt; &lt;span class="n"&gt;settings&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Test&lt;/span&gt; &lt;span class="p"&gt;||&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_currency&lt;/span&gt; &lt;span class="p"&gt;!=&lt;/span&gt; &lt;span class="n"&gt;settings&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Currency&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;false&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;signed&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;":"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;settings&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;SecretKey&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_store&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_type&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_class&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_test&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_ref&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_prevref&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_firstref&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_currency&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_amount&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_cartid&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_desc&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_status&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_authcode&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_authmessage&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;expected&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;Convert&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToHexStringLower&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;SHA1&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;HashData&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;Encoding&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;UTF8&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;GetBytes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;signed&lt;/span&gt;&lt;span class="p"&gt;)));&lt;/span&gt; &lt;span class="c1"&gt;// SHA1 is Telr's choice&lt;/span&gt;

&lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;CryptographicOperations&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;FixedTimeEquals&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="n"&gt;Encoding&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ASCII&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;GetBytes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;expected&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt; &lt;span class="n"&gt;Encoding&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ASCII&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;GetBytes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_check&lt;/span&gt; &lt;span class="p"&gt;??&lt;/span&gt; &lt;span class="s"&gt;""&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  ⁧طبّق النتيجة مرة واحدة فقط⁩
&lt;/h2&gt;

&lt;p&gt;⁧إشعار Telr وطلب التحقق من المتصفح يصلان غالبًا في الثانية نفسها، وكلاهما يريد أن يجعل الطلب مدفوعًا، ويحسب المقاعد مبيعة، ويفرغ السلة. القراءة ثم الكتابة تسمح بمرور الاثنين. التحديث المشروط يسمح بمرور واحد فقط: لا يطابق إلا ما دام الطلب معلّقًا أو في الانتظار.⁩&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;⁧عدد المبيعات يتحرك بزيادة ذرية في SQL، لا بقراءة ثم جمع ثم حفظ. إشعاران متزامنان كان يكتب أحدهما فوق الآخر.⁩&lt;/li&gt;
&lt;li&gt;⁧إن كانت المقاعد المحجوزة قد ذهبت عند وصول الدفعة، يوضع الطلب في الانتظار للمراجعة بدل تنفيذه بمقاعد شخص آخر.⁩&lt;/li&gt;
&lt;li&gt;⁧تُحذف من السلة البنود التي دُفعت فقط. قد يكون العميل يتصفح فعالية أخرى أثناء الدفع.⁩&lt;/li&gt;
&lt;li&gt;⁧تنفيذ الطلب يعيش في خدمة واحدة. كان لدينا يومًا ثلاثة معالجات تفعل ذلك، لكل منها خطأ مختلف.⁩&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;em&gt;⁧احجز الطلب، ثم نفّذ⁩&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;claimed&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Orders&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Where&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;o&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;o&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Id&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;orderId&lt;/span&gt; &lt;span class="p"&gt;&amp;amp;&amp;amp;&lt;/span&gt;
        &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;o&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentStatus&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;PaymentStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Pending&lt;/span&gt; &lt;span class="p"&gt;||&lt;/span&gt; &lt;span class="n"&gt;o&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentStatus&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;PaymentStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;OnHold&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ExecuteUpdateAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;s&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;s&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SetProperty&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;o&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;o&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentStatus&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SetProperty&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;o&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;o&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentTranRef&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;tranRef&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;claimed&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="m"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// Someone else already settled it. A "paid" for an order we cancelled goes to a person.&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;PaymentStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Authorized&lt;/span&gt; &lt;span class="p"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="n"&gt;current&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="n"&gt;PaymentStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Cancelled&lt;/span&gt; &lt;span class="n"&gt;or&lt;/span&gt; &lt;span class="n"&gt;PaymentStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Declined&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="n"&gt;logger&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;LogCritical&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"Late payment for released order {OrderId}: manual review"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;orderId&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  ⁧سوِّ ما انتهت مهلته⁩
&lt;/h2&gt;

&lt;p&gt;⁧تُحجز المقاعد 30 دقيقة. حين ينتهي الحجز يبدو الحل المغري أن تلغي الطلب وتحرر المقاعد. لكن انتهاء المهلة عندك ليس دليلًا على أن البوابة لم تعد قادرة على الخصم: قد يكون العميل في صفحة الدفع الآن.⁩&lt;/p&gt;

&lt;p&gt;⁧تعمل مهمة خلفية كل خمس دقائق. الطلبات المنتهية التي لها مرجع في Telr يُسأل عنها order/check أولًا، ويُطبَّق ما يقوله Telr. والطلبات التي لم تصل إلى Telr أصلًا تُلغى. وإن فشل السؤال يبقى الحجز حتى الدورة التالية. والطلبات في الانتظار تنتهي أيضًا، وإلا حجزت المقاعد إلى الأبد.⁩&lt;/p&gt;

&lt;h2&gt;
  
  
  ⁧الجوال: التطبيق لا يقرأ الرابط⁩
&lt;/h2&gt;

&lt;p&gt;⁧دفع الويب يعيد توجيه الصفحة كلها (framed 0). تطبيق Flutter يفتح الصفحة المستضافة نفسها في WebView ويراقب العودة إلى نطاقه، ثم يغلق WebView ويطلب من الواجهة البرمجية التحقق. لا يقرر النجاح أبدًا من الرابط الذي عاد إليه، للسبب نفسه الذي لا تفعل صفحة الويب ذلك من أجله.⁩&lt;/p&gt;

&lt;h2&gt;
  
  
  ⁧المفاتيح في البيئة، ونشر يرفض وضع الاختبار⁩
&lt;/h2&gt;

&lt;p&gt;⁧رقم المتجر ومفتاح المصادقة والمفتاح السري في متغيرات البيئة (Telr__StoreId وأخواتها)، لا في ملفات appsettings التي تنتهي في مستودع. وسكربت النشر للإنتاج يرفض الإطلاق إن كانت البيئة ما زالت في وضع الاختبار أو كانت روابط العودة تشير إلى مكان غير متوقع.⁩&lt;/p&gt;

&lt;p&gt;&lt;em&gt;⁧سطر واحد في سكربت النشر⁩&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;grep&lt;/span&gt; &lt;span class="nt"&gt;-Fxq&lt;/span&gt; &lt;span class="s1"&gt;'Telr__Test=0'&lt;/span&gt; .env &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="o"&gt;{&lt;/span&gt; &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s1"&gt;'Telr is still in test mode'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nb"&gt;exit &lt;/span&gt;1&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="o"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  ⁧قبل أن تستقبل مالًا حقيقيًا⁩
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;⁧هل يُنسَّق المبلغ بالثقافة الثابتة، وهل يساوي مجموع البنود المقرّبة؟⁩&lt;/li&gt;
&lt;li&gt;⁧هل يمكن لنقرة مزدوجة أو إعادة محاولة أن تفتح جلسة ثانية للطلب نفسه؟⁩&lt;/li&gt;
&lt;li&gt;⁧هل تسأل صفحة العودة خادمك، وهل يسأل خادمك Telr؟⁩&lt;/li&gt;
&lt;li&gt;⁧هل يتحقق الإشعار من المتجر وعلامة الاختبار والعملة والتوقيع والمبلغ، ثم يجيب بـ200 رغم ذلك؟⁩&lt;/li&gt;
&lt;li&gt;⁧هل يمكن للإشعار ولطلب التحقق أن ينفّذا الطلب نفسه مرتين؟⁩&lt;/li&gt;
&lt;li&gt;⁧ماذا يحدث لدفعة تصل بعد انتهاء الحجز؟⁩&lt;/li&gt;
&lt;li&gt;⁧هل المفاتيح خارج المستودع، وهل يمكن للإنتاج أن يعمل في وضع الاختبار بالخطأ؟⁩&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  ⁧أين استخدمت هذا⁩
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;⁧Zotic يبيع التذاكر للقاعات السعودية بهذه الطريقة: ASP.NET Core وEF Core خلف موقع Angular وتطبيق Flutter، والدفع بالريال عبر Telr. (&lt;a href="https://anasamin.dev/ar/work/zotic/" rel="noopener noreferrer"&gt;دراسة حالة Zotic&lt;/a&gt;)⁩&lt;/li&gt;
&lt;li&gt;⁧Happy Ticket يأخذ مدفوعات Telr أيضًا، على Blazor Server وMySQL، ويتحقق من توقيع كل رد قبل اعتبار الطلب مدفوعًا. (&lt;a href="https://anasamin.dev/ar/work/happy-ticket/" rel="noopener noreferrer"&gt;دراسة حالة Happy Ticket&lt;/a&gt;)⁩&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;⁧نُشر أولًا على &lt;a href="https://anasamin.dev/ar/notes/telr-payments-aspnet-core/" rel="noopener noreferrer"&gt;anasamin.dev&lt;/a&gt;. أنا أنس أمين، مهندس برمجيات ⁦.NET⁩ ومؤسس &lt;a href="https://arkedia.dev/ar" rel="noopener noreferrer"&gt;أركيديا&lt;/a&gt;.⁩&lt;/em&gt;&lt;/p&gt;

</description>
      <category>dotnet</category>
      <category>payments</category>
      <category>telr</category>
      <category>arabic</category>
    </item>
    <item>
      <title>Incremental RAG indexing without losing the old index</title>
      <dc:creator>Anas Amin</dc:creator>
      <pubDate>Tue, 10 Nov 2026 13:00:00 +0000</pubDate>
      <link>https://dev.to/anasamin22311/incremental-rag-indexing-without-losing-the-old-index-7cp</link>
      <guid>https://dev.to/anasamin22311/incremental-rag-indexing-without-losing-the-old-index-7cp</guid>
      <description>&lt;p&gt;&lt;em&gt;Re-indexing is easy when the collection is small and nobody is using it. The harder problem is changing a live index while documents, parsers, embedding services, and vector storage can all fail at different points. The examples come from Project Pavilion, which indexes its project records into Qdrant on .NET 9.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Treat indexing as a state transition
&lt;/h2&gt;

&lt;p&gt;An indexing job is not just a loop that reads files and writes vectors. It changes the version of knowledge that retrieval is allowed to use. That makes the publish boundary more important than the loop itself.&lt;/p&gt;

&lt;p&gt;If new chunks replace old chunks one at a time, users can query a half-updated collection. A document may have new text with old metadata, or only some of its chunks may exist. The system is technically online, but the answers are difficult to trust.&lt;/p&gt;

&lt;p&gt;A safer model separates preparation from publication. Build the next document version away from the active one, validate it, then make one small state change that tells retrieval which version is current.&lt;/p&gt;

&lt;h2&gt;
  
  
  Give each source a durable identity
&lt;/h2&gt;

&lt;p&gt;File names are weak identifiers. They change, collide, and say nothing about whether the content is actually different. Keep a small indexing record for each source so the job can make a deliberate decision before it calls an expensive parser or embedding model.&lt;/p&gt;

&lt;p&gt;In Project Pavilion each source is a record, such as a requirement or a task, and its key is the record’s type and id. The Qdrant point id comes from the first 16 bytes of a SHA-256 of those two, and each record is a single point, so indexing it again overwrites that point. Retrieval sees the old vector or the new one, never a mix and never two copies.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Source key.&lt;/strong&gt; A stable identifier from the business system, storage object, or document database.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Content hash.&lt;/strong&gt; A hash of the bytes or normalized text. Timestamps can be kept as hints, not proof of change.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Pipeline version.&lt;/strong&gt; The parser, chunking rules, embedding model, and index schema that produced the active version.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Lifecycle state.&lt;/strong&gt; Discovered, processing, staged, active, failed, or deleted. A job should never have to guess where it stopped.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;em&gt;Minimal indexing record&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;source_key
content_hash
pipeline_version
active_version
staged_version
status
last_error
updated_at
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Use a publish boundary
&lt;/h2&gt;

&lt;p&gt;The exact storage model can vary. The useful property is the same: retrieval sees either the old complete document or the new complete document, never a mixture.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Discover.&lt;/strong&gt; Read source metadata and compare it with the indexing record. Mark missing sources as deletion candidates, but do not delete them yet.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Prepare.&lt;/strong&gt; Parse, normalize, split, and enrich the changed document. Keep the resulting chunks under a new version identifier.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Embed and stage.&lt;/strong&gt; Write the full set of vectors and metadata without changing the active version.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Validate.&lt;/strong&gt; Check that the staged version has the expected document identity, non-empty text, valid vectors, and required retrieval metadata.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Publish.&lt;/strong&gt; Switch the active version in one durable operation. If the storage engine cannot do this atomically, use an alias or a separate manifest that retrieval reads first.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Clean up.&lt;/strong&gt; Remove superseded vectors later. Cleanup should not sit on the critical path of a successful publish.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Degraded mode is a product decision
&lt;/h2&gt;

&lt;p&gt;Degraded mode should be decided before an outage. Otherwise every dependency failure turns into an improvised choice between returning an error and returning an answer based on incomplete data.&lt;/p&gt;

&lt;p&gt;The safest fallback is often the last known-good index. It may be stale, but it has a clear boundary and can be labelled as stale. A partially written new index has neither property.&lt;/p&gt;

&lt;p&gt;Project Pavilion makes two of these decisions in code. If the embedding fails while a record is being indexed, the write is skipped and the old vector stays. If a question arrives while embeddings are down, retrieval returns no context instead of an error, the answer is built without it, and the chat’s search tool falls back to a SQL query when it knows which kind of record it wants.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Examples of explicit failure behaviour&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Failure&lt;/th&gt;
&lt;th&gt;Ingestion behaviour&lt;/th&gt;
&lt;th&gt;Retrieval behaviour&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Embedding service unavailable&lt;/td&gt;
&lt;td&gt;Keep the source pending and retry with limits.&lt;/td&gt;
&lt;td&gt;Serve the active index. Do not publish empty vectors.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Parser rejects one document&lt;/td&gt;
&lt;td&gt;Quarantine that source and retain its old active version.&lt;/td&gt;
&lt;td&gt;Continue serving other documents and expose the failed source to operators.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Vector store is slow&lt;/td&gt;
&lt;td&gt;Pause new batches when a bounded timeout is reached.&lt;/td&gt;
&lt;td&gt;Return a clear temporary failure, or use a tested secondary search path if one exists.&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Metadata store unavailable&lt;/td&gt;
&lt;td&gt;Do not start jobs that cannot record their state.&lt;/td&gt;
&lt;td&gt;Keep reading the active index only if its ownership and version remain unambiguous.&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  Retry the operation, not the ambiguity
&lt;/h2&gt;

&lt;p&gt;Retries are useful for temporary network and service failures. They are dangerous when the write may already have succeeded and the operation is not idempotent. Give each job, document version, and chunk a deterministic key so the same work can be attempted again without producing duplicates.&lt;/p&gt;

&lt;p&gt;A malformed file is not a temporary failure. After a small number of attempts, move it out of the normal queue and record enough context to repair it. One bad source should not block every healthy source behind it.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Put limits and jitter on retries. Infinite retry loops hide incidents and consume workers.&lt;/li&gt;
&lt;li&gt;Keep failed work visible. A dead-letter queue without an owner is only another place to lose documents.&lt;/li&gt;
&lt;li&gt;Make cancellation safe. Staged data can remain for diagnosis, but it must not become active by accident.&lt;/li&gt;
&lt;li&gt;In Project Pavilion the embedding call is retried three times with exponential backoff and jitter, behind a circuit breaker. The Qdrant client stops calling Qdrant for five minutes after two transient failures in a row, and a malformed request does not count as one.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Log the document journey
&lt;/h2&gt;

&lt;p&gt;An ingestion dashboard does not need dozens of charts. It needs to answer a few operational questions quickly: what changed, what is active, what failed, and whether retrieval is using stale data.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Correlate source key, job ID, pipeline version, and published document version.&lt;/li&gt;
&lt;li&gt;Count discovered, skipped, staged, published, quarantined, and deleted sources separately.&lt;/li&gt;
&lt;li&gt;Record dependency latency and failures without logging document text or other sensitive content.&lt;/li&gt;
&lt;li&gt;Expose index freshness and the last successful publish time to operators.&lt;/li&gt;
&lt;li&gt;Project Pavilion logs every index request with a short correlation id, its trigger, the node type and the record id, so repeated indexing of one record can be traced to whatever asked for it.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Before the next indexing release
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Can a document be reprocessed without creating duplicate active chunks?&lt;/li&gt;
&lt;li&gt;Can retrieval identify one complete active version?&lt;/li&gt;
&lt;li&gt;Does a failed new version leave the previous version usable?&lt;/li&gt;
&lt;li&gt;Are deletion and cleanup delayed until publication is safe?&lt;/li&gt;
&lt;li&gt;Can an operator find one failed source without reading application logs line by line?&lt;/li&gt;
&lt;li&gt;Does the UI say when results may be stale?&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Where this runs
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Project Pavilion indexes its project records into Qdrant on .NET 9. A saved requirement, task or risk re-indexes on its own under a fixed point id, and while the embedding service is down the chat answers without retrieved context instead of failing. (&lt;a href="https://anasamin.dev/work/project-pavilion/" rel="noopener noreferrer"&gt;Project Pavilion case study&lt;/a&gt;)&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://anasamin.dev/notes/incremental-rag-indexing/" rel="noopener noreferrer"&gt;anasamin.dev&lt;/a&gt;. I'm Anas Amin, a software engineer in .NET and the founder of &lt;a href="https://arkedia.dev" rel="noopener noreferrer"&gt;Arkedia&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>rag</category>
      <category>indexing</category>
      <category>reliability</category>
      <category>dotnet</category>
    </item>
    <item>
      <title>⁧تطبيق Angular بالعربية والإنجليزية: الاتجاه والخطوط والأرقام⁩</title>
      <dc:creator>Anas Amin</dc:creator>
      <pubDate>Mon, 09 Nov 2026 17:29:31 +0000</pubDate>
      <link>https://dev.to/anasamin22311/ttbyq-angular-blrby-wlnjlyzy-ltjh-wlkhtwt-wlrqm-5h7k</link>
      <guid>https://dev.to/anasamin22311/ttbyq-angular-blrby-wlnjlyzy-ltjh-wlkhtwt-wlrqm-5h7k</guid>
      <description>&lt;p&gt;&lt;em&gt;⁧ترجمة النصوص هي الجزء السهل. الصعب هو كل ما حولها: صفحة تنقلب قبل أن تصل كلماتها، وأسهم تشير إلى الاتجاه الخطأ، وتاريخ هجري لم يطلبه أحد، ونطاق صفحات يُقرأ بالمقلوب. هذا ما تعلّمته من ثلاثة أنظمة تعمل اليوم بالعربية والإنجليزية.⁩&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  ⁧اللغة في الرابط، لا في المتصفح⁩
&lt;/h2&gt;

&lt;p&gt;⁧في الصفحات العامة اجعل اللغة جزءًا من الرابط: ⁦/ar/...⁩ و⁦/en/...⁩. الرابط هو المصدر الوحيد للحقيقة. محرك البحث يرى صفحتين منفصلتين، والرابط المنسوخ يفتح بلغته، وزر التبديل ينقلك إلى الصفحة نفسها باللغة الأخرى دون أن يقفز بك إلى أعلى الصفحة.⁩&lt;/p&gt;

&lt;p&gt;⁧أي بادئة غير معروفة تُحوَّل إلى اللغة الافتراضية، والصفحة الرئيسية بلا بادئة تُحوَّل أيضًا. أما localStorage فاتركه لصفحات الإدارة وتسجيل الدخول التي لا تحتاجها محركات البحث. ولا تنسَ روابط hreflang بين النسختين، مع x-default.⁩&lt;/p&gt;

&lt;p&gt;&lt;em&gt;⁧محلّل المسار: لغة معروفة أو تحويل⁩&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;langResolver&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;ResolveFn&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;AppLang&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;async &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;route&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;translations&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;inject&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;TranslationCatalogService&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;router&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;inject&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;Router&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;lang&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;parseLang&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;route&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;paramMap&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;get&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;lang&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// Unknown locale: rewrite the first segment to the default one.&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;rest&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;url&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;split&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;/&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;rest&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nx"&gt;rest&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;DEFAULT_LANG&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="nx"&gt;rest&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;push&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;DEFAULT_LANG&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;RedirectCommand&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;router&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;parseUrl&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;`/&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;rest&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;/&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;)}&lt;/span&gt;&lt;span class="s2"&gt;`&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;replaceUrl&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt; &lt;span class="p"&gt;});&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nx"&gt;translations&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;switchTo&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;};&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  ⁧اقلب الاتجاه بعد وصول الكلمات⁩
&lt;/h2&gt;

&lt;p&gt;⁧إذا قلبت dir قبل أن يصل ملف الترجمة، يرى المستخدم واجهة مقلوبة بنصوص اللغة السابقة لجزء من الثانية. الترتيب الصحيح: حمّل الكلمات أولًا، ثم بدّل اللغة، ثم اقلب الاتجاه. وإذا ضغط المستخدم زر التبديل مرتين بسرعة، فالطلب الأحدث هو الذي يفوز، والأقدم يُلغى بصمت.⁩&lt;/p&gt;

&lt;p&gt;⁧اضبط dir وlang على عنصر html عبر Renderer2 والمستند المحقون، لا عبر document مباشرة، حتى يعمل ذلك على الخادم أيضًا. ومكونات Angular Material تقرأ الاتجاه من Directionality في CDK، فاستبدلها بخدمة تتبع لغة التطبيق، وإلا ظلت القوائم والنوافذ المنبثقة تفتح من الجهة الخطأ.⁩&lt;/p&gt;

&lt;p&gt;&lt;em&gt;⁧الكلمات أولًا، والاتجاه أخيرًا⁩&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="nf"&gt;switchTo&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;AppLang&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="nb"&gt;Promise&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="nx"&gt;boolean&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;latest&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ensure&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;                 &lt;span class="c1"&gt;// lazy-load the dictionary chunk&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;latest&lt;/span&gt; &lt;span class="o"&gt;!==&lt;/span&gt; &lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;  &lt;span class="c1"&gt;// a newer toggle won&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;firstValueFrom&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;translate&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;use&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
  &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;localization&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;setLanguage&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="c1"&gt;// App root: one effect sets &amp;lt;html dir lang&amp;gt;, in the browser and on the server.&lt;/span&gt;
&lt;span class="nf"&gt;effect&lt;/span&gt;&lt;span class="p"&gt;(()&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;lang&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;localization&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;language&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;root&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nb"&gt;document&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;documentElement&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;renderer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;setAttribute&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;root&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;dir&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;lang&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;ar&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;rtl&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;ltr&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="k"&gt;this&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;renderer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;setAttribute&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;root&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;lang&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nx"&gt;lang&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  ⁧خصائص CSS المنطقية أولًا⁩
&lt;/h2&gt;

&lt;p&gt;⁧margin-inline-start بدل margin-left، وpadding-inline بدل padding-right، وinset-inline-end بدل right. بهذا تنقلب الواجهة وحدها مع dir دون ملف أنماط ثانٍ. في Amlaak نحو 153 استخدامًا للخصائص المنطقية مقابل نحو 12 للخصائص الفيزيائية.⁩&lt;/p&gt;

&lt;p&gt;⁧أبقِ [dir=rtl] لما لا مقابل منطقيًا له: transform وtransform-origin والحركات. وقاعدة واحدة للأيقونات: اقلب فقط ما يدل على اتجاه، كالأسهم وعلامات التالي والسابق. علامة الصح وزر التشغيل والبحث تبقى كما هي.⁩&lt;/p&gt;

&lt;p&gt;&lt;em&gt;⁧صنف واحد للأيقونات التي تشير إلى اتجاه⁩&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight css"&gt;&lt;code&gt;&lt;span class="o"&gt;[&lt;/span&gt;&lt;span class="nt"&gt;dir&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;'rtl'&lt;/span&gt;&lt;span class="o"&gt;]&lt;/span&gt; &lt;span class="nc"&gt;.flip-rtl&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;transform&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nf"&gt;scaleX&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;-1&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nc"&gt;.card-cta&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="py"&gt;margin-inline-start&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;auto&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c"&gt;/* right in English, left in Arabic */&lt;/span&gt;
  &lt;span class="py"&gt;padding-inline&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="m"&gt;1rem&lt;/span&gt; &lt;span class="m"&gt;0.75rem&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  ⁧خط عربي لا يثقل الصفحة الإنجليزية⁩
&lt;/h2&gt;

&lt;p&gt;⁧قسّم الخط بـunicode-range إلى مجموعة عربية ومجموعة لاتينية، فلا تنزّل الصفحة الإنجليزية الحروف العربية أبدًا. وحمّل مسبقًا (preload) المجموعة التي تحتاجها الشاشة الأولى فقط: في Alreef يُحمَّل خط Tajawal مسبقًا لأن النص العربي هو أكبر ما يُرسم أولًا، وفي Amlaak يرسل الخادم تلميحات تحميل مختلفة لكل لغة.⁩&lt;/p&gt;

&lt;p&gt;⁧تفصيل صغير: اسم اللغة الأخرى على زر التبديل يُكتب بخط النظام، وإلا جرّ الزر وحده ملف الخط الآخر إلى كل صفحة. وتذكر أن letter-spacing يفصل الحروف العربية المتصلة، فألغه في الصفحات العربية.⁩&lt;/p&gt;

&lt;h2&gt;
  
  
  ⁧الأرقام والتواريخ⁩
&lt;/h2&gt;

&lt;p&gt;⁧ar-SA وحدها تعطيك التقويم الهجري والأرقام الهندية في كثير من المتصفحات. إن كان العمل بالميلادي وبالأرقام اللاتينية، فاطلب ذلك صراحة، وحدد المنطقة الزمنية بدل الاعتماد على جهاز المستخدم.⁩&lt;/p&gt;

&lt;p&gt;&lt;em&gt;⁧ميلادي، بأرقام لاتينية، بتوقيت الرياض⁩&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;date&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nx"&gt;Intl&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;DateTimeFormat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;ar-SA-u-ca-gregory-nu-latn&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="na"&gt;dateStyle&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;medium&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="na"&gt;timeZone&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;Asia/Riyadh&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;}).&lt;/span&gt;&lt;span class="nf"&gt;format&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Date&lt;/span&gt;&lt;span class="p"&gt;());&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;compact&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nx"&gt;Intl&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nc"&gt;NumberFormat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;ar-u-nu-latn&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;notation&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;compact&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;}).&lt;/span&gt;&lt;span class="nf"&gt;format&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;1250000&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  ⁧النص المختلط⁩
&lt;/h2&gt;

&lt;p&gt;⁧جملة تجمع العربية والأرقام والإنجليزية تتبع خوارزمية الاتجاه الثنائي، والنتيجة أحيانًا مفاجئة. عبارة النطاق في ترقيم الصفحات بـAngular Material (من 1 إلى 15 من أصل 44) تُبنى بلصق أرقام بجانب كلمات، وفي واجهة عربية تخرج مبعثرة. الحل في Alreef: ترجم العبارة كاملة بقالب فيه متغيرات، بدل لصق الأرقام بجانب كلمات مترجمة.⁩&lt;/p&gt;

&lt;p&gt;⁧وحين يكتب المستخدمون أنفسهم، كما في المحادثات، لا تفرض اتجاه الواجهة على المحتوى. في Project Pavilion تأخذ كل رسالة اتجاهها من الحروف الغالبة فيها، ويُسمح بخاصية dir في HTML المنقّى حتى لا يضيع الاتجاه في الطريق.⁩&lt;/p&gt;

&lt;p&gt;&lt;em&gt;⁧اتجاه الرسالة من محتواها⁩&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;detectContentDirection&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;text&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kr"&gt;string&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;undefined&lt;/span&gt;&lt;span class="p"&gt;):&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;rtl&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;ltr&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;text&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;text&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;trim&lt;/span&gt;&lt;span class="p"&gt;())&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;arabic&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;text&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;match&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;ARABIC_G&lt;/span&gt;&lt;span class="p"&gt;)?.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;arabic&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;ltr&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;latin&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;text&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;match&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;LATIN_G&lt;/span&gt;&lt;span class="p"&gt;)?.&lt;/span&gt;&lt;span class="nx"&gt;length&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nx"&gt;arabic&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;=&lt;/span&gt; &lt;span class="nx"&gt;latin&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;rtl&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;ltr&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  ⁧مع العرض على الخادم⁩
&lt;/h2&gt;

&lt;p&gt;⁧الخادم يعرف اللغة من الرابط، فليكتب dir وlang الصحيحين في HTML من البداية. لا شيء أسوأ من صفحة عربية تُرسم من اليسار ثم تقفز.⁩&lt;/p&gt;

&lt;p&gt;⁧وإن كانت الصفحات مولّدة مسبقًا بلغة واحدة، كما في Alreef بالعربية، فزائر اختار الإنجليزية سيرى العربية لحظة قبل أن يتبدل كل شيء. الحل هناك: سطر صغير في index.html يقرأ الاختيار المحفوظ ويخفي الصفحة حتى تُرسم بالإنجليزية، مع مهلة احتياطية ثلاث ثوانٍ، وبصمة السطر مثبتة في سياسة CSP. وهو حل التفافي له ثمن: يتأخر أول رسم للصفحة عند هؤلاء الزوار، والعرض على الخادم لكل لغة يتجنبه.⁩&lt;/p&gt;

&lt;h2&gt;
  
  
  ⁧قبل الإطلاق⁩
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;⁧هل لكل صفحة عامة رابط بلغتها، مع hreflang بين النسختين؟⁩&lt;/li&gt;
&lt;li&gt;⁧هل يتبدل الاتجاه بعد وصول الكلمات، وهل يفوز آخر ضغط على زر التبديل؟⁩&lt;/li&gt;
&lt;li&gt;⁧هل تفتح قوائم Material ونوافذها من الجهة الصحيحة؟⁩&lt;/li&gt;
&lt;li&gt;⁧هل بقي margin-left أو right دون سبب؟⁩&lt;/li&gt;
&lt;li&gt;⁧هل تنقلب الأسهم وحدها، لا علامة الصح ولا زر التشغيل؟⁩&lt;/li&gt;
&lt;li&gt;⁧هل تنزّل الصفحة الإنجليزية الخط العربي؟ افتح أدوات المطور وتأكد.⁩&lt;/li&gt;
&lt;li&gt;⁧هل التواريخ ميلادية أو هجرية عن قصد، وبأي أرقام؟⁩&lt;/li&gt;
&lt;li&gt;⁧هل يتطابق عدد مفاتيح الترجمة في اللغتين، ويفشل البناء إن لم يتطابق؟⁩&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  ⁧أين استخدمت هذا⁩
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;⁧Amlaak يعمل بهذه الطريقة: Angular مع العرض على الخادم، واللغة في الرابط (⁦/ar⁩ و⁦/en⁩)، وخصائص CSS المنطقية في كل مكان تقريبًا. (&lt;a href="https://anasamin.dev/ar/work/amlaak/" rel="noopener noreferrer"&gt;دراسة حالة Amlaak&lt;/a&gt;)⁩&lt;/li&gt;
&lt;li&gt;⁧Alreef عربي أولًا، بصفحات مولّدة مسبقًا بالعربية، و736 مفتاحًا للترجمة في كل لغة يفحص CI تطابقها. (&lt;a href="https://anasamin.dev/ar/work/alreef/" rel="noopener noreferrer"&gt;دراسة حالة Alreef&lt;/a&gt;)⁩&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;⁧نُشر أولًا على &lt;a href="https://anasamin.dev/ar/notes/arabic-english-angular/" rel="noopener noreferrer"&gt;anasamin.dev&lt;/a&gt;. أنا أنس أمين، مهندس برمجيات ⁦.NET⁩ ومؤسس &lt;a href="https://arkedia.dev/ar" rel="noopener noreferrer"&gt;أركيديا&lt;/a&gt;.⁩&lt;/em&gt;&lt;/p&gt;

</description>
      <category>angular</category>
      <category>i18n</category>
      <category>rtl</category>
      <category>arabic</category>
    </item>
    <item>
      <title>Permission-heavy multi-tenant systems: make the access check boring</title>
      <dc:creator>Anas Amin</dc:creator>
      <pubDate>Fri, 06 Nov 2026 13:00:00 +0000</pubDate>
      <link>https://dev.to/anasamin22311/permission-heavy-multi-tenant-systems-make-the-access-check-boring-khk</link>
      <guid>https://dev.to/anasamin22311/permission-heavy-multi-tenant-systems-make-the-access-check-boring-khk</guid>
      <description>&lt;p&gt;&lt;em&gt;Permission-heavy systems become risky when access rules are scattered across controllers, UI checks, repository filters, and background jobs. The aim is not a clever authorization framework. It is one rule path that is difficult to bypass. The examples come from Shield, Zotic, CAS, Question Banking and Amlaak.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Start with the access tuple
&lt;/h2&gt;

&lt;p&gt;Every protected operation can be described with four values: the actor, the tenant, the action, and the resource. If one is unknown, the system does not yet have enough information to allow the operation.&lt;/p&gt;

&lt;p&gt;This simple tuple prevents a common mistake: checking that a user has a permission somewhere, then loading a resource that belongs to another tenant. Permission and ownership need to be evaluated together.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The decision input&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;record&lt;/span&gt; &lt;span class="nc"&gt;AccessRequest&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="n"&gt;Guid&lt;/span&gt; &lt;span class="n"&gt;ActorId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;Guid&lt;/span&gt; &lt;span class="n"&gt;TenantId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;Action&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;ResourceType&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;Guid&lt;/span&gt;&lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;ResourceId&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Resolve the tenant from trusted context
&lt;/h2&gt;

&lt;p&gt;A route parameter or request body can name a tenant, but it cannot prove membership in that tenant. Resolve the active tenant from authenticated membership, then compare any requested tenant identifier with it.&lt;/p&gt;

&lt;p&gt;Administrative cross-tenant work should use an explicit path with separate policy and audit rules. Hiding it inside the normal tenant resolver makes ordinary code much harder to reason about.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Create one request-scoped tenant context after authentication.&lt;/li&gt;
&lt;li&gt;Reject a missing or ambiguous tenant before business logic starts.&lt;/li&gt;
&lt;li&gt;Pass the tenant identifier into application and data access boundaries explicitly.&lt;/li&gt;
&lt;li&gt;Do not accept a tenant identifier from a message or scheduled job without validating who created that work.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Keep roles and permissions separate
&lt;/h2&gt;

&lt;p&gt;Roles are a management tool. Permissions are the actions the application actually protects. Code that asks for a role name tends to grow exceptions such as manager-or-owner-or-support. Code that asks for a permission can keep the business decision in one place.&lt;/p&gt;

&lt;p&gt;Use stable permission names that describe an action, for example invoice.read or member.invite. Map tenant roles to those permissions in configuration or data. The application checks the permission; the administration UI decides which roles receive it.&lt;/p&gt;

&lt;p&gt;Shield has five user types: admin, company, facility, guard and preventive security. Each type has its own permission set, and every new company gets an admin role of its own that holds the company set.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Global policy.&lt;/strong&gt; Rules such as account status, tenant membership, and support access that apply before a resource is loaded. In Amlaak, an account whose role can manage users, roles or integrations, or export personal data, stays restricted until it enrols in TOTP MFA.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Permission policy.&lt;/strong&gt; Whether the actor may attempt the action in the active tenant.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Resource policy.&lt;/strong&gt; Ownership, state, department, or other facts that can only be checked against the resource. In Question Banking, the ReadQuestionBank permission only gets a request as far as the bank; the bank then lets in its owner, anyone if it is public, or someone holding a share that has not expired. Everyone else gets not found.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Queries are part of the security boundary
&lt;/h2&gt;

&lt;p&gt;An authorization check followed by an unscoped query is still a data leak. Put the tenant condition in the database query that loads or changes the resource. This also handles the case where a resource identifier is valid but belongs to another tenant.&lt;/p&gt;

&lt;p&gt;Global query filters can reduce repetition in Entity Framework Core, but they should not become invisible magic. Raw SQL, background work, admin queries, and filter disabling all need deliberate review. Sensitive writes benefit from a repository or application method that requires a tenant ID rather than reading one from a global static value.&lt;/p&gt;

&lt;p&gt;Zotic keeps tenant scoping out of individual queries: one query filter, registered for every entity that derives from its multi-tenant base class, and a SaveChanges interceptor that stamps the tenant on new rows. CAS scopes by person instead of tenant: a doctor’s course list holds only the courses they teach, and a receptionist’s only those of the doctors they are assigned to.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Scope the resource in the query&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Orders&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SingleOrDefaultAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="n"&gt;x&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;x&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Id&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;request&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;OrderId&lt;/span&gt;
          &lt;span class="p"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="n"&gt;x&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;TenantId&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;tenant&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;cancellationToken&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Protect the whole write path
&lt;/h2&gt;

&lt;p&gt;UI visibility is not authorization. Hiding a button helps the user understand the product, but the API or command handler must make the final decision. The same rule applies to bulk imports, message consumers, scheduled jobs, and internal tools.&lt;/p&gt;

&lt;p&gt;For background work, store the tenant and initiating actor with the job. At execution time, rebuild a limited authorization context or use a clearly named service identity. Do not let a worker inherit broad access simply because it runs inside the backend.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Resolve the actor and tenant.&lt;/li&gt;
&lt;li&gt;Check the action permission.&lt;/li&gt;
&lt;li&gt;Load the resource inside the tenant boundary.&lt;/li&gt;
&lt;li&gt;Apply resource-specific rules.&lt;/li&gt;
&lt;li&gt;Change state and write an audit event in the same application operation.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Permission caches need an invalidation story
&lt;/h2&gt;

&lt;p&gt;Caching a permission set can remove repeated database reads, but a key based only on user ID is unsafe in a multi-tenant system. Include the tenant and a policy version, role assignment version, or another value that changes when access is edited.&lt;/p&gt;

&lt;p&gt;Decide how quickly revocation must take effect. A short expiration may be acceptable for low-risk read access. Sensitive actions may need a fresh check or direct invalidation. This is a product and security choice, not only a cache setting.&lt;/p&gt;

&lt;p&gt;Amlaak keeps a user’s permissions in memory for three minutes, under a key made of the user id and a hash of the security stamp in their token. A role change rotates the stamp, and a token with an old stamp is rejected, so a newly issued token never reads a stale entry.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;A safer cache key shape&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;permissions:{tenantId}:{actorId}:{assignmentVersion}
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Audit decisions that matter
&lt;/h2&gt;

&lt;p&gt;A useful audit event says who attempted what, in which tenant, against which resource, and whether it was allowed. It also records the policy or permission involved. It should not copy tokens, request bodies, or sensitive fields into logs.&lt;/p&gt;

&lt;p&gt;Denied access can be noisy, so aggregate routine denials and keep detailed records for sensitive operations. A support team needs enough context to investigate without receiving the protected data itself.&lt;/p&gt;

&lt;p&gt;Amlaak marks each audited operation with an attribute that names the action, such as User.Block or Inquiry.Export. A MediatR behaviour at the end of the pipeline writes the row only after the handler succeeds, and masks any property named like a password, token or secret before it is stored.&lt;/p&gt;

&lt;h2&gt;
  
  
  Test boundaries, not only happy paths
&lt;/h2&gt;

&lt;p&gt;Authorization tests should prove that the boundary holds when identifiers are valid but belong to the wrong place. A test that uses only missing IDs cannot catch cross-tenant reads.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Minimum cases for a protected operation&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Case&lt;/th&gt;
&lt;th&gt;Expected result&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Member, correct tenant, allowed permission, owned resource&lt;/td&gt;
&lt;td&gt;Allow&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Member, correct tenant, missing permission&lt;/td&gt;
&lt;td&gt;Deny without loading protected data&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Member, other tenant, valid resource ID&lt;/td&gt;
&lt;td&gt;Deny or return not found consistently&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Permission was revoked after a cache entry was created&lt;/td&gt;
&lt;td&gt;Deny within the agreed revocation window&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Background job with removed initiator access&lt;/td&gt;
&lt;td&gt;Follow the documented service or initiator policy&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Administrator path used through a normal tenant endpoint&lt;/td&gt;
&lt;td&gt;Deny&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  Boring is the target
&lt;/h2&gt;

&lt;p&gt;A new endpoint should not require its author to invent an authorization sequence. Give it one tenant context, one permission name, one tenant-scoped resource query, and one place for the final decision. Reviewers can then look for missing steps instead of reverse-engineering a different security model in every feature.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where this runs
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Shield gives each of its five user types (admin, company, facility, guard and preventive security) its own permission set, and every new company gets an admin role of its own. (&lt;a href="https://anasamin.dev/work/shield/" rel="noopener noreferrer"&gt;Shield case study&lt;/a&gt;)&lt;/li&gt;
&lt;li&gt;Zotic scopes its multi-tenant entities with one EF Core query filter and stamps the tenant on new rows in a SaveChanges interceptor, with 82 permissions across the organiser dashboard. (&lt;a href="https://anasamin.dev/work/zotic/" rel="noopener noreferrer"&gt;Zotic case study&lt;/a&gt;)&lt;/li&gt;
&lt;li&gt;CAS has 85 permissions over five roles, and narrows each doctor’s and receptionist’s course list to the courses they teach or are assigned to. (&lt;a href="https://anasamin.dev/work/cas/" rel="noopener noreferrer"&gt;CAS case study&lt;/a&gt;)&lt;/li&gt;
&lt;li&gt;Question Banking lends a bank through five visibility levels and three share tiers (read only, read and write, admin), and a share can carry an expiry date that the database query itself checks. (&lt;a href="https://anasamin.dev/work/question-banking/" rel="noopener noreferrer"&gt;Question Banking case study&lt;/a&gt;)&lt;/li&gt;
&lt;li&gt;Amlaak restricts any account whose role can manage users, roles or integrations, or export personal data, until it enrols in TOTP MFA, and ties its permission cache to the security stamp in the token. (&lt;a href="https://anasamin.dev/work/amlaak/" rel="noopener noreferrer"&gt;Amlaak case study&lt;/a&gt;)&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://anasamin.dev/notes/permission-heavy-multi-tenant-dotnet/" rel="noopener noreferrer"&gt;anasamin.dev&lt;/a&gt;. I'm Anas Amin, a software engineer in .NET and the founder of &lt;a href="https://arkedia.dev" rel="noopener noreferrer"&gt;Arkedia&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>dotnet</category>
      <category>authorization</category>
      <category>multitenancy</category>
      <category>csharp</category>
    </item>
    <item>
      <title>Telr payments in ASP.NET Core: the parts the docs skip</title>
      <dc:creator>Anas Amin</dc:creator>
      <pubDate>Tue, 03 Nov 2026 13:00:00 +0000</pubDate>
      <link>https://dev.to/anasamin22311/telr-payments-in-aspnet-core-the-parts-the-docs-skip-2ca0</link>
      <guid>https://dev.to/anasamin22311/telr-payments-in-aspnet-core-the-parts-the-docs-skip-2ca0</guid>
      <description>&lt;p&gt;&lt;em&gt;Telr’s hosted payment page takes an afternoon to wire up. The real work is everything around it: the redirect that never comes back, the callback that arrives twice, and the payment that lands after you already released the seats.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Three signals, one of them trustworthy
&lt;/h2&gt;

&lt;p&gt;With a hosted payment page your API never touches the card. You create an order at Telr, send the customer to the page it returns, and wait to hear how it went. You hear it three ways, and they are not equal.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The return URL.&lt;/strong&gt; The browser comes back to your authorised, declined or cancelled page. Useful for the user, worthless as proof: anyone can type that URL, and a closed tab never arrives at all.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The callback.&lt;/strong&gt; Telr posts a signed, form-encoded advice to your server (ivp_update_url). Good evidence once you check the signature, but it can arrive late, twice, or before the browser does.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;order/check.&lt;/strong&gt; Your server asks Telr about the order by its reference. This is the answer you act on, and the one to fall back to whenever the other two disagree or go quiet.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Create the session once
&lt;/h2&gt;

&lt;p&gt;A double click on Pay, a retry from a flaky phone connection, two tabs: all of them ask for a second payment session for the same order. Two live sessions means a customer can pay twice. Lock the order row, reuse the session if one is already stored, and save the new reference and URL in the same transaction that created them.&lt;/p&gt;

&lt;p&gt;Retry the database work as much as you like. Never retry the call to the gateway. If it fails after the request went out, you do not know whether Telr opened a session, so the order goes on hold and the customer is told not to start another payment. An explicit rejection from Telr is different: delete the order and release the seats. And give the Telr call a short timeout, since the order row stays locked while you wait.&lt;/p&gt;

&lt;p&gt;One catch: a hosted-page reference is used up by its first page load. When the same customer comes back later to pay for the same cart, ask Telr about the old session first, and replace it only if it is still pending.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;One hosted-payment session per order (EF Core, SQL Server)&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;var&lt;/span&gt; &lt;span class="n"&gt;tx&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Database&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;BeginTransactionAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;IsolationLevel&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Serializable&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="c1"&gt;// UPDLOCK: two requests cannot both reach Telr before one has saved its session.&lt;/span&gt;
&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Orders&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;FromSqlInterpolated&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;$"SELECT * FROM Orders WITH (UPDLOCK, HOLDLOCK) WHERE Id = &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;orderId&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;AsTracking&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SingleAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentUrl&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="n"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt; &lt;span class="p"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentOrderRef&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="n"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;PaymentSession&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentUrl&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentOrderRef&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;try&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;session&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;telr&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;CreateSessionAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="c1"&gt;// method: "create"&lt;/span&gt;
    &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentUrl&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Url&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentOrderRef&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Ref&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SaveChangesAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;tx&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;CommitAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;session&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;Exception&lt;/span&gt; &lt;span class="n"&gt;ex&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;when&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ex&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="n"&gt;not&lt;/span&gt; &lt;span class="n"&gt;GatewayRejectedException&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// The request may have reached Telr: hold the order, never open a second session.&lt;/span&gt;
    &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;PaymentSessionUncertainException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ex&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Amounts are text, and culture bites
&lt;/h2&gt;

&lt;p&gt;Telr takes the amount as a string. ToString("F2") looks safe until the server runs with a culture that writes a comma, and "11,50" is not the price you meant. Format with the invariant culture, and keep a unit test that switches the thread culture to fr-FR to prove it.&lt;/p&gt;

&lt;p&gt;Round where the money is decided, not at the end. Tax rounded per ticket, away from zero, with the order total as the sum of the rounded lines, means the number you send is the number in your database. Our first version calculated tax in double; it is decimal everywhere now.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;The amount Telr sees, and the total it must match&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;foreach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;item&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Items&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;TaxAmount&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Round&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;item&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Price&lt;/span&gt; &lt;span class="p"&gt;*&lt;/span&gt; &lt;span class="n"&gt;taxRate&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="m"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;MidpointRounding&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;AwayFromZero&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;TotalAmount&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Items&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Sum&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;i&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Price&lt;/span&gt; &lt;span class="p"&gt;+&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;TaxAmount&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;amount&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;TotalAmount&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToString&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"F2"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;CultureInfo&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;InvariantCulture&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt; &lt;span class="c1"&gt;// "11.50", never "11,50"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Trust order/check, not the redirect
&lt;/h2&gt;

&lt;p&gt;The return page does not decide anything. It reads the order id from its URL and asks your API to verify, a few times, a couple of seconds apart. The API checks that the order belongs to the signed-in user, calls order/check with the stored reference, and only then compares and applies.&lt;/p&gt;

&lt;p&gt;Compare everything you can: the reference, the cart id, the amount, the currency and the test flag. A test-mode answer reaching production, or a payment in the wrong currency, is a configuration bug that should fail loudly rather than mark an order as paid.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Telr order status, and what the order becomes&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;order/check&lt;/th&gt;
&lt;th&gt;Meaning&lt;/th&gt;
&lt;th&gt;Order status&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;3, transaction A, sale or capture&lt;/td&gt;
&lt;td&gt;Paid&lt;/td&gt;
&lt;td&gt;Authorised: fulfil&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;Authorised, not captured&lt;/td&gt;
&lt;td&gt;On hold&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;1&lt;/td&gt;
&lt;td&gt;Pending&lt;/td&gt;
&lt;td&gt;Pending: ask again later&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;-1 or -2&lt;/td&gt;
&lt;td&gt;Expired or cancelled&lt;/td&gt;
&lt;td&gt;Cancelled&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;-3&lt;/td&gt;
&lt;td&gt;Declined&lt;/td&gt;
&lt;td&gt;Declined&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;anything else&lt;/td&gt;
&lt;td&gt;Unknown&lt;/td&gt;
&lt;td&gt;Error, and an alert&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  The callback: check it, then always answer 200
&lt;/h2&gt;

&lt;p&gt;Telr posts the advice as a form, so bind it as a form. It signs your secret key and fourteen of its fields with SHA1, joined by colons, the key first. Check the store id, the test flag and the currency against your settings before you even hash, and compare the hash in constant time.&lt;/p&gt;

&lt;p&gt;Then answer 200, whatever happened. A bad signature, an unknown order or an amount that does not match gets logged, with the amount mismatch as critical, but an error response only tells a stranger what you check and invites retries that will never succeed.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Checking the transaction advice&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_store&lt;/span&gt; &lt;span class="p"&gt;!=&lt;/span&gt; &lt;span class="n"&gt;settings&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;StoreId&lt;/span&gt; &lt;span class="p"&gt;||&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_test&lt;/span&gt; &lt;span class="p"&gt;!=&lt;/span&gt; &lt;span class="n"&gt;settings&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Test&lt;/span&gt; &lt;span class="p"&gt;||&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_currency&lt;/span&gt; &lt;span class="p"&gt;!=&lt;/span&gt; &lt;span class="n"&gt;settings&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Currency&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;false&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;signed&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;":"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;settings&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;SecretKey&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_store&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_type&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_class&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_test&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_ref&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_prevref&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_firstref&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_currency&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_amount&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_cartid&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_desc&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_status&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_authcode&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_authmessage&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;expected&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;Convert&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToHexStringLower&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;SHA1&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;HashData&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;Encoding&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;UTF8&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;GetBytes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;signed&lt;/span&gt;&lt;span class="p"&gt;)));&lt;/span&gt; &lt;span class="c1"&gt;// SHA1 is Telr's choice&lt;/span&gt;

&lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;CryptographicOperations&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;FixedTimeEquals&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="n"&gt;Encoding&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ASCII&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;GetBytes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;expected&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt; &lt;span class="n"&gt;Encoding&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ASCII&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;GetBytes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tran_check&lt;/span&gt; &lt;span class="p"&gt;??&lt;/span&gt; &lt;span class="s"&gt;""&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Apply the result exactly once
&lt;/h2&gt;

&lt;p&gt;The callback and the browser’s verify call often arrive within the same second, and both want to mark the order paid, count the seats as sold and clear the cart. Read-then-write lets both through. A conditional update lets exactly one through: it only matches while the order is still pending or on hold.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Sold counts move with an atomic SQL increment, not read, add, save. Two callbacks used to overwrite each other.&lt;/li&gt;
&lt;li&gt;If the reserved seats are gone by the time the payment lands, the order goes on hold for review instead of being fulfilled with someone else’s seats.&lt;/li&gt;
&lt;li&gt;Only the items that were checked out leave the cart. The customer may be browsing another event while the payment runs.&lt;/li&gt;
&lt;li&gt;Fulfilment lives in one service. We once had three handlers doing it, each with a different bug.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;em&gt;Claim the order, then fulfil&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;claimed&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Orders&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Where&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;o&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;o&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Id&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;orderId&lt;/span&gt; &lt;span class="p"&gt;&amp;amp;&amp;amp;&lt;/span&gt;
        &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;o&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentStatus&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;PaymentStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Pending&lt;/span&gt; &lt;span class="p"&gt;||&lt;/span&gt; &lt;span class="n"&gt;o&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentStatus&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;PaymentStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;OnHold&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ExecuteUpdateAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;s&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;s&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SetProperty&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;o&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;o&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentStatus&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SetProperty&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;o&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;o&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;PaymentTranRef&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;tranRef&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;claimed&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="m"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// Someone else already settled it. A "paid" for an order we cancelled goes to a person.&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;PaymentStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Authorized&lt;/span&gt; &lt;span class="p"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="n"&gt;current&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="n"&gt;PaymentStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Cancelled&lt;/span&gt; &lt;span class="n"&gt;or&lt;/span&gt; &lt;span class="n"&gt;PaymentStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Declined&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="n"&gt;logger&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;LogCritical&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"Late payment for released order {OrderId}: manual review"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;orderId&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Reconcile what timed out
&lt;/h2&gt;

&lt;p&gt;Seats are reserved for 30 minutes. When a reservation expires, the tempting move is to cancel the order and free the seats. But a local timeout is not proof that the gateway can no longer charge: the customer may be on the payment page right now.&lt;/p&gt;

&lt;p&gt;A background job runs every five minutes. Expired orders that have a Telr reference get an order/check first, and whatever Telr says is applied. Orders that never reached Telr are cancelled. If the check fails, the reservation stays until the next run. Orders on hold expire too, or they lock seats forever.&lt;/p&gt;

&lt;h2&gt;
  
  
  Mobile: the app never reads the URL
&lt;/h2&gt;

&lt;p&gt;The web checkout redirects the whole page (framed 0). The Flutter app opens the same hosted page in a WebView and watches for navigation back to its own return host, then closes the WebView and asks the API to verify. It never decides success from the URL it was sent to, for the same reason the web page does not.&lt;/p&gt;

&lt;h2&gt;
  
  
  Keys in the environment, and a deploy that refuses test mode
&lt;/h2&gt;

&lt;p&gt;The store id, auth key and secret key live in environment variables (Telr__StoreId and friends), never in appsettings files that end up in a repository. The production deploy script also refuses to ship if the environment still says test mode or points the return URLs anywhere unexpected.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;One line in the deploy script&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;grep&lt;/span&gt; &lt;span class="nt"&gt;-Fxq&lt;/span&gt; &lt;span class="s1"&gt;'Telr__Test=0'&lt;/span&gt; .env &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="o"&gt;{&lt;/span&gt; &lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s1"&gt;'Telr is still in test mode'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nb"&gt;exit &lt;/span&gt;1&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="o"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Before you take real money
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Is the amount formatted with the invariant culture, and does it equal the sum of the rounded lines?&lt;/li&gt;
&lt;li&gt;Can a double click or a retry ever open a second session for the same order?&lt;/li&gt;
&lt;li&gt;Does the return page ask your server, and does your server ask Telr?&lt;/li&gt;
&lt;li&gt;Does the callback check store, test flag, currency, signature and amount, and still answer 200?&lt;/li&gt;
&lt;li&gt;Can the callback and the verify call both fulfil the same order?&lt;/li&gt;
&lt;li&gt;What happens to a payment that lands after the reservation expired?&lt;/li&gt;
&lt;li&gt;Are the keys out of the repository, and can production run in test mode by accident?&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Where this runs
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Zotic sells tickets for Saudi venues this way: ASP.NET Core and EF Core behind an Angular site and a Flutter app, payments in SAR through Telr. (&lt;a href="https://anasamin.dev/work/zotic/" rel="noopener noreferrer"&gt;Zotic case study&lt;/a&gt;)&lt;/li&gt;
&lt;li&gt;Happy Ticket also takes Telr payments, on Blazor Server and MySQL; every callback’s signature is checked before an order is marked paid. (&lt;a href="https://anasamin.dev/work/happy-ticket/" rel="noopener noreferrer"&gt;Happy Ticket case study&lt;/a&gt;)&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://anasamin.dev/notes/telr-payments-aspnet-core/" rel="noopener noreferrer"&gt;anasamin.dev&lt;/a&gt;. I'm Anas Amin, a software engineer in .NET and the founder of &lt;a href="https://arkedia.dev" rel="noopener noreferrer"&gt;Arkedia&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>payments</category>
      <category>aspnetcore</category>
      <category>telr</category>
      <category>dotnet</category>
    </item>
    <item>
      <title>Sending leads to Odoo without losing one: a transactional outbox in ASP.NET Core</title>
      <dc:creator>Anas Amin</dc:creator>
      <pubDate>Sat, 31 Oct 2026 04:45:50 +0000</pubDate>
      <link>https://dev.to/anasamin22311/sending-leads-to-odoo-without-losing-one-a-transactional-outbox-in-aspnet-core-1iom</link>
      <guid>https://dev.to/anasamin22311/sending-leads-to-odoo-without-losing-one-a-transactional-outbox-in-aspnet-core-1iom</guid>
      <description>&lt;p&gt;&lt;em&gt;A lead that reaches the website but never reaches the sales team is worse than no website at all. The CRM will be down sometimes. The job is making sure the lead waits instead of disappearing.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Two writes, and one of them will fail
&lt;/h2&gt;

&lt;p&gt;Saving the lead and then calling Odoo looks fine until the call fails after the save: the lead sits in your database and nowhere in sales. Calling Odoo first fails the other way, when the save breaks after the CRM already has the record. Retrying inside the request only makes the page slow while the CRM is down.&lt;/p&gt;

&lt;p&gt;The outbox moves the second write out of the request. The business row and a message describing it commit in the same transaction, so either both exist or neither does. Delivering the message becomes a separate job that can take as long as the CRM needs.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;One SaveChanges, one SQL transaction&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="c1"&gt;// The enquiry and its outbox row commit together, or not at all.&lt;/span&gt;
&lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Inquiries&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;inquiry&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;OutboxMessages&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;OutboxMessage&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;Type&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"InquiryCreated"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;AggregateId&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;inquiry&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;PayloadJson&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;JsonSerializer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Serialize&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;InquiryPayload&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;From&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;inquiry&lt;/span&gt;&lt;span class="p"&gt;)),&lt;/span&gt;
    &lt;span class="n"&gt;OccurredUtc&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;now&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;Status&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;OutboxStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Pending&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;NextAttemptUtc&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;now&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SaveChangesAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  What a message carries
&lt;/h2&gt;

&lt;p&gt;Keep the row boring and complete. The dispatcher should never have to guess what a message is, whose it is, or why it last failed.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Type.&lt;/strong&gt; What happened: an enquiry created, a supplier approved, an email to send.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Record and payload.&lt;/strong&gt; The id of the record it is about, and a JSON snapshot of what the receiver needs.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Status.&lt;/strong&gt; Pending, Processing, Processed or DeadLettered. Nothing in between.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Attempts.&lt;/strong&gt; How many tries so far, and when the next one is due.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Lease.&lt;/strong&gt; Which worker holds the message, and until when.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Last error.&lt;/strong&gt; A code and a short reason, never the payload or a stack trace full of personal data.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Claim each message with a lease
&lt;/h2&gt;

&lt;p&gt;A Hangfire recurring job runs every 30 seconds and works through due messages, oldest first, for at most 20 seconds or 500 messages. It claims one row at a time with a guarded update: only a due pending row, or a processing row whose lease has run out, can move to processing, with a five-minute lease and the worker’s id.&lt;/p&gt;

&lt;p&gt;If the update touched no row, another worker got there first and this one moves on. Marking a message done or failed only works while the worker still holds the lease, so a worker that stalled past its lease cannot overwrite the one that took over. A crashed worker’s message comes back by itself when the lease expires.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Claim, or move on&lt;/em&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;claimed&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;OutboxMessages&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Where&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Id&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="p"&gt;&amp;amp;&amp;amp;&lt;/span&gt;
        &lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Status&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;OutboxStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Pending&lt;/span&gt; &lt;span class="p"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;NextAttemptUtc&lt;/span&gt; &lt;span class="p"&gt;&amp;lt;=&lt;/span&gt; &lt;span class="n"&gt;now&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;||&lt;/span&gt;
         &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Status&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;OutboxStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Processing&lt;/span&gt; &lt;span class="p"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;LeaseExpiresUtc&lt;/span&gt; &lt;span class="p"&gt;&amp;lt;&lt;/span&gt; &lt;span class="n"&gt;now&lt;/span&gt;&lt;span class="p"&gt;)))&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ExecuteUpdateAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;s&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;s&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SetProperty&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Status&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;OutboxStatus&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Processing&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SetProperty&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;LeaseExpiresUtc&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;now&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;AddMinutes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;5&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SetProperty&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;m&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;m&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;LockedBy&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;workerId&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;claimed&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="m"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;continue&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// someone else has it&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Make the CRM write safe to repeat
&lt;/h2&gt;

&lt;p&gt;A message can be delivered and the worker can still die before it records that. The next attempt must not create a second lead. The record’s own GUID goes into a custom field on the Odoo lead, and every delivery searches by it first: update if it exists, create if it does not. A delivery table with a unique key per provider, operation and record keeps one row per logical send.&lt;/p&gt;

&lt;p&gt;Search then create is still two calls. If two messages for the same record ever run at the same time, both can miss and both can create. Process messages for one record in order, or put a unique constraint on that field in Odoo; the field alone does not make it atomic.&lt;/p&gt;

&lt;h2&gt;
  
  
  Retry what can heal, dead-letter what cannot
&lt;/h2&gt;

&lt;p&gt;Every failure from the Odoo client is classified once, where it happens, so the dispatcher only has to read the answer.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Failures, and what the dispatcher does&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Failure&lt;/th&gt;
&lt;th&gt;Kind&lt;/th&gt;
&lt;th&gt;What happens&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Timeout, network error, 5xx&lt;/td&gt;
&lt;td&gt;Transient&lt;/td&gt;
&lt;td&gt;Retry after 1 minute, then 5, 15, 60 and 360&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;401, 403, other 4xx&lt;/td&gt;
&lt;td&gt;Permanent&lt;/td&gt;
&lt;td&gt;Dead-letter now; the lead shows its sync failed&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A payload that cannot be mapped&lt;/td&gt;
&lt;td&gt;Permanent&lt;/td&gt;
&lt;td&gt;Dead-letter now&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;The sixth failed attempt&lt;/td&gt;
&lt;td&gt;Gave up&lt;/td&gt;
&lt;td&gt;Dead-letter, and alert the admins with ids only&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;ul&gt;
&lt;li&gt;Add jitter to the delays, so a batch of failures does not retry on the same minute.&lt;/li&gt;
&lt;li&gt;Treat 408 and 429 as transient, and honour Retry-After. They are easy to file as permanent by accident.&lt;/li&gt;
&lt;li&gt;Let a manual retry reset the attempt count, or a dead letter gets one try and dies again.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Two Odoo APIs behind one interface
&lt;/h2&gt;

&lt;p&gt;Odoo 14 to 18 speak JSON-RPC with a session; Odoo 19 adds a JSON-2 API with a bearer key. One interface hides both, and a factory picks the client at startup from a config override or a version probe, falling back to JSON-RPC. When the integration is switched off, a no-op client marks messages as not applicable instead of failing them.&lt;/p&gt;

&lt;h2&gt;
  
  
  Make the queue visible
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Metrics for the dead-letter count and for the age of the oldest pending message, with an alert on each. Age catches a stuck dispatcher that a count never will.&lt;/li&gt;
&lt;li&gt;Logs carry ids and error codes, not names and phone numbers.&lt;/li&gt;
&lt;li&gt;Staff can retry one lead’s sync from the leads inbox. The retry endpoint for any message needs MFA and is audited.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Test it against something that fails
&lt;/h2&gt;

&lt;p&gt;The integration tests run the dispatcher against a real SQL Server 2022 container and a fake Odoo that can be told to fail. If the container will not start, the suite fails instead of skipping.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;A delivered message ends processed, with exactly one lead in Odoo; running the dispatcher again changes nothing.&lt;/li&gt;
&lt;li&gt;A 500 leaves the message pending with a retry scheduled; a 401 dead-letters it.&lt;/li&gt;
&lt;li&gt;An expired lease is reclaimed and a live one is left alone; an email is not sent twice after a crash.&lt;/li&gt;
&lt;li&gt;Four dispatchers draining twenty messages send each one exactly once.&lt;/li&gt;
&lt;li&gt;A k6 run with Odoo down fails unless 99.5% of form submissions succeed and p95 stays under a second.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Before you trust it
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Does the business row commit with its outbox row, in one transaction?&lt;/li&gt;
&lt;li&gt;Can two workers ever send the same message, and is there a test with several?&lt;/li&gt;
&lt;li&gt;Does a crashed worker’s message come back when its lease runs out?&lt;/li&gt;
&lt;li&gt;Is every external write keyed by your own id and safe to repeat?&lt;/li&gt;
&lt;li&gt;Which errors retry, which dead-letter, and who hears about a dead letter?&lt;/li&gt;
&lt;li&gt;Can anyone see how old the oldest pending message is?&lt;/li&gt;
&lt;li&gt;The payload holds personal data. When is it purged? Decide before launch, not after.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Where this runs
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Amlaak sends enquiries and approved suppliers to Odoo this way, on .NET 10 with SQL Server and Hangfire. The integration tests run it against SQL Server and a stand-in Odoo in containers. (&lt;a href="https://anasamin.dev/work/amlaak/" rel="noopener noreferrer"&gt;Amlaak case study&lt;/a&gt;)&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://anasamin.dev/notes/odoo-outbox-aspnet-core/" rel="noopener noreferrer"&gt;anasamin.dev&lt;/a&gt;. I'm Anas Amin, a software engineer in .NET and the founder of &lt;a href="https://arkedia.dev" rel="noopener noreferrer"&gt;Arkedia&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>integration</category>
      <category>aspnetcore</category>
      <category>odoo</category>
      <category>dotnet</category>
    </item>
  </channel>
</rss>
