ویرگول
ورودثبت نام
Maedeh Zarei
Maedeh Zarei
Maedeh Zarei
Maedeh Zarei
خواندن ۲۱ دقیقه·۳ ماه پیش

شرح کامل پروژه درس معماری نرم افزار، سامانهٔ اطلاعات و خدمات بیمارستانی HISS

وقتی صحبت از یک سامانهٔ بیمارستانی میشود، اولین تصویری که معمولاً به ذهن میرسد مجموعهای از قابلیتهای مختلف مانند ثبت بیمار، جستوجوی پزشک، نوبتدهی، پروندهٔ پزشکی و صدور صورتحساب است. اما در یک پروژهٔ معماری نرمافزار، پرسش اصلی فقط این نیست که سیستم چه کارهایی انجام میدهد؛ پرسش مهمتر این است که این سیستم چرا باید به این شکل طراحی شود و این طراحی چگونه کیفیتهای مورد انتظار را در شرایط واقعی تضمین میکند؟

پروژهٔ HISS یا Hospital Information and Service System با همین نگاه طراحی شده است؛ یک نمونهٔ کوچک اما معماریمحور از سامانهٔ اطلاعات و خدمات بیمارستانی که هدف آن، بیش از آن که شبیهسازی کامل یک بیمارستان واقعی باشد، نمایش تصمیمهای معماری، trade-offها، سناریوهای کیفیتی، جداسازی مسئولیتها، ارتباط رویدادمحور و یک حلقهٔ خودسازگار سبک است.

در این پروژه تلاش شده است میان سادگی لازم برای یک نمونهٔ دانشجویی و بررسی متعادل معماری برقرار شود. بنابراین سیستم عمداً به یک زیرساخت توزیعشدهٔ سنگین تبدیل نشده و در عوض، معماری آن بر پایهٔ یک Modular Monolith، لایهبندی داخلی هر ماژول، ارتباط Event-Driven درونبرنامهای، الگوی Adapter برای یکپارچهسازی و یک حلقهٔ MAPE-K مبتنی بر Rule بنا شده است.

HISS — Hospital Information & Service System
HISS — Hospital Information & Service System

مسئله و زمینهٔ کسب و کار

HISS تصویری سادهشده از گردش کار روزمرهٔ یک بیمارستان ارائه میدهد. در این محیط، بیمار ثبت میشود، پزشک جستوجو میشود، برای بیمار نوبت ثبت میشود، اطلاعات پایهٔ پزشکی در دسترس قرار میگیرد، صورتحساب ساخته میشود و در صورت نیاز، سیستم با سرویسهایی مانند بیمه، داروخانه یا آزمایشگاه تعامل میکند.

چهار نقش اصلی در سیستم وجود دارند:

. بیمار

. پزشک

. پذیرش

. مدیر سیستم

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

از طرف دیگر، سه سیستم بیرونی که در یک بیمارستان واقعی میتوانند وجود داشته باشند، در این پروژه به صورت Mock Adapter مدل شدهاند:

. سامانهٔ بیمه

. سامانهٔ داروخانه

. سامانهٔ آزمایشگاه

نکتهٔ معماری اینجا مهم است. هدف پروژه شبیهسازی شبکه و API واقعی این سرویسها نیست؛ هدف این است که مرز یکپارچهسازی بهشکل واقعی طراحی شود تا در آینده بتوان پیادهسازی Mock را با یک سرویس واقعی جایگزین کرد.

محدودهٔ سیستم

قابلیتهای اصلی HISS شامل این موارد است:

. احراز هویت و مدیریت کاربران

. مدیریت اطلاعات بیمار

. نمایش خلاصهٔ پروندهٔ پزشکی

. جستوجوی پزشک

. مشاهدهٔ زمانهای قابل رزرو

. ثبت، لغو و تغییر نوبت

. مدیریت اولویت نوبتهای اضطراری

. ایجاد فاکتور

. محاسبهٔ هزینه و وضعیت بیمه

. اعلانهای سیستم

. اتصال Mock به بیمه، داروخانه و آزمایشگاه

. داشبورد مدیریتی و پایش وضعیت سیستم

. ثبت رخدادهای عملیاتی و امنیتی

. مدیریت درخواستهای تغییر برخی اطلاعات حساس پروفایل

در مقابل، پروژه عمداً وارد حوزههایی مانند Telemedicine کامل، پیچیدگی کامل EMR/EHR، پرداخت واقعی، انبار دارو، LIS واقعی، PACS، فرآیند کامل اورژانس و زیرسیستمهای اداری بیمارستان نمیشود. این محدودسازی بخشی از تصمیم معماری پروژه است و نه یک کمبود تصادفی. هدف آن است که ظرفیت پروژه صرف نمایش استدلال معماری شود، نه پیادهسازی زیرساختی که از مسئلهٔ اصلی دور شود.

از Functionality تا Quality Attribute

یکی از مهمترین تفاوتهای دیدگاه معماری نرمافزار با توسعهٔ صرفاً قابلیتمحور، توجه به Quality Attributeها است.

در این پروژه، کیفیتها بهصورت صفتهای مبهم مانند "سیستم سریع باشد" یا "سیستم امن باشد" در نظر گرفته نشدهاند.

برای هر کیفیت، باید بتوان مشخص کرد:

. چه چیزی را اندازه میگیریم؟

. در چه شرایطی؟

. با چه هدفی؟

. اگر سیستم با یک محرک خاص مواجه شد، چه واکنشی باید نشان دهد؟

