→ بازگشت به صفحه اصلی

قالب مستند معماری نرم‌افزار

...

سند زیر شامل بخشی از قالب پیشنهادی سند معماری نرم‌افزار است. هرچند همین بخش هم قابل استفاده و مفید است، جهت دریافت نسخه کامل و جدید قالب سند معماری نرم‌افزار، لطفاً با کاملتر و جدیدتر این سند در قالب خدمات تیم چکاپ ارائه می‌شود. جهت آشنایی با خدمات تیم چکاپ به این‌جا مراجعه فرمایید و یا با آدرس checkup@asta.ir تماس بگیرید.

پیش‌گفتار: در مستند معماری نرم‌افزار، معماری یک سامانه نرم‌افزاری توصیف می‌شود. معماری نرم‌افزار، شامل تصمیمات مهم و کلان در طراحی نرم‌افزار است. هر آن چه از دید کلان و از دید معماری مهم است، در این مستند گنجانده می‌شود و جزئیات و فرعیات (مانند جزئیات پیاده‌سازی) در این مستند گنجانده نمی‌شود. قالب مطالب و سرفصل‌های لازم برای مستند معماری در ادامه آمده است. مستند معماری باید این سرفصل‌ها را به شکلی شفاف و مناسب، در کوتاه‌ترین و موجزترین حجم ممکن پوشش دهد. همچنین تغییرات مهم در نرم‌افزار که از نظر معماری مهم هستند، باید در سند معماری منعکس شوند. به عبارت دیگر، مستند معماری باید در طول فرایند توسعه نرم‌افزار، نگهداری و به‌روز شود.

...

اگر ارجاع به مستند یا مرجع دیگری لازم است، در این بخش ذکر شود.

2. نمای موارد کاربرد

← نمای موارد کاربردبرای مشاهده محتوای این بخش به نسخه کامل قالب سند معماری مراجعه نمایید.

3. ویژگی‌های کیفی

در این بخش، ویژگی‌های غیرکارکردی (Nonfunctional) یا به عبارت دیگر ویژگی‌های کیفی (Quality Attributes) مورد نیاز در سامانه نرم‌افزاری موردنظر ذکر شود. به عنوان مثال امنیت، کارایی، مقیاس‌پذیری و ...

...

8. نماهای متقاطع (اختیاری)

برای مشاهده محتوای این بخش حذف شده است.به نسخه کامل قالب سند معماری مراجعه نمایید.

9. نحوه تحقق موارد کاربرد کلیدی

برای مشاهده محتوای این بخش حذف شده استبه نسخه کامل قالب سند معماری مراجعه نمایید.

10. نمای تست

برای مشاهده محتوای این بخش حذف شده استبه نسخه کامل قالب سند معماری مراجعه نمایید.

11. مدیریت لاگ

برای مشاهده محتوای این بخش حذف شده استبه نسخه کامل قالب سند معماری مراجعه نمایید.

12. پایش (Monitoring)

برای مشاهده محتوای این بخش حذف شده استبه نسخه کامل قالب سند معماری مراجعه نمایید.

13. نمای داده

در این بخش، تصمیمات مهمی که در زمینه داده‌های سامانه گرفته شده ذکر می‌شود. به عنوان مثال، نحوه ذخیره داده‌ها، نوع پایگاه داده‌های مورد استفاده (sql/nosql/…)، مدیریت داده‌ها و فراداده‌ها، الگوها و تکنیک‌های اصلی در لایه داده (مثل CQRS و محل استفاده از Cache)، فرایند‌های پشتیبان‌گیری و بازیافت داده‌ها، امنیت داده‌ها و ساختار داده‌های کلیدی سیستم.

...

OLAP, Data-warehousing, Report Engines, Report Generators, Report Designers, Materialized View, Denormalization, Power BI, Jasper Reports, BERTBIRT,  ...

در این بخش، طراحی کلان امکاناتی که برای گزارش‌گیری تعبیه شده است، ذکر شود. با کمک محتوای این فصل، به سؤالات و دغدغه‌هایی مثل موارد زیر پاسخ داده می‌شود:

