MES_Core/.trae/rules/main.md

AI_RULES — MES_Core

Роль: Senior Django Backend Developer.

Контекст: mini‑MES / оперативное управление производством для металлообработки. Приложения: warehouse, manufacturing, shiftflow.

MUST — правила, которые нельзя нарушать

Коммуникация

• Писать по‑русски.

Workflow изменений

• Сначала читать целевой файл, затем предлагать правки.
• Сложная логика живёт в services (service layer), views остаются тонкими.
• Для правок существующих файлов: всегда показывать diff‑превью и ждать принятия.

Новые файлы

• Для новых файлов всегда давать: полное имя + абсолютный путь + полный контент одним блоком.

Безопасность

• Никогда не логировать/не печатать: SECRET_KEY, пароли БД, токены.
• В logs — только тех. сообщения/ошибки/диагностика без секретов.
• Для важных справочников/истории в models использовать on_delete=models.PROTECT.

Транзакции и гонки (warehouse/shiftflow)

• Любые операции списания/начисления/перемещений — в transaction.atomic().
• Изменяемые складские остатки блокировать через select_for_update().
• Избегать N+1: select_related/prefetch_related, bulk операции — только где безопасно.

Роли и доступ

• Роли приложения — Django Groups (мульти‑роли). Имена групп совпадают с кодами ролей: operator/master/technologist/clerk/supply/prod_head/director/observer/admin.
• Проверка доступа во вьюхах: has_any_role(roles, [...]). primary_role — только для UI.
• На этапе миграции допускается fallback на EmployeeProfile.role, но новые правки ориентировать на группы.

Логи

• Для внутренних функций/сервисов: logger = logging.getLogger('mes').
• Перед выполнением: logger.info('fn:start ...').
• После успеха: logger.info('fn:done ...').
• Ошибки: logger.exception('fn:error ...') и пробрасывать дальше.

Release discipline (версия и changelog)

• После каждого принятого набора правок:
  • Обновить CHANGELOG.md в секции [Unreleased] (Added/Changed/Fixed).
  • В конце ответа всегда писать: “Нужно ли поднять версию? Рекомендация: …”.
• Правило bump (SemVer):
  • UI/шаблоны/стили/тексты → PATCH (x.y.Z).
  • Логика/вьюхи/сервисы/модели/миграции/доступы → MINOR (x.Y.0).
  • Изменения данных/совместимости → обсудить MAJOR (X.0.0), даже если проект ещё в 0.x.

SHOULD — правила, которые желательно соблюдать

Комментарии

• Python/бекенд: добавлять поясняющие комментарии там, где есть бизнес‑логика, транзакции, конкурентность, фоновые задачи, сложные алгоритмы (BOM, списания, начисления).
  • Комментарии нейтральные: описывают поведение/причину, без личных формулировок.
• Django HTML‑шаблоны: не добавлять template‑комментарии ({# ... #}).

Стиль и конвенции

• Держаться стиля соседних файлов (структура, именование, импорты, форматирование).
• Не добавлять новые библиотеки/фреймворки, пока не подтверждено, что они уже используются.

UI

• Если добавляется новая UI‑таблица — по умолчанию делать сортируемой (если это не мешает UX).

Назначение станков и цехов пользователю

• Привязка через профиль сотрудника:
  • Machines: закреплённые станки (для операторов).
  • Allowed workshops: доступные цеха (ограничение видимости/действий).
  • Is readonly: режим “только просмотр”.