meraproject/docs/business-logic.md

MeraProject — бизнес-логика системы

Документ описывает предметную область, модули, хранимые данные и бизнес-процессы корпоративной системы MeraProject (тема Merakomis). Технические детали реализации (код, API, стек) намеренно опущены.

Не входит в scope: микросервис user-reader и прочие внешние read/write API.

---

1. Назначение системы

MeraProject — внутренняя система управления проектной организацией (инженерное проектирование). Она решает задачи:

• ведения каталога сотрудников и оргструктуры;
• управления проектами, командами и контрагентами;
• учёта рабочего времени (табель) и отсутствий;
• расчёта и контроля фонда оплаты труда (ФОТ);
• аналитики нагрузки по проектам, отделам и компании в целом.

Центральная бизнес-цепочка:

Сотрудник → участие в команде проекта → ввод часов → агрегация в аналитику и ФОТ

---

2. Структура продукта

2.1. Ядро — Merakomis

Основная бизнес-логика MeraProject сосредоточена в теме Merakomis. Это самостоятельный продукт для компании Merakom: проекты, табель, кадры, бюджет, аналитика.

2.2. Платформа CMS (Module.bz)

Параллельно в репозитории присутствует универсальная CMS-платформа с модулями: интернет-магазин, CRM-проекты, академия, таймер, блог и др. Эти модули используются в других продуктах (например, портал Module.bz) и не являются ядром MeraProject.

Область	Назначение в экосистеме
Merakomis	Корпоративный портал проектной организации
PM (CRM)	Воронки продаж, клиенты, CRM-проекты — отдельная модель, не связана с инженерными проектами Merakomis
Shop	Интернет-магазин
Timer	Личный тайм-трекер продуктивности (не корпоративный табель)
Academy	Онлайн-курсы и тесты
Common	Клиенты, задачи, лиды, контакты

---

3. Разделы интерфейса (бизнес-навигация)

Меню формируется динамически в зависимости от прав пользователя.

Раздел	Содержание
Личный кабинет	Мой табель, мои проекты, моя компания
Проекты	Список проектов, контрагенты
Кадры	Сотрудники, справочники отсутствий, статусов, видов сотрудничества
Бюджет	ФОТ сотрудников
Аналитика	Личная, по проектам, годовая, бюджет, все проекты, компания, кадры
Календарь	Производственный календарь, корпоративные события
Архив	Архивные проекты и сотрудники
Администрирование	Настройки портала, справочники, структура компании
Настройки	Портальные переменные, тексты разделов

---

4. Модули Merakomis

4.1. Сотрудники (Emp)

Назначение: каталог персонала компании, учётные записи, оргданные, контакты.

Хранимые данные:

Группа полей	Примеры
Идентификация	ФИО, логин, email, фото
Доступ	тип учётной записи, активность, подтверждение, архив
Контакты	телефон, Skype, Discord, Telegram
Оргструктура	город/офис, юрлицо, штатная позиция, должность, отдел, статус сотрудника, вид сотрудничества
Кадры	дата приёма, дата рождения, зарплата (для ФОТ), флаг фрилансера
Дополнительно	группы доступа, данные о детях

Типы учётных записей:

• Администратор — полный доступ ко всем разделам
• Сотрудник — доступ по ролям и группам

Группы доступа (назначаются сотруднику):

Группа	Назначение
Кадры	Управление персоналом, кадровая аналитика
Бюджет: редактор	Редактирование ФОТ
Бюджет: наблюдатель	Просмотр бюджетной аналитики
Проект: редактор	Создание и редактирование проектов
Проект: наблюдатель	Просмотр проектов и аналитики
Проект: финансы	Доступ к финансовым срезам аналитики
Компания	Аналитика по всей компании
Офис (Москва, Иваново, Новосибирск, Краснодар, Семей)	Аналитика и табели в рамках офиса

Бизнес-процессы:

1. Регистрация нового сотрудника → подтверждение учётной записи
2. Вход в систему (опционально — двухфакторная аутентификация через Telegram)
3. Работа в личном кабинете: табель, проекты, карточка
4. Архивация при увольнении (сотрудник исключается из активных списков, но данные сохраняются)
5. Экспорт карточки сотрудника в Excel (с учётом прав просматривающего)

Журнал действий: фиксируются вход, выход, регистрация, блокировка.

---

4.2. Проекты (Project)

Назначение: учёт инженерных проектов компании.

Хранимые данные:

Поле	Описание
Код и название	Идентификатор проекта; код формируется как {номер}-{стадия}
Стадия	ПД, РД, К, АН и др. (справочник стадий)
Статус	Не определён / В работе / Завершён / Пауза
Контрагент	Заказчик или партнёр
Команда	Привязка к команде проекта
Руководитель проекта (РП)	Ответственный сотрудник
Даты	Дата начала, дата окончания, дата архивации
Характеристики объекта	Площадь, объём, высота, тип объекта
Юрлицо, договор	Организация-исполнитель, ссылка на папку документов
Архив	Флаг и дата перевода в архив
Разделы	Какие инженерные разделы задействованы (ОВ, ТХ, АР…)

