# ТЗ: Модуль Склад наличие

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

- [План реорганизации](plan.md)
- [Карта нового меню](menu.md)
- [Исходное ТЗ](source-tz.md)
- [ТЗ: Каталог общий](tz-catalog-common.md)
- [ТЗ: Запчасти](tz-spare-parts.md)

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

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

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

## 2. Статус

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

На первом этапе в меню добавляются заглушки:

- `Наличие`;
- `Заказы`.

Полная реализация выполняется после согласования модели данных и переноса паттернов из `Запчасти`.

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

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

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

Требования:

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

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

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

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

На первом этапе:

- текущую систему прав не перерабатывать;
- заглушки `Наличие` и `Заказы` показывать всем авторизованным пользователям;
- при реализации добавить/назначить права согласно таблице выше.
- роль `помощник руководителя` в системе соответствует `assistant_head`.

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

Назначение:

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

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

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

Колонки:

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

Функционал:

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

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

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

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

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

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

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

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

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

Поля:

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

Правила:

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

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

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

## 8. Списание

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

Правила:

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

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

Правила:

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

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

Назначение:

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

Поля заказа:

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

Функционал:

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

## 11. Экспорт

Требования:

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

## 12. Связи

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

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

Проектируется по образцу `Запчасти`.

Предварительные сущности:

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

Открыто:

- точные имена таблиц и моделей;
- использовать ли отдельную сущность наличия или рассчитывать ее из заказов;
- как связать заказ склада с позицией общего каталога: по `product_id`, артикулу или обоим полям.

## 14. Что не входит в первый этап

- полная реализация склада;
- проектирование финальной БД;
- PDF-шаблон;
- интеграция с графиком отгрузок;
- новые постоянные permissions.

Первый этап:

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

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

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

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

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

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

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