# ТЗ: Подрядчики и формирование спецификаций на монтаж

## 1. Цель

Добавить в систему учёт подрядчиков с индивидуальными прайсами на монтаж МАФ и возможность формировать Excel-спецификации на монтаж по площадке.

---

## 2. Раздел «Подрядчики» в Администрировании

### 2.1. Список подрядчиков

- В меню **Администрирование** добавить пункт **«Подрядчики»**.
- Страница представляет собой таблицу со списком всех подрядчиков.
- Кнопка **«Добавить подрядчика»** — открывает форму создания.
- Клик по строке — открывает карточку подрядчика на редактирование.
- Удаление подрядчиков не предусмотрено.
- Для подрядчика нужна возможность скрытия из выпадающих списков без удаления из справочника.

### 2.2. Карточка подрядчика (создание/редактирование)

Поля (все редактируемые в режиме просмотра):

| # | Поле | Тип | Примечание |
|---|------|-----|------------|
| 1 | Наименование подрядчика | текст | короткое имя для выпадающих списков |
| 2 | Юридическое имя | текст | полное юр. наименование |
| 3 | № договора | текст | |
| 4 | Дата договора | дата | |
| 5 | ФИО руководителя | текст | |
| 6 | Форма организации | select | ИП / ООО / Самозанятый |
| 7 | Налог | select | Без НДС / 5% / 7% / 15% / 22% |
| 8 | Шапка в договоре | textarea (большое поле) | используется в шаблоне спецификации |

Все 8 полей обязательны для создания и сохранения подрядчика.

---

## 3. Вкладка «Цены монтажа» в карточке подрядчика

Вкладка **«Цены монтажа»** доступна ролям **Администратор** и **Помощник руководителя**. Эти же роли могут редактировать цены монтажа и наименования для спецификации.

### 3.1. Таблица цен

Внутри карточки подрядчика — вкладка **«Цены монтажа»**.

Таблица формируется на основе **каталога МАФ текущего года**. Для каждого нового года прайс подрядчика начинается пустым: каталог текущего года выводится, а поля «Наименование по спецификации» и «Цена монтажа» изначально пустые.

Колонки:

| # | Колонка | Источник |
|---|---------|----------|
| 1 | Картинка МАФ | каталог МАФ текущего года |
| 2 | Артикул МАФ | каталог МАФ текущего года |
| 3 | Номер номенклатуры | каталог МАФ текущего года |
| 4 | Наименование по спецификации | заполняется импортом или руками (уникально для подрядчика) |
| 5 | Цена монтажа | заполняется импортом или руками (уникально для подрядчика) |

У каждого подрядчика — **собственный набор значений** для колонок 4 и 5.

Редактирование прямо в строке таблицы не требуется. Редактирование значений колонок 4 и 5 выполняется через модальное окно редактирования строки либо через импорт.

Если МАФ убран из каталога, его цена у подрядчика сохраняется и строка остаётся в списке с пометкой **«МАФ недоступен»**.

### 3.2. Формат файла импорта/экспорта

Импорт и экспорт используют **единый набор колонок** (5 колонок), полностью совпадающий с отображением в таблице «Цены монтажа»:

1. Картинка МАФ
2. Артикул МАФ
3. Номер номенклатуры
4. Наименование по спецификации
5. Цена монтажа

Редактируемые при импорте: только **«Наименование по спецификации»** и **«Цена монтажа»**. Остальные колонки (картинка, артикул, номер номенклатуры) — справочные; берутся из каталога МАФ и при импорте игнорируются (используются только для идентификации строки по артикулу).

Пустые значения при импорте:

- пустая ячейка «Наименование по спецификации» очищает поле у подрядчика;
- пустая ячейка «Цена монтажа» очищает цену и сохраняет значение `0`.

### 3.3. Импорт цен

Кнопка **«Импортировать/обновить цены»**.

**Логика:**

- По **артикулу МАФ** (колонка 2) находим строку в таблице подрядчика.
- Сравниваем значения «Наименование по спецификации» и «Цена монтажа».
- Если значения отличаются — обновляем.
- Если совпадают — пропускаем.
- Если артикула в каталоге подрядчика нет — пишем в **лог ошибок** и продолжаем.
- По окончании показываем сводку: обновлено / без изменений / ошибки.

### 3.4. Экспорт цен

Кнопка **«Экспортировать»** — выгружает таблицу цен в Excel в формате, описанном в п. 3.2. Файл полностью совместим с импортом: можно поправить значения в редактируемых колонках и загрузить обратно.

---

## 4. Формирование спецификации на площадке

### 4.1. Кнопка «Спецификация»

- В карточке площадки добавить кнопку **«Спецификация»** сразу после кнопки **«ТН»**.
- **Видимость:** только роли **Администратор** и **Помощник руководителя**.
- **Условие активации:** в площадке выбран как минимум **1 МАФ**. Иначе — сообщение «Выберите хотя бы один МАФ».

### 4.2. Модальное окно формирования

Поля (каждое с подписью сверху):

