bank-flow/docs/bank-flow.md

# چالش BankFlow 2026

## ۱. مقدمه

در این چالش، شما مسئول طراحی و پیاده‌سازی یک سامانه Backend برای پردازش درخواست‌های تسهیلات بانکی هستید. هدف صرفاً نوشتن چند API یا پیاده‌سازی مجموعه‌ای از قابلیت‌های مشخص نیست؛ انتظار می‌رود راهکاری ارائه کنید که از نظر طراحی نرم‌افزار، توسعه‌پذیری، خوانایی کد و نگهداری، کیفیت مناسبی داشته باشد.

علاوه بر صحت عملکرد سیستم، کیفیت تصمیم‌های مهندسی شما نیز ارزیابی خواهد شد. بنابراین معماری سیستم، نحوه مدل‌سازی فرایندها، تفکیک مسئولیت‌ها و توسعه‌پذیری راهکار، به‌اندازه عملکرد صحیح آن اهمیت دارد.

## ۲. داستان مسئله

شرکت داتین یکی از ارائه‌دهندگان زیرساخت‌های بانکی (Banking Service Provider) است و سرویس‌های مختلفی را در اختیار بانک‌ها و مؤسسات مالی قرار می‌دهد. یکی از محصولات این شرکت، سامانه پردازش درخواست تسهیلات است.

روزانه هزاران درخواست وام از بانک‌های مختلف وارد این سامانه می‌شود. هر درخواست باید پیش از تأیید نهایی، مراحل مختلفی را طی کند. برای نمونه:

```text
ثبت درخواست
    ↓
اعتبارسنجی اولیه
    ↓
بررسی تقلب
    ↓
اعتبارسنجی مالی
    ↓
تأیید مدیر
    ↓
تأیید نهایی
```

تمام بانک‌ها فرایند یکسانی ندارند. برای مثال:

| بانک | فرایند نمونه |
| --- | --- |
| بانک اول | اعتبارسنجی ← بررسی تقلب ← اعتبارسنجی مالی ← تأیید |
| بانک دوم | اعتبارسنجی ← بررسی AML ← بررسی تقلب ← بررسی ضامن ← اعتبارسنجی مالی ← تأیید |
| بانک سوم | اعتبارسنجی ← تأیید مدیر ← تأیید |

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

## ۳. هدف چالش

هدف، طراحی و پیاده‌سازی یک **سامانه پردازش درخواست تسهیلات** است که بتواند فرایند بررسی درخواست‌های وام را مدیریت کند.

سامانه باید امکانات زیر را فراهم کند:

- ثبت درخواست تسهیلات؛
- پردازش درخواست بر اساس Workflow؛
- مشاهده وضعیت فعلی درخواست؛
- مشاهده تاریخچه پردازش درخواست.

راهکار ارائه‌شده باید ویژگی‌های زیر را داشته باشد:

- طراحی مناسب؛
- توسعه‌پذیری و نگهداری آسان؛
- خوانایی مناسب؛
- قابلیت تست؛
- تفکیک صحیح مسئولیت‌ها.

## ۴. محدوده مسئله

تنها مسئولیت شما پیاده‌سازی **سامانه پردازش درخواست تسهیلات** است. سرویس‌ها و قابلیت‌های خارج از این محدوده، بخشی از چالش محسوب نمی‌شوند.

### قابلیت‌های الزامی

- ثبت درخواست تسهیلات؛
- اجرای فرایند بررسی درخواست؛
- مدیریت وضعیت درخواست؛
- ثبت تاریخچه اجرای مراحل؛
- نگهداری اطلاعات پس از راه‌اندازی مجدد برنامه؛
- ارائه REST API؛
- اجرای پروژه از طریق Docker.

### موارد خارج از محدوده

پیاده‌سازی موارد زیر الزامی نیست:

- احراز هویت و مجوزدهی کاربران؛
- مدیریت نقش‌ها و سطوح دسترسی؛
- رابط کاربری؛
- اتصال واقعی به سامانه‌های بانکی؛
- ارسال پیامک، ایمیل یا اعلان؛
- Message Brokerهایی مانند Kafka و RabbitMQ؛
- Redis، Kubernetes و استقرار ابری؛
- CI/CD؛
- معماری Microservice؛
- پردازش یا تراکنش توزیع‌شده؛
- CQRS و Event Sourcing؛
- سامانه واقعی بررسی دستی.