...

15. الگوها و تکنیک‌های مورد استفاده

برای مشاهده محتوای این بخش حذف شده استبه نسخه کامل قالب سند معماری مراجعه نمایید.

16. ابزارها و فناوری‌ها

در این بخش، مجموعه ابزارها، استانداردها، الگوها و فناوری‌های مورد استفاده در توسعه محصول که از جنبه معماری اهمیت دارند، مرور می‌شود. برای هر ابزار یا استاندارد، در صورت امکان نسخه (version) و جایگاه استفاده هم ذکر شود. در واقع، جایگاه همه یا اکثر این موارد در فصل‌های قبلی تبیین شده است و در این فصل، فهرستی از این موارد به صورت تجمیعی و متمرکز ذکر می‌شود. این فصل فقط شامل یک جدول است شامل سه ستون است:

...

17. مهم‌ترین تصمیمات معماری

برای مشاهده محتوای این بخش حذف شده استبه نسخه کامل قالب سند معماری مراجعه نمایید.

18. ریسک‌ها و بدهی‌های فنی

برای مشاهده محتوای این بخش حذف شده استبه نسخه کامل قالب سند معماری مراجعه نمایید.

19. بهبودهای پیشنهادی در آینده

برای مشاهده محتوای این بخش حذف شده استبه نسخه کامل قالب سند معماری مراجعه نمایید.

20. سایر نماهای مفید/لازم

...

1. چرخه اول: نگارش فضای مسأله.
   در این چرخه، یک دور (چرخه) تلاش شود و نیمه اول سند معماری که شامل «فضای مسأله» است، مستند شود. فضای مسأله شامل فصلهای «مقدمه»، «نمای موارد کاربرد» و «ویژگی‌های کیفی» است. پس از این چرخه، صورت مسأله و نیازمندی‌های کلان نرم‌افزار مشخص می‌شوند. ترتیب پیشنهادی:
   • مقدمه
   • نمای موارد کاربرد
   • ویژگی‌های کیفی
2. چرخه دوم: توصیف طراحی کلان سامانه نرم‌افزاری، شامل فصلهای «نمای منطقی» ، «نمای پردازه» و «ابزارها و فناوری‌ها». ترتیب پیشنهادی:
   • نمای پردازهنمای استقرارمنطقی
   • ابزارها و فناوری‌ها
   • بازنگری فصلهایی که قبلاً نگارش شده
3. چرخه سوم: تکمیل سایر فصلهای اصلی جهت توصیف معماری کلان. ترتیب پیشنهادی:
   • نمای پردازه
   • نمای استقرار منطقی
   • نمای توسعه و پیاده‌سازی
   • نماهای متقاطع (در صورت نیاز)
   • بازنگری فصلهایی که قبلاً نگارش شده
4. چرخه چهارم. ترتیب پیشنهادی:
   • فصل نحوه تحقق موارد کاربرد کلیدی
   • نمای تست
   • نمای داده
   • الگوها و تکنیک‌های مورداستفاده
   • ریسک‌ها و بدهی‌های فنی
   • بازنگری فصلهایی که قبلاً نگارش شده
5. چرخه پنجم. ترتیب پیشنهادی:
   • سایر فصلهای باقی‌مانده
   • بازنگری فصلهایی که قبلاً نگارش شده

...

• آیا قالب سند معماری رعایت شده است؟ (دوباره آخرین نسخه از قالب سند معماری را با مستندی که نوشته‌اید مقایسه کنید)
• آیا همه فصل‌های قالب سند معماری را تکمیل کرده‌اید؟ 
• آیا سند از دید معماری نوشته شده است؟ (سند باید توسط فردی که طراحی کلان سامانه را از نظر فنی می‌شناسد نوشته یا تایید شده باشد)
• آیا مستند را در قالب ورد تحویل داده‌اید؟ (اگر سامانه مدیریت دانش مبتنی بر ویکی هنوز راه‌اندازی نشده است، مستند در قالب docx و اگر نه، در قالب pdf تحویل داده شود)

