SOP: معماری دامنه‌ی لایه‌ای

وقتی ایجنت مدام مرزها را نقض می‌کند، منطق را بین لایه‌ها تکرار می‌کند، یا بعد از چند نشست کدی تولید می‌کند که بازبینی‌اش سخت می‌شود، از این رویه استفاده کنید.

هدف#

مرزهای دامنه را آن‌قدر صریح کنید که ایجنت‌ها بتوانند سریع حرکت کنند بدون اینکه ساختار بی‌صدا خراب شود.

مدل هدف#

درون یک دامنه‌ی کسب‌وکار، این جریان جهت‌دار را ترجیح دهید:

Types -> Config -> Repo -> Service -> Runtime -> UI

دغدغه‌های مشترک باید از راه provider یا adapter صریح وارد شوند. ابزارهای عمومی مشترک بیرون از دامنه می‌مانند و نباید منطق دامنه جمع کنند.

چک‌لیست راه‌اندازی#

• دامنه‌های فعلی را در ARCHITECTURE.md تعریف کنید.
• جهت‌های مجاز وابستگی را در ARCHITECTURE.md بنویسید.
• رابط‌های مشترک مثل احراز هویت، telemetry و APIهای بیرونی را ثبت کنید.
• برای سخت‌ترین نقض مرزِ فعلی یک یادداشت کوتاه بگذارید.
• تصمیم بگیرید چه چیزی باید با lint، تست یا اسکریپت به‌صورت مکانیکی اعمال شود.

رویه‌ی اجرا#

1. پیش از دست زدن به سبک پیاده‌سازی، کدبیس را به دامنه‌ها نگاشت کنید.
2. برای هر دامنه، ترتیب مجاز لایه‌ها را مشخص کنید.
3. همه‌ی دغدغه‌های مشترک را شناسایی کنید و از راه provider یا adapter عبور دهید.
4. منطق مشترکِ مبهم را یا به دامنه‌ی مالکش ببرید یا به ابزارهای واقعاً عمومی.
5. قواعد را در ARCHITECTURE.md مستند کنید.
6. برای پرهزینه‌ترین نقض یک حفاظ اجرایی اضافه کنید.
7. پس از تغییر، امتیاز کیفیت را به‌روز کنید.

تعریف اتمام#

• یک ایجنت تازه می‌تواند بگوید هر تغییر مال کدام لایه است.
• کد رابط کاربری دیگر مستقیم به repo یا اثرات جانبی بیرونی دست نمی‌زند.
• دغدغه‌های مشترک نقطه‌ی ورود نام‌دار دارند.
• دست‌کم یک مرز مهم به‌صورت مکانیکی اعمال می‌شود.

مصنوعاتی که باید به‌روز شوند#

• ARCHITECTURE.md
• docs/QUALITY_SCORE.md
• docs/design-docs/، اگر دلیل طراحی عوض شد
• docs/PLANS.md یا برنامه‌ی اجرایی فعال