استفاده از این فناوری‌ها امتیاز مستقیم یا اضافی ایجاد نمی‌کند.

## ۵. نیازمندی‌های عملکردی

### FR-1: ثبت درخواست تسهیلات

کاربر باید بتواند یک درخواست جدید ثبت کند. سامانه باید برای هر درخواست، شناسه‌ای یکتا تولید کند.

پس از ثبت موفق، وضعیت اولیه و نخستین مرحله پردازش به‌ترتیب زیر خواهند بود:

```text
status: SUBMITTED
currentStage: VALIDATION
```

### FR-2: پردازش درخواست

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

- `APPROVED`
- `REJECTED`
- `MANUAL_REVIEW`

### FR-3: مشاهده اطلاعات درخواست

کاربر باید بتواند حداقل اطلاعات زیر را مشاهده کند:

- شناسه درخواست؛
- اطلاعات ثبت‌شده؛
- وضعیت فعلی؛
- مرحله فعلی؛
- زمان ایجاد؛
- زمان آخرین تغییر.

### FR-4: مشاهده تاریخچه پردازش

برای هر مرحله اجراشده، حداقل اطلاعات زیر باید ذخیره و به‌ترتیب زمانی نمایش داده شود:

- نام مرحله؛
- نتیجه اجرا؛
- زمان اجرا؛
- علت یا توضیح نتیجه.

### FR-5: اجرای Workflow

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

### FR-6: مدیریت وضعیت

هر درخواست در هر لحظه دقیقاً یک وضعیت جاری دارد. تغییر وضعیت‌ها باید قابل پیش‌بینی و مطابق قوانین Workflow باشد.

### FR-7: ماندگاری اطلاعات

حداقل اطلاعات زیر باید پس از راه‌اندازی مجدد برنامه حفظ شوند:

- اطلاعات درخواست؛
- وضعیت فعلی؛
- مرحله فعلی؛
- تاریخچه اجرای مراحل.

روش ذخیره‌سازی بر عهده شرکت‌کننده است. استفاده صرف از حافظه (`In-Memory Storage`) این نیازمندی را برآورده نمی‌کند.

### FR-8: بازیابی پس از راه‌اندازی مجدد

درخواست‌هایی که پیش‌تر ثبت شده‌اند، باید پس از راه‌اندازی مجدد برنامه همچنان قابل مشاهده و پردازش باشند.

### FR-9: جلوگیری از پردازش تکراری

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

- مراحل قبلی را دوباره اجرا کند؛
- تاریخچه تکراری ایجاد کند؛
- وضعیت نهایی درخواست را تغییر دهد.

### FR-10: توسعه‌پذیری

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

## ۶. انتظارات کیفی

در طراحی سامانه، موارد زیر باید رعایت شوند:

- خوانایی مناسب کد؛
- تفکیک مسئولیت‌ها؛
- وابستگی کم میان بخش‌های مختلف؛
- قابلیت تست، توسعه و نگهداری.

استفاده از Design Patternها اجباری نیست. یک الگو فقط زمانی ارزشمند است که مسئله‌ای واقعی را حل کند؛ پیچیدگی بیشتر لزوماً به‌معنای کیفیت بالاتر نیست.

## ۷. آزادی در انتخاب فناوری

شرکت‌کنندگان در انتخاب زبان برنامه‌نویسی، Framework، پایگاه داده، ORM و ابزارهای توسعه کاملاً آزاد هستند. فناوری انتخاب‌شده به‌خودی‌خود امتیاز مثبت یا منفی ندارد؛ کیفیت راهکار مهم‌تر است.

## ۸. مدل دامنه

هر درخواست تسهیلات یک موجودیت مستقل (`Entity`) است که در طول چرخه عمر خود از مراحل مختلف Workflow عبور می‌کند.

هر درخواست حداقل شامل اطلاعات زیر است:

| فیلد | نوع | توضیح |
| --- | --- | --- |
| `loanId` | `String` | شناسه یکتای درخواست که سیستم تولید می‌کند |
| `customerId` | `String` | شناسه مشتری |
| `amount` | `Integer` | مبلغ درخواست |
| `phone` | `String` | شماره تلفن همراه |
| `loanType` | `Enum` | نوع تسهیلات |
| `monthlyIncome` | `Integer` | درآمد ماهانه |
| `creditScore` | `Integer` | امتیاز اعتباری |
| `hasGuarantor` | `Boolean` | وجود یا عدم وجود ضامن |
| `status` | `Enum` | وضعیت فعلی درخواست |
| `currentStage` | `Enum\|null` | مرحله فعلی Workflow |
| `createdAt` | `Timestamp` | زمان ایجاد |
| `updatedAt` | `Timestamp` | زمان آخرین تغییر |

