# Техническое задание: обработчик брака

Версия ТЗ: 1.3  
Дата: 28.10.2026 10:44 МСК  
Источник логики: Google Sheets «Обработчик», вкладки «Товары», «ОБРАБОТКА», листы менеджеров, `NO SEGMENT`, `SPLIT`, «списки», «Приоритет».

## 1. Цель

Создать в разделе «Брак» отдельное рабочее место «Обработчик», пригодное для телефона и компьютера. Оно должно:

1. показывать очередь физических БК-единиц из текущих складских остатков;
2. позволять зафиксировать осмотр и результат обработки;
3. хранить все повторные обработки как отдельные события;
4. связывать событие с текущим остатком без уничтожения истории после перемещения или выбытия товара;
5. распределять обработанные позиции менеджерам по управляемым правилам;
6. временно принимать полный XLSX-экспорт действующей Google-таблицы;
7. импортировать уже накопленную историю обработки.

## 2. Что установлено в действующем файле

### 2.1. Вкладка «Товары»

Это снимок складских остатков. Поля соответствуют используемой приложением выгрузке: сегмент/менеджер, полная номенклатура с БК-ключом, классификация, вид номенклатуры, склад, описание брака, заключение СЦ, даты, поставщик, остаток, себестоимость и сумма брака.

### 2.2. Вкладка «ОБРАБОТКА»

Одна строка — одно событие работы с конкретной физической единицей. Ручные поля: обработчик, дата, состояние, упаковка, инструкция, гарантийный талон, комплектация, СИ, УКЗ, серийный номер, описание дефектов, фото, заключение СЦ, вид брака, признак ячейки обработки и вид работы.

Себестоимость, классификация, описание 1С, вид номенклатуры, вес, поставщик и менеджер подтягиваются из «Товары» через `MAP` + `XLOOKUP` по полному наименованию.

Одинаковая БК-единица встречается несколько раз. Эти строки означают повторную обработку и не являются техническими дублями.

### 2.3. Распределение

Листы менеджеров фильтруют «ОБРАБОТКА» по вычисленному менеджеру и дате. `NO SEGMENT` собирает строки без менеджера. `SPLIT` содержит отдельное распределение по поставщику. Лист «Приоритет» содержит заготовки весов по стоимости, виду брака и ВГХ.

В текущем источнике формула столбца Y «Менеджер» имеет `#REF!`: массив не разворачивается из-за заполненной Y38664. Поэтому импорт обязан хранить исходное значение, но не использовать его как единственную истину.

## 3. Термины и идентификаторы

- **Номенклатура** — модель/карточка товара.
- **БК-единица** — физический экземпляр. Основной внешний ключ берётся из начала полного наименования, например `8027747-БК-1233788`.
- **Снимок остатков** — состояние товара и склада на дату выгрузки. Это не журнал движений.
- **Событие обработки** — неизменяемый факт осмотра БК-единицы в определённое время определённым сотрудником.
- **Назначение менеджеру** — отдельное текущее решение, которое не должно переписывать исходного менеджера снимка или историю события.

## 4. Связь трёх контуров

### 4.1. Остатки

Отвечают на вопрос: «Где экземпляр находится сейчас, сколько он стоит и кто указан в текущей выгрузке?» При новом снимке прежние строки остаются в истории, текущим становится один последний снимок.

### 4.2. Обработчик

Отвечает на вопрос: «Кто, когда и что установил при осмотре?» Событие остаётся даже после перемещения или исчезновения экземпляра из текущих остатков.

### 4.3. Рабочее место менеджера

Отвечает на вопрос: «Кому назначено дальнейшее действие, что нужно сделать, в какой срок и с каким результатом?» Оно использует последнее релевантное событие обработки, текущее местонахождение и правила конкретного склада.

Связь строится по БК-единице. Точное полное наименование имеет приоритет, затем используется нормализованный БК-ключ. Код модели без номера физической единицы для автоматической связи недостаточен.

## 5. Статусы сверки с остатками

1. `exact_current` — точное совпадение полного наименования в текущем снимке.
2. `unit_key_current` — совпадение по нормализованному БК-ключу.
3. `ambiguous_current` — найдено несколько возможных текущих строк/товаров; нужна ручная сверка.
4. `not_in_current_stock` — экземпляра нет в текущих остатках. Это не ошибка импорта и не означает удаление истории.

Связь и текущий менеджер пересчитываются после каждой загрузки остатков. Поля самого события не меняются.

## 6. Импорт накопленной истории

### 6.1. Источник

Полный XLSX-экспорт Google Sheets. Импортируется только вкладка «ОБРАБОТКА», начиная с третьей строки. `НЕ РАЗМЕЩЕННЫЙ ТОВАР!` относится к будущей очереди исключений и не считается обработанной историей.

### 6.2. Проверки