Статусы проекта:

Статус	Значение
Не определён	Статус не назначен
В работе	Активный проект
Завершён	Проект закрыт
Пауза	Работа приостановлена

Бизнес-правила:

• Удаление проекта — мягкое (запись помечается как удалённая, физически не уничтожается)
• Архивный проект доступен для просмотра; самостоятельный ввод часов по нему ограничен
• При снятии с архива статус сбрасывается в «Не определён»
• Флаг «включить всех сотрудников» позволяет открыть проект для всей компании

Бизнес-процесс:

Создание проекта → назначение РП и команды → привязка разделов →
участники вносят часы → аналитика и ФОТ

---

4.3. Команды и участники (Team, Team Member)

Назначение: формирование проектных команд, роли и привязка к инженерным разделам.

Хранимые данные:

Сущность	Содержание
Команда	Именованная команда, привязанная к проекту (1:1)
Участник команды	Сотрудник + роль + инженерный раздел + флаг активности

Иерархия ролей в проекте:

Уровень	Роли
1	ГИП (главный инженер проекта), BIM-координатор, Сотрудник
2	ГАП, ГКП, ведущие инженеры (ЭОМ, ССиАК, ВК, ОВиК)
3	Архитектор, инженер-конструктор, инженер-геотехник, инженер-обследователь, инженеры разделов
Архивные	Ведущий инженер, Инженер (устаревшие роли)

Бизнес-правила:

• Один сотрудник — одна запись в команде проекта
• Без активного членства в команде сотрудник не может вносить часы по проекту
• Роли определяют доступ к аналитике и право редактировать табели подчинённых
• РП, ГИП, ГАП, ГКП, директора отделов и ведущие инженеры получают расширенные права в рамках своих проектов

Бизнес-процесс:

РП/ГИП формирует состав → сотрудник видит проект в «Мои проекты» →
открывает табель по проекту

---

4.4. Табель рабочего времени (Time)

Назначение: учёт отработанных часов по проектам и дням.

Хранимые данные (запись времени):

Поле	Описание
Сотрудник	За кого учтены часы
Проект	По какому проекту
Дата	Календарный день
Длительность	Количество часов
Тип	Рабочие часы или переработка (сверхурочные)

Уникальность записи: комбинация (проект + сотрудник + тип часов + дата).

Бизнес-правила ввода часов:

Правило	Описание
Округление	Часы округляются до 0, 0.5 или 1
Диапазон	От 0 до 24 часов в сутки
Лимит рабочих часов	Берётся из производственного календаря (по умолчанию 8 в будний день)
Лимит переработки	Остаток до 24 часов за вычетом рабочих
Удаление	Установка 0 часов удаляет запись
Сводный табель	Проект с id = 0 — только просмотр, запись запрещена
Архивный проект	Самостоятельный ввод часов ограничен

Кто может вносить часы:

• Сотрудник — за себя
• Руководитель (РП, ГИП, директор отдела и др.) — за подчинённых, если есть право на чтение/запись чужого табеля

Кэш отчётов: при изменении часов или календаря агрегированные отчёты инвалидируются и пересчитываются.

Бизнес-процессы:

1. Сотрудник открывает календарь табеля → вносит часы по проектам за каждый день
2. Руководитель открывает табель подчинённого и корректирует записи
3. Сводный виджет показывает итоги за месяц и год
4. Данные используются в аналитике и расчёте стоимости трудозатрат

---

4.5. Отсутствия (Time Absence)

Назначение: учёт отпусков, больничных и прочих причин неявки.

Хранимые данные:

Поле	Описание
Сотрудник	Кто отсутствует
Дата	День отсутствия
Тип	Ссылка на справочник причин (отпуск, больничный…)

Уникальность: одна запись на (сотрудник + дата).

Бизнес-правила:

• Установка отсутствия на дату удаляет рабочие часы за этот день
• Массовая установка — на диапазон дат (например, отпуск на две недели)
• Типы отсутствий ведутся в справочнике «Причины отсутствия»

---

4.6. Производственный календарь (Day)

Назначение: определение нормы рабочих часов по дням.

Типы дней:

Тип	Норма часов
Рабочий	8 (или заданное значение)
Не рабочий	0
Сокращённый	Уменьшенная норма (предпраздничный)

Влияние на бизнес-логику:

• Лимит рабочих часов в табеле рассчитывается по календарю
• Изменение календаря инвалидирует кэш трудозатратных отчётов

---

4.7. События (Event)