این نگاه با الگوی سناریوهای Quality Attribute که در درس معماری نرمافزار مطرح میشود همراستا است. در پروژه، سناریوها به اجزایی مانند منبع محرک، خود محرک، محیط، Artifact، پاسخ و معیار پاسخ شکسته شدهاند.

اولویت Quality Attributeها

از همان ابتدا برای کیفیتهای سیستم یک ترتیب اولویت مشخص در نظر گرفته شد:

1. Availability

2. Performance

3. Security

4. Integrability

5. Modern Architectural Topics

6. Testability

7. Maintainability / Modifiability

این ترتیب صرفاً یک فهرست نیست. مهمترین کاربرد آن زمانی مشخص میشود که دو کیفیت با یکدیگر تعارض دارند.

برای مثال، استفاده از bcrypt هزینهٔ محاسباتی بیشتری نسبت به روشهای سادهتر دارد، اما به دلیل اهمیت Security قابل توجیه است. از طرف دیگر، در مسیرهای پرتکرار مانند جستوجو و نوبتدهی، Performance اهمیت بیشتری پیدا میکند. به بیان دیگر، Quality Attributeها رایگان نیستند و هر تصمیم معماری روی چند کیفیت اثر میگذارد. بنابراین معماری به یک اولویت صریح نیاز دارد تا هنگام تعارض بتواند تصمیم بگیرد کدام کیفیت در آن پروژه مهمتر است.

معماری انتخابشده

معماری HISS از ترکیب چند ایده شکل گرفته است:

Modular Monolith + Layered Architecture + Event-Driven Communication + Rule-Based Self-Adaptation

در نگاه اول ممکن است این ترکیب متناقض به نظر برسد؛ چون Event-Driven و MAPE-K گاهی با سیستمهای توزیعشده، Microserviceها و زیرساختهای پیچیده تداعی میشوند. اما در این پروژه این مفاهیم در اندازهٔ یک برنامهٔ تکفرآیندی پیادهسازی شدهاند.

چرا Modular Monolith؟

HISS یک برنامهٔ قابل استقرار دارد، اما داخل آن به چندین ماژول مستقل تقسیم شده است.

ماژولهای اصلی شامل این بخشها هستند:

. Authentication

. Patients

. Doctors

. Appointments

. Billing

. Notifications

. Integrations

. Profile

. Tickets

. Events

. Adaptation

. Audit

این ساختار اجازه میدهد سیستم از نظر فیزیکی ساده باقی بماند، اما از نظر منطقی مانند مجموعهای از زیرسیستمهای مستقل سازماندهی شود. در ارائهٔ پروژه، این ساختار در قالب دوازده ماژول و یک پردازش اصلی FastAPI مستند شده است.

در نتیجه، یک ماژول جدید لزوماً نباید به فایلها و پوشههای مشترک همهٔ ماژولهای دیگر دست بزند.

این انتخاب آگاهانه در مقابل Microservices قرار گرفته است. تبدیل دوازده ماژول داخلی به سرویسهای شبکهای، مسئلههای دیگری مانند Service Discovery، Serialization، Failureهای شبکه، Partial Failure و مدیریت چند Process را وارد پروژه میکرد؛ مسائلی که برای این نمونهٔ دانشگاهی نه تنها ضروری نبودند، بلکه تمرکز را از بحث معماری مورد نظر دور میکردند.

