meraproject/docs/integration-external-app-employees.md

# Отчёт: интеграция внешнего приложения — данные сотрудников (Merakomis)

**Дата:** 13.05.2026  
**Кодовая база:** `d:\MeraProject` (PHP CMS, тема `themes\merakomis`).

## 1. Краткий вывод

- Данные сотрудников хранятся в модуле **`themes\merakomis\Emp`** (таблица `tMerakomisEmp`, контроллер CMS `themes.merakomis.emp`).
- **Публичного REST API с API-ключом для выгрузки сотрудников в коде нет.** Доступ к спискам и карточкам строится на **сессии через cookie** после входа (`login`), по тем же правилам, что и веб-интерфейс.
- Для вызова из браузера с другого домена хост должен попадать в **белый список CORS** в `module/engine.php` (для продуктивного домена Merakomis указан `merakomis.in`).

## 2. Как устроен HTTP API движка

### 2.1. Маршрутизация

В корневом `.htaccess`:

```55:55:d:\MeraProject\.htaccess
RewriteRule ^api/([^/]+)?/?([^/]+)?/$ index.php?api=1&module=$1&action=$2&%{QUERY_STRING} [L]
```

Пример: **`https://<хост>/api/themes.merakomis.emp/login/`** → `api=1`, `module=themes.merakomis.emp`, `action=login`.

Альтернатива — query-string: `index.php?api=1&module=themes.merakomis.emp&action=login`.

### 2.2. Вызов контроллера

В `module/engine.php` при `api=1` создаётся класс:

- Имя класса: `controller\<module с точками как NS>\Api`
- Для сотрудников: **`controller\themes\merakomis\emp\Api`** (файл `themes\merakomis\emp\controller.php`).

Вызывается метод с именем из параметра **`action`**.

### 2.3. Тело запроса (JSON)

При `Content-Type: application/json` тело подставляется в `$_POST`:

```104:107:d:\MeraProject\module\core\core\model.php
        if(substr($_SERVER["CONTENT_TYPE"],0,16) ==  'application/json') {
            $_POST = json_decode(file_get_contents('php://input'),true);
```

Имеет смысл отправлять JSON с клиента, как это делает фронтенд CMS.

### 2.4. CORS

Для ряда хостов, включая `merakomis.in`, при `api=1` выставляются заголовки `Access-Control-Allow-Origin: *` и др. — см. `module/engine.php` (список `HTTP_HOST`).

## 3. Модель «сотрудник» (поля БД / сущности)

Основные константы полей в `themes\merakomis\emp\model.php` (фрагмент):

- Идентификация и доступ: `id`, `name`, `login`, `email`, `pass`, `type`, `active`, `accept`, `archive`, `portal`, `account`, …
- Контакты и профиль: `phone`, `skype`, `discrod` (поле Discord в коде), `city`, `image`, `birthdate`, `date_hire`, …
- Орг. данные: `org`, `org_type`, `staffing`, `status`, `is_freelancer`, …
- Прочее: `salary`, `tg_acc` (Telegram), группы `group`, и т.д.

Форматирование записи для API/карточек — методы **`Emp::format()`** и **`Emp::getPublicData($emp_id)`** (учёт прав через `themes\merakomis\emp\Rules`).

## 4. Аутентификация для внешнего клиента

### 4.1. Cookie после `login`

После успешного входа выставляются cookie (имена в модели):

- **`fg_emp_id`** — id сотрудника  
- **`fg_emp_h`** — **не хэш пароля**, а значение поля пароля из БД (сервер сравнивает cookie с текущим значением в записи — см. `if_auth`).

```482:493:d:\MeraProject\themes\merakomis\emp\model.php
    static function if_auth(){
        if($uid = intval($_COOKIE[ self::$cookieIDKey ]) and $hash = $_COOKIE[ self::$cookieHashKey ]) {
            $acc = self::getByID($uid);
            $res = ( strcmp($acc[self::$PASSWORD],$hash)==0
                    && boolval($acc[self::$ACTIVE])
                    && !boolval($acc[self::$ARCHIVE])
                    && !boolval($acc[self::$REMOVED])
                )
```

Внешнее приложение (**сервер-сервер** или **мобильное**) должно **сохранять и передавать эти cookie** на последующие запросы к `/api/...`.

### 4.2. Двухфакторная цепочка через Telegram

Если у учётной записи включена схема «Telegram», `login` может вернуть **`e: 3`** и **`key`**: тогда ожидается повторный запрос с полями `key`, `code` (код из Telegram). Это нужно заложить в сценарий интеграции.

## 5. Методы `controller\themes\merakomis\emp\Api` (по коду)

Модуль: **`themes.merakomis.emp`**. Базовый URL:  
`https://<хост>/api/themes.merakomis.emp/<action>/`

