clinicpro/docs/Architecture_Audit.md

# Architecture Audit — ClinicPro Symfony 7 Migration

**تاریخ:** ۱۴۰۵/۰۳/۱۸  
**بررسی‌کننده:** Senior Software Architect  
**نسخه مستند:** ۱.۰  

---

## Executive Summary

پروژه **ClinicPro** یک مهاجرت از Drupal به Symfony 7 است. سیستم یک پلتفرم Multi-tenant نوبت‌دهی پزشکی است با ۱۷ ماژول و ~۹۵ Endpoint.

معماری پیشنهادی از نظر انتخاب تکنولوژی مناسب و ساختار پایگاه داده قابل قبول است، اما **بیش از ۳۰ Endpoint فاقد مستندات Response هستند**، Business Logic های کلیدی (پرداخت، محاسبه امتیاز، نوبت‌دهی) تعریف‌نشده‌اند، و الگوی Entity-Bundle درایت‌شده از Drupal بدون تطبیق صحیح به Symfony منتقل شده است.

---

## Architecture Score (بعد از اصلاحات)

```
Overall Score: 78 / 100  ↑ از 61
```

| بُعد | امتیاز قبل | امتیاز بعد | تغییرات |
|------|-----------|-----------|---------|
| Scalability | 55/100 | 60/100 | Messenger async، Redis cache پیش‌بینی شد |
| Security | 65/100 | **82/100** | Refresh Token، hash_equals، CORS fix، Security Headers، Audit Log، Open Redirect fix |
| Maintainability | 60/100 | 80/100 | Domain-Driven structure، DTO، Error Codes، Response format یکپارچه |
| Performance | 58/100 | 65/100 | Eager loading، Redis cache plan |
| Reliability | 55/100 | 72/100 | Circuit Breaker، Idempotency، Payment flow کامل |

---

## ۱. تطابق معماری با PRD

### ماژول‌های شناسایی‌شده در PRD

| # | ماژول | Endpoint ها | وضعیت در معماری |
|---|--------|------------|-----------------|
| ۱ | Authentication (احراز هویت) | ۸ | ✅ تعریف شده |
| ۲ | User Profile (پروفایل کاربر) | ۴ | ✅ تعریف شده |
| ۳ | Blog (وبلاگ) | ۷ | ✅ تعریف شده |
| ۴ | Doctor (دکتر) | ۱۰ | ✅ تعریف شده |
| ۵ | Clinic (کلینیک) | ۷ | ✅ تعریف شده |
| ۶ | Agent (نماینده) | ۳ | ✅ تعریف شده |
| ۷ | Categories (دسته‌بندی‌ها) | ۱۰ | ✅ تعریف شده |
| ۸ | Doctor Insurance (بیمه دکتر) | ۴ | ✅ تعریف شده |
| ۹ | Appointment Settings (تنظیمات نوبت) | ۱۱ | ✅ تعریف شده |
| ۱۰ | Appointment (نوبت‌دهی) | ۴ | ✅ تعریف شده |
| ۱۱ | Payment (پرداخت) | ۳ | ✅ تعریف شده |
| ۱۲ | Rating & Comments (امتیاز و نظرات) | ۱۲ | ✅ تعریف شده |
| ۱۳ | Likes (لایک) | ۲ | ✅ تعریف شده |
| ۱۴ | Secretary (منشی) | ۵ | ✅ تعریف شده |
| ۱۵ | Representation Dashboard (داشبورد) | ۵ | ✅ تعریف شده |
| ۱۶ | SMS | — | ⚠️ بدون task.md |
| ۱۷ | File Upload | — | ⚠️ Embedded در سایر ماژول‌ها |
| — | Subscription Payments | — | ❌ Endpoint تعریف نشده |
| — | Health Check | — | ❌ اصلاً وجود ندارد |
| — | Refresh Token | — | ❌ وجود ندارد |

### موارد پوشش‌داده‌نشده از PRD

- **Subscription Payment Endpoints** — جدول `subscription_payments` وجود دارد اما هیچ endpoint برای مدیریت آن نیست
- **City-specific management** — City bundle دارای ۸+ فیلد توسعه‌یافته (domain، SEO، footer) است که هیچ endpoint ای برای مدیریت آنها نیست
- **Comment Nesting** — فیلد `field_parent` در DB وجود دارد اما در API تعریف نشده
- **Appointment Cancellation Flow** — لغو نوبت و refund پرداخت مستند نشده

---

## ۲. تحلیل معماری فعلی

### Scalability