- наличие вкладки и 25 ожидаемых колонок с учётом известных вариантов написания;
- непустая номенклатура;
- распознавание БК-ключа;
- безопасное чтение чисел с пробелом и запятой;
- дата сохраняется как дата/время; нераспознанный исходный текст не теряется;
- SHA-256 всего файла защищает от повторной загрузки неизменённого экспорта;
- SHA-256 строки показывает, изменилась ли существующая строка источника.

### 6.3. Повторная загрузка

Стабильный временный идентификатор — `spreadsheet_id + sheet + source_row`. Неизменённые строки не дублируются, изменённые обновляются. Исчезнувшие строки не удаляются: они получают признак отсутствия в последнем экспорте. До перехода на собственные постоянные ID строки Google-таблицы нельзя без необходимости сортировать или вставлять в середину массива.

## 7. Правила распределения менеджерам

Хранить раздельно:

1. менеджера/сегмент из снимка остатков;
2. вычисленное значение из источника обработчика;
3. фактическое назначение менеджеру в приложении;
4. пользователя, время и причину ручного изменения.

Правила должны быть версионируемыми и применяться по приоритету:

1. ручное действующее назначение;
2. специальное правило поставщика (`SPLIT`);
3. правило сегмента/вида номенклатуры;
4. допустимые склады менеджера;
5. очередь «Без менеджера».

Перемещение между группами складов не удаляет задачу, но может менять доступные действия. Для «Наших складов», поставщика, ПВЗ, Депо, «21Век Сервис» и иных складов должны быть отдельные матрицы действий.

## 8. Интерфейс компьютера

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

## 9. Интерфейс телефона

- поиск или сканирование БК/штрихкода на первом экране;
- одна карточка на экран без широкой таблицы;
- крупные элементы выбора из справочников;
- обязательные поля показываются сразу, дополнительные раскрываются секциями;
- фото создаётся камерой телефона и привязывается к событию;
- «Сохранить черновик» и «Завершить обработку» — разные действия;
- защита от двойного нажатия и повторной отправки;
- при потере сети черновик сохраняется локально, завершение требует подтверждённой записи сервером.

## 10. Минимальный состав карточки обработки

Обязательные поля первого этапа:

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

Условно обязательные поля зависят от категории и действия: комплектность, упаковка, инструкция, гарантийный талон, СИ, УКЗ, серийный номер, фото и заключение СЦ.

Статусы карточки:

- «Не обработан» — события ещё нет;
- «Требует заполнения» — есть черновик или неполная историческая запись;
- «Обработан» — обязательные поля заполнены или старая запись содержит достаточные признаки выполненной работы.

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

### Этап 0 — выполненный старт

- новый пункт меню «Обработчик»;
- таблицы импорта и событий;
- импорт старой вкладки «ОБРАБОТКА»;
- защита от повторного файла и обновление изменённых строк;
- сверка с текущими остатками;
- просмотр, поиск, фильтры, пагинация и мобильное карточное отображение.
- ручное изменение импортированного события с защитой правок от следующего импорта;
- отдельное фактическое назначение менеджера и журнал ручных изменений.
- модальная карточка, черновик/завершение и цветная индикация статуса;
- статус обработки в списке текущих остатков.

### Этап 1 — собственный ввод

- выполнено 28.10.2026: кнопка «Новая обработка», асинхронный поиск в текущих остатках, явный выбор складской строки, создание черновика и снимок исходных данных;
- выполнено 28.10.2026: предупреждение о прежних обработках, переход в свой черновик и история одной БК-единицы;
- выполнено 28.10.2026: управляемые администратором справочники вместо свободного текста;
- выполнено 28.10.2026: множественная загрузка фото с камеры телефона и автономный мобильный черновик;
- история одной БК-единицы.

### Этап 2 — назначение и рабочие места

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

### Этап 3 — синхронизация и отказ от Google-обработчика

- безопасное чтение Google Sheets по сервисной учётной записи или API;
- журнал запусков, контроль версии источника и уведомление об ошибках;
- двусторонняя запись допускается только после определения владельца каждого поля и правил разрешения конфликтов;
- после приёмки собственного ввода Google Sheets переводится в режим архива/контроля.

## 12. Критерии приёмки этапа 0

1. Повторный импорт одного файла не увеличивает число событий.
2. Повторная обработка одной БК-единицы отображается несколькими событиями.
3. Исчезновение товара из нового снимка остатков не удаляет событие.
4. После нового снимка автоматически меняются только связь с остатком и текущий менеджер.
5. Ошибка формулы менеджера в Google Sheets не блокирует импорт.
6. Нераспознанная дата сохраняется исходным текстом и попадает в предупреждение.
7. На телефоне строки выводятся карточками без горизонтальной прокрутки.
8. Пользователь без права администрирования видит историю, но не загружает файл.
