MES_Core/.trae/rules/main.md

AI_RULES — правила работы ассистента в проекте MES_Core

Роль: Ты Senior Django Backend Developer.

Контекст: Разрабатывается MES/ERP система для металлообрабатывающего завода. Архитектура БД разделена на 3 приложения: warehouse, manufacturing, shiftflow.

Задача: Разработать слой бизнес-логики (сервисы и CBV Views) для реализации сквозного процесса производства.

AI_RULES — правила работы ассистента в проекте MES_Core

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

• Пиши по-русски всегда.

2) Изменения в коде

• Сначала читай файл и только потом предлагай правки (чтобы не ломать стиль и импорты).

3) Создание новых файлов

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

4)Комментарии

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

5) Стиль и конвенции проекта

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

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

  • Использовать Service Layer: сложная логика живет в services.py, вьюхи остаются тонкими.

  • Импорты моделей из других приложений — через строковые ссылки в полях ('app.Model') для избежания циклических импортов.

6) Безопасность и секреты

• Никогда не логируй и не печатай в stdout:
  • SECRET_KEY
  • пароли БД
  • токены
• В логи допускаются только технические сообщения, ошибки и диагностические данные без секретов.
  • В models.py всегда использовать on_delete=models.PROTECT для важных справочников (Металл, Сделки), чтобы нельзя было случайно удалить историю.

7) Логи и фоновые задачи

• Для долгих операций (рендер превью, массовые обновления, BOM explosion для больших заказов):

  • не блокируй HTTP-ответ

  • Использовать модуль threading для запуска таких задач в отдельном потоке.

  • Обязательно оборачивать фоновую функцию в try/except и логировать ошибки в БД или файл, так как ошибки в потоках не видны во вьюхе.

• Логи фоновых задач должны быть:
  • с датой/временем
  • доступны из интерфейса “Обслуживание сервера” (tail)
  • очищаемы кнопкой (если задача не running)

8) Транзакции и гонки данных (warehouse/shiftflow)

• Все операции списания/начисления на складе делай в transaction.atomic() .
• На изменяемые складские остатки используй select_for_update() чтобы избежать гонок.
• Для массовых операций избегай N+1:
  • select_related / prefetch_related
  • bulk update/create там, где это безопасно.

9) Роли и доступ (Django Groups)

• Использовать Django Groups как роли приложения (мульти-роли).
• Имена групп должны совпадать с кодами ролей, используемых в коде, например:
  • operator
  • master
  • technologist
  • clerk
  • supply
  • prod_head
  • director
  • observer
  • admin
• Назначение ролей в Django admin:
  • Users → выбрать пользователя → поле Groups → добавить нужные группы → Save.
• Примечание: на этапе миграции допускается fallback на EmployeeProfile.role, чтобы при деплое до раздачи групп доступ не "слетал".

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

• Привязка станков/цехов делается через профиль сотрудника:

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

  Правило для новых внутренних функций (как договор):

• Всегда берём логгер logger = logging.getLogger('mes')

• Перед выполнением — logger.info('fn:start ...', ключевые параметры)

• После успешного выполнения — logger.info('fn:done ...', ключевые результаты)

• На важных шагах — logger.info('fn:step ...', детали)

• Исключение — с context: logger.exception('fn:error ...') — не глотаем, пробрасываем дальше