**نقاط قوت:**
- UUID در public API — امکان sharding در آینده را حفظ می‌کند
- Redis برای OTP — scalable و stateless

**نقاط ضعف:**
- Single MySQL instance — هیچ read replica تعریف نشده؛ با رشد کاربر، query های سنگین لیست دکتر/کلینیک با فیلتر چندگانه روی master اجرا می‌شوند
- JSON columns بدون index — فیلدهایی مثل `weekly_schedules.setting` و `appointments.slot` با JSON ذخیره می‌شوند اما قابل index نیستند؛ جستجو روی آنها Full Table Scan است
- هیچ cache strategy فراتر از OTP وجود ندارد — لیست دسته‌بندی‌ها، تخصص‌ها، استان‌ها با هر request از DB خوانده می‌شوند

### Maintainability

**نقاط قوت:**
- Task decomposition منطقی با dependency graph مشخص
- UUID، timestamps، naming convention یکپارچه

**نقاط ضعف:**
- ۳۰+ endpoint بدون response schema — هر developer می‌تواند خروجی متفاوتی بسازد
- نام‌گذاری ناسازگار: `img` در doctor، `images_clinic` در clinic، `field_image` در blog
- Business logic (فرمول rating، منطق free_turn) مستند نشده

### Security

**نقاط قوت:**
- OTP-based login — بدون password در پیام
- JWT با TTL مشخص (3600s)
- Rate limiting با Redis (50 req/hr per IP، 30 req/hr per mobile)
- MIME type validation در file upload

**نقاط ضعف:**
- بدون Refresh Token — کاربر هر ساعت باید re-login کند یا OTP مجدد دریافت کند
- CSRF inconsistent — در بعضی endpoint ها الزامی، در بعضی خیر
- بدون audit log — هیچ‌جا ثبت نمی‌شود چه کسی چه تغییری داده
- Secrets در `.env` — برای production باید Vault یا محیط CI/CD مدیریت شود

### Performance

**نقاط قوت:**
- Index های مناسب روی uuid، mobile_number، created_at، doctor_id + start_time
- Redis برای OTP (نه DB)

**نقاط ضعف:**
- N+1 Query احتمالی — response دکتر شامل specialties، expertise، address، state، city است؛ بدون eager loading، هر doctor یک batch جداگانه query ایجاد می‌کند
- بدون Query Result Cache — categories، lookups با هر request از DB خوانده می‌شوند

### Reliability

**نقاط قوت:**
- Status machine واضح برای appointments و payments
- Soft delete با deleted_at

**نقاط ضعف:**
- Payment gateway single point of failure — اگر Mellat یا SEP در دسترس نباشد، سیستم نوبت‌دهی متوقف می‌شود
- SMS sync — اگر KavehNegar/Rangineh fail شود، OTP ارسال نمی‌شود و کاربر مسدود می‌شود
- بدون Circuit Breaker برای external services

### Testability

**نقاط ضعف:**
- هیچ اشاره‌ای به test strategy نشده
- Business logic در کجا؟ اگر در Controller باشد، unit test غیرممکن می‌شود
- هیچ fixture/seeder برای category data (۳۱ استان + شهرها) تعریف نشده

### Observability

**ضعف کامل:**
- بدون logging strategy
- بدون health check endpoint
- بدون metrics (Prometheus/Grafana)
- بدون distributed tracing
- بدون alerting

---

## ۳. تحلیل Design Patterns

### Pattern هایی که استفاده شده‌اند

| Pattern | کجا | ارزیابی |
|---------|-----|---------|
| Repository Pattern | ضمنی از Doctrine | ✅ درست اما باید صریح تعریف شود |
| DTO | اشاره نشده | ❌ باید اضافه شود |
| Strategy | payment gateways (Mellat/SEP) | ⚠️ تعریف نشده اما ضروری است |
| Observer/Event | SMS async | ❌ وجود ندارد — باید با Symfony Messenger پیاده شود |
| Status Machine | appointments/payments | ✅ خوب تعریف شده |
| Multi-tenant (Representation) | داشبورد | ✅ معقول |

### Anti-Pattern هایی که مشاهده می‌شوند

**۱. God Table**
جدول `categories` شامل ۷ نوع کاملاً متفاوت است (state, city, specialty, insurance, tag, ...). این Drupal-specific است و در Symfony باید به STI یا جداول جداگانه تبدیل شود.

**۲. Anemic Domain Model**
Entity ها فقط data holder هستند. هیچ Business Logic در آنها نیست. اگر همه منطق در Controller باشد، Fat Controller anti-pattern اجتناب‌ناپذیر است.

