Skip to content

README.md

Latest commit

 

History

History
382 lines (311 loc) · 13.3 KB

README.md

File metadata and controls

382 lines (311 loc) · 13.3 KB

Metarang Microservice Admin Panel - README

Copy everything below this line from to the ending and paste into your README.md file.


# پنل مدیریت میکروسرویس متارنگ (Microservice Admin Panel)

پنل مدیریت مدرن و مقیاس‌پذیر برای سامانه متارنگ، ساخته شده با **Laravel 11**، **Blade**، **Vue 3** و **ابزارهای مدرن فرانت‌اند**.

[![PHP Version](https://img.shields.io/badge/PHP-8.2%2B-blue)](https://php.net)
[![Laravel Version](https://img.shields.io/badge/Laravel-11.x-red)](https://laravel.com)
[![Vue Version](https://img.shields.io/badge/Vue-3.x-green)](https://vuejs.org)
[![License](https://img.shields.io/badge/license-MIT-purple)](LICENSE)

## ✨ ویژگی‌ها

- **معماری میکروسرویس** – آماده اتصال به سرویس‌های مجزای متارنگ
- **ترکیب Blade + Vue 3** – قدرت SEO و سرعت Blade با تعامل‌پذیری Vue
- **مدیریت جامع کاربران و نقش‌ها** – سیستم ACL توکار
- **مدیریت ترجمه‌ها** – از طریق API و کامپوننت‌های Vue
- **پروفایل کاربری** – ویرایش اطلاعات و آپلود تصویر
- **باکس آپلود فایل پیشرفته (`FileInput`)** – با پشتیبانی از حالت بارگذاری
- **کامپوننت جدول پویا (`TableAction`)** – برای نمایش و عملیات روی داده‌ها
- **دارک/لایت مود** – از طریق `useBreakpoint` و قابلیت‌های مدرن CSS
- **مدیریت ناوبری** – کامپوننت `Breadcrumb` یکپارچه
- **فرانت‌اند سریع با Vite** – هات ریلود، TypeScript، PostCSS

## 📋 پیش‌نیازها

- PHP 8.2 یا بالاتر
- Composer
- Node.js 18+ و NPM
- MySQL 8.0 / PostgreSQL / MariaDB
- Redis (اختیاری – برای کش و صف)

## 🚀 مراحل نصب و راه‌اندازی

### 1. کلون مخزن
```bash
git clone https://github.com/iranpsc/microservice-admin-panel.git
cd microservice-admin-panel

2. نصب وابستگی‌های Backend

composer install

3. تنظیم فایل محیطی

cp .env.example .env
php artisan key:generate

سپس اطلاعات پایگاه داده و سرویس‌های جانبی را در .env ویرایش کنید:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=metarang_admin
DB_USERNAME=root
DB_PASSWORD=

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

4. نصب وابستگی‌های Frontend

npm install

5. کامپایل دارایی‌ها (برای توسعه)

npm run dev

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

npm run build

6. اجرای مهاجرت‌ها و سیدرها

php artisan migrate --seed

سیدر ReplaceImagesUrlSeeder آدرس API کارت ملی را به‌روز می‌کند.

7. لینک استوریج (برای فایل‌های آپلودی)

php artisan storage:link

8. اجرای سرور توسعه

php artisan serve

و در ترمینال مجزا (برای فرانت‌اند):

npm run dev

پنل ادمین در آدرس http://localhost:8000 در دسترس است.

🧱 ساختار پروژه (لاراول + ویو)

├── app/
│   ├── Http/
│   │   ├── Controllers/     (کنترلرهای API و Web)
│   │   └── Middleware/
│   ├── Models/              (User, Role, Translation, ...)
│   └── Services/            (لایه سرویس برای میکروسرویس‌ها)
├── database/
│   ├── migrations/          (جدول‌های users, roles, translations, ...)
│   └── seeders/             (ReplaceImagesUrlSeeder و ...)
├── resources/
│   ├── js/
│   │   ├── components/      (کامپوننت‌های Vue: FileInput, TableAction, Breadcrumb)
│   │   ├── composables/     (useBreakpoint و ...)
│   │   └── pages/           (صفحات Vue – مدیریت ترجمه، پروفایل و ...)
│   └── views/               (فایل‌های Blade اصلی که Vue در آن‌ها مانت می‌شود)
├── routes/
│   ├── web.php              (مسیرهای Blade و صفحات اصلی)
│   └── api.php              (APIهای مدیریت ترجمه، پروفایل، دیتابیس)
├── public/                  (فونت‌ها، فایل‌های استاتیک)
├── vite.config.js           (تنظیمات Vite با پشتیبانی از Vue)
└── package.json             (Vue, @vitejs/plugin-vue, tailwindcss, ...)

📦 اسکریپت‌های مهم NPM

دستور توضیح
npm run dev اجرای Vite در حالت توسعه (Hot reload)
npm run build ساختن نسخه بهینه‌شده برای production
npm run preview پیش‌نمایش نسخه production به صورت محلی

🛠 استانداردهای توسعه

Backend (Laravel)

  • PSR-12 برای کد PHP
  • استفاده از Route Model Binding
  • استفاده از Form Requests برای اعتبارسنجی
  • استفاده از Services و Repository Pattern برای لایه دسترسی به داده (پیشنهادی)
  • نام‌گذاری توابع: camelCase – متغیرها: snake_case

Frontend (Vue 3 + TypeScript)

  • استفاده از Composition API و <script setup>
  • کامپوننت‌ها: PascalCase (مثل FileInput.vue)
  • کامپوزابل‌ها: useCamelCase (مثل useBreakpoint)
  • استایل‌ها: Tailwind CSS (در فایل کامپوننت با <style scoped>)
  • ترجیحاً از TypeScript برای props و emits استفاده شود

کامیت و کنترل نسخه

  • از Conventional Commits استفاده کنید:
    • feat: add new button component
    • fix: resolve image upload issue in FileInput
    • chore: update dependencies

🧪 تست

php artisan test

تست‌های واحد و ویژگی در پوشه tests/ قرار دارند.

🔐 امنیت

  • تمام APIها با Laravel Sanctum (یا JWT) محافظت می‌شوند.
  • خروجی‌ها در Blade با {{ }} و در Vue با {{ }} خودکار XSS-safe هستند.
  • برای آپلود فایل، نوع و سایز فایل در FileInput اعتبارسنجی می‌شود.

🤝 مشارکت (Contributing)

  1. مخزن را فورک کنید.
  2. یک برنچ جدید ایجاد کنید (git checkout -b feature/awesome-feature).
  3. تغییرات خود را کامیت کنید (git commit -m 'feat: add awesome feature').
  4. پوش کنید (git push origin feature/awesome-feature).
  5. یک Pull Request ایجاد کنید.

لطفاً قبل از PR، تست‌ها را اجرا کرده و از کیفیت کد اطمینان حاصل کنید.

📄 لایسنس

این پروژه تحت لایسنس MIT منتشر شده است – برای جزئیات به فایل LICENSE مراجعه کنید.

🙏 قدردانی

  • تیم متارنگ برای زیرساخت میکروسرویس
  • مشارکت‌کنندگان: abbasajorlou1371 و theAwmin
  • اکوسیستم بزرگ Laravel و Vue.js

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


---

## English Version

Metarang Microservice Admin Panel

A modern, scalable admin panel for the Metarang system, built with Laravel 11, Blade, Vue 3, and modern frontend tooling.

PHP Version Laravel Version Vue Version License

✨ Features

  • Microservice Architecture – Ready to connect with Metarang's separate services
  • Blade + Vue 3 Hybrid – SEO power and Blade speed with Vue interactivity
  • Comprehensive User & Role Management – Built-in ACL system
  • Translation Management – Through API and Vue components
  • User Profile – Edit information and upload images
  • Advanced File Upload (FileInput) – With loading state support
  • Dynamic Data Table (TableAction) – Display and operations on data
  • Dark/Light Mode – Via useBreakpoint and modern CSS features
  • Navigation Management – Integrated Breadcrumb component
  • Fast Frontend with Vite – Hot reload, TypeScript, PostCSS

📋 Prerequisites

  • PHP 8.2 or higher
  • Composer
  • Node.js 18+ and NPM
  • MySQL 8.0 / PostgreSQL / MariaDB
  • Redis (optional – for caching and queues)

🚀 Installation & Setup

1. Clone the repository

git clone https://github.com/iranpsc/microservice-admin-panel.git
cd microservice-admin-panel

2. Install Backend Dependencies

composer install

3. Environment Configuration

cp .env.example .env
php artisan key:generate

Then edit database and service credentials in .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=metarang_admin
DB_USERNAME=root
DB_PASSWORD=

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

4. Install Frontend Dependencies

npm install

5. Compile Assets (for development)

npm run dev

For production build:

npm run build

6. Run Migrations & Seeders

php artisan migrate --seed

The ReplaceImagesUrlSeeder updates the Melli Card API endpoints.

7. Link Storage (for uploaded files)

php artisan storage:link

8. Run Development Server

php artisan serve

And in a separate terminal (for frontend):

npm run dev

The admin panel will be available at http://localhost:8000

🧱 Project Structure (Laravel + Vue)

├── app/
│   ├── Http/
│   │   ├── Controllers/     (API and Web controllers)
│   │   └── Middleware/
│   ├── Models/              (User, Role, Translation, ...)
│   └── Services/            (Service layer for microservices)
├── database/
│   ├── migrations/          (users, roles, translations tables)
│   └── seeders/             (ReplaceImagesUrlSeeder, etc.)
├── resources/
│   ├── js/
│   │   ├── components/      (Vue components: FileInput, TableAction, Breadcrumb)
│   │   ├── composables/     (useBreakpoint, etc.)
│   │   └── pages/           (Vue pages – translation mgmt, profile, etc.)
│   └── views/               (Main Blade files where Vue mounts)
├── routes/
│   ├── web.php              (Blade routes and main pages)
│   └── api.php              (APIs for translations, profile, database)
├── public/                  (Fonts, static files)
├── vite.config.js           (Vite config with Vue support)
└── package.json             (Vue, @vitejs/plugin-vue, tailwindcss, ...)

📦 Important NPM Scripts

Command Description
npm run dev Run Vite in development mode (Hot reload)
npm run build Build optimized production version
npm run preview Preview production build locally

🛠 Development Standards

Backend (Laravel)

  • PSR-12 for PHP code
  • Use Route Model Binding
  • Use Form Requests for validation
  • Use Services and Repository Pattern for data access layer (recommended)
  • Naming: camelCase for methods – snake_case for variables

Frontend (Vue 3 + TypeScript)

  • Use Composition API and <script setup>
  • Components: PascalCase (e.g., FileInput.vue)
  • Composables: useCamelCase (e.g., useBreakpoint)
  • Styling: Tailwind CSS (in component with <style scoped>)
  • Prefer TypeScript for props and emits

Commit & Version Control

  • Use Conventional Commits:
    • feat: add new button component
    • fix: resolve image upload issue in FileInput
    • chore: update dependencies

🧪 Testing

php artisan test

Unit and feature tests are located in the tests/ directory.

🔐 Security

  • All APIs are protected with Laravel Sanctum (or JWT)
  • Outputs are XSS-safe using {{ }} in both Blade and Vue
  • File uploads are validated for type and size in FileInput

🤝 Contributing

  1. Fork the repository
  2. Create a new branch (git checkout -b feature/awesome-feature)
  3. Commit your changes (git commit -m 'feat: add awesome feature')
  4. Push to the branch (git push origin feature/awesome-feature)
  5. Open a Pull Request

Please run tests and ensure code quality before submitting a PR.

📄 License

This project is open-sourced under the MIT license – see the LICENSE file for details.

🙏 Acknowledgments

  • Metarang team for microservice infrastructure
  • Contributors: abbasajorlou1371 and theAwmin
  • The great Laravel and Vue.js ecosystems

💡 Note: This repository is under active development. For bugs or feature requests, use Issues.


**END OF README**