strprfcrm/docs/refactor/tz-stock-availability.md

ТЗ: Модуль Склад

Связанные документы:

• План реорганизации
• Карта нового меню
• Исходное ТЗ
• ТЗ: Каталог общий
• ТЗ: Запчасти

1. Назначение

Склад — новый модуль для учета МАФ/позиций, которые есть на складе или заказаны.

Модуль должен быть реализован полностью по образцу раздела Запчасти, с адаптацией под МАФ/позиции из Каталог общий.

2. Статус

Статус модуля: ядро реализовано, ожидает пользовательской проверки.

Реализованы Наличие, Заказы, карточка позиции, бронирование, списание, отмена, история движений, импорт и постоянные права. PDF-экспорт ожидает согласованного шаблона.

3. Место в меню

Целевое меню:

Склад
├── Наличие
└── Заказы

Требования:

• добавить верхний пункт Склад;
• добавить пункты Наличие и Заказы;
• рабочие страницы размещаются под префиксом маршрутов stock;
• выбранный год в CRM не влияет на отображение и данные модуля;
• техническое имя маршрутов, таблиц и прав модуля: stock.

4. Права доступа

Требования из исходного ТЗ:

Подраздел	Доступ
Наличие	Видно всем пользователям
Заказы	Видит только админ и помощник руководителя (assistant_head)

Реализованные права:

• штатные авторизованные роли получают просмотр наличия, бронирование, списание и отмену;
• просмотр и управление заказами, а также импорт доступны администратору и assistant_head;
• роль помощник руководителя в системе соответствует assistant_head.

5. Подраздел Наличие

Назначение:

• отображать список МАФ/позиций, у которых есть наличие на складе.

Правило вывода:

• показывать МАФ, у которых есть хотя бы одна запись в подвкладке Заказы;
• в итоговом списке основное внимание на позициях с остатком на складе больше 0.

Колонки:

Колонка	Источник
Картинка	Каталог общий
Артикул	Каталог общий
Наименование	Каталог общий
Характеристики	Каталог общий
Ед. измерения	Каталог общий
Кол-во в наличии	Подвкладка Заказы
Забронировано	Функция бронирования
Остаток фактический	Кол-во в наличии минус забронировано и списано
Заказано	Сумма позиций со статусом заказан
Примечание	Добавление или импорт

Функционал:

• список наличия;
• поиск и фильтры;
• переход в карточку позиции по двойному клику;
• экспорт в PDF всех позиций в наличии;
• отображение фактического остатка;
• отображение количества в бронях;
• отображение заказанного количества.

6. Карточка позиции

Карточка открывается из Наличие двойным кликом.

Нередактируемые поля:

• картинка;
• артикул;
• наименование;
• характеристики;
• единица измерения;
• количество в наличии;
• забронировано;
• остаток фактический;
• заказано;
• примечание.

Функционал карточки:

• отображение остатков внизу карточки аналогично Запчастям;
• список активных броней;
• история бронирований и списаний;
• кнопка Забронировать;
• действие Списать;
• действие Отменить бронь.

7. Бронирование

Кнопка Забронировать открывает модальное окно.

Поля:

• менеджер из выпадающего списка;
• количество;
• примечание.

Правила:

• нельзя забронировать больше доступного остатка;
• при попытке превышения показывать ошибку Такого кол-ва нет в наличии;
• после бронирования запись появляется в списке Забронировано.

Список Забронировано:

• менеджер;
• количество;
• номер заказа или заказов;
• примечание;
• действие Списать;
• действие Отменить бронь.

8. Списание

Списание выполняется по активной брони.

Правила:

• количество списывается с соответствующих заказов;
• сохраняется история, куда ушла позиция;
• сохраняется история, из какого заказа списана позиция;
• фиксируется пользователь и время операции;
• после списания фактический остаток пересчитывается.

9. Отмена брони

Правила:

• отмена возвращает количество в доступный остаток;
• история отмены сохраняется;
• отмененная бронь не участвует в расчете активного забронированного количества.

10. Подраздел Заказы

Назначение:

• ручное добавление складских заказов;
• импорт складских заказов;
• источник данных для расчета наличия.

Поля заказа:

Поле	Описание
Номер заказа	Вводится вручную
Артикул	Артикул позиции из общего каталога
Статус заказа	на складе / заказан / отгружено
Кол-во заказано	Вводится вручную
Остаток	Фактический остаток с учетом бронирований и списаний
Примечание	Ручной ввод или импорт
Дата добавления	Заполняется автоматически

Функционал:

• список заказов;
• создание заказа;
• редактирование заказа;
• импорт;
• изменение статуса;
• массовый перевод всех заказанных позиций с выбранным номером заказа в статус на складе;
• связь с позицией общего каталога;
• расчет остатка по заказу;
• отображение активных броней.

11. Экспорт

Требования:

• в Наличие должна быть кнопка Экспорт;
• экспорт выполняется в PDF;
• экспортируются все позиции в наличии;
• PDF формируется по отдельному шаблону;
• шаблон PDF нужно подготовить отдельно.

12. Связи

Модуль	Связь	Требование
Каталог общий	Источник картинки, артикула, наименования, характеристик, ед. изм.	Обязательная связь.
График отгрузок / График заказов	Данные об отгрузках	Уточнить после реализации графиков.
Запчасти	Эталон логики	Использовать паттерны реализации.

13. Модель данных

Реализация использует следующие соответствия:

Запчасти	Склад	Таблица
SparePart	CommonCatalogItem	common_catalog_items
SparePartOrder	StockOrder	stock_orders
Reservation	StockReservation	stock_reservations
InventoryMovement	StockMovement	stock_movements

Отдельная таблица остатков не создаётся: физическое наличие, активная бронь, доступный остаток и заказанное количество рассчитываются из заказов и броней. Заказ связан с общей позицией по common_catalog_item_id; при импорте позиция разрешается по уникальному артикулу общего каталога.

14. Отложенная функциональность

• PDF-шаблон;
• интеграция с графиком отгрузок;

Ядро склада, финальная схема таблиц и постоянные permissions входят в текущую реализацию.

15. Этапы реализации

• Разобрать текущие модели и сервисы Запчасти.
• Составить карту соответствия сущностей Запчасти -> Склад.
• Согласовать имя модуля в маршрутах и таблицах.
• Спроектировать таблицы.
• Добавить модели.
• Реализовать Заказы.
• Реализовать Наличие.
• Реализовать карточку позиции.
• Реализовать бронирование.
• Реализовать списание.
• Реализовать отмену брони.
• Реализовать историю.
• Реализовать импорт.
• Реализовать PDF-экспорт.
• Настроить права доступа.
• Покрыть расчеты остатков тестами.

16. Критерии приемки

• В меню есть Склад.
• Есть подвкладки Наличие и Заказы.
• Наличие доступно всем пользователям.
• Заказы доступны админу и помощнику руководителя.
• помощник руководителя соответствует роли assistant_head.
• Позиции берут справочные данные из Каталог общий.
• Нельзя забронировать больше доступного остатка.
• Списание уменьшает остаток соответствующего заказа.
• Отмена брони возвращает доступный остаток.
• История операций сохраняется.
• PDF-экспорт формируется по шаблону после его согласования и передачи в проект.

17. Открытые вопросы

• Какой точный PDF-шаблон нужен для экспорта?
• Как будет выглядеть связь с графиком отгрузок/заказов?