### انواع تسهیلات

در این نسخه، فقط دو نوع تسهیلات تعریف شده است:

- `PERSONAL`
- `BUSINESS`

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

## ۹. وضعیت‌های درخواست

هر درخواست در هر لحظه دقیقاً یکی از وضعیت‌های زیر را دارد:

| وضعیت | توضیح |
| --- | --- |
| `SUBMITTED` | درخواست ثبت شده است |
| `IN_PROGRESS` | درخواست در حال پردازش است |
| `MANUAL_REVIEW` | درخواست به بررسی دستی نیاز دارد |
| `APPROVED` | درخواست تأیید شده است |
| `REJECTED` | درخواست رد شده است |

پس از ورود به یکی از وضعیت‌های `APPROVED`، `REJECTED` یا `MANUAL_REVIEW`، پردازش خودکار متوقف می‌شود.

## ۱۰. مراحل Workflow

سامانه باید حداقل مراحل زیر را پشتیبانی کند:

| مرحله | مسئولیت |
| --- | --- |
| `VALIDATION` | بررسی صحت اطلاعات ورودی |
| `FRAUD_CHECK` | بررسی تقلب |
| `GUARANTOR_CHECK` | بررسی وجود ضامن |
| `CREDIT_CHECK` | بررسی اعتبار مالی |
| `MANAGER_APPROVAL` | تأیید مدیر |

هر مرحله فقط مسئول یک وظیفه است و منطق دو مرحله نباید در یک کلاس یا ماژول پیاده‌سازی شود.

## ۱۱. نتیجه اجرای مراحل

هر مرحله یکی از نتایج زیر را تولید می‌کند:

- `PASS`
- `FAIL`
- `MANUAL_REVIEW`

در صورت `FAIL`، پردازش متوقف و وضعیت درخواست `REJECTED` می‌شود. در صورت `MANUAL_REVIEW`، پردازش متوقف و وضعیت درخواست `MANUAL_REVIEW` می‌شود.

## ۱۲. Workflow پایه و مسیرهای شرطی

تمام درخواست‌ها از مسیر زیر آغاز می‌شوند:

```text
SUBMITTED → VALIDATION → FRAUD_CHECK
```

اگر `VALIDATION` یا `FRAUD_CHECK` با شکست مواجه شود، درخواست رد خواهد شد.

### درخواست PERSONAL

```text
VALIDATION
    ↓
FRAUD_CHECK
    ↓
CREDIT_CHECK
    ↓
[در صورت عبور مبلغ از حد تعیین‌شده: MANAGER_APPROVAL]
    ↓
APPROVED
```

### درخواست BUSINESS

```text
VALIDATION
    ↓
FRAUD_CHECK
    ↓
GUARANTOR_CHECK
    ↓
CREDIT_CHECK
    ↓
[در صورت عبور مبلغ از حد تعیین‌شده: MANAGER_APPROVAL]
    ↓
APPROVED
```

## ۱۳. قوانین اعتبارسنجی

مرحله `VALIDATION` حداقل باید قوانین زیر را بررسی کند:

| فیلد | قانون | کد خطا |
| --- | --- | --- |
| `customerId` | الزامی و غیرخالی | `INVALID_CUSTOMER_ID` |
| `amount` | عددی بزرگ‌تر از صفر | `INVALID_AMOUNT` |
| `phone` | دقیقاً ۱۱ رقم، شروع با `09` و فقط شامل رقم | `INVALID_PHONE` |
| `loanType` | یکی از مقادیر `PERSONAL` یا `BUSINESS` | `INVALID_LOAN_TYPE` |
| `monthlyIncome` | عددی نامنفی | `INVALID_MONTHLY_INCOME` |
| `creditScore` | عددی بین ۰ تا ۱۰۰۰ | `INVALID_CREDIT_SCORE` |

اگر یکی از قوانین نقض شود، نتیجه مرحله `VALIDATION` برابر `FAIL` خواهد بود.

## ۱۴. قوانین بررسی تقلب

برای جلوگیری از وابستگی به سرویس‌های خارجی، رفتار مرحله `FRAUD_CHECK` به‌صورت Mock تعریف می‌شود:

