# 🏢 سیستم مدیریت ساختمان — پروپوزال اولیه و سوالات کلیدی

> نسخه PHP: 8.3 | معماری: Pure PHP (بدون فریم‌ورک سنگین) | الگو: MVC + PSR + REST API
> پایگاه داده: Single DB / Single Schema (MySQL 8 / MariaDB 11) | کش: Redis + OPcache
> وب‌سرور: LiteSpeed | ذخیره‌سازی: محلی با تفکیک ساختمان/کاربر

---

## ۱. ساختار پیشنهادی پروژه (Draft Architecture)

```
Building_Management/
├── public/                  # Entry point / index.php (REST)
├── config/                  # Config (DB, Redis, JWT, File Storage)
├── src/
│   ├── Core/                # Kernel, Router, Request, Response, Middleware
│   ├── Http/                # Controllers (REST only)
│   ├── Services/            # Business logic (Buildings, Users, Costs, Tickets)
│   ├── Repositories/        # Data access layer (PSR style, abstracted)
│   ├── Models/              # Entities (User, Building, Block, Floor, Unit, Cost, Ticket)
│   ├── Middleware/          # Auth (JWT), RateLimit, CORS, Cache
│   ├── Utilities/           # Helper, Validator, ImageProcessor
│   └── Exceptions/          # Custom exception handler
├── database/
│   ├── migrations/          # Schema version control (manual or custom)
│   └── seeds/               # Default data
├── storage/
│   ├── buildings/{id}/      # Per-building storage (receipts, docs, images)
│   └── users/{id}/          # Per-user storage
├── tests/
├── docs/
│   └── proposal.md          # ریز جزئیات (این فایل)
└── composer.json
```

### نکات کلیدی معماری:
- **بدون Laravel / Symfony**: یک هسته سبک خودنویس با Router و DI ساده.
- **PSR-4 Autoload + PSR-7 Request/Response**: استاندارد و قابل فروش.
- **JWT (HS256)**: توکن در Header (`Authorization: Bearer`)، Refresh Token در Redis.
- **Redis**: Session cache, Rate limit, Queue برای اعلانات ایمیل.
- **LiteSpeed**: استفاده از `.htaccess` با Rewrite برای REST.
- **MVC واقعی**: Controller → Service → Repository → Model.

---

## ۲. دیتابیس پیشنهادی (Single Schema — بهینه)

### جداول اصلی (با ایندکس دقیق):

| جدول | توضیح | کلید خارجی |
|---|---|---|
| `users` | اطلاعات پایه + `role_global` (admin / super_admin) | — |
| `buildings` | ساختمان (نام، آدرس، تنظیمات سلسله مراتب) | `created_by` |
| `building_members` | عضویت + نقش در ساختمان (`manager`, `resident`, `tenant`, `accountant`) | `user_id`, `building_id` |
| `building_hierarchy_settings` | تنظیم داینامیک: آیا بلوک دارد؟ طبقه؟ واحد؟ مشاعات؟ | `building_id` |
| `blocks` | بلوک (داینامیک) | `building_id` |
| `floors` | طبقه (داینامیک) | `block_id` / `building_id` |
| `units` | واحد (داینامیک) | `floor_id` / `building_id` |
| `common_areas` | مشاعات (پارکینگ، انباری، سالن، استخر...) | `building_id` |
| `costs` | هزینه‌ها (داینامیک: مالکان / مستاجران / ساکنان / همه) | `building_id` |
| `cost_payments` | پرداخت‌ها (وضعیت: pending → upload_receipt → confirmed) | `cost_id`, `user_id` |
| `receipts` | فایل رسید واریزی (مسیر ذخیره محلی) | `cost_payment_id` |
| `notifications` | اعلانات (نوع، ساختمان، کاربر، خوانده شده؟) | `user_id`, `building_id` |
| `tickets` | تیکت‌ها (انتقاد، پیشنهاد، گزارش، شکایت از واحد) | `user_id`, `building_id`, `unit_id?` |
| `ticket_comments` | کامنت‌های تیکت | `ticket_id` |
| `invitations` | لینک دعوت (توکن، نوع عضو، استفاده شده؟) | `building_id`, `invited_by` |
| `penalty_settings` | تنظیم جریمه دیرکرد (داینامیک: مبلغ ثابت یا درصد، روز تاخیر) | `building_id` |
| `penalties` | جریمه‌های اعمال شده روی پرداخت‌ها | `cost_payment_id` |

### بهینه‌سازی:
- **Composite Index** روی `(building_id, created_at)` برای کوئری‌های ساختمان.
- **Covering Index** برای جستجو در `units`.
- **Soft Delete** (`deleted_at`) در جداول حساس.
- **JSON Columns** برای تنظیمات داینامیک (مثلاً `building_hierarchy_settings`).

---

## ۳. سوالات کلیدی برای رسیدن به استراکچر دقیق

