# معماری — تسک ۰۱: راه‌اندازی پروژه

## ساختار پوشه‌های پروژه
```
clinic-pro-symfony/
├── .ddev/
│   ├── config.yaml
│   └── docker-compose.redis.yaml
├── config/
│   ├── packages/
│   │   ├── doctrine.yaml
│   │   ├── lexik_jwt_authentication.yaml
│   │   ├── nelmio_cors.yaml
│   │   ├── framework.yaml
│   │   ├── cache.yaml
│   │   └── security.yaml
│   ├── routes/
│   │   └── api.yaml
│   └── services.yaml
├── src/
│   ├── Module/
│   │   ├── Auth/
│   │   ├── UserProfile/
│   │   ├── Blog/
│   │   ├── Doctor/
│   │   ├── Clinic/
│   │   ├── Agent/
│   │   ├── Category/
│   │   ├── AppointmentSettings/
│   │   ├── Appointment/
│   │   ├── Insurance/
│   │   ├── Rating/
│   │   ├── Comment/
│   │   ├── Like/
│   │   ├── Secretary/
│   │   ├── Payment/
│   │   └── Representation/
│   └── Shared/
│       ├── Response/
│       │   └── ApiResponse.php
│       ├── Exception/
│       │   ├── ValidationException.php
│       │   └── NotFoundException.php
│       ├── Trait/
│       │   └── TimestampableTrait.php
│       └── EventSubscriber/
│           └── ExceptionSubscriber.php
├── migrations/
├── tests/
├── public/
│   └── index.php
└── .env
```

## ساختار داخلی هر ماژول
```
src/Module/{ModuleName}/
├── Controller/
│   └── {Name}Controller.php      ← دریافت request، فراخوانی service، بازگشت response
├── Service/
│   └── {Name}Service.php         ← منطق تجاری
├── Repository/
│   └── {Name}Repository.php      ← کوئری‌های پایگاه داده
├── Entity/
│   └── {Name}.php                ← Doctrine ORM mapping
├── DTO/
│   ├── Request/
│   │   └── Create{Name}Request.php   ← validation ورودی
│   └── Response/
│       └── {Name}Response.php        ← شکل‌دهی خروجی JSON
└── Voter/
    └── {Name}Voter.php           ← بررسی مجوزها
```

## مسئولیت هر لایه

| لایه | مسئولیت |
|------|---------|
| Controller | دریافت HTTP، اعتبارسنجی DTO، فراخوانی Service، بازگشت ApiResponse |
| Service | منطق تجاری، فراخوانی Repository، dispatch Event |
| Repository | تمام کوئری‌های Doctrine، بدون منطق تجاری |
| Entity | تعریف ساختار جداول با ORM Attribute |
| DTO | اعتبارسنجی ورودی و شکل‌دهی خروجی |
| Voter | بررسی اینکه چه کسی به چه چیزی دسترسی دارد |

## فرمت استاندارد پاسخ (ApiResponse)

> **⚠ فرمت رسمی از task.md است — این فایل با آن sync شده.**

### موفق (بدون صفحه‌بندی)
```json
{
  "success": true,
  "data": { "..." }
}
```

### موفق (با صفحه‌بندی)
```json
{
  "success": true,
  "data": [ "..." ],
  "meta": {
    "totalRecords": 47,
    "totalPages": 5,
    "currentPage": 1
  }
}
```

### خطا
```json
{
  "success": false,
  "data": null,
  "errors": [
    {
      "code": "ERR_VALIDATION_001",
      "field": "mobile_number",
      "message": "فرمت شماره موبایل نادرست است"
    }
  ]
}
```

## نمودار ارتباط لایه‌ها
```
HTTP Request
     │
     ▼
┌─────────────┐
│ Controller  │  ← Route, DTO bind, Validate
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Service   │  ← Business logic, Events
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Repository  │  ← Doctrine queries
└──────┬──────┘
       │
       ▼
┌─────────────┐
│   Entity    │  ← Database row
└─────────────┘
```