# Operations guide (administrators)

## Daily / weekly checks

| When | What | Where |
|---|---|---|
| Daily | Everything green | **System → System health** |
| Daily | Last night's backup succeeded | **System → Backups → Recent runs** |
| Daily | Critical alerts acknowledged | Notification center (bell / inbox icon) |
| Weekly | Failed notifications retried or explained | **Notifications → Notification log** (filter: Failed) |
| Weekly | Contracts without a renewal decision | Dashboard → priority list |
| Monthly | Unused or departed users suspended | **Users** |
| Quarterly | Roles reviewed; restore drill | **Roles & permissions**; [BACKUP_RESTORE.md](BACKUP_RESTORE.md) |

## Scheduled jobs (Asia/Dubai)

| Time | Job |
|---|---|
| every minute | Scheduler heartbeat (health page) |
| every 5 min | Queue heartbeat job |
| every 15 min | Task reminders |
| 01:30 | Backup cleanup |
| 02:00 | Backup (database, documents, logo, .env) |
| 03:30 | Delete generated report files past retention (history is kept) |
| 06:00 | **Expiry check:** updates statuses, plans reminders (catches up missed days) |
| 08:00 | Backup health check |
| daily | Prune failed queue jobs older than 30 days |

Run the expiry check by hand: **Notifications → Delivery channels → Run now**, or
`php artisan contracts:check-expiry`.

## Health page: what to do when a line is red

| Check | Fix |
|---|---|
| Database / Cache | `sudo systemctl status mysql redis-server`; check `.env` credentials |
| Queue workers | `sudo supervisorctl status`; `sudo supervisorctl restart almasa-worker:*` |
| Scheduler | Is the cron line there? `sudo crontab -u almasa -l` |
| Daily expiry check | Scheduler must be running; then run it by hand (above) |
| Document storage | Permissions: `sudo chown -R almasa:www-data storage && sudo chmod -R ug+rwX storage` |
| Free disk space | Clean old logs; move backups to S3; grow the disk |
| Last backup | Open **System → Backups**, read the failure message; `storage/logs/backups-*.log` |
| Email / WhatsApp / Telegram | [CREDENTIALS_SETUP.md](CREDENTIALS_SETUP.md) and the *Test* buttons |
| OCR | `tesseract --version`; install `tesseract-ocr-ara` |
| AI extraction | Key missing or wrong: Settings Center → OCR & AI (Super Admin) |
| Failed jobs | See below |
| Debug mode / HTTPS | Fix `.env` (`APP_DEBUG=false`, `APP_URL=https://…`), then run `./deploy.sh` |

## Failed jobs

```bash
php artisan queue:failed                 # list
php artisan queue:retry all              # retry after fixing the cause
php artisan queue:forget <id>            # drop one
```

Every finally-failed job is also logged in `storage/logs/queue-*.log`.

## Logs

All logs are in `storage/logs/`, one file per day:

| Log | Contents |
|---|---|
| `laravel` | General errors |
| `security` | Failed sign-ins, backup downloads |
| `notifications`, `email`, `whatsapp`, `telegram` | Delivery |
| `reports` | Report generation |
| `ai`, `ocr` | Extraction |
| `scheduler` | Expiry runs |
| `backups` | Backup runs |
| `queue` | Failed jobs |
| `worker` | Supervisor output |

Live view: `tail -f storage/logs/laravel-$(date +%F).log`.

## Common tasks

| Task | How |
|---|---|
| Add a user | **Users → New**: role, department, mobile/WhatsApp, Telegram chat ID |
| Someone leaves | Suspend the user (signs them out everywhere), then **Transfer ownership** of their contracts |
| Change reminder timing | **Notifications → Notification rules** |
| Change wording of messages | **Notifications → Message templates** (Arabic and English) |
| Change company details / VAT defaults | **System → Settings Center** |
| Switch a feature off | Settings Center → Features (no data is deleted) |
| Approval steps | **Master data → Approval workflows** |
| Contract categories, types, document checklist | **Master data** |
| Reset someone's password | **Users →** the user **→ Send password reset link** |

## Maintenance mode

```bash
php artisan down --retry=60      # users see a "back soon" page
php artisan up
```

`deploy.sh` does this automatically.

## Local development (Docker on Windows)

- Start: `docker compose up -d`, then open <http://localhost:8088>.
- The PHP packages (`vendor/`) live in the `sail-vendor` volume. Install packages *inside* the container:
  `docker compose exec -u sail laravel.test composer install`.
- PHP picks up code changes within 30 seconds; `docker compose restart laravel.test` applies them at once.
- After adding Filament pages or resources, or changing routes, run
  `php artisan optimize:clear && php artisan route:cache && php artisan filament:optimize`.
- Moving the project into the WSL2 Linux file system (`\\wsl$\Ubuntu\home\...`) makes it up to 3× faster
  again.
