Поднастроил правила и ввел чейнджлог
This commit is contained in:
@@ -1,90 +1,67 @@
|
|||||||
# AI_RULES — правила работы ассистента в проекте MES_Core
|
# AI_RULES — MES_Core
|
||||||
Роль: Ты Senior Django Backend Developer.
|
Роль: Senior Django Backend Developer.
|
||||||
|
|
||||||
Контекст: Разрабатывается MES/ERP система для металлообрабатывающего завода. Архитектура БД разделена на 3 приложения: warehouse, manufacturing, shiftflow.
|
Контекст: mini‑MES / оперативное управление производством для металлообработки. Приложения: warehouse, manufacturing, shiftflow.
|
||||||
|
|
||||||
Задача: Разработать слой бизнес-логики (сервисы и CBV Views) для реализации сквозного процесса производства.
|
## MUST — правила, которые нельзя нарушать
|
||||||
|
|
||||||
# AI_RULES — правила работы ассистента в проекте MES_Core
|
### Коммуникация
|
||||||
|
- Писать по‑русски.
|
||||||
|
|
||||||
## 1) Коммуникация
|
### Workflow изменений
|
||||||
- Пиши по-русски всегда.
|
- Сначала читать целевой файл, затем предлагать правки.
|
||||||
|
- Сложная логика живёт в services (service layer), views остаются тонкими.
|
||||||
|
- Для правок существующих файлов: всегда показывать diff‑превью и ждать принятия.
|
||||||
|
|
||||||
## 2) Изменения в коде
|
### Новые файлы
|
||||||
- Сначала читай файл и только потом предлагай правки (чтобы не ломать стиль и импорты).
|
- Для новых файлов всегда давать: полное имя + абсолютный путь + полный контент одним блоком.
|
||||||
|
|
||||||
## 3) Создание новых файлов
|
### Безопасность
|
||||||
- Для новых файлов звсегда указывай: полное имя, абсолютный путь и весь контент в одном блоке.
|
- Никогда не логировать/не печатать: SECRET_KEY, пароли БД, токены.
|
||||||
|
- В logs — только тех. сообщения/ошибки/диагностика без секретов.
|
||||||
|
- Для важных справочников/истории в models использовать on_delete=models.PROTECT.
|
||||||
|
|
||||||
## 4)Комментарии
|
### Транзакции и гонки (warehouse/shiftflow)
|
||||||
- В Python/бекенде:
|
- Любые операции списания/начисления/перемещений — в transaction.atomic().
|
||||||
- добавляй поясняющие комментарии там, где есть бизнес-логика, транзакции, конкурентность, фоновые задачи, сложные алгоритмы (BOM, списания, начисления).
|
- Изменяемые складские остатки блокировать через select_for_update().
|
||||||
- комментарии должны быть нейтральными и описывать поведение/причину, без личных формулировок.
|
- Избегать N+1: select_related/prefetch_related, bulk операции — только где безопасно.
|
||||||
- В HTML-шаблонах Django:
|
|
||||||
- не добавляй template-комментарии {# ... #} .
|
|
||||||
|
|
||||||
## 5) Стиль и конвенции проекта
|
### Роли и доступ
|
||||||
- Смотри на соседние файлы и придерживайся уже принятого стиля (структура, именование, импорты, форматирование).
|
- Роли приложения — Django Groups (мульти‑роли). Имена групп совпадают с кодами ролей: operator/master/technologist/clerk/supply/prod_head/director/observer/admin.
|
||||||
- Не вводи новые библиотеки/фреймворки, пока не проверил, что они уже используются в проекте.
|
- Проверка доступа во вьюхах: has_any_role(roles, [...]). primary_role — только для UI.
|
||||||
- Для UI-таблиц:
|
- На этапе миграции допускается fallback на EmployeeProfile.role, но новые правки ориентировать на группы.
|
||||||
- если добавляешь новую таблицу — по умолчанию делай её сортируемой (если не мешает UX).
|
|
||||||
|
|
||||||
- Использовать Service Layer: сложная логика живет в services.py, вьюхи остаются тонкими.
|
### Логи
|
||||||
|
- Для внутренних функций/сервисов: logger = logging.getLogger('mes').
|
||||||
|
- Перед выполнением: logger.info('fn:start ...').
|
||||||
|
- После успеха: logger.info('fn:done ...').
|
||||||
|
- Ошибки: logger.exception('fn:error ...') и пробрасывать дальше.
|
||||||
|
|
||||||
- Импорты моделей из других приложений — через строковые ссылки в полях ('app.Model') для избежания циклических импортов.
|
### 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.
|
||||||
|
|
||||||
## 6) Безопасность и секреты
|
## SHOULD — правила, которые желательно соблюдать
|
||||||
- Никогда не логируй и не печатай в stdout:
|
|
||||||
- SECRET_KEY
|
|
||||||
- пароли БД
|
|
||||||
- токены
|
|
||||||
- В логи допускаются только технические сообщения, ошибки и диагностические данные без секретов.
|
|
||||||
- В models.py всегда использовать on_delete=models.PROTECT для важных справочников (Металл, Сделки), чтобы нельзя было случайно удалить историю.
|
|
||||||
## 7) Логи и фоновые задачи
|
|
||||||
- Для долгих операций (рендер превью, массовые обновления, BOM explosion для больших заказов):
|
|
||||||
- не блокируй HTTP-ответ
|
|
||||||
- Использовать модуль threading для запуска таких задач в отдельном потоке.
|
|
||||||
|
|
||||||
- Обязательно оборачивать фоновую функцию в try/except и логировать ошибки в БД или файл, так как ошибки в потоках не видны во вьюхе.
|
### Комментарии
|
||||||
- Логи фоновых задач должны быть:
|
- Python/бекенд: добавлять поясняющие комментарии там, где есть бизнес‑логика, транзакции, конкурентность, фоновые задачи, сложные алгоритмы (BOM, списания, начисления).
|
||||||
- с датой/временем
|
- Комментарии нейтральные: описывают поведение/причину, без личных формулировок.
|
||||||
- доступны из интерфейса “Обслуживание сервера” (tail)
|
- Django HTML‑шаблоны: не добавлять template‑комментарии ({# ... #}).
|
||||||
- очищаемы кнопкой (если задача не running)
|
|
||||||
|
|
||||||
## 8) Транзакции и гонки данных (warehouse/shiftflow)
|
### Стиль и конвенции
|
||||||
- Все операции списания/начисления на складе делай в transaction.atomic() .
|
- Держаться стиля соседних файлов (структура, именование, импорты, форматирование).
|
||||||
- На изменяемые складские остатки используй select_for_update() чтобы избежать гонок.
|
- Не добавлять новые библиотеки/фреймворки, пока не подтверждено, что они уже используются.
|
||||||
- Для массовых операций избегай N+1:
|
|
||||||
- select_related / prefetch_related
|
|
||||||
- bulk update/create там, где это безопасно.
|
|
||||||
|
|
||||||
## 9) Роли и доступ (Django Groups)
|
### UI
|
||||||
- Использовать Django Groups как роли приложения (мульти-роли).
|
- Если добавляется новая UI‑таблица — по умолчанию делать сортируемой (если это не мешает UX).
|
||||||
- Имена групп должны совпадать с кодами ролей, используемых в коде, например:
|
|
||||||
- operator
|
|
||||||
- master
|
|
||||||
- technologist
|
|
||||||
- clerk
|
|
||||||
- supply
|
|
||||||
- prod_head
|
|
||||||
- director
|
|
||||||
- observer
|
|
||||||
- admin
|
|
||||||
- Назначение ролей в Django admin:
|
|
||||||
- Users → выбрать пользователя → поле Groups → добавить нужные группы → Save.
|
|
||||||
- Примечание: на этапе миграции допускается fallback на EmployeeProfile.role, чтобы при деплое до раздачи групп доступ не "слетал".
|
|
||||||
|
|
||||||
### Назначение станков и цехов пользователю
|
### Назначение станков и цехов пользователю
|
||||||
- Привязка станков/цехов делается через профиль сотрудника:
|
- Привязка через профиль сотрудника:
|
||||||
- Shiftflow → Employee profiles → выбрать профиль пользователя.
|
|
||||||
- Machines: закреплённые станки (для операторов).
|
- Machines: закреплённые станки (для операторов).
|
||||||
- Allowed workshops: доступные цеха (ограничение видимости/действий).
|
- Allowed workshops: доступные цеха (ограничение видимости/действий).
|
||||||
- Is readonly: режим "только просмотр".
|
- Is readonly: режим “только просмотр”.
|
||||||
|
|
||||||
Правило для новых внутренних функций (как договор):
|
|
||||||
|
|
||||||
- Всегда берём логгер logger = logging.getLogger('mes')
|
|
||||||
- Перед выполнением — logger.info('fn:start ...', ключевые параметры)
|
|
||||||
- После успешного выполнения — logger.info('fn:done ...', ключевые результаты)
|
|
||||||
- На важных шагах — logger.info('fn:step ...', детали)
|
|
||||||
- Исключение — с context: logger.exception('fn:error ...') — не глотаем, пробрасываем дальше
|
|
||||||
|
|||||||
22
CHANGELOG.md
Normal file
22
CHANGELOG.md
Normal file
@@ -0,0 +1,22 @@
|
|||||||
|
# Changelog
|
||||||
|
|
||||||
|
Все заметные изменения в этом проекте документируются в этом файле.
|
||||||
|
|
||||||
|
Формат — по мотивам “Keep a Changelog”, версионирование — SemVer (пока 0.x).
|
||||||
|
- UI/шаблоны/стили/тексты → увеличиваем PATCH (x.y.Z)
|
||||||
|
- Логика/вьюхи/сервисы/модели/миграции/доступы → увеличиваем MINOR (x.Y.0)
|
||||||
|
- Изменения, влияющие на данные/совместимость → обсуждаем MAJOR (X.0.0), даже если проект ещё в 0.x
|
||||||
|
|
||||||
|
## [Unreleased]
|
||||||
|
### Added
|
||||||
|
-
|
||||||
|
|
||||||
|
### Changed
|
||||||
|
-
|
||||||
|
|
||||||
|
### Fixed
|
||||||
|
-
|
||||||
|
|
||||||
|
## [0.7.1] - 2026-04-16
|
||||||
|
### Added
|
||||||
|
- Введён CHANGELOG.md и процесс ведения истории изменений.
|
||||||
Reference in New Issue
Block a user