قواعد كود القاعدة

هذا الملحق يلخص تخطيط الاتفاقيات المستخدمة في قاعدة كود Asset Core للقراء الخارجيين والمساهمين.

نظرة عامة

يتبع Asset Core أنماطًا متسقة عبر جميع الحزم من حيث الهيكل والتسمية والتوثيق. يساعد فهم هذه الاتفاقيات في التنقل في الشيفرة والحفاظ على الاتساق عند المساهمة.

شرح مفصل

تخطيط المستودع

asset-core/
├── core/                 # Runtime engine (L1/L2/L3)
├── daemon-write/         # HTTP write daemon
├── daemon-read/          # HTTP read daemon
├── acctl/                # CLI tool
├── telemetry/            # Shared metrics crate
├── api-contract/         # OpenAPI spec generation
├── assetcore-adapters/   # Protocol adapters
├── system-tests/         # E2E test harness
├── sdk-python/           # Python SDK
└── Docs/                 # Architecture documentation

هيكل الصندوق

كل صندوق يتبع هذا النمط:

crate/
├── Cargo.toml
├── README.md            # Crate overview
├── AGENTS.md            # Rules for LLM agents
└── src/
    ├── lib.rs           # Public API
    ├── mod.rs files     # Module organization
    └── tests/           # Unit tests

بنية الطبقات (L1/L2/L3)

تفرض حزمة النواة فصلًا صارمًا بين الطبقات:

إرشادات إضافية:

الطبقة	الموقع	المسؤولية
L1	core/src/storage/	هياكل البيانات الخام
L2	core/src/operations/	منطق الأعمال، الأحداث
L3	core/src/runtime/	المعاملات، التراجع

قواعد:

إرشادات إضافية:

نبرة: رسمية سجل: تقني

السياق:

• المجال: بنية تحتية للبلوك تشين
• الجمهور: مهندسو الأمن وقادة البنية التحتية
• الغرض: وثائق تقنية
• الموقع: ar
• الاتجاه: من اليمين إلى اليسار

القيود:

• استخدام لغة محايدة للجنس
• الحفاظ على أسماء العلامات التجارية
• الحفاظ على الدقة التقنية
• ضمان أن تبقى علامات الترقيم والترقيم مناسبة من حيث الاتجاه
• الحفاظ على أسماء العلامات التجارية والمصطلحات غير مترجمة

إرشادات المصطلحات:

الحفاظ على هذه المصطلحات كما هي (لا تترجم): Asset Core، Asset‑Core، CSP، API، Docker، ECS، daemon، L1، L2، L3، OpenGraph، GitHub، Astro، TypeScript، JavaScript، ℤ، ℤ²، ℤ³، ℝ²، ℝ³، 0D، 1D، 2D، 3D

• يمكن لـ L2 الاتصال بـ L1، وليس العكس
• يمكن لـ L3 الاتصال بـ L2، وليس العكس
• لا توجد استيرادات عبر الطبقات إلا للأسفل

قواعد التسمية

الملفات: snake_case

ingress_orchestrator.rs
commit_log_driver.rs

أنواع: PascalCase

struct ValidatedCommit { ... }
enum ContainerKind { ... }

الوظائف: snake_case

fn prepare_commit(&mut self) -> Result<...>

الثوابت: SCREAMING_SNAKE_CASE

const MAX_BATCH_SIZE: usize = 1000;

رؤوس الوثائق

كل ملف مصدر يتضمن رأسًا:

// =============================================================================
// Module: ingress/orchestrator
// Description: Coordinates request sequencing and commit pipeline
// Purpose: Provide backpressure-aware ingestion
// Dependencies: worker, append, state
// =============================================================================

هذا يساعد وكلاء LLM على فهم السياق دون الحاجة لقراءة التنفيذات الكاملة.

معالجة الأخطاء

أخطاء استخدام أنواع البيانات المحددة مع السياق:

إرشادات إضافية:

#[derive(Debug, thiserror::Error)]
pub enum CommitError {
    #[error("Container {0} not found")]
    ContainerNotFound(ContainerId),

    #[error("Insufficient balance: requested {requested}, available {available}")]
    InsufficientBalance {
        requested: u64,
        available: u64,
    },
}

تتوافق الأخطاء مع رموز حالة HTTP عبر طبقة API.

تسمية المقاييس

تتبع المقاييس نمطًا متسقًا:

assetcore_{daemon}_{subsystem}_{metric}_{unit}

أمثلة:

إرشادات إضافية:

نبرة: رسمية سجل: تقني

السياق:

• المجال: بنية تحتية للبلوك تشين
• الجمهور: مهندسو الأمان وقادة البنية التحتية
• الغرض: وثائق تقنية
• اللغة: ar
• الاتجاه: من اليمين إلى اليسار

القيود:

• استخدام لغة محايدة للجنس
• الحفاظ على أسماء العلامات التجارية
• الحفاظ على الدقة التقنية
• ضمان أن تظل علامات الترقيم والترقيم مناسبة للاتجاه من اليمين إلى اليسار
• الحفاظ على أسماء العلامات التجارية والمصطلحات في القاموس دون ترجمة

الحفاظ على هذه المصطلحات بالضبط (لا تترجم): Asset Core، Asset‑Core، CSP، API، Docker، ECS، daemon، L1، L2، L3، OpenGraph، GitHub، Astro، TypeScript، JavaScript، ℤ، ℤ²، ℤ³، ℝ²، ℝ³، 0D، 1D، 2D، 3D

• assetcore_write_ingress_queue_depth
• assetcore_read_snapshot_publish_duration_seconds
• assetcore_write_commit_log_lag

أنماط الاختبار

اختبارات الوحدة: مضمنة في ملفات المصدر

#[cfg(test)]
mod tests {
    use super::*;
    // ...
}

اختبارات التكامل: تحت دليل tests/

اختبارات النظام: في system-tests crate

ملفات AGENTS.md

كل صندوق يحتوي على ملف AGENTS.md يحتوي على قواعد لوكلاء توليد الشيفرة:

• الثوابت التي يجب الحفاظ عليها
• الأنماط التي يجب اتباعها
• الملفات التي يجب مراجعتها قبل إجراء التغييرات
• الأخطاء الشائعة

اقرأ ملف AGENTS.md المعني قبل تعديل أي حزمة.

ملاحظات التنفيذ

لا يوجد خطر في المسارات الساخنة

الأداء يأتي من تخطيط البيانات، وليس من الشيفرة غير الآمنة:

• هيكل المصفوفات (SoA) لكفاءة التخزين المؤقت
• معرفات كثيفة بدلاً من التجزئة
• المخازن المخصصة مسبقًا

لا قيود على المسارات الساخنة

المعرفات هي أعداد صحيحة:

type ContainerId = u64;
type ClassId = u64;
type InstanceId = u64;

السلاسل مخصصة فقط لأسماء المستخدمين وتهيئة الإعدادات.

متطلبات الحتمية

يجب أن تكون العمليات حتمية:

• لا يوجد وقت نظام أثناء إعادة التشغيل
• لا قيم عشوائية
• لا توجد تبعيات خارجية أثناء الالتزام

الأحداث تحمل حالة ما بعد، لذا فإن إعادة التشغيل هي عملية غير حساسة.

متى يجب قراءة هذا

اقرأ هذا الملحق عندما:

• الانضمام إلى قاعدة الشيفرة
• المساهمات في التغييرات
• فهم أسماء المقاييس
• التنقل في المناطق غير المألوفة

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

انظر أيضًا

• كتابة بنية المسار - تفاصيل خط الأنابيب
• نموذج وقت التشغيل - نظرة عامة معمارية