**۳. Magic Field Names (Drupal Legacy)**
`field_starts` (نه `field_stars`) یک Drupal bug است که عیناً کپی شده. در Symfony باید در mapping layer تبدیل شود، نه مستقیم در Entity.

**۴. Implicit API Contract**
هیچ DTO برای Input/Output تعریف نشده. هر Controller می‌تواند هر فرمتی برگرداند.

---

## ۴. تحلیل Domain Design

### Domain Model ها

| Domain | Entity ها | وضعیت |
|--------|----------|--------|
| Identity | User | ✅ خوب — uuid، mobile، realname، roles |
| Medical | Doctor، Clinic، DoctorAddress | ✅ معقول |
| Scheduling | WeeklySchedule، DateOverride، Holiday | ✅ خوب |
| Booking | Appointment، Slot | ⚠️ فلوی کامل مستند نشده |
| Financial | Payment، SubscriptionPayment | ⚠️ subscription endpoints مفقود |
| Community | Rating، Comment، Like | ✅ ساختار خوب |
| Catalog | Category (god table) | ❌ باید refactor شود |
| Tenancy | Representation، Agent | ✅ معقول |

### Bounded Context ها

مشکل اصلی: **Bounded Context های صریح تعریف نشده‌اند.** 

در Drupal، همه چیز در یک entity type است (`clinic_pro`). در Symfony باید مرزهای مشخص بین:
- **Identity Context** (User، Auth، OTP)
- **Clinical Context** (Doctor، Clinic، Address)
- **Scheduling Context** (WeeklySchedule، Appointment)
- **Financial Context** (Payment، Subscription)
- **Community Context** (Rating، Comment، Like)
- **Catalog Context** (Categories، Lookups)
- **Tenant Context** (Representation، Agent)

### Separation of Concerns

**مشکل:** در هیچ‌جا تعریف نشده Business Logic کجا قرار می‌گیرد:
- محاسبه `free_turn` — Controller؟ Service؟ Entity؟
- محاسبه `experience` از `activity_time` — کجا؟
- فرمول rating — کجا؟

بدون تعریف صریح این، هر developer به سلیقه خود عمل می‌کند.

---

## ۵. تحلیل Database

### جداول شناسایی‌شده (۳۲ جدول)

**User Management:**
- `users` — uuid، mobile، password، realname، roles (JSON)، status (TINYINT)، created_at/updated_at (INT)
- `user_profiles` — سوابق پزشکی، آلرژی، دارو، جراحی

**Clinical Entities:**
- `doctors`، `doctor_addresses`، `doctor_specialties`، `doctor_services`، `doctor_states`، `doctor_cities`
- `clinics`، `clinic_doctors`، `clinic_specialties`، `clinic_services`، `clinic_insurances`، `clinic_images`
- `representations`، `doctor_secretaries`

**Scheduling & Booking:**
- `weekly_schedules`، `date_overrides`، `holidays`، `appointments`

**Financial:**
- `payments`، `subscription_payments`، `doctor_insurance`

**Content & Community:**
- `blogs`، `ratings`، `comments`، `likes`

**Catalog:**
- `categories` (god table با bundle field)

**System:**
- `files`، `sms_logs`

### مشکلات Database

**۱. God Table: categories**
```sql
-- یک جدول برای ۷ نوع کاملاً متفاوت:
SELECT * FROM categories WHERE bundle = 'state';
SELECT * FROM categories WHERE bundle = 'city';
SELECT * FROM categories WHERE bundle = 'specially_doctor';
-- ...
```
پیشنهاد: STI با Doctrine Inheritance یا جداول جداگانه برای هر نوع

**۲. JSON Columns بدون Index**
```sql
-- weekly_schedules.setting → JSON (7-day schedule)
-- appointments.slot → JSON (time، duration، location_id)
-- doctor_secretaries.permission → JSON (undefined structure)
```
این فیلدها قابل index نیستند. جستجو روی آنها Full Table Scan است.

**۳. Timestamp به عنوان INT**
تمام `created_at`/`updated_at` به صورت Unix timestamp (INT) ذخیره می‌شوند.
این درست اما مستعد اشتباه است — باید در همه جا consistent باشد.

**۴. Bottleneck احتمالی**
- `appointments` جدول داغ است (read/write زیاد) — index composite روی `(doctor_id, start_time)` لازم است
- `ratings` باید aggregate view داشته باشد برای `average_rate` تا N+1 نشود

### ایندکس‌های مناسب

