# Kufar: изученные требования и текущая граница модуля

Проверено 04.11.2026 по официальным источникам. Это справка для последующей реализации, а не утверждённая бизнес-логика.

## Реализация 2026.11.04.3

- Самостоятельный раздел /kufar; рабочие места менеджера/специалиста не изменяются.
- FTPS по IP 178.172.217.166 с проверкой сертификата streetbob.hostflyby.net. DNS исходного FTP-домена указывал на другой сервер. Пароль в Windows DPAPI, в документах и журналах отсутствует.
- В FTP-корне создан kufar.xml, каталог фото photo. Начальный XML пуст; успешно скачан обратно, проверен также HTTP на целевом IP с Host сайта.
- Публичные адреса http://kufar.strominvest.ru/kufar.xml и /photo требуют работоспособного DNS. При недоступности публичного XML отправка объявлений блокируется; FTP-сверка остаётся доступной.
- 275 прежних объявлений размещены вручную, подтверждено пользователем/скриншотом 04.11.2026. В XML их нет. Они учитываются отдельным подтверждаемым счётчиком. Свободно 25 мест до добавления новых записей.
- Ручные объявления не могут быть изменены или сняты через новый пустой XML. Их перенос требует отдельной проверки дублей и согласованного перехода на импорт; автоматического преобразования нет.
- Новые объявления: полный уникальный код БК/расп однозначно передаётся в UNID латиницей без дефисов (БК → BK, расп → RASP); исходный код сохраняется в описании и локальной привязке. выбор категории и обязательных характеристик из сохранённой официальной редакции 5, проверка точной номенклатуры в локальном текущем остатке брака/уценки.
- Настройка продавца в начальной форме — Минск, выбор района, телефон и контакт из предоставленного примера. Публикация в других населённых пунктах пока не реализована.
- Сверка обязательна до правок; локальные черновики, фото на хостинге, снятие и полная выгрузка по кнопке. Лимит 300 проверяется на полном файле вместе с ручными объявлениями.
- На сервер отправляются все записи, не только видимая выборка. Неизвестные поля XML и стабильные старые UNID сохраняются. Удалённые импортные записи сохраняются в локальном архиве.
- Внешнее изменение XML блокирует отправку. Черновики можно сохранить в JSON, отменить и повторить сверку; автоматического слияния/обратного импорта JSON нет.
- Фото загружаются отдельной кнопкой, уникальными именами, затем ссылка добавляется в черновик. Старые файлы не удаляются автоматически. Каталожная картинка 21vek и заглушка не используются как фото продаваемого экземпляра.
- Пропажа сопоставленного кода из последнего локального среза уценки вызывает предупреждение специалисту. Непривязанные и БК-позиции показаны как не сопоставленные с уценкой; отсутствием товара это не объявляется. Ручные объявления не проверяются без списка и сопоставления их позиций.
- Локальная база out/kufar/workspace.sqlite3 содержит позиции, ссылки на фото, архив и журнал. Для резервного копирования нужны вся папка out/kufar и учётная запись Windows, способная расшифровать DPAPI. Переезд на другого пользователя потребует повторного ввода пароля.
- Периодическая проверка самого аккаунта Kufar, сообщения по почте и фоновые уведомления вне страницы модуля не реализованы. Предупреждения видны в разделе при открытии.

## Подтверждённый механизм Kufar

- Импорт использует KML — XML-формат Kufar в UTF-8, структура `uedb/records/record`.
- Файл размещается по доступному извне HTTP/HTTPS URL; ссылку для подключения импорта передают поддержке Kufar. Локальный адрес приложения не является публичным адресом такого файла.
- `unid` уникален и должен сохраняться при обновлении объявления. В инструкции создания указаны латинские буквы и цифры.
- Удаление записи из подключённого файла приводит к удалению/деактивации соответствующего объявления. При будущей реализации нельзя автоматически подменять полный опубликованный набор текущими фильтрами интерфейса.
- Изменения импортируемых объявлений вносятся в тот же размещённый файл. Все объявления проходят модерацию.
- Документы расходятся в периодичности: техническая редакция 5 указывает раз в сутки; справочные статьи описывают три обновления в сутки и отдельный режим для более 1000 позиций. Частоту для конкретного аккаунта требуется уточнить при подключении; фиксированный интервал не обещать.

## Требования к полям

Общие обязательные поля в редакции 5: `unid`, `area`, `region`, `remuneration_type`, `subject`, `body`, `category`, `type`, `phone`, `price`, `currency`, `contact_person`.