اشتباه‌های رایج در نگارش سند معماری

• اشتباه رایج: رعایت نشدن قالب سند
  • سند معماری طبق قالب باشد. انطباق با قالب سند معماری، مهم است.
  • همه بخش‌های مطرح‌شده در قالب سند معماری و با همان ترتیب، در مستندسازی پوشش داده شود.
• نویسنده سند معماری، یک فرد ارشد فنی (مثلا مدیر فنی، معمار نرم‌افزار یا ...) باشد که در جریان تصمیمات اصلی و کلان طراحی سامانه باشد.
  • این نکته برای سند معماری (SAD) است. در مورد سند SCD (سند توصیف ارتباطات سامانه) لازم نیست نویسنده‌ سند SCD معمار سامانه (یا یک فرد ارشد فنی) باشد. کسی که در جریان کلیات کارکرد و ارتباطات سامانه باشد می‌تواند سند SCD را بنویسد.
• انگیزش: توجه شود که سند معماری به درد تیم توسعه هم می‌خورد (خود شرکت پیمانکار ذی‌نفع تولید این سند است). اگر معماری سامانه مستند نشده، یک مخاطره (ریسک) برای تیم/شرکت توسعه‌دهنده هم هست. به این سند، فقط به عنوان یک نیازمندی از سمت کارفرما نگاه نشود. ذی‌نفعان مختلفی (طراحان، مدیران، کارفرما، برنامه‌نویسان و ...) در طول زمان ممکن است ازبخش‌هایی از سند معماری استفاده کنند.
• به سطح سند معماری توجه شود. در نمودارها و جداول سند معماری، معمولا درباره المان‌ها و ساختارهای سطح بالا صحبت می‌کنیم و درباره جزییات پیاده‌سازی صحبت نمی‌کنیم. مثلا نمودار sequence بین چند کلاس پروژه در سند معماری جای نمی‌گیرد ولی نمودار sequence بین چند کامپوننت سطح بالا ممکن است در معماری نمایش داده شود.
• به فلسفه‌ ایجاد سند معماری (SAD) توجه شود.
  • این سند دارای دو بخش اصلی است:
    • بخش اول: شامل بیان نیازمندی‌های کارکردی و غیرکارکردی سیستم (فضای مساله)
      • این بخش باید دقیق و شفاف باشد (مساله به خوبی بیان شود)
    • بخش دوم: بیان راهکارها و تکنیک‌ها برای پوشش نیازمندی‌های بخش اول از نماها/دیدگاه‌های مختلف (فضای راه‌حل)
      • فضای راه‌حل، باید مطابق با فضای مساله باشد.
      • هر مورد از محتوای این بخش باید سرنخی در بخش اول داشته باشد.

• اشتباه‌های رایج در بخش اول (فضای مساله)
  • اشتباه‌های رایج در بخش نمای Usecase (مورد کاربرد):
    • بیان نیازمندی‌ها به صورت یک عنوان و عدم ارایه توضیحات کافی  
    • تمرکز بیش از حد بر روی نمودارهای موارد کاربرد و عدم توجه به ارایه مطالب به صورت سازمان‌دهی‌شده و گویا
    • عدم تبیین کنشگرها (actorهای سامانه) به تفکیک کنشرگرهای انسانی و سیستمی
  • اشتباه‌های رایج در بخش ویژگی‌های کیفی
    • بیان کلی ویژگی‌های کیفی (مثلا امنیت و کارایی). نام بردن از ویژگی‌های کیفی کافی نیست و بی‌فایده است.
    • عدم ذکر  معیار ارزیابی. روش محاسبه میزان کیفیت در هر ویژگی کیفی باید ذکر شود (مثلاً معیار TPS برای کارایی)
    • عدم ذکر محدوده مطلوب (مثلا محدوده‌ی حداقل 100 برای معیار TPS)

...

اشتباه‌های رایج در نگارش سند معماری

برای مشاهده محتوای این بخش به نسخه کامل قالب سند معماری مراجعه نمایید