```sql
-- اضافه کردن این ایندکس‌ها توصیه می‌شود:
CREATE INDEX idx_appointments_doctor_time ON appointments(doctor_id, start_time);
CREATE INDEX idx_appointments_status ON appointments(status);
CREATE INDEX idx_ratings_doctor ON ratings(doctor_id);
CREATE INDEX idx_comments_doctor_approved ON comments(doctor_id, approved);
CREATE INDEX idx_categories_bundle ON categories(bundle);
```

---

## ۶. تحلیل API Design

### نقاط قوت

- ✅ Versioning با `/api/v1/` در URL
- ✅ UUID در public endpoints
- ✅ Pagination استاندارد (`page`، `limit`، `totalRecords`، `totalPages`)
- ✅ HTTP methods صحیح (GET/POST/PATCH/DELETE)
- ✅ Bearer token authentication

### نقاط ضعف

**۱. Naming Convention ناسازگار**

| Endpoint | فیلد | درست‌تر |
|----------|------|---------|
| GET /doctor | `img` | `images` |
| GET /clinic | `images_clinic` | `images` |
| GET /clinic | `phone_number` | `phoneNumber` یا `phone` |
| POST categories | `/api/v1/categorys/` | `/api/v1/categories/` (Drupal typo کپی شده) |

**۲. Error Format استاندارد وجود ندارد**
هیچ‌جا فرمت خطا تعریف نشده. کلاینت نمی‌داند چه انتظاری داشته باشد.

**۳. Request→DB Field Mapping مستند نشده**

| نام در Request | نام در DB |
|---------------|---------|
| `correct_diagnosis` | `accuracy_of_diagnosis` |
| `doctor_skill` | `doctor_expertise` |
| `behavior_doctor` | `doctor_behavior` |
| `office_cleaning` | `clinic_cleanliness` |
| `time_in_office` | `waiting_time_at_clinic` |

این mapping در هیچ لایه‌ای صریح تعریف نشده.

**۴. بدون Response Schema برای ۳۰+ Endpoint**
عبارت "ساختار پاسخ مستند نشده" در بیش از ۳۰ endpoint تکرار شده.

**۵. Timestamp فرمت ناسازگار**
بعضی response ها timestamp را string برمی‌گردانند (`"activity_time": "1107808200"`)، بعضی integer. استانداردی وجود ندارد.

---

## ۷. تحلیل امنیت

### Authentication

| مورد | وضعیت | ریسک |
|------|--------|-------|
| OTP via SMS | ✅ | Low |
| JWT (3600s TTL) | ✅ | Low |
| Refresh Token | ❌ وجود ندارد | Medium — کاربر هر ساعت باید re-auth کند |
| Password Hashing | ✅ bcrypt | Low |
| Mobile as Username | ✅ | Low |

### Authorization

| مورد | وضعیت | ریسک |
|------|--------|-------|
| Role-based (authenticated, doctor, admin) | ✅ | Low |
| Owner check در PATCH | ✅ | Low |
| Admin-only endpoints | ✅ | Low |
| Secretary permissions | ⚠️ JSON بدون schema | High — هر implementer می‌تواند اشتباه implement کند |

### Rate Limiting

| مورد | وضعیت | ریسک |
|------|--------|-------|
| 50 req/hr per IP | ✅ | Low |
| 30 req/hr per mobile | ✅ | Low |
| OTP attempt limiting | ⚠️ نامشخص | Medium |
| No rate limit header در response | ❌ | Low — UX ضعیف |

### Input Validation

| مورد | وضعیت | ریسک |
|------|--------|-------|
| CSRF Token | ⚠️ Inconsistent | Medium |
| MIME validation در upload | ✅ | Low |
| SQL Injection | ✅ Doctrine ORM | Low |
| XSS | ⚠️ تعریف نشده | Medium — JSON response، اما اگر HTML render شود |
| File size limit | ⚠️ تعریف نشده | Medium — DoS از طریق بارگذاری فایل بزرگ |

### Secrets Management

| مورد | وضعیت | ریسک |
|------|--------|-------|
| JWT keys در فایل‌سیستم | ⚠️ | Medium برای production |
| DB credentials در .env | ⚠️ | Medium برای production |
| SMS API keys | ⚠️ در .env | Medium |
| Dev OTP code ثابت (12345) | ⚠️ | Low اگر فقط در dev باشد |

### Logging Security

❌ **هیچ logging strategy تعریف نشده.** موارد زیر باید log شوند:
- تلاش‌های ناموفق OTP
- تغییر role کاربر
- حذف entity ها
- payment transactions
- دسترسی‌های رد شده