| action | Назначение | Авторизация |
|--------|------------|-------------|
| `login` | Вход (`login`, `pass`; при Telegram — доп. `key`, `code`) | Нет |
| `reg` | Регистрация | Нет |
| `remind` | Восстановление пароля | Нет |
| `new_pass` | Установка пароля по ссылке восстановления | Нет |
| `exit` | Выход (сброс сессии) | Ожидается cookie |
| `getTableData` | Таблица сотрудников (разные «режимы» через `data` в теле запроса) | **Требуется** (`Emp::$IS_AUTH`) |
| `getForm` | Данные формы редактирования (как в CMS) | Требуется |
| `getData` | Карточка по `id` (POST) | Требуется |
| `getMyData` | Текущий авторизованный сотрудник (`Emp::format`) | Требуется |
| `getMyForm` | Публичная карточка / форма (`Emp::getPublicData`) | Требуется |
| `updateMe` | Обновление своих контактов (`phone`, `skype`, `discord`) | Требуется |
| `updatePassword` | Смена пароля | Требуется |
| `getBirthday` | Именинники на сегодня (для авторизованных) | Требуется |
| `isSummaryAnalysis` | Флаг доступа к сводному анализу (`Rules::isAnalysisProjectsSummary`) | Требуется |
| `qr` / `toTelegram` / `checkTelegram` / `removeTelegram` | Интеграция с Telegram | Частично / полностью только с сессией |

Наследованные из `merakomisControllerTable` (при наличии вызова с фронта): `getForm`, `getTableData` фильтруют данные **только если `Emp::$IS_AUTH`**.

### 5.1. Режимы `getTableData` (список сотрудников)

Реализация в `themes\merakomis\emp\controller.php` задаёт набор колонок и фильтры в зависимости от флагов в **`post['data']`**:

- **`my_company`** — «Моя компания»: неархивные (`archive = 0`), контактные колонки (имя, staffing, роли, skype, discord, email, город и т.д.).
- **`my`** — подчинённые/доступные id: если нет «superview», ограничение `Emp::getSubEmps(Emp::$AUTH_ID)`.
- **`archive`** — архив / не архив по `data.archive`.
- **`mini`** — компактный админ-список.
- **`all`** — расширенные колонки, включая ФОТ и др.

Фактические **права на строки** определяются логикой `Emp` / `Rules` и фильтрами запроса; при интеграции нужно повторить те же запросы, что и клиент CMS, либо задать новый контракт на бэкенде (см. раздел 7).

## 6. Выгрузка файла (Excel) по сотруднику

В карточке в `Emp::format` указывается ссылка:

- **`/api/themes.merakomis.download/emp/?id=<id>`** — отдаёт XLSX с полями из `Emp::getPublicData` (набор колонок зависит от прав текущей сессии).

Класс в проекте: `controller\themes\merakomis\download\API` (`themes\merakomis\download\controller.php`, метод **`emp()`**). Требуется **`Emp::$IS_AUTH`**.

**Замечание по именованию:** в файле объявлен класс `API` (все буквы заглавные); при строгом автозагрузчике и регистрозависимой ФС путь `.../Api` должен совпадать с именем класса. На окружении разработки это уже работает или учтено конфигурацией сервера — при переносе интеграции стоит проверить фактический вызов этого URL в вашей среде.

## 7. Рекомендуемая стратегия интеграции

### Вариант A — использовать текущий API «как веб-клиент» (быстрый старт)

1. Реализовать HTTP-клиент с **cookie jar**.  
2. `POST /api/themes.merakomis.emp/login/` с учётными данными сервисного пользователя (роль с нужными правами).  
3. Вызывать `getTableData` / `getData` / `getMyData` с JSON-телом, как в интерфейсе.  
4. Учесть CORS только если интеграция идёт из браузера; для **server-to-server CORS не нужен**.

**Минусы:** нет отдельного ограничения scope; компрометация учётной записи = полный доступ веб-пользователя; смена пароля ломает интеграцию; зависимость от внутреннего формата `getTableData`.

### Вариант B — отдельный интеграционный endpoint (рекомендуется для продакшена)

Добавить узкий контроллер, например `themes.merakomis.emp.integration.Api`:

- авторизация по **секрету** (заголовок или env), отдельно от cookie пользователя;
- явные методы: «список сотрудников с полями X», «карточка по id», пагинация;
- журналирование и ограничение по IP.

Этого **нет в текущем репозитории** — потребуется разработка и согласование полей (в т.ч. персональные данные, 152-ФЗ).

## 8. Связанные модули API (справочники и оргструктура)

Для полноценного отображения данных сотрудника используются справочники с собственными `Api` в `themes\merakomis\dictionary\...` (город, оргштат, департамент, статусы и т.д.) и модуль **команды** `themes.merakomis.team.member` и др. Их можно вызывать тем же шаблоном `/api/<module>/<action>/`, если есть права у той же сессии.

## 9. Итоговая таблица «что есть сейчас»

| Возможность | Есть? |
|------------|-------|
| Открытый API-ключ только для чтения сотрудников | Нет |
| JSON API под cookie-сессией сотрудника/админа | Да (`themes.merakomis.emp`) |
| CORS для стороннего фронта | Да, для перечисленных в `engine.php` хостов |
| Экспорт карточки в XLSX | Да (`themes.merakomis.download/emp`) |

---

*Документ составлен по статическому анализу кода; для точного контракта полей тела запросов к `getTableData` при необходимости следует снять примеры запросов с рабочего фронтенда (DevTools → Network).*