Назначение: корпоративные события, отображаемые в календаре портала (совещания, дедлайны, праздники).

---

4.8. ФОТ и бюджет (Fot, Fot Budget, Variable)

Назначение: учёт фонда оплаты труда и сопоставление с бюджетом компании.

ФОТ сотрудника (помесячно):

Поле	Описание
Сотрудник, год, месяц	Уникальная запись на период
ФЗП	Фонд заработной платы
Коэффициенты	k, доплаты, страховые взносы
Итоговый ФОТ	Рассчитанная сумма
Ставка в час	Для сопоставления с трудозатратами
Статус	Состояние записи

Бюджет ФОТ (помесячно):

Поле	Описание
Период	Год и месяц
Выделенный бюджет	Плановая сумма
Фактический ФОТ	Реализованные расходы

Расчётные переменные (по годам):

Годовые константы: МРОТ, фонды, коэффициенты k1/k2 — используются при расчёте ФОТ.

Бизнес-правила:

• Финансовые поля ФОТ хранятся в зашифрованном виде
• Доступ к ФОТ: группы «Бюджет: редактор/наблюдатель», кадры, руководители
• Аналитика сравнивает отработанные часы со стоимостью по ставке и бюджетом

Бизнес-процесс:

Кадры/финансы ведут ФОТ → аналитика сравнивает часы с бюджетом →
отчёты по компании, отделам, проектам

---

4.9. Оргструктура и справочники (Dictionary)

Назначение: нормативно-справочная информация, используемая во всех модулях.

Справочник	Содержание
Отделы (Department)	Иерархия оргструктуры (АР, ОВ, ТХ…)
Должности (Post)	Позиция сотрудника в отделе
Города (City)	Офисы и локации
Юрлица (Org)	Организации-работодатели
Виды сотрудничества (OrgType)	Штат, ГПХ, фриланс и т.д.
Статусы сотрудника (EmpStatus)	Работает, в отпуске, декрет…
Штатное расписание (Staffing)	Должность в оргштате
Стадии проекта (Step)	ПД, РД, К, АН…
Разделы (Section)	Инженерные разделы: ОВ1, ТХ, АР…
Контрагенты (Contractor)	Заказчики и подрядчики
Статусы контрагентов	Состояние взаимоотношений
Типы объектов (ObjType)	Классификация объектов проектирования
Причины отсутствия (Absence)	Отпуск, больничный, командировка…

---

4.10. Аналитика

Назначение: агрегированные отчёты на основе табеля, ФОТ и оргструктуры. Отдельной таблицы нет — данные вычисляются из Time, Fot, Emp, Project.

Разделы аналитики:

Раздел	Содержание
Личная	Мои часы, отсутствия, распределение по проектам
Мои проекты	Затраты по проектам, разделам, команде
Годовой отчёт	Сводка за год по проектам
Бюджет	Сопоставление ФОТ и трудозатрат
Все проекты	Сводка по всем доступным проектам
Моя компания	Нагрузка по отделам и сотрудникам
Мои кадры	Кадровая аналитика (для группы «Кадры»)

Матрица доступа: права определяются комбинацией:

• типа учётной записи (админ / сотрудник);
• роли в проектах (РП, ГИП, ГАП, ГКП, ведущие инженеры);
• роли в компании (директор отдела);
• групп доступа (кадры, бюджет, проекты, офисы).

Примеры:

Роль / группа	Типичные права
Обычный сотрудник	Свой табель, свои проекты, личная аналитика
РП	Аналитика проектов, редактирование состава, табели подчинённых (чтение)
ГИП	Аналитика проектов (без финансов), управление командой
Директор отдела	Табели подчинённых (чтение и запись), аналитика компании
Кадры	Управление сотрудниками, кадровая аналитика, архив
Бюджет: редактор	Редактирование ФОТ
Бюджет: наблюдатель	Просмотр бюджетной аналитики
Офис (регион)	Аналитика и табели сотрудников своего офиса

---

4.11. Прочие модули Merakomis

Модуль	Назначение
History	Журнал действий пользователей
Page	CMS-страницы портала
Variable	Портальные переменные и тексты разделов
Emp Group	Назначение групп доступа сотрудникам
Emp Children	Данные о детях сотрудника (кадровый учёт)
Download	Экспорт карточек сотрудников
Telegram	Привязка Telegram для 2FA и уведомлений
Post	Должности в оргструктуре

---

5. Сводная модель данных

5.1. Основные сущности