| شرط | نتیجه |
| --- | --- |
| `customerId` با `FRAUD` آغاز شود | `FAIL` |
| `customerId` با `REVIEW` آغاز شود | `MANUAL_REVIEW` |
| سایر موارد | `PASS` |

## ۱۵. بررسی ضامن

مرحله `GUARANTOR_CHECK` فقط برای تسهیلات `BUSINESS` اجرا می‌شود:

| شرط | نتیجه |
| --- | --- |
| `hasGuarantor == false` | `FAIL` |
| `hasGuarantor == true` | `PASS` |

## ۱۶. اعتبارسنجی مالی

مرحله `CREDIT_CHECK` بر اساس `creditScore` و مقادیر فایل پیکربندی تصمیم می‌گیرد:

| شرط پیش‌فرض | نتیجه |
| --- | --- |
| `creditScore < 500` | `FAIL` |
| `500 <= creditScore < 650` | `MANUAL_REVIEW` |
| `creditScore >= 650` | `PASS` |

## ۱۷. تأیید مدیر

اگر مبلغ درخواست از `managerApprovalThreshold` بیشتر باشد، مرحله `MANAGER_APPROVAL` اجرا می‌شود. مقدار پیش‌فرض این حد `500000000` است و باید قابل پیکربندی باشد.

رفتار Mock مدیر به‌صورت زیر است:

| شرط | نتیجه |
| --- | --- |
| `amount > monthlyIncome × incomeMultiplier` | `FAIL` |
| سایر موارد | `PASS` |

## ۱۸. رفتار بررسی دستی

اگر هر مرحله نتیجه `MANUAL_REVIEW` برگرداند:

- پردازش متوقف می‌شود؛
- وضعیت درخواست `MANUAL_REVIEW` می‌شود؛
- `currentStage` برابر `null` قرار می‌گیرد؛
- اجرای مجدد Workflow بدون تصمیم جدید نباید ادامه پیدا کند.

پیاده‌سازی سامانه بررسی دستی در این نسخه الزامی نیست.

## ۱۹. پیکربندی قوانین کسب‌وکار

قوانین زیر باید از طریق یک فایل پیکربندی با قالبی مانند JSON، YAML، TOML یا Properties قابل تنظیم باشند:

- حداقل امتیاز اعتباری قابل قبول؛
- بازه امتیاز بررسی دستی؛
- سقف نیاز به تأیید مدیر؛
- ضریب بررسی درآمد.

قالب فایل به انتخاب تیم است. تمام مقادیر باید هنگام راه‌اندازی برنامه خوانده شوند و نیازی به بارگذاری مجدد فایل در زمان اجرا نیست.

نمونه فایل `rules.json`:

```json
{
  "minimumCreditScore": 650,
  "managerApprovalThreshold": 500000000,
  "incomeMultiplier": 20,
  "manualReview": {
    "minScore": 500,
    "maxScore": 649
  }
}
```

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

```java
if (score >= 650) { /* ... */ }
if (amount > 500000000) { /* ... */ }
if (score >= 500 && score < 650) { /* ... */ }
```

اگر فایل پیکربندی به‌شکل زیر تغییر کند، رفتار سامانه باید بدون تغییر کد اصلاح شود:

```json
{
  "minimumCreditScore": 700,
  "managerApprovalThreshold": 900000000,
  "incomeMultiplier": 15,
  "manualReview": {
    "minScore": 650,
    "maxScore": 699
  }
}
```

هدف این بخش، پیاده‌سازی یک Rule Engine عمومی نیست. کافی است قوانین تعریف‌شده در این سند از فایل پیکربندی خوانده و در تصمیم‌گیری سیستم استفاده شوند. پیاده‌سازی DSL یا Rule Engine اختصاصی امتیاز اضافی ندارد.

## ۲۰. قرارداد API

تمام APIها باید از استاندارد REST پیروی کنند. قالب تبادل داده‌ها JSON است و تمام پاسخ‌ها باید Header زیر را داشته باشند:

```http
Content-Type: application/json
```

### ۲۰.۱. ایجاد درخواست تسهیلات

```http
POST /api/v1/loans
```

#### بدنه درخواست

```json
{
  "customerId": "C-1001",
  "amount": 400000000,
  "phone": "09121234567",
  "loanType": "PERSONAL",
  "monthlyIncome": 50000000,
  "creditScore": 720,
  "hasGuarantor": false
}
```