- Заголовок: 2–100 печатных символов. Описание: 20–4000. Контактное лицо: до 50.
- Цена передаётся с двумя знаками после точки; `0.00` означает договорную стоимость, а не отсутствие цены.
- Валюты справочника: BYN, EUR, USD, RUB. `remuneration_type`: 1 — с ценой, 2 — бесплатно.
- Телефоны: `+375YYXXXXXXX`, коды из документации — 25, 29, 33, 44, 24; несколько номеров разделяются запятыми. Первые три идут в контакты, остальные также попадают в описание.
- Категории, регионы и населённые пункты передаются кодами справочников. Для категории/типа сделки могут быть дополнительные обязательные поля и зависимости.
- Например, для крупной техники (`15020`) обязательны `condition` и `large_appliance_type`; для аудиотехники (`5020`) — `condition` и `audio_type`. Значения состояния: 1 — б/у, 2 — новое. Автоматическое сопоставление с состояниями брака пока не согласовано.
- Пустые теги запрещены. Техническая инструкция требует CDATA для текстовых блоков со специальными XML-символами.
- Пример фото: `<photos><photo picture="https://…" /></photos>`. Изображения должны быть доступны загрузчику Kufar. В документации приведены адреса его загрузчиков; будущий хостинг должен допускать такие обращения. Ссылки на локальный кеш и заглушки приложения автоматически использовать в объявлениях не согласовано.

## Официальные источники

