# درخت کامل فایل‌ها

نسخه: ۱.۰.۰ — PHP 8.2+ / SQLite یا MySQL — رابط فارسی (RTL)

```
aquacoin-marketplace/
│
├── .env.example                    # نمونهٔ متغیرهای محیطی (بدون هیچ راز واقعی)
├── .htaccess                       # مسدودسازی دسترسی وب به ریشه (Apache 2.4)
├── README.md                       # معرفی، امکانات، نصب سریع، یکپارچه‌سازی‌ها
│
├── app/                            # کد برنامه — خارج از DocumentRoot
│   ├── .htaccess                   # Require all denied
│   ├── index.html                  # صفحهٔ خالی برای جلوگیری از لیست شدن پوشه
│   ├── bootstrap.php               # ثابت‌های مسیر، Autoload، Config، منطقه زمانی Asia/Tehran
│   │
│   ├── Core/                       # هستهٔ چارچوب
│   │   ├── App.php                 # جدول روت‌ها + dispatch + تبدیل HttpException به صفحات خطا
│   │   ├── Autoload.php            # نگاشت PSR-4 ساده برای App\* و Tests\*
│   │   ├── Auth.php                # نقش‌ها، login/logout، بررسی نقش، ریست کش کاربر
│   │   ├── Audit.php               # ثبت رویدادهای حسابرسی (ادمین/مدیر/سیستم)
│   │   ├── Config.php              # ادغام پیش‌فرض‌ها + config.php + متغیرهای محیطی
│   │   ├── Csrf.php                # تولید و اعتبارسنجی توکن فرم (hash_equals)
│   │   ├── Database.php            # PDO، تراکنش (BEGIN IMMEDIATE)، fetch/insert/update
│   │   ├── ErrorHandler.php        # تبدیل خطاها به پاسخ امن (بدون نمایش جزئیات)
│   │   ├── Format.php              # اعداد/تاریخ/پول فارسی، ماسک شمارت کارت
│   │   ├── Helpers.php             # e(), url(), csrf_field(), status_badge() و …
│   │   ├── Http.php                # کلاینت HTTP کمینه (cURL/streams) با تایم‌اوت سخت‌گیرانه
│   │   ├── HttpException.php       # خطای HTTP با وضعیت (403/404/419/429/500)
│   │   ├── Logger.php              # نوشتن لاگ روزانه در storage/logs
│   │   ├── RateLimiter.php         # محدودسازی نرخ بر پایهٔ دیتابیس (ورود، فرم‌ها)
│   │   ├── Request.php             # متد، مسیر، ورودی‌ها، IP، User-Agent
│   │   ├── Response.php            # پاسخ HTML/JSON/Redirect + هدرهای امنیتی و CSP
│   │   ├── Router.php              # روت‌های پویا + میان‌افزار csrf|auth|role:|throttle:
│   │   ├── Security.php            # هدرهای امنیتی، CSP با nonce، پاک‌سازی ورودی
│   │   ├── Session.php             # نشست امن (HttpOnly, SameSite، بازسازی شناسه)
│   │   └── Validator.php           # قوانین اعتبارسنجی (required, int, min, regex, same…)
│   │
│   ├── Models/                     # لایهٔ داده (همگی با Prepared Statements)
│   │   ├── Order.php               # ۹ وضعیت + گذارهای مجاز، محاسبهٔ صحیح مبلغ
│   │   ├── PaymentAttempt.php      # ثبت تلاش‌های پرداخت و پاسخ درگاه
│   │   ├── Delivery.php            # صف تحویل، کلید یکتا (order-{id}-v{n})، لاگ تلاش‌ها
│   │   ├── Settlement.php          # درخواست‌های تسویه + رمزنگاری شمارت کارت
│   │   ├── Setting.php             # تنظیمات ذخیره‌شده در دیتابیس (قیمت، محدودیت…)
│   │   └── User.php                # کاربران، نقش‌ها، قفل شدن، رمز عبور
│   │
│   ├── Services/                   # لایهٔ سرویس (یکپارچه‌سازی‌ها)
│   │   ├── GatewayInterface.php    # قرارداد درگاه پرداخت + تبدیل واحد پول
│   │   ├── ZarinpalGateway.php     # request/verify زرین‌پال (IRT)، تطبیق مبلغ/authority
│   │   ├── PaymentService.php      # ایمن‌سازی جریان پرداخت (Idempotent verify)
│   │   ├── RconClient.php          # پروتکل RCON با تایم‌اوت اتصال/خواندن
│   │   ├── DeliveryDriverInterface.php + DeliveryResult.php  # قرارداد درایور تحویل
│   │   ├── RconDriver.php          # اجرای فرمان از طریق RCON
│   │   ├── BridgeDriver.php        # تماس با افزونهٔ پل (HMAC + کلید یکتا)
│   │   ├── NullDriver.php          # بدون تحویل خودکار (بررسی دستی)
│   │   ├── DeliveryService.php     # صف، تلاش مجدد، بررسی دستی، تطبیق
│   │   └── HealthService.php       # بررسی سلامت (دیتابیس، درگاه، ماینکرفت، مجوزها)
│   │
│   ├── Controllers/                # کنترلرها
│   │   ├── BaseController.php      # رندر، JSON، بررسی نقش/مالکیت، redirect
│   │   ├── HomeController.php      # صفحهٔ اصلی + محاسبهٔ لحظه‌ای قیمت (JSON)
│   │   ├── ShopController.php      # تسویه (checkout)، ثبت سفارش، پیگیری سفارش
│   │   ├── PaymentController.php   # انتقال به درگاه، callback، نتیجه
│   │   ├── AuthController.php      # ورود، خروج، تغییر رمز عبور
│   │   ├── AdminController.php     # پنل WinixStore (سفارش‌ها، تحویل، تسویه، مدیران، تنظیمات…)
│   │   └── ManagerController.php   # پنل مدیر AquaMC (آمار، تسویه، پروفایل)
│   │
│   └── Install/
│       └── Installer.php           # منطق ۸ گام نصاب، ایجاد schema، قفل نصب، سخت‌سازی
│
├── config/                         # پیکربندی — خارج از DocumentRoot
│   ├── .htaccess                   # Require all denied
│   ├── index.html                  # جلوگیری از لیست شدن
│   ├── app.php                     # پیش‌فرض‌ها (بدون راز)
│   └── config.php                  # ⚠ تولیدشده توسط نصاب (رازها، کلید برنامه) — مجوز ۰۶۴۰
│
├── schema/
│   ├── .htaccess / index.html
│   ├── sqlite.sql                  # جداول، ایندکس‌ها، یکتایی‌ها برای SQLite
│   └── mysql.sql                   # همان ساختار برای MySQL/MariaDB (utf8mb4)
│
├── storage/                        # داده‌های زمان اجرا — خارج از DocumentRoot
│   ├── .htaccess                   # Require all denied
│   ├── index.html
│   ├── database/app.sqlite         # پایگاه داده (حالت پیش‌فرض)
│   ├── logs/app-YYYY-MM-DD.log     # لاگ روزانه (هرگز رمز عبور/راز ثبت نمی‌شود)
│   ├── sessions/                   # فایل‌های نشست
│   ├── cache/                      # کش/محدودسازی نرخ
│   └── installed.lock             # قفل نصاب
│
├── public/                         # ⬅︎ DocumentRoot — تنها پوشهٔ عمومی
│   ├── .htaccess                   # مسدودسازی فایل‌های حساس + rewrite به index.php
│   ├── index.php                   # نقطهٔ ورود
│   ├── install.php                  # نصاب (پس از نصب حذف شود)
│   └── assets/
│       ├── css/app.css             # طراحی آبی‌ـمشکی، واکنش‌گرا، فونت Vazirmatn
│       └── js/app.js               # تعاملات بدون وابستگی (سازگار با CSP)
│
├── views/
│   ├── .htaccess / index.html
│   ├── layouts/
│   │   ├── main.php                # قالب عمومی (هدر، فوتر، nonce، BASE_PATH)
│   │   ├── dashboard.php           # قالب پنل (منوی نقش‌محور)
│   │   ├── auth.php                # قالب صفحات ورود
│   │   └── install.php             # قالب نصاب (قدم‌شمار)
│   ├── home/index.php              # فروشگاه: انتخاب تعداد، محاسبهٔ زنده
│   ├── shop/{checkout.php, order.php}
│   ├── auth/{login.php, password.php}
│   ├── admin/                      # dashboard, orders, order, payments, deliveries,
│   │                               # settlements, managers, settings, health, audit, logs
│   ├── manager/                    # dashboard, settlements, profile
│   ├── errors/                     # 403, 404, 419, 429, 500, maintenance
│   └── install/                    # step1…step8, locked
│
├── bin/
│   ├── worker.php                  # کارگر صف تحویل (cron هر دقیقه)
│   ├── reconcile.php               # گزارش/ترمیم تطبیق (cron روزانه)
│   ├── create-admin.php            # ساخت/بازنشانی حساب مدیر از خط فرمان
│   └── seed-demo.php               # دادهٔ نمایشی برای دمو/تست دستی
│
├── tests/
│   ├── run.php                     # اجراکنندهٔ آزمون‌ها (خروجی فارسی)
│   ├── bootstrap.php               # دیتابیس موقت در tests/.tmp
│   ├── TestCase.php, Helpers.php   # زیرساخت و شبیه‌ساز درخواست
│   ├── Fakes.php                   # درگاه جعلی + درایور تحویل جعلی (دفتر کل یکتا)
│   ├── Unit/{PricingTest.php, OrderStateTest.php}
│   ├── Feature/{PaymentFlowTest.php, DeliveryReliabilityTest.php,
│   │            RoleAccessTest.php, SettlementTest.php, SecurityTest.php}
│   ├── screenshots.py              # تصویربرداری خودکار (بررسی ظاهری)
│   └── visual_audit.py             # بررسی سرریز افقی/خطای کنسول/فونت در ۴ اندازه
│
├── docs/
│   ├── INSTALL.md                  # نصب و استقرار (هاست اشتراکی + Ubuntu VPS)
│   ├── SECURITY.md                 # مدل امنیتی و سخت‌سازی
│   ├── TEST-CHECKLIST.md           # چک‌لیست دستی فارسی (۱۵ معیار پذیرش)
│   ├── FILE-TREE.md                # همین فایل
│   └── screenshots/*.png           # تصاویر بررسی ظاهری (دسکتاپ/تبلت/موبایل)
│
└── minecraft-plugin/
    ├── pom.xml                     # ساخت با Maven (Paper API 1.20.6+)
    ├── README.md                   # راهنمای نصب افزونه
    ├── AquaCoinBridge-1.0.0.jar    # خروجی کامپایل‌شده
    └── src/main/
        ├── java/ir/winix/aquamc/aquacoin/AquaCoinBridge.java
        │        # فرمان /giveaquacoin + پل HTTP محدود با HMAC و کلید یکتا
        └── resources/{plugin.yml, config.yml}
```

## نکات امنیتی ساختار

* فقط `public/` باید از وب در دسترس باشد. اگر هاست شما امکان تغییر DocumentRoot ندارد،
  کل پروژه را یک پوشه بالاتر از `public_html` قرار دهید و محتوای `public/` را درون آن بریزید
  (جزئیات در `docs/INSTALL.md`).
* `config/config.php` بعد از نصب با مجوز `۰۶۴۰` نوشته می‌شود و تنها شامل رازهاست؛
  آن را در بکاپ‌ها محرمانه نگه دارید و هرگز در مخزن عمومی قرار ندهید.
* `storage/` شامل پایگاه داده، نشست‌ها و لاگ‌هاست؛ هرگز آن را عمومی نکنید.