flowchart TD
    Emp[Сотрудник] --> TeamMember[Участник команды]
    Project[Проект] --> Team[Команда]
    Team --> TeamMember
    TeamMember --> Time[Запись времени]
    Project --> Time
    Project --> ProjSection[Разделы проекта]
    ProjSection --> DSection[Справочник разделов]
    Emp --> Absence[Отсутствие]
    Day[Производственный календарь] --> Time
    Time --> Cache[Кэш отчётов]
    Emp --> Fot[ФОТ]
    Variable[Расчётные переменные] --> Fot
    Fot --> Budget[Бюджет ФОТ]
    Department[Отдел] --> Post[Должность]
    Post --> Emp
    DStep[Стадия проекта] --> Project
    Contractor[Контрагент] --> Project

5.2. Таблицы и бизнес-смысл

Таблица	Бизнес-сущность
tMerakomisEmp	Сотрудник
tMerakomisEmpGroup	Группы доступа сотрудника
tMerakomisEmpChildren	Дети сотрудника
tMerakomisProject	Проект
tMerakomisTeam	Команда проекта
tMerakomisTeamMember	Участник команды
tMerakomisProjectSection	Разделы, задействованные в проекте
tMerakomisTime	Запись рабочих часов
tMerakomisTimeAbsence	Отсутствие сотрудника
tMerakomisTimeCache	Кэш трудозатратных отчётов
tMerakomisDay	Производственный календарь
tMerakomisEvent	События календаря
tMerakomisDAbsence	Типы отсутствий
tMerakomisDStep	Стадии проекта
tMerakomisDSection	Инженерные разделы
tMerakomisDDepartment	Орготделы
tMerakomisPost	Должности
tMerakomisDStaffing	Штатное расписание
tMerakomisDCity	Города и офисы
tMerakomisDOrg	Юридические лица
tMerakomisDOrgtype	Виды сотрудничества
tMerakomisDEmpstatus	Статусы сотрудника
tMerakomisDContractor	Контрагенты
tMerakomisDContractorStatus	Статусы контрагентов
tMerakomisObjType	Типы объектов
tMerakomisFot	ФОТ сотрудника за месяц
tMerakomisFotBudget	Бюджет ФОТ за месяц
tMerakomisVariable	Расчётные переменные по годам
tMerakomisHistory	Журнал действий
tMerakomisPage	CMS-страницы

---

6. Ключевые бизнес-сценарии

6.1. Ежедневная работа сотрудника

1. Вход в систему
2. Открытие «Мой табель»
3. Выбор проекта из списка «Мои проекты»
4. Ввод часов за текущий день (рабочие и/или переработка)
5. При необходимости — отметка отсутствия

6.2. Запуск нового проекта

1. Сотрудник с правом «Проект: редактор» создаёт проект
2. Указывает код, стадию, контрагента, характеристики
3. Назначает РП и формирует команду
4. Привязывает инженерные разделы
5. Участники начинают вносить часы

6.3. Контроль нагрузки руководителем

1. РП/ГИП/директор отдела открывает аналитику проекта или табель подчинённого
2. Сравнивает плановую и фактическую нагрузку
3. При необходимости корректирует часы или состав команды

6.4. Кадровый учёт

1. Кадровая служба ведёт карточки сотрудников
2. Назначает группы доступа, статусы, оргпринадлежность
3. При увольнении — архивация учётной записи
4. Аналитика «Мои кадры» — текучесть, нагрузка, отсутствия

6.5. Бюджетирование

1. Редактор бюджета вносит помесячный ФОТ по сотрудникам
2. Задаёт бюджет компании на период
3. Аналитика «Бюджет» сопоставляет часы, ставки и план

6.6. Закрытие проекта

1. Смена статуса на «Завершён»
2. Перевод в архив (с фиксацией даты)
3. Ограничение ввода новых часов
4. Сохранение данных для исторической аналитики

---

7. Связи между доменами

Связь	Описание
Merakomis ↔ PM (CRM)	Независимые модели проектов; инженерные проекты и CRM-проекты не связаны
Merakomis ↔ Timer	Timer — личный инструмент; табель Merakomis — корпоративный учёт с правами
Merakomis ↔ Shop/Academy	Платформенные модули CMS, не входят в ядро MeraProject
Сотрудник ↔ Проект	Только через активное членство в команде
Часы ↔ ФОТ	Часы умножаются на ставку в час для оценки стоимости трудозатрат
Календарь ↔ Табель	Календарь задаёт лимиты; изменения календаря влияют на отчёты

---

8. Ограничения и особенности

• Конфиденциальность: пароли и финансовые поля ФОТ не отображаются без соответствующих прав
• Архив: архивные сущности доступны для просмотра и аналитики, но с ограничениями на изменения
• Мягкое удаление: проекты и другие сущности помечаются как удалённые, а не уничтожаются
• Делегирование: руководители могут действовать от имени подчинённых при вводе табеля
• Региональность: группы офисов ограничивают видимость аналитики и табелей по географии

---

Документ составлен на основе бизнес-логики темы Merakomis. Для интеграционных контрактов см. отдельную документацию по внешним API.