1. [Назначение и работа импорта](https://helpcenter.kufar.by/knowledge_base/item/367777).
2. [Редактирование импортируемых объявлений](https://helpcenter.kufar.by/knowledge_base/item/367945).
3. [Способы автоматической выгрузки](https://helpcenter.kufar.by/knowledge_base/item/366679).
4. [Техническая документация, редакция 5](https://import-docs.kufar.by/import_documentation_revision_5.html).
5. [Самостоятельное создание файла](https://helpcenter.kufar.by/knowledge_base/item/366357).

## Пакет переноса от 04.11.2026

Исходник: kufar_base/Куфар — база объявлений.xlsx. Он читается без изменений. Пользователь поручил исключить позиции без однозначного кода и все повторяющиеся коды. Подготовленный файл размещается отдельно от действующего kufar.xml. Переход существующих ручных объявлений на импорт не выполняется автоматически: новый UNID не доказывает связь со старым ad_id. Подключение требует согласования перехода без дублей; в аккаунте сейчас 275 ручных объявлений.

## Рабочее место 2026.11.04.5

Основной /kufar — учёт 275 ручных объявлений из снимка prepared/2026-11-04/all-positions.json. Автозагрузка выполняется один раз в локальную таблицу kufar_inventory; ручные привязки не перезаписываются при повторном открытии. Этот реестр независим от listing и baseline файла импорта. Наличие в снимке не выдаётся за текущую онлайн-проверку аккаунта.

Сверка читает последний успешный локальный срез app.discount_product по точному полному product_id. Кнопка «Сверить остатки» фиксирует время и итог в журнале; она не загружает новый срез ch-stage и не снимает объявления. Для обновления среза есть ссылка в существующий раздел уценки. Статусы: есть в срезе; отсутствует в срезе (запись существует и is_active=false); код не найден; код не указан. БК-позиция, которой нет в базе уценки, не считается проданной.

Кнопка проверки страницы обращается к публичному /item/ad_id и сверяет идентификатор в HTML, без undocumented API. Только подтверждённая страница обновляет живое описание и цену; дата проверки видна. 404/410 — «страница недоступна публично», а не подтверждённая продажа; 429/капча/неизвестная структура — ошибка без смены статуса. Проверки всех аккаунтных объявлений в фоне и автоматическое обнаружение новых объявлений пока отсутствуют.

Вкладка файла импорта — /kufar?view=feed. Подготовленные 203 записи не подменяют реестр размещённых 275 объявлений. Изменение привязки в реестре не пересобирает ранее подготовленный XML.

## Новые объявления 2026.11.10.1

- Форма нового объявления принимает до 15 фотографий: локальные JPEG/PNG/WebP загружаются в настроенный каталог хостинга, а внешние изображения передаются публичными HTTP/HTTPS-ссылками.
- Файлы и ссылки образуют одну изменяемую очередь. Первый элемент очереди записывается первым в `photos` и используется Kufar как главное фото.
- Обязательные параметры выбранной категории (в том числе `condition` и тип товара, когда они требуются категорией) берутся из сохранённого справочника редакции 5.
- Гарантийный срок передаётся отдельным тегом `shop_guarantee`; также поддержаны необязательные `shop_manufacturer`, `shop_service`, `shop_manufacturer_country` и `other_parameters`.
- `body` остаётся обычным текстом. Сохраняются переносы строк и текстовые маркеры, но жирный шрифт, курсив, HTML и Markdown на Kufar не поддерживаются.
- Признак показа по всей Беларуси относится к мультирегиону партнёрского аккаунта Kufar; форма не подменяет его произвольным XML-полем.

Выгрузка `21_vek.xlsx` от 10.11.2026 содержит 1 689 строк истории, из них 275 без `end_date`, и только восемь общих полей: телефон, id, регион, время публикации, дата окончания, цена, заголовок и описание. Категорийные характеристики и фотографии из неё восстановить нельзя, поэтому для новых объявлений они заполняются в рабочем месте отдельно.

## Архив выгрузки 2026.11.10.6

- Импорт архива выполняет tools/import_kufar_archive.py в локальную таблицу kufar_inventory (колонки archived, archived_at); XML-фид и хостинг не затрагиваются.
- Строки с `end_date` добавляются как архивные (1 414 шт.); строки без `end_date` — как активные на момент выгрузки. Активные совпали с текущей базой по ad_id (275) и не дублируются: существующие карточки, привязки и правки при импорте не изменяются.
- По правилу руководителя активные строки выгрузки, отсутствующие в текущей базе, активными не считаются: опубликованные в последние 10 дней пропускаются (вероятно, проданы или сняты), более старые добавляются сразу в архив. В выгрузке от 10.11.2026 таких строк нет.
- Код БК/расп извлекается из описания при единственном совпадении шаблона; найден у 1 358 из 1 414 архивных. Неоднозначные (несколько разных кодов) остаются без кода.
- Архивные карточки: фильтр «В архиве» в каталоге, не входят в рекомендации снятия и в полный файл-кандидат даже при повторном появлении в профиле. Резервная копия перед импортом: workspace-backup-20261110T152515.sqlite3 в папке out/kufar.

## Переход на файл импорта 2026.11.10.7

- Порядок подключения: собрать полный файл-кандидат и активировать его (файл уходит на FTP как kufar.xml с резервной копией и проверкой хеша), затем передать публичную ссылку kufar.xml в поддержку Kufar для подключения импорта. Ручные объявления аккаунта при переходе удаляются — это ожидаемое поведение, подтверждённое руководителем.
- После обработки Kufar создаёт объявления с новыми ad_id под теми же unid. Сверка профиля предложит их в «Добавить в базу»; приём (по одной или все сразу) пополняет каталог без изменения XML. Привязки уценки уже перенесены в файл из реестра, поэтому цены и остатки поддерживаются кнопкой «Обновить цены и остатки на сервере».
- Обновление цен и остатков (FTP): для привязанных позиций берётся site_price текущего среза app.discount_product; позиция, которой нет в активном остатке, исключается из файла (объявление удаляется на Kufar). Непривязанные карточки обновлением не затрагиваются. Файл публикуется только при наличии изменений; перед отправкой проверяется публичная ссылка и хеш файла на сервере.
- Привязка карточки: Каталог объявлений → карточка → «Привязка к уценке» → поиск по названию или полному коду → выбор точной позиции. Привязка меняет и карточку реестра, и запись рабочего XML (unid KF+ad_id), поэтому следующее обновление использует новую привязку. Очистка поля и сохранение снимает привязку.

## Единый файл и архив 2026.11.10.8 (обновлено 2026.11.16.1)

- Эксплуатация: работает только установленная копия AppData\Local\ooucr\app (порт 8000). Исходная копия Documents\приложение\app — только исходник для правок: у неё общий кластер PostgreSQL (ooucr_v11), но собственная пустая папка out\kufar; параллельный запуск разъединил бы базу Куфара. Обновление кода — перенос файлов из Documents в AppData с сохранением заменяемых копий.
- До перехода на импорт передача файла — одна кнопка «Собрать полный файл и передать на FTP» (сборка, проверка категорий и цен, загрузка на FTP одним действием); «Собрать локально без отправки» — вспомогательная. После перехода остаётся одна рабочая кнопка «Актуализировать цены и остатки и передать файл на FTP».

- Модель «один файл на FTP»: kufar.xml всегда содержит полный актуальный каталог с ценами. Кнопка «Актуализировать цены и остатки и передать файл на FTP» (страница «Подготовка и публикация») сверяет файл с последним срезом app.discount_product, обновляет цены привязанных позиций, исключает позиции без активного остатка и публикует полный XML с резервной копией и проверкой хешей. Доступна при любом состоянии файла, включая период до подключения импорта.
- Блок «Сверка файла с остатками уценки» показывает до отправки: изменения цен (старая → новая), позиции вне активного остатка, число карточек без привязки. Сверка идёт против файла (baseline сверяется с сервером по хешу при отправке), публичный профиль Kufar для цен и остатков не используется.
- Архив карточки: кнопка «В архив» в карточке каталога помечает карточку (archived, archived_at), исключает её из файла и сразу публикует файл на FTP; после обработки Kufar объявление удаляется. «Вернуть из архива» восстанавливает последнюю сохранённую запись файла из локального архива и публикует файл. Если записи в файле ещё нет (период до перехода), архивация действует локально до следующей передачи полного файла.
- Автоматическая архивация: при актуализации все снятые из-за отсутствия остатка позиции, имеющие привязку каталога (unid KF+ad_id), помечаются архивными автоматически.
- publish() сохраняет XML снимаемых записей в таблицу archive в том числе при удалении записей, существовавших только локально (source_xml); восстановление из архива возможно всегда. Маршрут /kufar/inventory/local-removal заменён на /kufar/inventory/archive; функция set_local_removed сохранена для совместимости.