تمام فیلدهای فوق الزامی هستند.

#### پاسخ موفق

```http
HTTP/1.1 201 Created
```

```json
{
  "loanId": "L-10001",
  "status": "SUBMITTED",
  "currentStage": "VALIDATION"
}
```

اگر JSON ارسالی قابل Parse نباشد:

```http
HTTP/1.1 400 Bad Request
```

```json
{
  "error": "INVALID_REQUEST"
}
```

اعتبارسنجی مقادیری مانند `amount` و `phone` داخل Workflow انجام می‌شود و نباید باعث پاسخ HTTP 400 شود.

### ۲۰.۲. اجرای Workflow

```http
POST /api/v1/loans/{loanId}/process
```

پردازش از مرحله فعلی آغاز می‌شود و تا رسیدن به یکی از وضعیت‌های `APPROVED`، `REJECTED` یا `MANUAL_REVIEW` ادامه پیدا می‌کند.

#### پاسخ

```http
HTTP/1.1 200 OK
```

```json
{
  "loanId": "L-10001",
  "status": "APPROVED",
  "currentStage": null
}
```

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

```json
{
  "loanId": "L-10001",
  "status": "MANUAL_REVIEW",
  "currentStage": null
}
```

اگر شناسه وجود نداشته باشد:

```http
HTTP/1.1 404 Not Found
```

```json
{
  "error": "LOAN_NOT_FOUND"
}
```

اگر درخواست قبلاً به وضعیت `APPROVED`، `REJECTED` یا `MANUAL_REVIEW` رسیده باشد، اجرای مجدد این Endpoint نباید Workflow را دوباره اجرا کند و باید وضعیت فعلی را برگرداند.

### ۲۰.۳. دریافت اطلاعات درخواست

```http
GET /api/v1/loans/{loanId}
```

#### پاسخ

```json
{
  "loanId": "L-10001",
  "customerId": "C-1001",
  "amount": 400000000,
  "phone": "09121234567",
  "loanType": "PERSONAL",
  "monthlyIncome": 50000000,
  "creditScore": 720,
  "hasGuarantor": false,
  "status": "APPROVED",
  "currentStage": null,
  "createdAt": "2026-07-15T10:00:00Z",
  "updatedAt": "2026-07-15T10:00:03Z"
}
```

اگر شناسه وجود نداشته باشد، پاسخ `404 Not Found` با کد `LOAN_NOT_FOUND` برگردانده می‌شود.

### ۲۰.۴. دریافت تاریخچه پردازش

```http
GET /api/v1/loans/{loanId}/history
```

#### پاسخ

```json
[
  {
    "stage": "VALIDATION",
    "result": "PASS",
    "timestamp": "2026-07-15T10:00:00Z",
    "reason": "SUCCESS"
  },
  {
    "stage": "FRAUD_CHECK",
    "result": "PASS",
    "timestamp": "2026-07-15T10:00:01Z",
    "reason": "SUCCESS"
  },
  {
    "stage": "CREDIT_CHECK",
    "result": "PASS",
    "timestamp": "2026-07-15T10:00:02Z",
    "reason": "SUCCESS"
  }
]
```

تاریخچه باید بر اساس زمان اجرا مرتب شود و هر Stage فقط یک بار ثبت شود.

### ۲۰.۵. Health Check

```http
GET /health
```

```http
HTTP/1.1 200 OK
```

```json
{
  "status": "UP"
}
```

## ۲۱. قالب زمان

تمام Timestampها باید مطابق استاندارد ISO 8601 و در منطقه زمانی UTC باشند:

```text
2026-07-15T10:00:00Z
```

## ۲۲. کدهای خطا

سامانه حداقل باید از کدهای زیر استفاده کند:

| کد | توضیح |
| --- | --- |
| `INVALID_REQUEST` | JSON نامعتبر است |
| `LOAN_NOT_FOUND` | شناسه درخواست وجود ندارد |
| `INVALID_AMOUNT` | مبلغ نامعتبر است |
| `INVALID_PHONE` | شماره موبایل نامعتبر است |
| `INVALID_CUSTOMER_ID` | شناسه مشتری نامعتبر است |
| `INVALID_LOAN_TYPE` | نوع وام نامعتبر است |
| `INVALID_CREDIT_SCORE` | امتیاز اعتباری نامعتبر است |
| `INVALID_MONTHLY_INCOME` | درآمد ماهانه نامعتبر است |