### الف) سلسله مراتب ساختمان و انعطاف‌پذیری
1. آیا هر ساختمان **باید** حتماً از «بلوک» استفاده کند؟ یا فقط در صورت فعال کردن در تنظیمات ساختمان؟
2. آیا یک ساختمان می‌تواند **چندین بلوک** داشته باشد و هر بلوک **طبقات متفاوت**؟ (مثلاً بلوک A طبقه ۱ تا ۵، بلوک B طبقه ۱ تا ۳)
3. آیا **مشاعات** باید به هر واحد لینک شوند؟ (مثلاً پارکینگ شماره ۵ متعلق به واحد ۱۰۱) یا فقط لیست مشاعات عمومی ساختمان؟
4. آیا نیاز به **واحد تجاری / مسکونی** جداگانه در ساختار وجود دارد؟

### ب) نقش‌ها و مدیریت ساختمان
5. آیا یک کاربر می‌تواند **در چند ساختمان همزمان** نقش‌های متفاوت داشته باشد؟ (مثلاً در ساختمان A مدیر، در ساختمان B ساکن)
6. آیا می‌توان **نقش‌ها را کاملاً سفارشی** کرد؟ (مثلاً «حسابدار» فقط دسترسی به هزینه‌ها، «مدیر» همه چیز، «ساکن» فقط پرداخت و تیکت)
7. آیا **انتقال مدیریت** باید با تایید مدیر فعلی باشد یا مستقیماً توسط مدیر جدید؟ آیا نیاز به «انتقال موقت» وجود دارد؟ (مثلاً در سفر)
8. آیا کاربر می‌تواند **خودش** از ساختمان خارج شود یا فقط با تایید مدیر؟

### ج) سیستم دعوت و عضویت
9. آیا لینک دعوت **فقط برای مدیر** قابل ارسال است یا هر عضو با دسترسی خاص؟
10. آیا دعوت می‌تواند برای **نقش خاص** باشد؟ (مثلاً دعوت فقط به عنوان «حسابدار»)
11. آیا پس از کلیک روی لینک دعوت، کاربر باید **ثبت‌نام جدید** کند یا اگر از قبل ثبت‌نام کرده مستقیماً اضافه می‌شود؟
12. آیا لینک دعوت **انقضا** دارد؟ (مثلاً ۷ روزه)

### د) هزینه‌ها و پرداخت
13. آیا هزینه‌ها فقط **ماهانه/دوره‌ای** هستند یا می‌توان **هزینه یک‌باره** (مثلاً تعمیرات) هم تعریف کرد؟
14. آیا نیاز به **تقسیم هزینه** بین واحدها وجود دارد؟ (مثلاً بر اساس متراژ، تعداد ساکنان، یا سهم ثابت)
15. آیا جریمه دیرکرد **فقط روی پرداخت‌های تایید نشده** اعمال می‌شود یا روی کل بدهی ساختمان؟
16. آیا می‌توان **تخفیف** هم تعریف کرد؟ (مثلاً پرداخت زودهنگام)

### ه) اعلانات و ارتباطات
17. آیا اعلانات باید از طریق **ایمیل** هم ارسال شوند؟ یا فقط در پنل؟ (با توجه به Redis Queue، می‌توان ایمیل را هم اضافه کرد)
18. آیا نیاز به **اعلان فوری (Realtime)** با WebSocket یا فقط Polling کافی است؟
19. آیا **انتقاد از واحد دیگر** باید به صورت **ناشناس** هم قابل انجام باشد؟

### و) ذخیره‌سازی و امنیت
20. آیا فایل‌های رسید پرداخت باید **فقط مدیر ساختمان** ببیند یا همه اعضا؟ (پیشنهاد: فقط مدیر + پرداخت‌کننده)
21. آیا نیاز به **رمزنگاری فایل‌ها** در ذخیره‌سازی محلی وجود دارد؟
22. آیا حجم فایل‌ها محدودیت دارد؟ (مثلاً حداکثر ۵ مگابایت برای عکس رسید)

### ز) گزارش‌گیری و تیکت
23. آیا گزارش‌ها باید **خروجی PDF / Excel** هم داشته باشند؟
24. آیا تیکت‌ها می‌توانند **دسته‌بندی** شوند؟ (مثلاً «فنی»، «مالی»، «مدیریتی»)
25. آیا هر تیکت می‌تواند **چندین کاربر** درگیر کند؟ (مثلاً مدیر + حسابدار)

### ح) قابلیت‌های فروش و مقیاس‌پذیری
26. آیا سیستم باید **چند زبان** باشد؟ (فارسی پیش‌فرض + انگلیسی)
27. آیا نیاز به **نسخه موبایل** (PWA) در همین پروژه هست یا فقط REST API کافی است؟
28. آیا سیستم باید **مقیاس‌پذیر برای چند ساختمان همزمان** توسط یک کاربر باشد؟ (داشبورد مرکزی)

