# 🎪 Damoon Exhibition — Lead Capture System

> **Persian:** سیستم ثبت لید بازدیدکنندگان نمایشگاه هایپرصنعت دامون — با پنل کارمند، مدیریت ادمین و نصب‌کننده وب.

A lightweight PHP application for exhibition booths. Employees log in, register visitor leads (name, phone, description, optional photo), and admins manage users and view all registrations.

![PHP](https://img.shields.io/badge/PHP-8.1%2B-777BB4?logo=php&logoColor=white)
![MySQL](https://img.shields.io/badge/MySQL-5.7%2B-4479A1?logo=mysql&logoColor=white)
![Tailwind CSS](https://img.shields.io/badge/Tailwind-4.x-06B6D4?logo=tailwindcss&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-green)

---

## ✨ Features

| Area | Description |
|------|-------------|
| **Lead form** | RTL Persian UI, phone validation, optional image upload (JPG, PNG, WebP, GIF — max 5 MB) |
| **Ownership** | Each phone number belongs to one employee; duplicates blocked across users |
| **My Leads** | Employees see only their own registered numbers |
| **Admin panel** | Create employees, view stats, browse all leads with photos |
| **Security** | Bcrypt passwords, CSRF tokens, login rate limiting, prepared statements |
| **Installer** | 4-step web wizard — no manual SQL required on fresh deploys |
| **Clean URLs** | `/login`, `/admin`, `/leads`, `/install` via Apache rewrite |

---

## 📋 Requirements

- PHP **8.1+** with extensions: `pdo`, `pdo_mysql`, `mbstring`, `json`, `fileinfo`, `session`
- MySQL **5.7+** or MariaDB **10.3+**
- Apache with `mod_rewrite` enabled
- Node.js **18+** (development only — for Tailwind CSS build)

---

## 🚀 Quick Start (Web Installer)

1. Clone the repository into your web root:

   ```bash
   git clone https://github.com/ahmadreza-log/damoon-exhibition.git
   cd damoon-exhibition
   ```

2. Make `storage/` writable by the web server.

3. Open the installer in your browser:

   ```
   http://localhost/damoon-exhibition/install
   ```

4. Follow the 4 steps:
   - **Requirements** — PHP extensions and directory permissions
   - **Database** — host, name, user, password (connection test included)
   - **Admin account** — first admin user + application base path
   - **Install** — creates schema, config files, and lock file

5. Log in at `/login` with your admin credentials.

> After installation, `storage/installed.lock` is created. Delete it only if you need to re-run the installer.

---

## 🛠️ Manual Setup (Alternative)

```bash
# 1. Import schema
mysql -u root -p < database/exhibition.sql

# 2. Copy config examples
cp config/database.php.example config/database.php
cp config/app.php.example config/app.php

# 3. Edit config/database.php and config/app.php (especially base_path)

# 4. Create admin user via installer OR insert manually into users table
```

**`base_path`** must match the URL path where the app lives (e.g. `/php/exhibition` or `/damoon-exhibition`).

---

## 🎨 Frontend Development

Tailwind CSS v4 is used for styling. Build or watch during development:

```bash
npm install
npx @tailwindcss/cli -i ./assets/css/input.css -o ./assets/css/style.css --watch
```

Commit `assets/css/style.css` after building for production — the app does not require Node.js at runtime.

---

## 🏷️ Versioning

The app version is stored in the root `VERSION` file (semver).

```bash
# Show current version
php scripts/version.php show

# Bump version
php scripts/version.php patch   # 1.1.0 → 1.1.1
php scripts/version.php minor   # 1.1.0 → 1.2.0
php scripts/version.php major   # 1.1.0 → 2.0.0
php scripts/version.php set 1.2.0
```

The version is displayed in the UI, saved in `storage/installed.lock` at install time, and the admin dashboard warns when a newer `VERSION` file is deployed.

---

## 🗺️ Routes

| URL | Handler | Access |
|-----|---------|--------|
| `/` | Lead registration form (+ POST JSON) | Authenticated employees |
| `/login` | Login page (+ POST JSON) | Public |
| `/logout` | Logout | Authenticated |
| `/leads` | My Leads list | Authenticated |
| `/admin` | Admin dashboard (+ POST JSON) | Admin only |
| `/install` | Setup wizard (+ JSON actions) | Public (until installed) |

---

## 📁 Project Structure

```
damoon-exhibition/
├── app/              # PHP classes (Auth, Storage, Install, Upload, …)
├── assets/           # CSS, JS, fonts, images
├── config/           # app.php, database.php (generated by installer)
├── database/         # exhibition.sql schema
├── storage/          # uploads/, installed.lock
├── autoload.php      # Class autoloader
├── bootstrap.php     # App bootstrap & service wiring
├── index.php         # Main lead form
├── install.php       # Web installer UI
└── .htaccess         # Clean URL rewrites
```

---

## 🔒 Security Notes

- Never commit `storage/installed.lock` or uploaded photos — they are gitignored.
- `config/` and `app/` are blocked from direct HTTP access via `.htaccess`.
- PHP execution is disabled in `storage/uploads/`.
- Change default credentials immediately after first login.
- Use HTTPS in production.

See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.

---

## 🤝 Contributing

Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).

---

## 👤 Author

**Ahmadreza Ebrahimi** — [@ahmadreza-log](https://github.com/ahmadreza-log)

Built for **هایپرصنعت دامون (Damoon Hyper Industry)** exhibition events.
