# Сайт шпаргалок `history.solfa.ru`

Каталог шпаргалок по банкам вопросов Moodle. Содержание (данные) отделено от
отображения (view). Всё в формате PHP. Каталог страниц строится автоматически:
PHP-скрипт сканирует папки сайта и находит все шпаргалки.

## Структура

```
history.solfa.ru/
├── .htaccess                  # красивые адреса, DirectoryIndex, запрет листинга
├── index.php                  # главная: все шпаргалки во всех папках
├── README.md                  # эта инструкция
├── lib/                       # общий код
│   ├── data.php               # модель: shpargalki_scan() — сканирование и метаданные
│   ├── view.php               # отображение каталога: render_catalog()
│   └── shpargalka_view.php    # отображение шпаргалки: render_shpargalka()
├── tools/
│   └── convert_html_to_php.py # одноразовый конвертер старых HTML-шпаргалок в PHP
├── bjd/                       # папка-раздел (БЖД)
│   ├── index.php              # каталог: только шпаргалки этой папки + ссылка на главную
│   └── shpargalka_bjd_1kurs.php
├── hm/                        # история музыки (I и II курс)
│   ├── index.php
│   ├── shpargalka_1kurs_dopusk.php
│   └── shpargalka_2kurs_dopusk.php
├── hist/                      # история
│   ├── index.php
│   └── shpargalka_istoria.php
└── mi/                        # математика и информатика
    ├── index.php
    └── shpargalka_minf_dopusk.php
```

## Адреса страниц (pretty URLs)

Настраивает `.htaccess` (нужен `mod_rewrite`):

| Открываете             | Показывается                        |
|------------------------|-------------------------------------|
| `/`                    | каталог всех шпаргалок              |
| `/bjd/`, `/hm/`, …     | каталог только этой папки + «← На главную» |
| `/bjd/shpargalka_bjd_1kurs` | шпаргалка (без `.php`)         |
| `/bjd/shpargalka_bjd_1kurs.html`, `…​.php` | 301-редирект на адрес без расширения |

Требования: PHP 7.4+, Apache с `mod_rewrite` и `AllowOverride All`.

## Формат данных шпаргалки

Каждая шпаргалка — PHP-файл, который определяет массив `$__shp` и **возвращает его**
(`return $__shp;`). При прямом открытии по URL файл сам вызывает
`render_shpargalka()` из `lib/shpargalka_view.php` и показывает страницу;
при подключении из каталога (`lib/data.php`) просто возвращает массив.
Отображение целиком берёт на себя `lib/shpargalka_view.php` (CSS, JS,
flip-карточки, print-стили и т.д.) — в файле данных только содержание.
Файл данных должен лежать на один уровень ниже корня сайта.

```php
<?php
$__shp = [
    'title'    => 'Шпаргалка · БЖД · I курс · осенний допуск',
    'subtitle' => '45 вопросов · 11 тем',                    // необязательно
    'hint'     => 'Тапай по карточке…',                      // необязательно
    'footer'   => 'Шпаргалка подготовлена по банку вопросов…', // необязательно
    'themes'   => [
        [
            'num'   => 1,                                    // номер темы
            'title' => 'Основы БЖД и управление рисками',
            'sub'   => 'вопросы №1, 5, 9',                   // необязательно
            'toc'   => '1 Основы',                           // необязательно: метка в оглавлении
            'ac'    => '#C2410C',                            // акцентный цвет темы
            'acbg'  => '#FBEDE4',                            // фон шапки темы
            'acbd'  => '#F0CFBC',                            // цвет рамок
            'blocks' => [                                    // блоки в порядке вывода
                ['type' => 'theses', 'items' => [
                    '<b>Безопасность</b> — состояние защищённости…',
                ]],
                ['type' => 'table',
                 'title' => 'этапы управления рисками',
                 'head'  => ['№', 'Этап', 'Суть'],
                 'rows'  => [['1', '<b>Идентификация</b>', 'Распознавание и описание']]],
                ['type' => 'cards',
                 'title' => 'цитаты',                        // необязательно
                 'cards' => [                                // flip-карточки
                    ['k' => 'Термин', 'hint' => 'подсказка',
                     'back' => 'Оборот карточки', 'tall' => false],
                 ]],
                ['type' => 'traps', 'traps' => [             // ловушки для теста
                    ['claim' => 'Неверное утверждение', 'why' => '<b>НЕВЕРНО.</b> Пояснение'],
                ]],
            ],
        ],
    ],
    ],
];
```

(после массива в файле идёт служебный блок прямого доступа — см. конец
любого файла шпаргалки)

В строках разрешён HTML (`<b>`, `<i>`, сущности `&nbsp;` и т.п.) — рендерер
вставляет его как есть. Не забывайте экранировать одинарные кавычки `\'`.

## Как добавить новую шпаргалку

1. Создайте папку-раздел, если её ещё нет, и положите в неё `index.php`:

   ```php
   <?php
   require dirname(__DIR__) . '/lib/data.php';
   require dirname(__DIR__) . '/lib/view.php';
   $scan = shpargalki_scan(__DIR__, dirname(__DIR__));
   render_catalog($scan, false, basename(__DIR__));
   ```

2. Создайте файл шпаргалки (например, `fiz/shpargalka_fiz_1kurs.php`) с массивом
   данных по формату выше — удобнее всего скопировать существующую и заменить
   содержание.

3. Готово: главная страница и каталог папки подхватят шпаргалку автоматически
   (сканирование по факту файлов, никаких списков править не нужно). Статистика
   «N тем · M карточек · K ловушек» считается из массива.

## Конвертер старых HTML-шпаргалок

Исторические HTML-файлы конвертируются одной командой:

```bash
python3 tools/convert_html_to_php.py путь/к/shpargalka.html [выход.php]
```

Скрипт разбирает стандартный шаблон (`.theme`, `.theses`, `.tblwrap`, `.cards`,
ловушки) и генерирует PHP-массив. Полезно при переносе новых шпаргалок,
сделанных в старом формате.

## Как это работает

- **Модель** (`lib/data.php`): `shpargalki_scan($scopeDir, $siteRoot)`
  рекурсивно ищет `*.php`, кроме `index*` и папок `lib/`, `tools/`;
  подключает каждый файл и читает метаданные из массива
  (title, subtitle, число тем/карточек/ловушек, mtime).
- **Отображение каталога** (`lib/view.php`): `render_catalog($scan, $isRoot, $scopeName)`
  рисует главную (с заголовками папок) или страницу одной папки (с кнопкой
  «← На главную»).
- **Отображение шпаргалки** (`lib/shpargalka_view.php`):
  `render_shpargalka($data)` — sticky-шапка, оглавление тем, тезисы, таблицы,
  flip-карточки, ловушки, кнопка «наверх», стили печати.