## ۲۳. توسعه‌پذیری Workflow

فرض کنید بانک در آینده تغییرات زیر را درخواست کند:

- اجرای `AML_CHECK` پس از `FRAUD_CHECK`؛
- افزودن `LEGAL_CHECK` برای تسهیلات `BUSINESS`؛
- اجرای `RISK_SCORE` پیش از `CREDIT_CHECK`؛
- افزودن نوع جدیدی از تسهیلات؛
- تعریف Workflowهای متفاوت برای بانک‌ها.

پیاده‌سازی این موارد در نسخه فعلی الزامی نیست، اما افزودن آن‌ها نباید به بازنویسی گسترده منطق اصلی سیستم نیاز داشته باشد.

## ۲۴. قرارداد Docker

پروژه باید فقط با دستورهای زیر قابل Build و اجرا باشد:

```bash
docker build -t bankflow .
docker run -p 8080:8080 bankflow
```

سرویس باید روی پورت `8080` در دسترس باشد و حداکثر ظرف ۶۰ ثانیه آماده پاسخ‌گویی شود.

## ۲۵. اقلام قابل تحویل

حداقل ساختار فایل‌های تحویلی باید به‌شکل زیر باشد:

```text
project/
├── src/
├── Dockerfile
├── README.md
├── DESIGN.md
├── ENGINEERING_DECISIONS.md
└── TESTING.md
```

در صورت نیاز می‌توانید فایل‌های تکمیلی دیگری نیز اضافه کنید.

### README.md

این فایل مهم‌ترین راهنمای داور برای اجرای پروژه است و باید شامل موارد زیر باشد:

- معرفی کوتاه راهکار؛
- پیش‌نیازها و وابستگی‌های اصلی؛
- روش Build؛
- روش اجرا؛
- روش اجرای تست‌ها؛
- معرفی کوتاه ساختار پروژه؛
- فهرست فناوری‌های اصلی.

### DESIGN.md

این فایل حداکثر سه صفحه است و باید حداقل موارد زیر را پوشش دهد:

1. معماری و اجزای اصلی سیستم؛
2. نحوه مدل‌سازی و اجرای Workflow؛
3. نحوه انتخاب مرحله بعد؛
4. تغییرات لازم برای افزودن یک Stage جدید؛
5. نحوه خواندن قوانین کسب‌وکار از فایل تنظیمات؛
6. نحوه ذخیره اطلاعات و مدیریت وضعیت‌ها؛
7. نحوه جلوگیری از پردازش تکراری؛
8. تغییرات لازم برای افزودن مرحله‌ای مانند `AML_CHECK`؛
9. مهم‌ترین تصمیم‌ها و Trade-offهای طراحی.

### ENGINEERING_DECISIONS.md

این فایل حداکثر دو صفحه است و باید حداقل به پرسش‌های زیر پاسخ دهد:

1. معماری کلی سیستم چیست و چرا انتخاب شده است؟
2. چه گزینه‌های دیگری وجود داشت و چرا انتخاب نشدند؟
3. Workflow چگونه مدل شده و افزودن یک مرحله چه بخش‌هایی را تغییر می‌دهد؟
4. قوانین کسب‌وکار چگونه از فایل تنظیمات خوانده می‌شوند؟
5. وضعیت فعلی چگونه مدیریت و از اجرای مجدد مراحل جلوگیری می‌شود؟
6. چه مکانیزمی برای ماندگاری اطلاعات انتخاب شده و چرا؟
7. سه تصمیم یا Trade-off مهم طراحی چه بوده‌اند؟
8. محدودیت اصلی راهکار چیست؟
9. اگر یک هفته زمان بیشتر داشتید، چه بخش‌هایی را بهبود می‌دادید؟
10. معماری فعلی چگونه از توسعه‌های آینده پشتیبانی می‌کند؟

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

### TESTING.md

این فایل حداکثر یک صفحه است و باید توضیح دهد:

- چه تست‌هایی نوشته شده‌اند؛
- چه بخش‌هایی Unit Test شده‌اند؛
- چه بخش‌هایی Integration Test شده‌اند؛
- چه بخش‌هایی به‌دلیل محدودیت زمان تست نشده‌اند.

## ۲۶. نکات پایانی

این چالش بیش از آنکه یک مسئله الگوریتمی باشد، یک مسئله مهندسی نرم‌افزار است و راه‌حل یا معماری واحدی ندارد.

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