Fig. 3 — c4 model,container diagram. "Container" is the C4 sense (an independently runnable unit) — not Docker. There is deliberately exactly one running process (ADR 008).
Fig. 3 — c4 model,container diagram. "Container" is the C4 sense (an independently runnable unit) — not Docker. There is deliberately exactly one running process (ADR 008).
Fig. 4 — c4 model, component diagram (relationship list trimmed for legibility — the file on disk lists every module's core dependency too). No Code-level (4th) C4 diagram is maintained by hand, per the course's own guidance.
Fig. 4 — c4 model, component diagram (relationship list trimmed for legibility — the file on disk lists every module's core dependency too). No Code-level (4th) C4 diagram is maintained by hand, per the course's own guidance.

چهار لایه، اما درون هر ماژول

یکی از تصمیمهای مهم HISS این است که لایهبندی بهشکل یک ساختار سراسری مانند api/, service/, domain/ و repository/ در نظر گرفته نشده است.

در عوض، هر ماژول تا حد امکان ساختار لایهای خودش را دارد:

app/appointments/

api.py

service.py

domain.py

repository.py

models.py

در نتیجه، چهار لایهٔ مفهومی عبارتاند از:

Presentation

مسئول Routeها، شکل ورودی و خروجی درخواستها و تعامل با UI است.

Application

منطق Use Case، orchestration، تراکنشها و کنترل دسترسی در این لایه قرار دارد.

Domain

قوانین کسبوکار خالص، بدون دسترسی مستقیم به I/O، در این بخش قرار میگیرند؛ البته فقط در ماژولهایی که واقعاً به منطق دامنهٔ غنی نیاز دارند.

Infrastructure

مسئول Persistence و تعامل با SQLAlchemy و سایر جزئیات فنی است.

این موضوع با ایدهٔ Clean Architecture در جداسازی وابستگیها و حفاظت از منطق کسبوکار همجهت است، اما پروژه یک پیادهسازی کاملاً کلاسیک و یکسان از آن ارائه نمیدهد. تصمیم عملی پروژه این بوده که لایهها درون Feature Moduleها قرار بگیرند.

Fig. 5 — the stack repeated identically in auth/, patients/, appointments/, ... Only appointments and billing have a real domain.py — other modules' logic is thin enough to live directly in service.py, which is itself a documented, deliberate choice, not an inconsistency.
Fig. 5 — the stack repeated identically in auth/, patients/, appointments/, ... Only appointments and billing have a real domain.py — other modules' logic is thin enough to live directly in service.py, which is itself a documented, deliberate choice, not an inconsistency.

چرا Domain بهصورت Shared Package نیست؟

در پروژه میتوانستیم یک پوشهٔ مشترک مانند app/domain/ داشته باشیم؛ اما چنین ساختاری باعث میشد Featureهای مختلف مرتباً وارد یک فضای مشترک شوند. در یک Modular Monolith، این موضوع میتواند Coupling سازمانی ایجاد کند؛ حتی اگر Coupling فنی ظاهراً کم باشد.

در HISS، با قرار گرفتن لایهها داخل هر ماژول، یک Feature را میتوان تقریباً از ابتدا تا انتها در یک مکان دنبال کرد.

هزینهٔ این تصمیم مقداری تکرار در Serviceها است، اما با توجه به اینکه Maintainability پایینترین اولویت پروژه تعیین شده، این Trade-off به نفع خوانایی محلی و کاهش وابستگی بین ماژولها پذیرفته شده است.

حتی این اصل در Controllerها نیز قابل مشاهده و قابل بررسی است: api.py صرفاً کار تبدیل Request و Response را انجام میدهد و Query مربوط به SQLAlchemy یا Business Rule در آن قرار نگرفته است.

نمای C4 و تقسیمبندی سیستم

برای توضیح معماری از Viewهای C4 نیز استفاده شده است.

در سطح Container، عمداً تنها یک واحد اجرایی واقعی وجود دارد؛ همان برنامهٔ FastAPI. در اینجا Container به معنای C4 است و نه Docker Container. درون این Application، Componentهای اصلی شامل Authentication، Patient، Doctor، Appointment، Billing، Notification، Integration Adapter، Profile، Tickets، Event Bus، Adaptation، Audit و Core هستند.

ارتباط آنها نیز به شکل مشخصی تعریف شده است. برای مثال:

. Appointment رویداد منتشر میکند.

. Notification رویداد را مصرف میکند.

. Audit رویدادها را ثبت میکند.

. Billing از Adapter facade استفاده میکند.

. Integration timeoutها را به Adaptation گزارش میدهد.

. Authentication failureها نیز ورودی حلقهٔ Adaptation هستند.

این Viewها کمک میکنند تفاوت میان «ساختار استقرار» و «ساختار منطقی» روشن بماند.

مدل داده و موجودیتهای اصلی

مدل دادهٔ HISS نیز با تمرکز بر دامنهٔ اصلی سیستم طراحی شده است.

موجودیتهای اصلی شامل موارد زیر هستند:

. User

. Role

. Patient

. Doctor

. DoctorSpecialization

. DoctorAvailability

. Appointment

. Invoice

. Notification

. Ticket

. AuditLog

. AdaptationRule

. AdaptationEvent

. MockAdapterState

برای نمونه، Appointment به Patient و Doctor وابسته است و میتواند Invoice متناظر داشته باشد. Invoice نیز وضعیت پرداخت و وضعیت بررسی بیمه را نگه میدارد. همچنین AdaptationRule و AdaptationEvent بخشی از Model مربوط به خودسازگاری سیستم هستند.

نکتهٔ جالب این است که Profile بهعنوان یک Table مستقل وجود ندارد. این بخش بیشتر یک Use Case و orchestration روی موجودیتهای User، Patient و Doctor است و به همین دلیل ایجاد یک موجودیت جدید صرفاً برای نامگذاری Profile ضروری تشخیص داده نشده است.

Fig. 6 — domain model. Profile is deliberately absent as a table: app/profile/ has no models.py — it orchestrates User/Patient/Doctor directly.
Fig. 6 — domain model. Profile is deliberately absent as a table: app/profile/ has no models.py — it orchestrates User/Patient/Doctor directly.
patient
patient
doctor
doctor
receptionist
receptionist
admin
admin

ارتباط Event-Driven درون برنامه

یکی از مهمترین ایدههای پروژه، Event-Driven Communication است.

برای این کار یک Event Bus بسیار سبک درونپردازشی وجود دارد که از الگوی Publish/Subscribe استفاده میکند.

برای مثال، پس از ثبت موفق نوبت:

AppointmentService > publish(AppointmentBooked) > Notification > Audit

در نتیجه Appointment Module لازم نیست Notification یا Audit را مستقیماً Import کند.

این موضوع یک Decoupling واقعی ایجاد میکند. در Sequence Diagram پروژه، پس از انتشار AppointmentBooked تمام واکنشهای بعدی از طریق Event Bus انجام میشوند و Service نوبتدهی مستقیماً با Notification یا Audit صحبت نمیکند.

مزیت مهم این کار برای آینده این است که اگر مثلاً کانال SMS اضافه شود، لازم نیست منطق Appointment تغییر کند. کافی است یک Handler جدید برای Event مورد نظر اضافه شود.

به همین دلیل، Event-Driven Design در این پروژه فقط یک موضوع مدرن نیست؛ یک ابزار مستقیم برای Integrability و Modifiability است.

Adapter و Integrability

یک بیمارستان واقعی وابسته به سیستمهای بیرونی متعددی است. در این پروژهٔ دانشجویی، اتصال واقعی به چنین سرویسهایی عملی و حتی ضروری نیست. اما حذف کامل مرز Integration هم از نظر معماری منطقی نبود.

راهحل HISS، استفاده از یک BaseAdapter است.

منطق مصرفکننده به یک Interface مشخص وابسته میماند و جزئیات سرویس خارجی پشت Adapter قرار میگیرد.

بنابراین:

Billing → BaseAdapter → Mock Insurance

و در نسخهٔ آینده میتواند به:

Billing → BaseAdapter → Real Insurance API

تبدیل شود.

این دقیقاً همان نقطهای است که معماری از قابل اجرا بودن به قابل توسعه بودن میرسد. حتی اگر سرویس واقعی هرگز ساخته نشود، مرز آن از ابتدا در معماری مشخص شده است.

گردش کامل یک نوبت

یکی از مهمترین Use Caseهای سیستم، رزرو نوبت است.

گردش کلی به شکل زیر است:

ورود کاربر

↓

جستوجوی پزشک

↓

انتخاب زمان

↓

بررسی قوانین رزرو

↓

ایجاد Appointment

↓

بررسی صف و وضعیت سیستم

↓

بررسی بیمه

↓

ایجاد Invoice در صورت نیاز

↓

ثبت Audit

↓

انتشار AppointmentBooked

↓

Notification

↓

ثبت رویدادهای مرتبط

اما در این فرآیند چند Gate معماری نیز وجود دارد.

برای مثال، اگر سیستم وارد حالت degraded_read_only شده باشد، درخواستهای غیراضطراری ممکن است با خطای 503 رد شوند، در حالی که نوبت اضطراری همچنان مجاز باقی بماند. همچنین زمان گذشته یا تداخل زمانی یک نوبت با نوبت قبلی، قبل از ایجاد Appointment بررسی میشود.

این مثال نشان میدهد که Quality Attributeها صرفاً در یک سند نوشته نشدهاند؛ بلکه مستقیماً وارد Flow اصلی سیستم شدهاند.

Performance Scenario 3 — search by name/specialization, target <2s. Single indexed query, doctors/repository.py.
Performance Scenario 3 — search by name/specialization, target <2s. Single indexed query, doctors/repository.py.
Performance Scenario 4 — booking completes, target <3s. Naive-UTC slot comparison avoids an aware/naive datetime bug this project hit once.
Performance Scenario 4 — booking completes, target <3s. Naive-UTC slot comparison avoids an aware/naive datetime bug this project hit once.
Three notifications, three different domain events, same in-process bus — proof the fan-out actually ran, not just that it compiles.
Three notifications, three different domain events, same in-process bus — proof the fan-out actually ran, not just that it compiles.

Availability؛ مهمترین کیفیت سیستم

اولین Quality Attribute در این پروژه Availability است.

در یک سامانهٔ بیمارستانی، شکست یک زیرسیستم نباید الزاماً به معنای شکست کل فرآیند باشد. بنابراین، HISS بهجای طراحی برای همهچیز یا هیچچیز، از Graceful Degradation استفاده میکند.

سناریوی نمونه

فرض کنید سرویس بررسی بیمه از دسترس خارج شود.

یک معماری ساده ممکن است چنین رفتاری داشته باشد:

Insurance timeout

↓

Exception

↓

Booking failed

اما HISS تلاش میکند چنین رفتاری داشته باشد:

Insurance timeout

↓

AdapterResult(deferred=True)

↓

Insurance = DEFERRED

↓

Billing continues

↓

Core workflow remains available

در این طراحی، شکست Adapter به یک Result معنادار تبدیل میشود، نه یک Exception خام. در نتیجه Billing مجبور میشود آگاهانه تصمیم بگیرد با حالت Deferred چه کند. این رفتار باعث میشود اختلال بیمه، کل فرآیند نوبتدهی و صورتحساب را از کار نیندازد.

در واقع، در این پروژه Availability از طریق Redundancy چند سرور تأمین نمیشود؛ چون سیستم اصلاً معماری چندسروری ندارد. Availability با کاهش دامنهٔ اثر Failure و ادامهٔ سرویسهای حیاتی محقق میشود.

/ui/admin — Mock adapters
/ui/admin — Mock adapters
/ui/invoices/1
/ui/invoices/1
app/integrations/ - base.pyBaseAdapter.call()
app/integrations/ - base.pyBaseAdapter.call()

Performance و مدیریت بار

Quality Attribute دوم Performance است.

دو سناریوی مشخص برای Performance تعریف شدهاند:

جستوجوی پزشک

درخواست جستوجوی پزشک بر اساس نام یا تخصص باید معمولاً در کمتر از دو ثانیه پاسخ دهد.

ثبت نوبت

در شرایط بار عادی، ثبت نوبت باید معمولاً کمتر از سه ثانیه طول بکشد.

این اهداف در قالب Testهای جداگانه نیز بررسی شدهاند.

علاوه بر کاهش Latency در مسیرهای اصلی، پروژه از Performance در کنار Availability نیز استفاده میکند. برای مثال، وقتی Queue بیش از مقدار مشخصی رشد کند، سیستم وارد حالت اولویتدهی به نوبتهای اضطراری میشود.

در نتیجه بهجای اینکه صرفاً تعداد بیشتری از درخواستها را بپذیرد، تلاش میکند در شرایط فشار، درخواست مهمتر را زودتر سرویس دهد.

/ui/profile
/ui/profile
/ui/patient
/ui/patient

MAPE-K؛ خودسازگاری بدون هوش مصنوعی

یکی از بخشهای معماری که پروژه را از یک CRUD ساده جدا میکند، وجود یک حلقهٔ MAPE-K است:

Monitor

Analyze

Plan

Execute

Knowledge

این حلقه در HISS کاملاً Rule-Based است و از Machine Learning استفاده نمیکند.

دلیل این انتخاب این است که در یک پروژه، مهم است تصمیم سیستم قابل مشاهده و قابل توضیح باشد. وقتی Rule مشخص است، میتوان دقیقاً گفت: "اگر این وضعیت رخ داد، این سیاست اجرا میشود".

در پروژه حتی یک Thread پسزمینهٔ دائمی برای Poll کردن وضعیت وجود ندارد. چون اغلب Signalهای مورد نیاز، مانند Login Failure، Queue Length، Adapter Timeout و Latency، همان لحظهٔ پردازش Request اتفاق میافتند. بنابراین MAPE-K به صورت Synchronous و در همان مسیر اجرا میشود.

Monitor

Monitor وضعیتهایی مانند این موارد را میگیرد:

تعداد درخواستهای در حال پردازش

طول صف نوبت

میانگین Latency

تعداد Login Failureها

Timeoutهای Adapter

تعداد Notificationهای معوق

Analyze

Analyze وضعیت فعلی را با Thresholdهای از پیش تعریفشده مقایسه میکند.

مثلاً:

queue_length > 15

یا:

failed_logins >= 5

Plan

پس از شناسایی Condition، یک Policy انتخاب میشود.

Execute

Policy انتخابشده روی وضعیت Runtime اعمال میشود.

Knowledge

Knowledge Base شامل Ruleها، Thresholdها، Policyها و وضعیت سازگاری است.

در HISS این Knowledge Base عمداً پیچیده نشده و به صورت Ruleهای ساده و محلی نگهداری میشود.

Ruleهای واقعی سیستم

چند Rule مهم پروژه عبارتاند از:

. QUEUE_OVERLOAD طول صف بیشتر از ۱۵ ENABLE_EMERGENCY_PRIORITY انتقال نوبتهای اضطراری به ابتدای صف

. HIGH_LOAD بیش از ۲۵ درخواست در حال پردازش ENABLE_EMERGENCY_PRIORITY افزایش اولویت درخواستهای بحرانی

. HIGH_LATENCY میانگین Latency بیشتر از ۸۰۰ms DEGRADE_READ_ONLY محدود کردن Writeهای غیراضطراری

. AUTH_BRUTE_FORCE حداقل ۵ Login ناموفق در ۵ دقیقه RATE_LIMIT_LOGIN کاهش یا توقف موقت Login

. ADAPTER_DOWN حداقل ۳ Timeout متوالی ROUTE_TO_FALLBACK عبور از مسیر اصلی و ورود به حالت Deferred

. NOTIFICATION_BACKLOG بیشتر از ۵۰ اعلان خواندهنشده DELAY_NONCRITICAL_OPS تعویق عملیات غیرضروری

این Ruleها نمونهای از یک Self-Adaptive System بسیار سبک هستند. سیستم رفتار خود را با توجه به وضعیت Runtime تغییر میدهد، اما این تغییر Behavior کاملاً قابل توضیح است.

Fig. 9 — the loop has five parts, not four: Knowledge is the shared object every other stage reads or writes (AdaptationRule/AdaptationEvent tables for durable history, the in-memory AdaptationState singleton for live counters).
Fig. 9 — the loop has five parts, not four: Knowledge is the shared object every other stage reads or writes (AdaptationRule/AdaptationEvent tables for durable history, the in-memory AdaptationState singleton for live counters).
Adaptation Rules
Adaptation Rules
app/adaptation/monitor.py
app/adaptation/monitor.py
Live state exposed at GET /admin/dashboard — the Monitor's raw observations, human-readable.
Live state exposed at GET /admin/dashboard — the Monitor's raw observations, human-readable.
The knowledge base (six rules) and a real firing.
The knowledge base (six rules) and a real firing.

Security؛ فراتر از Login

Security در HISS فقط به Login محدود نشده است.

سه سطح مهم در اینجا وجود دارد:

Authentication

ابتدا باید مشخص شود کاربر واقعاً چه کسی است.

برای این کار:

. Username & Password

. Password Hashing

. JWT

. FastAPI Dependency

استفاده شده است.

همین Dependency هم API و هم رابط Server-Rendered را پوشش میدهد. در API، Token از Authorization Header گرفته میشود و در UI، همان Token از HttpOnly Cookie خوانده میشود. سپس require_role() سطح Authorization را اعمال میکند.

Authorization

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

برای مثال، اینکه فرد Doctor است لزوماً به معنی آن نیست که بتواند پروندهٔ هر بیمار را ببیند. به همین دلیل، علاوه بر RBAC، Object-Level Authorization نیز وجود دارد.

مثلاً پزشک فقط باید بتواند پروندهٔ بیمارانی را ببیند که ارتباط کاری مجاز با آنها دارد. بیمار نیز فقط باید به پروندهٔ خودش دسترسی داشته باشد.

Audit & Traceability

برای عملیات حساس، Audit Log نیز وجود دارد.

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

127.0.0.1:8000/ui/login
127.0.0.1:8000/ui/login
app/core/deps.py - get_current_user()
app/core/deps.py - get_current_user()

سناریوی امنیتی Brute Force

یکی از سناریوهای مشخص Security، تکرار Login ناموفق است.

اگر در یک بازهٔ کوتاه چند تلاش ناموفق انجام شود:

Failed logins

↓

Monitor

↓

Analyze

↓

AUTH_BRUTE_FORCE

↓

RATE_LIMIT_LOGIN

↓

Lock / Delay

Cooldown نیز بعد از نقضهای بعدی افزایش پیدا میکند.

این نکته جالب است که یک Tactic با ریشهٔ Performance/Availability در اینجا برای Security استفاده شده است. Rate Limiting فقط یک ابزار امنیتی نیست؛ در واقع با محدود کردن مصرف منابع، میتواند روی Performance نیز اثر بگذارد. پروژه عمداً این تعامل میان Quality Attributeها را نشان میدهد. همچنین Check مربوط به Lockout قبل از محاسبهٔ Password Hash انجام میشود تا حتی در حالت Lock شده، هزینهٔ اضافی bcrypt پرداخت نشود.

Fig. 10 — reproduced verbatim against the running server: five curl requests with a wrong password, then a sixth with the correct password — still rejected with 429.
Fig. 10 — reproduced verbatim against the running server: five curl requests with a wrong password, then a sixth with the correct password — still rejected with 429.

یک تصمیم امنیتی دیگر؛ تغییر اطلاعات هویتی

در طول توسعه، یک سؤال معماری واقعی ایجاد شد که آیا کاربر باید بتواند تمام اطلاعات پروفایل خود را مستقیماً ویرایش کند؟

برای بعضی فیلدها پاسخ مثبت است و برای برخی دیگر پاسخ منفی؛ در نتیجه فرآیند Ticket ایجاد شد.

برای نمونه، تغییر برخی فیلدهای حساس مانند نام، Username یا شمارهٔ تلفن ابتدا به یک Ticket تبدیل میشود:

User

↓

Profile Change Request

↓

Ticket

↓

TicketCreated

↓

Admin Review

├── Approve

└── Reject

↓

TicketResolved

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

/ui/profile/edit
/ui/profile/edit
/ui/admin/tickets
/ui/admin/tickets

/ui/admin/tickets
/ui/admin/tickets
OWASP password policy
OWASP password policy

سناریوهای رسمی Quality Attribute

پروژه برای QAهای اصلی، هشت سناریوی مشخص تعریف و به Code و Test متناظر متصل کرده است:

سناریوی ۱ — Availability

محرک: Timeout سرویس بیمه هنگام نوبتدهی یا صورتحساب

پاسخ: سیستم وارد حالت Deferred میشود و جریان اصلی ادامه پیدا میکند.

معیار: سیستم Crash نکند و Booking/Billing امکان ادامه داشته باشد.

سناریوی ۲ — Availability

محرک: افزایش شدید بار و تعداد زیاد درخواستهای نوبت

پاسخ: سیستم درخواستهای اضطراری را در اولویت قرار دهد.

معیار: فرآیند اصلی نوبتدهی همچنان قابل استفاده باشد.

سناریوی ۳ — Performance

محرک: جستوجوی پزشک

معیار: معمولاً کمتر از دو ثانیه.

سناریوی ۴ — Performance

محرک: ثبت نوبت

معیار: معمولاً کمتر از سه ثانیه.

سناریوی ۵ — Security

محرک: تلاش بیمار برای دسترسی به پروندهٔ بیمار دیگر

پاسخ: دسترسی رد و رخداد ثبت شود.

معیار: هیچ دادهٔ خصوصی افشا نشود.

سناریوی ۶ — Security

محرک: چند Login ناموفق

پاسخ: سیستم Login را محدود یا موقتاً مسدود کند.

سناریوی ۷ — Integrability

محرک: از دسترس خارج شدن Adapter بیمه

پاسخ: استفاده از Fallback یا Pending/Deferred State.

معیار: جریان اصلی همچنان فعال باشد.

سناریوی ۸ — Testability

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

پاسخ: تست بدون UI یا Database اجرا شود.

معیار: Core Business Logic مستقل و قابل آزمون باشد.

این نکته اهمیت دارد که سناریوها صرفاً در گزارش نوشته نشدهاند؛ برای آنها Test و Code مشخص معرفی شده است.

Quality Attribute Scenarios
Quality Attribute Scenarios

Testability و Maintainability

Testability در این پروژه، نتیجهٔ مستقیم مرزبندی معماری است.

برای Unit Test، منطق Domain و بخشهایی از Adaptation بدون نیاز به FastAPI یا Database تست میشوند.

در Integration Test نیز یک SQLite موقت به همراه TestClient استفاده میشود تا ارتباط میان ماژولها بررسی شود.

در زمان تهیه، مجموعهٔ تستها ۱۴۰ تست موفق داشته است. تستهای Integration مسائلی مانند RBAC، انتشار Eventها و فعال شدن Adaptation را از ابتدا تا انتهای مسیر بررسی میکنند.

بنابراین Testability صرفاً یک نتیجهٔ جانبی نیست؛ یکی از دلایل اصلی جداسازی Domain، Application و Infrastructure است.

تصمیمهای معماری در قالب ADR

برای اینکه تصمیمهای معماری فقط در ذهن توسعهدهنده نمانند، در قالب Architecture Decision Record مستند شده اند.

مهمترین تصمیمها عبارتاند از:

001 Modular Monolith به جای Microservices

002 SQLite برای Prototype با آمادگی مهاجرت به MySQL

003 Event Bus درونپردازشی به جای Message Broker

004 JWT به جای Server-Side Session

005 Rule-Based Adaptation به جای ML

006 Layering درون هر Module به جای Shared Domain Layer

007 Server-Rendered Jinja2 به جای SPA

008 عدم استفاده از Docker/Kubernetes برای Prototype

009 Ticket برای تغییر فیلدهای حساس هویتی

010 اعمال Password Strength هنگام تغییر رمز به جای Registration

وجود این ADRها یک نکتهٔ مهم معماری را نشان میدهد:

معماری فقط مجموعهای از فایلها نیست؛ مجموعهای از تصمیمها و دلایل پشت آن تصمیمهاست.

چرا Kafka، RabbitMQ یا Event Broker واقعی نداریم؟

ممکن است این سؤال مطرح شود که اگر سیستم Event-Driven است، چرا از Kafka یا RabbitMQ استفاده نشده است؟

پاسخ از اولویتهای پروژه میآید:

. Event Bus این پروژه یک کار مشخص دارد: کاهش Coupling بین ماژولها.

. برای رسیدن به این هدف، یک Publish/Subscribe درونپردازشی کافی است.

. استفاده از Broker واقعی، یک Process دیگر، Serialization، مدیریت Failureهای بیشتر، راهاندازی زیرساخت و هزینهٔ عملیاتی وارد پروژه میکرد.

در نتیجه برای این Prototype، آن مزیتها ارزش هزینهٔ خود را نداشتند. این تصمیم به معنی بد بودن Kafka یا RabbitMQ نیست؛ بلکه به معنی نامتناسب بودن آنها با مسئلهٔ حاضر است.

چرا Microservice نداریم؟

همین منطق دربارهٔ Microservice نیز صدق میکند.

اگر Appointment، Billing، Notification و Authentication هرکدام سرویس جداگانهای بودند، مسائل توزیعشدهٔ جدیدی ایجاد میشدند.

اما در این پروژه، هدف اصلی مطالعهٔ:

. Separation of Concerns

. Modularity

. Quality Attributes

. Event-Driven Communication

. Adaptation

. Testability

است.

بنابراین، انتخاب Modular Monolith امکان میدهد این مفاهیم با پیچیدگی عملیاتی بسیار کمتر بررسی شوند.

چرا Docker و Kubernetes نداریم؟

Docker و Kubernetes در این پروژه حذف شدهاند، نه به دلیل اینکه معماری مدرن نیستند، بلکه دقیقاً به دلیل توجه به Scope.

سیستمی که قرار است بهصورت محلی و در یک Process اجرا شود، از Orchestration سود آموزشی کافی نمیبرد. اضافه کردن چنین زیرساختی بخش قابل توجهی از زمان را صرف Deployment و Operations میکند، در حالی که هدف پروژه بررسی تصمیمهای معماری نرمافزار است.

چرا SQLite؟

برای Prototype، SQLite انتخاب شده است؛ چون بدون Configuration پیچیده اجرا میشود و یک گزینهٔ مناسب برای تست و Demo محلی است.

در عین حال، Repository Pattern باعث شده Persistence از Business Logic جدا بماند؛ بنابراین مهاجرت به MySQL در آینده نیازمند بازنویسی منطق Use Caseها نیست.

این تصمیم نمونهٔ خوبی از یک Trade-off است:

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

چرا Frontend ساده است؟

Frontend پروژه با Server-Rendered HTML و Jinja2 ساخته شده و Framework سنگینی مانند React یا Angular در آن وجود ندارد.

علت اصلی این تصمیم نیز کاهش پیچیدگی است:

. Build Step وجود ندارد.

. Bundler وجود ندارد.

. Client-State پیچیده وجود ندارد.

. برای یک Prototype آموزشی، نگهداری UI سادهتر است.

در این پروژه قرار نبوده Frontend موضوع اصلی باشد؛ Frontend باید آنقدر خوب باشد که Architecture قابل نمایش و تست شود.

یک نکتهٔ مهم دربارهٔ Clean Architecture

یکی از درسهای مهم پروژه، این است که Clean Architecture نباید به معنای ایجاد تعداد زیادی Folder و Interface و Abstraction فهمیده شود.

اصل مهم، Dependency Direction و جداسازی مسئولیتها است.

در HISS:

. UI نباید منطق کسبوکار را در خودش نگه دارد.

. Application نباید به Template وابسته باشد.

. Business Rule نباید به Database وابسته باشد.

. Integration باید پشت مرز مشخص قرار گیرد.

. تست Domain باید بدون UI و Database ممکن باشد.

. اما در عین حال، هر انتزاعی فقط زمانی اضافه شده که ارزش معماری مشخصی ایجاد کند.

این دقیقاً دلیل وجود Domain Layer where warranted در بعضی ماژولهاست؛ در appointments و billing منطق دامنهٔ واقعیتر و مستقلتری وجود دارد، اما در برخی ماژولهای دیگر، منطق آنقدر ساده است که قرار دادن آن در Service Layer منطقیتر بوده است.

ارزیابی نهایی معماری

برای ارزیابی، سؤال اصلی این نیست که آیا سیستم چند قابلیت دارد؛ بلکه باید پرسید:

آیا معماری واقعاً Quality Attributeهای هدف را پشتیبانی میکند؟

Availability

با Graceful Degradation، Adapter Failure به Failure کل سیستم تبدیل نمیشود.

Performance

با تمرکز روی Hot Pathهای جستوجو و نوبتدهی، معیارهای زمانی مشخص شده و تستهای مربوط به آنها وجود دارند.

Security

Authentication، Authorization، Object-Level Authorization، Audit و Login Lockout یک مرز امنیتی چندلایه ایجاد میکنند.

Integrability

Adapter Boundary و Event Bus وابستگی مستقیم به سرویسهای بیرونی و Side Effectها را کاهش میدهند.

Self-Adaptation

MAPE-K اجازه میدهد سیستم در زمان اجرا نسبت به Load، Failure و Abuse واکنش نشان دهد.

Testability

منطق مرکزی بدون UI و Database قابل آزمون است.

Modifiability

Module Boundary، Adapter Boundary و Event Boundary باعث میشوند بعضی قابلیتهای آینده بدون بازنویسی گستردهٔ Core اضافه شوند.

یک نقص واقعی که در فرآیند ارزیابی پیدا شد

یکی از نکات ارزشمند این پروژه این است که نتیجهٔ ارزیابی فقط شامل نقاط قوت نیست.

یک مشکل واقعی در Admin Monitor پیدا شد: جدول وضعیت Mock Adapterها در یک Database تازه میتوانست خالی باشد.

دلیل آن این بود که API مربوط به Adapterها در صورت نبودن Rowها آنها را Lazy-Creation میکرد، اما مسیر UI مستقیماً Rowهای موجود را میخواند و خودش آنها را ایجاد نمیکرد. در نتیجه روی یک سیستم تازه، ممکن بود مدیر داشبوردی بدون Adapter قابل مشاهده ببیند.

این مشکل عمداً اینجا پنهان نشده است و بهعنوان یک Gap واقعی معماری و پیادهسازی ثبت شده و راهحل پیشنهادی آن نیز مشخص شد: Seed کردن Rowهای اولیه یا استفاده از همان منطق getor_create() در مسیر UI.

بنابراین معماری خوب فقط به معنای داشتن Diagram زیبا نیست؛ معماری باید با رفتار واقعی سیستم هم تطبیق داده شود.

CIA, mapped to actual code — and a real bug this project shipped and fixed
CIA, mapped to actual code — and a real bug this project shipped and fixed
before and after of app/templates/invoice_view.html
before and after of app/templates/invoice_view.html

چه چیزهایی میتوانند در آینده اضافه شوند؟

ساختار پروژه عمداً طوری طراحی شده که چند قابلیت بتوانند بدون بازنویسی گسترده به آن اضافه شوند.

اتصال واقعی به بیمه، داروخانه و آزمایشگاه

با جایگزین کردن Adapterهای Mock با Adapterهای واقعی.

Telemedicine

میتواند بهصورت یک ماژول جدید وارد همین معماری شود.

EMR/EHR بهتر

مدل فعلی عمداً فقط خلاصهٔ پرونده را نگه میدارد و میتوان آن را گسترش داد.

Role جدید برای Technical Staff

مدل Authorization بهگونهای طراحی شده که اضافه کردن Role جدید نیازمند بازنویسی ساختار اصلی نیست.

MySQL

Repository Boundary برای مهاجرت Persistence طراحی شده است.

جمعبندی

HISS در ظاهر یک سامانهٔ کوچک بیمارستانی است، اما مسئلهٔ اصلی پروژه، تعداد قابلیتها نیست. موضوع اصلی، معماری بهعنوان مجموعهای از تصمیمهای آگاهانه برای رسیدن به کیفیتهای مورد نظر است.

در این پروژه تلاش شد نشان داده شود که میتوان بدون رفتن به سمت زیرساختهای سنگین، همچنان مفاهیم مهم معماری را در یک نمونهٔ عملی پیاده کرد:

. یک Modular Monolith بهجای Microservices

. Layering درون هر Module

. Event-Driven Communication برای کاهش Coupling

. Adapter برای Integrability

. Graceful Degradation برای Availability

. RBAC و Object-Level Authorization برای Security

. MAPE-K برای Self-Adaptation

. Unit و Integration Test برای Testability

. ADR برای ثبت تصمیمها و Trade-offها

شاید مهمترین نتیجهٔ این پروژه همین باشد که معماری نرمافزار مجموعهای از تکنولوژیهای پرزرقوبرق نیست. گاهی انتخاب Kafka یا Kubernetes معماری نیست؛ انتخاب نکردن آنها و داشتن یک دلیل روشن برای انتخاب نکردنشان، خود یک تصمیم معماری است.

گاهی Self-Adaptive بودن به معنی استفاده از Machine Learning نیست؛ چند Rule شفاف که دقیقاً مشخص کنند سیستم در یک وضعیت غیرعادی چگونه رفتار خود را تغییر میدهد، میتواند برای مسئلهٔ مورد نظر کافی و حتی مناسبتر باشد.

و در نهایت، یک معماری زمانی ارزشمند است که بتوان برای تصمیمهای آن پاسخ "چرا" داشت.

HISS تلاشی است برای ساختن چنین سیستمی؛ سیستمی کوچک از نظر زیرساخت، اما جدی از نظر استدلال معماری.

منابع

۱. Bass, L., Clements, P., Kazman, R. — Software Architecture in Practice.

۲. Martin, R. C. — Clean Architecture: A Craftsman's Guide to Software Structure and Design.

۳. مستندات توضیحات پروژهٔ HISS.

به دلیل وجود مشکل در پلتفرم ویرگول و عدم امکان بارگذاری گزارش پروژه، ویدیوی منتشر شده از گزارش پروژه در آپارات مشاهده شود:

https://www.aparat.com/v/zdi0190

اين مطلب، بخشی از تمرين ها و پروژه درس معماری نرمافزار دانشگاه شهيد بهشتی است.

این پست تبلیغاتی نیست.

clean architectureمعماری نرم افزارمعماری نرم افزار شهید بهشتی
۱
۰
Maedeh Zarei
Maedeh Zarei
شاید از این پست‌ها خوشتان بیاید