| # | Поле | Тип | Поведение |
|---|------|-----|-----------|
| 1 | Подрядчик | select | список из «Наименование подрядчика» |
| 2 | № спецификации | текст | ручной ввод |
| 3 | Дата спецификации | date | по умолчанию — сегодня, редактируемо |
| 4 | Начало работ | date | пусто по умолчанию |
| 5 | Окончание работ | date | авто = «Начало работ» + 4 календарных дня при заполнении п.4, редактируемо |
| 6 | Кнопка «Сформировать» | — | генерирует Excel |

### 4.3. Агрегация МАФ для спецификации

- В площадке МАФ может быть расписан построчно. В спецификации **одинаковые артикулы суммируются** в одну строку с указанием количества.
- Стоимость позиции = Цена монтажа × Количество.
- Если у выбранного подрядчика для одного или нескольких МАФ не указана цена монтажа, формирование спецификации блокируется. Пользователю показывается ошибка со списком проблемных артикулов. Документ не формируется.

---

## 5. Заполнение Excel-шаблона спецификации

Заказчиком предоставлен шаблон (Приложение «Форма Спецификации»). Привязка полей:

| Строка | Содержимое | Источник |
|--------|------------|----------|
| 2 | № договора и дата договора | карточка подрядчика |
| 5 | № спецификации | модальное окно |
| 9 | «Шапка в договоре» | карточка подрядчика |
| 12 | `г. Москва, <Название площадки>` | площадка |
| 14+ | Таблица позиций (см. ниже) | каталог подрядчика + площадка |
| 21 | Итого = сумма колонки «Стоимость» | расчёт |
| 22 | НДС (только если налог ≠ «Без НДС») | расчёт по формуле |
| 23 | Итого суммой + прописью | расчёт + пропись |
| 24 | «Без НДС» или «В т.ч. НДС X%» + сумма | карточка подрядчика |
| 25, 26 | Начало работ / Окончание работ | модальное окно |
| 27 | № договора и дата | карточка подрядчика |
| 30 | Юридическое имя | карточка подрядчика |
| 31 | Должность подписанта (см. маппинг) | карточка подрядчика |
| 34 | ФИО руководителя | карточка подрядчика |

> В исходном ТЗ п. xiii была указана «Строка 21». Подтверждено, что это опечатка: верная строка для должности подписанта — **строка 31**.

### 5.1. Таблица позиций (начиная со строки 14)

Колонки:

1. **№ п/п** — автонумерация
2. **Наименование МАФ** — «Наименование по спецификации» из цен подрядчика
3. **Цена** — «Цена монтажа» из цен подрядчика
4. **Ед. изм** — из каталога МАФ
5. **Кол-во** — сумма одинаковых артикулов по площадке
6. **Стоимость** — Цена × Кол-во

### 5.2. Расчёт НДС (строка 22)

Только если в карточке подрядчика выбран налог ≠ «Без НДС»:

| Ставка | Формула |
|--------|---------|
| 5% | ИТОГО / 1,05 × 0,05 |
| 7% | ИТОГО / 1,07 × 0,07 |
| 15% | ИТОГО / 1,15 × 0,15 |
| 22% | ИТОГО / 1,22 × 0,22 |

Если «Без НДС» — **строка 22 оставляется пустой полностью** (не формируется).

Строка 24 при этом содержит пометку **«Без НДС»**. Для ставок НДС строка 24 содержит текст **«В т.ч. НДС X%»** и рассчитанную сумму НДС.

### 5.3. Формат суммы прописью (строка 23)

Формат: `157 300 рублей 00 копеек (Сто пятьдесят семь тысяч триста рублей 00 копеек)`.

Правила:

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

### 5.4. Маппинг «Форма организации» → подпись (строка 31)

| Форма | Текст |
|-------|-------|
| ИП | Индивидуальный предприниматель |
| ООО | Генеральный директор |
| Самозанятый | Самозанятый |

---

## 6. Модель данных (предварительно)

Новые сущности:

- `contractors` — карточка подрядчика (8 полей + признак скрытия из выпадающих списков + timestamps).
- `contractor_installation_prices` — цены монтажа: `contractor_id`, `product_sku_id`, `catalog_year`, `name_in_spec`, `price`.

История сформированных спецификаций не хранится. Документ формируется и скачивается «на лету»; дальнейшее хранение выполняется вне CRM.

**Мультигодовая структура:** цены монтажа привязаны к году каталога. При наступлении нового года прайс подрядчика не копируется из прошлого года; значения для нового каталога заполняются заново вручную или импортом.

---

## 7. Роли и права

- Раздел «Подрядчики»: **Администратор** (полный доступ).
- Кнопка «Спецификация» на площадке: **Администратор**, **Помощник руководителя**.
- Вкладка «Цены монтажа»: просмотр и редактирование — **Администратор**, **Помощник руководителя**.

---

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

Часть вопросов закрыта ответами заказчика и перенесена в это ТЗ.

Остаются открытыми:

- формат вывода дат в Excel-шаблоне;
- точное расположение кнопки «Спецификация» в интерфейсе карточки площадки;
- нужны ли поиск, фильтрация, сортировка и пагинация в таблице «Цены монтажа».

Развёрнутый список вопросов к заказчику: [contractors-questions.md](./contractors-questions.md). Ответы заказчика: [contractors-answers.md](./contractors-answers.md).