...

• نحوه‌ ارتباط بین مولفه‌های اصلی سامانه مشخص شود.
  • عبارت مولفه اصلی در جمله قبل نقش کلیدی دارد. همانطور که ارتباطات بین سامانه‌های مختلف مهم است، ارتباط بین مولفه‌های مهم درون یک سامانه نیز مهم است.
• هریک از نمودارهای ارایه‌شده مربوط به یک یا چند نیازمندی functional یا nonfunctional باشد.
• مولفه‌ اصلی، یک صفحه‌ (مثلا یک فرم کاربری) یا یک موجودیت سطح پایین (در سطح پیاده‌سازی) در نظر گرفته نشود. بلکه یک کامپوننت یا موجودیت نرم‌افزاری سطح بالا (مهم در سطح معماری) باشد.
•  موارد کاربرد کوچک و جزیی (مثل مورد کاربرد ورود به سامانه) نباید به صورت نمودار در این بخش توصیف شود.
• صرفا ارایه یک یا چند نمودار کافی نیست و حتما بایستی شرحی در کنار نمودارها باشد.

...

• گاهی در نمای استقرار چندین سرور مشاهده می‌شود ولی در نمای پردازه فقط نام پردازه‌ها ذکر می‌شود.
  • دقیقا ذکر شود در هر سرور چه پردازه‌هایی در حال اجرا هستند.
• در نمای استقرار، اطلاعاتی مثل IP سرورها ذکر نشود.

...

• بیان الگوهای کلی بی‌فایده است. در عوض باید بیان شود چه تقسیم‌بندی‌ها و تصمیماتی در سطح کد گرفته شده است. مثلا به جای ترسیم شکل یک معماری سه لایه، که احتمالا از اینترنت کپی شده است، تبیین شود که محتوای لایه‌ها در پروژه چگونه است و در هر لایه، چه بسته‌ها و کدهایی قرار می‌گیرد.
• در این نما بایستی مولفه‌های اصلی و ارتباطاتشان مشخص شود.
• هم‌چنین تصمیات کلیدی در پیاده‌سازی، بیان شود. مثلا ذکر شود بحث validation مربوط به موجودیت‌ها و درخواست‌های وب‌سرویس به صورت کد پیاده‌سازی شده و یا توصیف آن در فایل XML ذخیره می‌شود. نحوه‌ دسترسی به افراد در پایگاه‌داده جدا ذخیره شده است.

...

• معرفی ابزارهای تست
• بیان سطوح تست
• بیان تصمیمات کلان برای تست سامانه
• نحوه مدیریت ارتباط تست‌ها با نیازمندی‌ها 

...

• بیان دقیق اطلاعات ذخیره‌شده در لاگ
  • مثلا بیان کلی این که «اطلاعات نشست کاربری لاگ می‌شود» کافی نیست.

...

• بیان سناریوهایی مثل اندازه‌گیری میزان استفاده از شبکه و منابع سیستم کافی نیست.
• نحوه استفاده از لاگ‌های سامانه (موضوع فصل قبل) برای پایش ذکر شود.
• سناریوهای پایش (افراد/نقش‌ها/فرایندها/هشدارها/اقدام‌ها/...) بیان شود.

...

• تصمیمات اساسی در زمینه داده‌های سامانه ذکر شود. این تصمیمات فقط شامل مدل داده‌ها (مثلا جداول اصلی و مهم) نیست. بلکه مواردی مثل تکنیک‌های کلان مورد استفاده در لایه داده (مثلا نحوه و فناوری Cache و Backup/Restore و Data Migration و ...) ذکر شود.

...

• قرار نیست جزییات روش‌ها بیان شود، بلکه به طور کلی بیان شود که برای هر مساله/نیازمندی دقیقا چه تکنیک‌هایی مورد استفاده قرار گرفته است.

...

.

پیوست

فایل قالب پیشنهادی

برای مشاهده محتوای این بخش حذف شده استبه نسخه کامل قالب سند معماری مراجعه نمایید.