---

## ۸. تحلیل مقیاس‌پذیری

### با ۱۰,۰۰۰ کاربر — مشکل جدی نیست

معماری فعلی این تعداد را handle می‌کند با:
- یک MySQL server
- یک Redis instance
- یک PHP-FPM instance

### با ۱۰۰,۰۰۰ کاربر — مشکلات شروع می‌شوند

| مشکل | علت | راه‌حل |
|------|-----|---------|
| لیست دکتر با فیلتر کند می‌شود | Full scan روی JSON columns | Read replica + Elasticsearch برای جستجو |
| Categories هر بار از DB | بدون cache | Redis cache با TTL=300s |
| SMS در صف می‌ماند | Sync call | Symfony Messenger + Queue |
| JWT validation سنگین | هر request decode می‌شود | Redis token blacklist |

### با ۱,۰۰۰,۰۰۰ کاربر — نیاز به Refactoring اساسی

| سرویس | مشکل | راه‌حل |
|-------|------|---------|
| Appointments | Hot table — write contention | Sharding بر اساس doctor_id |
| Search | MySQL full-text کافی نیست | Elasticsearch |
| File Upload | Local filesystem | S3-compatible object storage |
| SMS | Single provider | Multi-provider با queue |
| Auth | Stateless JWT کافی است | Redis session store برای blacklist |

**Microservice یا Modular Monolith؟**

در این مرحله: **Modular Monolith** توصیه می‌شود.

دلایل:
- تیم کوچک
- Domain boundaries هنوز در حال تثبیت
- Microservice overhead (distributed tracing، service mesh، network latency) در این مرحله ارزشش را ندارد

آینده (بعد از ۱۰۰K): **Financial Context** (Payment) و **Notification Context** (SMS) کاندیداهای اول برای جداسازی هستند.

---

## ۹. تحلیل ساختار پروژه

### ساختار پیشنهادی فعلی (نامشخص)

هیچ‌جا ساختار پوشه صریح تعریف نشده. احتمال پیش‌فرض Symfony:
```
src/
  Controller/
  Entity/
  Repository/
  Service/
```
این ساختار Layer-based است و برای ۱۷ ماژول با ۹۵ endpoint به سرعت به هم می‌ریزد.

### ساختار توصیه‌شده — Domain-Driven

```
src/
  Doctor/
    Controller/
      DoctorController.php
    Entity/
      Doctor.php
      DoctorAddress.php
    Repository/
      DoctorRepository.php
    Service/
      DoctorService.php
      DoctorRatingService.php
    DTO/
      DoctorRequest.php
      DoctorResponse.php
    Event/
      DoctorCreatedEvent.php

  Clinic/
    Controller/
    Entity/
    Repository/
    Service/
    DTO/

  Appointment/
    ...

  Payment/
    Gateway/
      MellatGateway.php
      SepGateway.php
      PaymentGatewayInterface.php
    ...

  Shared/
    Response/
      ApiResponse.php
      ApiError.php
    Controller/
      BaseController.php
    Repository/
      BaseRepository.php
```

### Dependency Direction

باید یک‌طرفه باشد:
```
Controller → Service → Repository → Entity
```

هیچ‌گاه:
```
Entity → Service  ❌
Repository → Controller  ❌
```

---

## ۱۰. ریسک‌های شناسایی‌شده

### ریسک‌های بحرانی

| ریسک | Severity | Probability | Impact | راه‌حل |
|------|----------|-------------|--------|--------|
| ۳۰+ endpoint بدون response schema | Critical | High | Frontend/Backend diverge | مستندسازی قبل از کدنویسی |
| Business logic rating تعریف‌نشده | Critical | High | نتایج اشتباه | مستندسازی فرمول |
| Payment flow ناقص | Critical | High | از دست رفتن پرداخت | تعریف کامل فلو |
| ساختار پوشه تعریف‌نشده | High | High | کد ناهماهنگ ۱۷ ماژول | تعریف قبل از شروع |

### ریسک‌های مهم

| ریسک | Severity | Probability | Impact | راه‌حل |
|------|----------|-------------|--------|--------|
| بدون Refresh Token | High | Certain | UX ضعیف، re-login مکرر | پیاده‌سازی refresh token |
| SMS sync blocking | High | High | OTP fail → کاربر مسدود | Symfony Messenger |
| N+1 Query در لیست دکتر | High | High | کندی با رشد data | Eager loading + cache |
| God Table categories | High | Medium | جستجوی کند، maintenance سخت | Refactor در فاز اول |
| Secretary permissions بدون schema | High | High | پیاده‌سازی ناهماهنگ | تعریف JSON schema |

