webl/README.md

# WebLab

Дз по лекциям

## Возможности

1. **Заметки** - создание и просмотр заметок через веб-интерфейс (`app/public/index.php`, модель `App\Models\Note`).
2. **Миграции БД** - версионирование схемы PostgreSQL через `php bin/migrate` и Eloquent.
3. **Логирование запросов** - каждый HTTP-запрос пишется с `method`, `uri`, `status`, `body`.
4. **Статический конфиг с шифрованными значениями** - файлы конфигурации по окружениям (`app/config/*.php`), шифрование значений через `App\Crypto\Encryptor` (openssl AES-256-GCM) и CLI-утилиты.

## Быстрый старт

```sh
make setup
```

Или:

```bash
make init      # создать .env (+UID/GID)
make build     # сборка образа
make up        # запустить контейнеры
make composer  # установить зависимости
make migrate   # применить миграции
```

Приложение: <http://localhost:8090> 

Порт задается `APP_PORT` в `.env` (по умолчанию 8090)

## Команды

| Команда                 | Описание                                                              |
|-------------------------|-----------------------------------------------------------------------|
| `make help`             | Показать список всех команд                                           |
| `make init`             | Создать `.env` из `.env.example`, подставить UID/GID                  |
| `make build`            | Собрать Docker-образы                                                 |
| `make up`               | Запустить контейнеры в фоне                                           |
| `make down`             | Остановить контейнеры                                                 |
| `make ps`               | Показать состояние контейнеров                                        |
| `make logs`             | Логи контейнеров в реальном времени                                   |
| `make clean`            | Остановить контейнеры и удалить данные PostgreSQL (`-v`)              |
| `make setup`            | Быстрый старт: init + build + up + composer + migrate                 |
| `make composer`         | `composer install` внутри контейнера                                  |
| `make migrate`          | Применить миграции (`php bin/migrate up`)                             |
| `make migrate-status`   | Статус миграций (`php bin/migrate status`)                            |
| `make migrate-rollback` | Откатить последнюю миграцию (`php bin/migrate down`)                  |
| `make keygen`           | Сгенерировать `APP_KEY` и записать в `.env` (`php bin/config keygen`) |
| `make config-show`      | Показать конфиг текущего окружения (`php bin/config show`)            |
| `make sh`               | Shell внутри контейнера приложения                                    |
| `make psql`             | Подключиться к PostgreSQL                                             |

## Логи

Каждый HTTP-запрос логируется с `method`, `uri`, `status`, `body`.

- Консоль: `docker compose logs app`
- Файлы: `app/storage/logs/app-*.log` (ротация 7 дней)

## Конфиг и шифрование

Окружение и ключ шифрования читаются из переменных окружения (`.env` -> `compose.yaml`):

| Переменная | Назначение                                                       | По умолчанию |
|------------|------------------------------------------------------------------|--------------|
| `APP_ENV`  | Окружение: `local`, `dev` или `prod`                             | `local`      |
| `APP_KEY`  | base64-ключ длиной 32 байта для AES-256-GCM                      | -            |

Ключ: `.env` в `.gitignore`, а в `.env.example` лежит только плейсхолдер. Сгенерировать и записать ключ в `.env` можно командой `make keygen`. После смены ключа перезапустите приложение (`make up`) и перешифруйте `enc:`-значения - под новым ключом старые не расшифруются.

Файлы конфигурации лежат в `app/config/*.php` (например, `app.php`, `database.php`). Каждый файл возвращает массив с секциями по окружениям; значения окружения накладываются поверх `default` (`array_replace_recursive`):

```php
<?php

return [
    'default' => [
        // общие значения для всех окружений
    ],
    'local' => [
        // переопределения для APP_ENV=local
    ],
    'dev' => [],
    'prod' => [],
];
```

Значения, начинающиеся с `enc:v1:`, расшифровываются автоматически при загрузке конфига. Конверт (`envelope`) имеет вид `enc:v1:` + `base64(iv | tag | ciphertext)`, шифр - `aes-256-gcm` (`App\Crypto\Encryptor`). В не-production окружениях битый шифротекст или отсутствующий ключ деградирует до `null` с предупреждением в лог; в `prod` в этом случае выбрасывается исключение.

Консольные утилиты (`bin/config`):

```sh
docker compose exec -T app php bin/config keygen          # сгенерировать APP_KEY
docker compose exec -T app php bin/config encrypt "значение"
docker compose exec -T app php bin/config decrypt "enc:v1:..."
docker compose exec -T app php bin/config show            # показать конфиг для APP_ENV

make keygen
make config-show
```

Внутри контейнера также доступен CLI `openssl` (`/usr/bin/openssl`, версия 3.5.7) - для ручных операций

## Схема БД

| Таблица         | Ключевые колонки                                                                                          |
|-----------------|-----------------------------------------------------------------------------------------------------------|
| `users`         | `user_id` (PK), `email`, `password_hash`, `name`, `created_datetime`, `updated_datetime`                 |
| `boards`        | `board_id` (PK), `title`, `owner_user_id` → `users.user_id`, `is_public`, `created_datetime`, `updated_datetime` |
| `board_columns` | `column_id` (PK), `board_id` → `boards.board_id`, `ordinal_position`, `title`, `color`                   |
| `cards`         | `card_id` (PK), `board_id` → `boards.board_id`, `column_id` → `board_columns.column_id`, `sort_index`, `title`, `content`, `color`, `is_archived`, `created_datetime`, `updated_datetime` |

| Индекс                 | Тип       | Таблица / колонки                                    |
|------------------------|-----------|------------------------------------------------------|
| `idx_email`            | UNIQUE    | `users (email)`                                      |
| `idx_board_id`         | обычный   | `board_columns (board_id)`                           |
| `idx_active_board_id`  | PARTIAL   | `cards (board_id)` WHERE `is_archived = false`       |

Миграции лежат в `app/database/migrations`, применяются командой `make migrate` и откатываются `make migrate-rollback`.

## Структура

```
├── compose.yaml          # сервисы db и app
├── .env.example          
├── Makefile               
├── docker/php/           # Dockerfile и php.ini
└── app/                  # PHP-код (монтируется в контейнер)
    ├── public/           # index.php, router.php
    ├── src/              # исходники
    │   ├── Config/       # App\Config\Config - загрузка и слияние конфигов
    │   └── Crypto/       # App\Crypto\Encryptor - AES-256-GCM
    ├── config/           # конфиги по окружениям (app.php, database.php, ...)
    ├── bin/              # мигратор (migrate) и CLI конфига (config)
    ├── database/         # миграции
    └── storage/logs/     # логи
```

## Технологии

- PHP 8.5 (`php:8.5-cli`, встроенный сервер)
- Eloquent - illuminate/database 12 (standalone)
- Monolog 3
- PostgreSQL 18 (`postgres:18-alpine`)
- Docker Compose v2