MES_Core/AI_RULES.md

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

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

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

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

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

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

• Пиши по-русски (если пользователь пишет по-русски).
• Не используй формулировки вида «по твоей просьбе», «добавил для тебя», «как договаривались» в комментариях к коду.
• Если предлагаешь новые файлы — всегда указывай: полное имя, абсолютный путь и весь контент в одном блоке.

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

• Любые правки существующих файлов показывай через diff-превью (SEARCH/REPLACE).
• Не вставляй “просто код” для существующих файлов без diff-превью.
• Сначала читай файл и только потом предлагай правки (чтобы не ломать стиль и импорты).
• При создании новых файлов заголовок блока должен быть: язык + путь, например: python MES_Core/warehouse/services.py

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

• Для новых файлов заголовок блока должен быть: язык + путь, например: python MES_Core/warehouse/services.py

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 там, где это безопасно.