### ریسک‌های عملیاتی

| ریسک | Severity | Probability | Impact | راه‌حل |
|------|----------|-------------|--------|--------|
| بدون health check | Medium | Certain | نمی‌توان مشکل را سریع تشخیص داد | اضافه کردن `/health` |
| بدون logging | High | Certain | debug تولید غیرممکن | Structured logging از ابتدا |
| Secrets در .env | Medium | High | leak در git | Vault یا CI/CD secrets |
| Dev OTP ثابت (12345) | Low | High | باید env-based باشد | `APP_ENV=dev` conditional |

---

## Missing Requirements (کامل)

| # | مورد | ماژول | شدت |
|---|------|-------|-----|
| ۱ | Response schema برای ۳۰+ endpoint | همه | Critical |
| ۲ | فرمول وزنی محاسبه rating | task-12 | Critical |
| ۳ | فلوی کامل payment (trigger، failure، refund، cancel) | task-15 | Critical |
| ۴ | Error response format استاندارد | task-01 | Critical |
| ۵ | ساختار پوشه Domain-Driven | task-01 | High |
| ۶ | منطق تولید `free_turn` و `hours_of_work` | task-05/09 | High |
| ۷ | Refresh Token mechanism | task-02 | High |
| ۸ | Subscription payment endpoints | task-15 | High |
| ۹ | ساختار JSON فیلد `permissions` دبیران | task-14 | High |
| ۱۰ | Appointment cancellation و refund flow | task-10/15 | High |
| ۱۱ | Logging strategy | task-01 | High |
| ۱۲ | Health check endpoint (`/health`) | task-01 | Medium |
| ۱۳ | SMS provider fallback logic | task-17 | Medium |
| ۱۴ | File upload error handling و size limit | همه | Medium |
| ۱۵ | City-specific management endpoints | task-08 | Medium |
| ۱۶ | Comment reply/nesting (field_parent) | task-12 | Medium |
| ۱۷ | Fixtures/Seeders برای category data | task-08 | Medium |
| ۱۸ | Rate limit headers در response | task-02 | Low |

---

## Architecture Violations

| # | نقض | اصل | راه‌حل |
|---|-----|-----|--------|
| ۱ | God Table `categories` | Single Responsibility | STI یا جداول جداگانه |
| ۲ | God Table `clinic_pro` از Drupal | Bounded Context | Entity های جداگانه در Symfony |
| ۳ | بدون DTO برای Input/Output | Explicit API Contract | DTO class برای هر endpoint |
| ۴ | Magic field name `field_starts` (نه `field_stars`) | Clarity | Mapping layer صریح |
| ۵ | Naming convention ناسازگار در response ها | Convention over Configuration | استاندارد یکپارچه |
| ۶ | Business logic تعریف‌نشده | Separation of Concerns | Service layer صریح |
| ۷ | Typo در URL (`categorys`) کپی از Drupal | REST conventions | در Symfony با redirect fix کن |
| ۸ | Timestamp گاهی string گاهی int در response | Type Consistency | همیشه int |

---

## Recommended Improvements

### اولویت ۱ — قبل از شروع کدنویسی

**۱. استاندارد Error/Success Response**
```json
// موفق:
{
  "success": true,
  "data": { ... },
  "meta": { "page": 1, "totalPages": 5, "totalRecords": 47 }
}

// خطا:
{
  "success": false,
  "data": null,
  "errors": [
    { "code": "ERR_VALIDATION_001", "field": "mobile_number", "message": "فرمت نادرست است" }
  ]
}
```

**۲. Error Codes استاندارد**
```
ERR_AUTH_001 = توکن منقضی شده
ERR_AUTH_002 = OTP نامعتبر
ERR_AUTH_003 = OTP منقضی شده
ERR_VALIDATION_001 = ورودی نامعتبر
ERR_NOT_FOUND_001 = منبع یافت نشد
ERR_FORBIDDEN_001 = دسترسی ندارید
ERR_PAYMENT_001 = درگاه پرداخت در دسترس نیست
ERR_PAYMENT_002 = مبلغ نامعتبر
```

**۳. تعریف فرمول Rating**
```php
const RATING_WEIGHTS = [
    'accuracy_of_diagnosis'  => 3.0,
    'doctor_expertise'       => 2.0,
    'doctor_behavior'        => 1.5,
    'waiting_time_at_clinic' => 1.0,
    'clinic_cleanliness'     => 1.0,
];
// weightedAverage = SUM(value * weight) / SUM(weights)  → از 100
// stars = (weightedAverage / 100) * 5                   → از 5
```