---

## ۴. پیشنهادات حرفه‌ای اضافی (که فروش و کیفیت را بالا می‌برد)

### ۴.۱. سیستم Cache پیشرفته
- **Redis Tag-based Cache**: هر ساختمان با تگ (`cache:building:{id}`) قابل پاک‌سازی جمعی.
- **Query Cache**: نتایج کوئری‌های سنگین (مثلاً گزارش هزینه‌ها) با TTL قابل تنظیم.
- **OPcache Preload**: بارگذاری کلاس‌های اصلی در حافظه سرور.

### ۴.۲. امنیت حرفه‌ای
- **Rate Limiting** بر اساس IP + User ID با Redis.
- **SQL Injection Prevention**: فقط Prepared Statements (PDO / mysqli با پارامتر).
- **XSS / CSRF Protection**: در لایه Middleware.
- **File Upload Validation**: MIME Type + Extension + Magic Number برای رسیدها.
- **JWT Blacklist**: توکن‌های باطل شده در Redis نگهداری شوند.

### ۴.۳. Storage حرفه‌ای
```
/storage/
  /buildings/
    /{building_id}/
      /receipts/
        /{cost_payment_id}/
          receipt.jpg
      /documents/
      /common_areas/
  /users/
    /{user_id}/
      /avatar/
```
- هر ساختمان یک پوشه جداگانه: امنیت و مدیریت ساده‌تر.
- محدودیت دسترسی با `open_basedir` یا `.htaccess` (deny all).

### ۴.۴. سیستم Queue و اعلانات
- **Redis Queue** برای ارسال ایمیل (غیرهمزمان).
- **Notification Types**: `cost_due`, `ticket_reply`, `invitation`, `payment_confirmed`, `penalty_applied`.
- **Read Status** در جدول جداگانه یا JSON.

### ۴.۵. API Documentation
- **Swagger / OpenAPI** با خروجی خودکار از Controllerها.
- **Postman Collection** آماده برای اپ موبایل.

### ۴.۶. تست و کیفیت کد
- **PHPUnit**: Unit Test برای Service Layer.
- **PHPStan / Psalm**: تحلیل استاتیک.
- **Code Style**: PHP_CodeSniffer با استاندارد PSR-12.

### ۴.۷. قابلیت‌های فروش برتر
- **White Label**: امکان تغییر نام و لوگو برای هر ساختمان (یا نسخه SaaS).
- **Role Templates**: قالب‌های آماده نقش (مثلاً «مدیر ساختمان مسکونی»، «حسابدار مجتمع تجاری»).
- **Audit Log**: ثبت تمام تغییرات مهم (چه کسی، چه زمانی، چه تغییری).
- **Backup Strategy**: اسکریپت خودکار خروجی SQL + فایل‌ها.

---

## ۵. نقشه راه اولیه (Roadmap پیشنهادی)

| فاز | توضیحات | زمان تخمینی |
|---|---|---|
| **فاز ۱** | هسته (Kernel, Router, Middleware, JWT Auth) + دیتابیس پایه | ۱-۲ روز |
| **فاز ۲** | ساختمان (Hierarchy داینامیک) + مشاعات | ۲ روز |
| **فاز ۳** | کاربران + نقش‌ها + دعوت (Invitation System) | ۲-۳ روز |
| **فاز ۴** | هزینه‌ها + پرداخت‌ها + رسید + جریمه داینامیک | ۳-۴ روز |
| **فاز ۵** | اعلانات (Redis Queue) + تیکت + گزارش | ۲-۳ روز |
| **فاز ۶** | کش (Redis + OPcache) + بهینه‌سازی + مستندات API | ۲ روز |
| **فاز ۷** | تست + امنیت + خروجی نهایی قابل فروش | ۲-۳ روز |

---

## ۶. سوال نهایی از شما

لطفاً به سوالات شماره‌گذاری شده در بخش ۳ پاسخ دهید (حتی با «بله» یا «نه» یا توضیح کوتاه). پس از آن:

- آیا می‌خواهید **فاز ۱** را همین حالا شروع کنم؟
- آیا نیاز به **فایل پروپوزال PDF/Markdown** جداگانه برای ارائه به مشتری دارید؟
- آیا **طراحی دیتابیس دقیق (Migration Scripts)** را هم در همین پروژه قرار دهم؟

> 💡 یک پیشنهاد مهم: با توجه به حجم پروژه، بهتر است ابتدا یک **نمونه اولیه (Prototype)** از هسته و یک ماژول (مثلاً ساختمان + کاربر) بسازیم تا ساختار را تایید کنید، سپس بقیه را گسترش دهیم.

---
*این فایل به صورت داینامیک به‌روزرسانی می‌شود. هر تغییر در نیازمندی‌ها مستقیماً در ساختار پروژه اعمال خواهد شد.*
