ملف dukkan.app.toml

هذه الصفحة لمن يحمل تطبيقه ملف dukkan.app.toml. في نهايتها تعرف معنى كل مفتاح، والقيم التي تتحقق منها البوابة، وكيف يبقي dukkan app config push وpull الملف ومسودة إصدارك متطابقين.

ما هو الملف#

dukkan.app.toml هو الوصف التصريحي لتطبيقك: اسمه، والنطاقات التي يطلبها، وروابط إعادة التوجيه الدقيقة، ومواضيع Webhooks، والمسارات التي تركّبها الحزمة. تقرؤه ثلاث جهات:

• @dukkan.one/nuxt عند البناء، لتركيب مسارات التثبيت وإعادة التوجيه واستقبال Webhooks.
• dukkan app config push، لتحويله إلى مسودة إصدار تطبيقك في البوابة.
• dukkan app dev، للمنفذ ومزوّد النفق.

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

ملف كامل#

config_version = 1

[app]
name = "Order notifier"
client_id = "dukkan_app_1f3c9e2a"
api_version = "v1"

[auth]
scopes = ["orders:read", "orders:write"]
redirect_uris = [
  "https://app.example.com/dukkan/callback",
  "http://localhost:3000/dukkan/callback",
]

[webhooks]
topics = ["order.created", "order.paid", "app.uninstalled"]

[urls]
app_url = "https://app.example.com"
install_path = "/dukkan/install"
callback_path = "/dukkan/callback"
webhook_path = "/dukkan/webhooks"

[dev]
port = 3000
tunnel = "cloudflared"

المفاتيح#

تبدأ المسارات بـ / وتحوي حروفاً لاتينية وأرقاماً و/ و_ و- فقط.

التحقق#

المخطط نفسه يعمل في ثلاثة مواضع: الأداة قبل الدفع، والبوابة عند استقباله، ووحدة Nuxt عند البناء. يُنشر مخطط JSON Schema على /contracts/v1/dukkan.app.schema.json لإكمال المحرّرات وللغات الأخرى؛ راجع العقد للغات الأخرى.

يطبع الملف الفاشل كل مشكلة مع مسارها:

✗ dukkan.app.toml is invalid:
  auth.redirect_uris.0: Redirect URIs must be https, or http on localhost
  webhooks.topics: These topics need scopes the app does not request: order.paid

الدفع والسحب#

يرسل dukkan app config push سطح الملف (النطاقات وروابط إعادة التوجيه والمواضيع) إلى مسودة إصدار تطبيقك ويسجّل الملف مصدراً. تعرض البوابة عندها الإصدار على أنه يُدار من ملف dukkan.app.toml مع وقت الدفع. الدفع لا يفعّل إصداراً أبداً؛ الإطلاق يبقى في البوابة.

Updating draft version 4:
  + scope: orders:write
  + redirect: https://app.example.com/dukkan/callback
  - topic: product.updated
✓ Updated draft version 4; the portal now shows it as managed by dukkan.app.toml.

يكتب dukkan app config pull مسودة البوابة (أو الإصدار النشط عندما لا توجد مسودة) في الملف من جديد، بما فيها app.client_id.

عندما تختلف البوابة عن الملف#

تعديل المسودة في البوابة بعد الدفع يعلّم الإصدار على أنه عُدّل يدوياً. تعرض البوابة تنبيه البوابة والملف مختلفان مع أمر السحب، ويرفض الدفع التالي:

✗ The portal draft changed since your last pull (last push 2026-09-08T14:02:11Z, then edited in the portal). Run: dukkan app config pull, or push again with --force to overwrite it.

اسحب لاعتماد تعديلات البوابة في الملف، أو ادفع بـ --force لاستبدالها. المسودة الخاضعة لمراجعة السوق مجمّدة في الحالتين؛ اسحب الإرسال أولاً.

الخطوات التالية#

• البداية السريعة
• وحدة Nuxt
• مرجع الأداة