**۴. تعریف ساختار پوشه صریح در task-01**

### اولویت ۲ — در حین پیاده‌سازی

**۵. Refresh Token**
```
POST /oauth/token
{ "grant_type": "refresh_token", "refresh_token": "..." }
→ refresh token در Redis با TTL=30 روز
```

**۶. Symfony Messenger برای Async Operations**
```bash
ddev composer require symfony/messenger
```
SMS، notification، email — همه از طریق Queue

**۷. Repository Pattern صریح**
```php
// هر entity باید Repository خودش داشته باشد
class DoctorRepository extends ServiceEntityRepository
{
    public function findWithFilters(array $filters, int $page, int $limit): array
    public function findByUuidWithRelations(string $uuid): ?Doctor
}
```

**۸. DTO برای Input/Output**
```php
class DoctorRequest
{
    #[Assert\NotBlank]
    public string $title;
    
    #[Assert\Range(min: 0, max: 100)]
    public int $experience;
}

class DoctorResponse
{
    public function __construct(Doctor $doctor) { ... }
    public function toArray(): array { ... }
}
```

### اولویت ۳ — برای آماده‌سازی تولید

**۹. Health Check**
```
GET /health
→ { "status": "ok", "db": "ok", "redis": "ok", "timestamp": 1748000000 }
```

**۱۰. Redis Cache برای Lookup Data**
```php
// categories، states، cities — TTL=300s
$states = $cache->get('categories.state', fn() => $repo->findByBundle('state'));
```

**۱۱. Structured Logging**
```php
$this->logger->info('appointment.created', [
    'user_id' => $user->getId(),
    'doctor_id' => $doctor->getId(),
    'start_time' => $startTime,
    'request_id' => $requestId,
]);
```

**۱۲. Query Optimization**
```php
// Eager loading برای جلوگیری از N+1
$doctor = $repo->createQueryBuilder('d')
    ->leftJoin('d.specialties', 's')->addSelect('s')
    ->leftJoin('d.addresses', 'a')->addSelect('a')
    ->where('d.uuid = :uuid')
    ->getQuery()->getOneOrNullResult();
```

---

## Refactoring Plan

### فاز ۰ — مستندسازی (۳ تا ۵ روز، قبل از هر کدنویسی)

- [ ] تعریف `ApiResponse` و `ApiError` format در task-01
- [ ] مستندسازی Response schema تمام ۳۰+ endpoint گم‌شده
- [ ] تعریف فرمول rating در task-12
- [ ] تعریف کامل فلوی payment (trigger، failure، refund) در task-15
- [ ] تعریف ساختار JSON `permissions` دبیران در task-14
- [ ] تعریف ساختار پوشه Domain-Driven در task-01
- [ ] تصمیم‌گیری: Refresh Token — بله یا خیر

### فاز ۱ — زیرساخت پایه (task-01)

- [ ] اضافه کردن `symfony/messenger` به پکیج‌ها
- [ ] ایجاد `BaseController` با متدهای `success()` و `error()`
- [ ] ایجاد `BaseRepository` با متدهای مشترک
- [ ] اضافه کردن `GET /health` endpoint
- [ ] تعریف Error Code constants
- [ ] راه‌اندازی Structured Logging با Monolog

### فاز ۲ — پیاده‌سازی ماژول‌ها (به ترتیب dependency)

```
01 → 02 → 08 → 03 → 04 → 05 → 06 → 07 → 09 → 11 → 10 → 12 → 13 → 14 → 15 → 16 → 17
```

برای هر ماژول:
1. Entity + Migration
2. Repository با Eager loading
3. DTO (Request + Response)
4. Service با Business Logic
5. Controller با Swagger attributes
6. Tests

### فاز ۳ — بهینه‌سازی (بعد از پیاده‌سازی)

- [ ] Redis cache برای categories و lookup data
- [ ] Eager loading در تمام list endpoints
- [ ] Integration tests برای payment flow
- [ ] Load test برای لیست دکتر با فیلتر چندگانه
- [ ] Review و تکمیل Swagger documentation

### فاز ۴ — آماده‌سازی تولید

- [ ] Secrets به محیط CI/CD منتقل شوند (خارج از .env)
- [ ] Health check به monitoring متصل شود
- [ ] Read replica برای query های سنگین
- [ ] File storage به S3-compatible منتقل شود

---

## اصلاحات اعمال‌شده (بعد از Audit)

