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. Связи

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

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-шаблон нужен для экспорта?
• Как будет выглядеть связь с графиком отгрузок/заказов?