Arxi بوابة القرار أصل أساسي
Docs
وثائق أصول Core

توثيق محرك حالة العالم الحتمي ومراجع API.

وثائق بوابة القرار

أول التزام وقراءة

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

المتطلبات السابقة

تأكد من أنه يمكنك تشغيل العمليات المحلية وقراءة ملفات الرموز. ستفتح نافذتين طرفيتين حتى تتمكن من مراقبة كل من الـ daemons ومسار القراءة بشكل مستقل.

  • Docker + Docker Compose (موصى به) أو Rust toolchain للبناء المحلي
  • عميل HTTP (curl) بالإضافة إلى jq لاستخراج الرموز
  • محطة تحتوي على نافذتين أو علامات تبويب

الخطوة 1 - بدء الخدمات (Docker Compose)

من جذر مستودع Asset Core:

docker-compose up -d

هذا يبدأ عمليات الكتابة والقراءة على المنافذ 8080 و 8081 باستخدام ./data للتخزين. سيتم إنشاء سجل الالتزام وملفات الرموز تحت هذا الدليل.

الخطوة 2 - تعيين مساحة الأسماء والرموز

في المحطة الأولى:

export ASSETCORE_NAMESPACE_ID=5001
export ASSETCORE_ADMIN_TOKEN=$(jq -r .token data/auth/tokens/admin.json)
export ASSETCORE_WRITE_TOKEN=$(jq -r .token data/auth/tokens/writer.json)
export ASSETCORE_READ_TOKEN=$(jq -r .token data/auth/tokens/reader.json)

تُخزن الرموز تحت data/auth/tokens في سير عمل Docker (أو ./.assetcore/auth/tokens للثنائيات المحلية). احتفظ بهذه الرموز خاصة واعتبرها بيانات اعتماد الإنتاج.

تحقق من أنه يعمل:

curl -H "Authorization: Bearer $ASSETCORE_ADMIN_TOKEN" \
  http://127.0.0.1:8080/v1/write/health

متوقع الرد:

{
  "status": "healthy",
  "version": "0.1.0",
  "api_version": "0.1.0",
  "build_git_sha": "abc123",
  "uptime_secs": 3600
}

الخطوة 3 - تحقق من صحة عملية القراءة

في المحطة الثانية:

curl -H "Authorization: Bearer $ASSETCORE_READ_TOKEN" \
  -H "x-assetcore-namespace: $ASSETCORE_NAMESPACE_ID" \
  http://127.0.0.1:8081/v1/read/health

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

الاستجابة المتوقعة تشمل بيانات الاستعداد والانتعاش.

الخطوة 4 - أرسل أول عملية التزام لك

قم بتوفير مساحة الأسماء (مرة واحدة) ثم أنشئ حاوية وأضف رصيدًا قابلًا للتبادل في معاملة واحدة. هذا يعكس نمط “إنشاء + تزويد” الواقعي دون الحاجة إلى أي مخطط مخصص.

curl -X POST http://127.0.0.1:8080/v1/write/namespaces/${ASSETCORE_NAMESPACE_ID}/lifecycle \
  -H "Authorization: Bearer $ASSETCORE_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_state":"provisioned","reason":"quickstart bootstrap"}'

curl -X POST http://127.0.0.1:8080/v1/write/namespaces/${ASSETCORE_NAMESPACE_ID}/commit \
  -H "Authorization: Bearer $ASSETCORE_WRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "op": "CreateContainer",
        "args": {
          "container_id": 1001,
          "kind": { "type": "balance" },
          "owner": null,
          "policies": null
        }
      },
      {
        "op": "AddFungible",
        "args": {
          "class_id": 100,
          "key": 1,
          "quantity": 500,
          "location": {
            "container_id": 1001,
            "kind": "balance"
          }
        }
      }
    ],
    "idempotency_key": "first-commit-2026-01-15"
  }'

متوقع الرد:

{
  "namespace": 5001,
  "commit_id": "00000000000000000000000000000001",
  "outcome": "Committed",
  "world_seq_start": 1,
  "world_seq_end": 1,
  "event_count": 2,
  "start_time_ms": 1769800000000,
  "commit_time_ms": 1769800000123,
  "server_correlation_id": "wr-0000000000000001-0000000000000042",
  "echo": {
    "idempotency_key": "first-commit-2026-01-15"
  },
  "created_entities": {
    "containers": [1001]
  }
}

يؤكد world_seq_start أن التزامك تم تعيينه برقم تسلسل 1. هذا الرقم هو الرقم العام لكل مساحة اسم والذي يجب عليك استخدامه من أجل التحقق وإعادة التشغيل.

الخطوة 5 - قراءة الحالة مرة أخرى

استعلام عن أرصدة الحاويات:

curl -H "Authorization: Bearer $ASSETCORE_READ_TOKEN" \
  http://127.0.0.1:8081/v1/read/namespaces/${ASSETCORE_NAMESPACE_ID}/containers/1001/balances

متوقع الرد:

{
  "container_id": 1001,
  "balances": [
    {
      "class_id": 100,
      "key": 1,
      "quantity": 500
    }
  ],
  "server_correlation_id": "rd-0000000000000001-0000000000000042",
  "freshness": {
    "namespace": 5001,
    "world_seq": 1,
    "commit_log_world_seq": 1,
    "lag": 0,
    "lag_ms": 0
  }
}

تظهر بيانات التعريف الخاصة بـ freshness أن عملية القراءة قد عالجت جميع الالتزامات من خلال التسلسل 1. في الإنتاج، يمكنك استخدام freshness لاكتشاف التأخير وفرض تسلسل القراءة الأدنى.

استكشاف الأخطاء وإصلاحها

”تم رفض الاتصال” عند الالتزام

خدمة الكتابة غير قيد التشغيل أو تعمل على منفذ مختلف. تحقق من الطرفية بحثًا عن الأخطاء وتأكد من أن مسار --config صحيح.

أرصدة فارغة عند القراءة

لم يلحق خادم القراءة بخادم الكتابة. تحقق من أن كلا الخادمين يستخدمان نفس مسار سجل الالتزام. تُظهر بيانات الحداثة أحدث تسلسل عالمي تم تطبيقه.

خطأ “ContainerNotFound”

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

”InvalidQuantity” error

يجب أن تكون الكمية أكبر من الصفر. تحقق من عملية AddFungible.

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