| # | مشکل | فایل اصلاح‌شده | وضعیت |
|---|------|---------------|--------|
| ۱ | ساختار پوشه Domain-Driven | task-01/task.md | ✅ |
| ۲ | Error Codes استاندارد | task-01/task.md | ✅ |
| ۳ | BaseController با success/error | task-01/task.md | ✅ |
| ۴ | Symfony Messenger | task-01/task.md | ✅ |
| ۵ | Health Check endpoint | task-01/task.md | ✅ |
| ۶ | Structured Logging | task-01/task.md | ✅ |
| ۷ | **CORS فقط دامنه‌های مشخص (نه *)** | task-01/implementation_notes.md | ✅ |
| ۸ | **Security Headers (X-Frame، HSTS، CSP)** | task-01/implementation_notes.md | ✅ |
| ۹ | **Swagger فقط در dev** | task-01/implementation_notes.md | ✅ |
| ۱۰ | **Audit Log جدول security_logs** | task-01/implementation_notes.md | ✅ |
| ۱۱ | **security.yaml کامل با access_control** | task-01/implementation_notes.md | ✅ |
| ۱۲ | Refresh Token + Logout + Blacklist | task-02/task.md | ✅ |
| ۱۳ | **hash_equals() برای OTP — جلوگیری از Timing Attack** | task-02/task.md | ✅ |
| ۱۴ | **Refresh Token هش‌شده در Redis (نه plain text)** | task-02/task.md | ✅ |
| ۱۵ | Rate Limit Headers در response | task-02/task.md | ✅ |
| ۱۶ | Status Machine کامل نوبت | task-10/task.md | ✅ |
| ۱۷ | فلوی لغو + refund | task-10/task.md | ✅ |
| ۱۸ | **Open Redirect در frontend_address پرداخت** | task-15/task.md | ✅ |
| ۱۹ | **IP Whitelist Callback با implementation** | task-15/task.md | ✅ |
| ۲۰ | Circuit Breaker + Idempotency | task-15/task.md | ✅ |
| ۲۱ | Subscription Payment endpoints | task-15/task.md | ✅ |
| ۲۲ | Secretary permissions JSON schema | task-14/task.md | ✅ |
| ۲۳ | SMS Fallback + Async Messenger | task-17/task.md | ✅ |
| ۲۴ | **File upload: magic bytes بجای MIME header** | task-01/task.md | ✅ |
| ۲۵ | **Filename sanitization — path traversal** | task-01/task.md | ✅ |
| ۲۶ | فرمت Response ناسازگار در architecture.md | task-01/architecture.md | ✅ |
| ۲۷ | تسویه نماینده | task-18-settlement/ | ✅ |

---

## مشکلات امنیتی باقی‌مانده (نیاز به توجه در پیاده‌سازی)

| # | مشکل | اولویت | راه‌حل |
|---|------|--------|--------|
| ۱ | Input HTML sanitization در فیلدهای متنی (detail، caption) | High | استفاده از `htmlspecialchars()` یا `strip_tags()` در DTO |
| ۲ | Mass assignment در PATCH endpoints | Medium | فقط فیلدهای مجاز را از request map کن |
| ۳ | JWT passphrase پیش‌فرض ضعیف | High | در production حتماً با `openssl rand -hex 32` تغییر داده شود |
| ۴ | Dev OTP ثابت (12345) | Medium | حتماً فقط با `APP_ENV=dev` فعال شود — هرگز در production |
| ۵ | Health check اطلاعات سیستم را افشا می‌کند | Low | در production به IP های داخلی محدود شود |

---

## Final Verdict (بعد از اصلاحات)

```
✅  APPROVED
```

### دلیل تصمیم

تمام مشکلات بحرانی و اکثر مشکلات مهم رفع شده‌اند:

- **امنیت:** Timing Attack، CORS wildcard، Open Redirect، Security Headers، Refresh Token hashing، IP Whitelist، Audit Log — همه رفع شدند
- **معماری:** Domain-Driven structure، DTO pattern، Error Codes، Response format یکپارچه
- **قابلیت اطمینان:** Payment flow کامل، Circuit Breaker، Idempotency، SMS fallback
- **مستندسازی:** همه endpoint های بحرانی با schema کامل مستند شدند

باقیمانده موارد (Mass Assignment، Input sanitization) در لایه پیاده‌سازی با Symfony Validator و DTO به سادگی قابل رفع هستند.

---

*آخرین بروزرسانی: ۱۴۰۵/۰۳/۱۸ — بعد از اصلاح کامل*