WB Localization 2.0

01 · Что делает сервис

Проблема, которую решаем. У Wookiee 920+ артикулов лежат на 23 рабочих складах WB по всей России. Когда покупатель из Новосибирска заказывает товар, который физически лежит в Коледино — WB везёт его 5 дней через всю страну и берёт с нас за это повышенный коэффициент тарифа (КТР) и сниженный коэффициент региональной приоритезации (КРП). Покупатель ждёт долго → выкуп падает. Карточка не попадает в ТОП регионального поиска → продаж меньше.

Что делает сервис. Каждый день автоматически считает: «вот этот товар лучше переставить из Коледино в Новосибирск, потому что там его всё равно покупают». Отправляет такие задачи в WBcon. Следит, чтобы за неделю индекс локализации (доля заказов с ближайшего склада) рос.

Из каких четырёх блоков состоит сервис

Как они связаны

Контроль возвращает данные в алгоритм: какие пары (склад A → склад B) выполняются успешно, какие WB отклоняет, какие зависают. Это та самая «калибровка по факту», которая будет в Sub-project B.

02 · Откуда сервис берёт данные

Сервис общается с тремя внешними системами. Понимать кто кому хозяин — критично, иначе непонятно почему мы не можем просто «прийти и взять».

Кто здесь кто

Почему нельзя «просто взять у WB напрямую»

• WB API селлера отдаёт остатки в момент запроса и сильно лимитирован. Чтобы посчитать «как товар вёл себя на каждом складе за 30 дней» — нужны исторические снимки. Их WB не отдаёт.
• Подрядчик уже собрал эту историю в свою БД (Wildberries DB) и держит на актуальном уровне. Мы платим за доступ и читаем готовое. Свою БД с нуля строить ≈ полгода работы.
• WBcon — это вообще отдельный сторонний сервис, через который WB разрешает делать перестановки (внутри WB этой функции нет). Туда мы пишем напрямую.

03 · Главная метрика — индекс локализации

Что это. Доля заказов, которые ушли с ближайшего к покупателю склада. Если покупатель из Новосибирска купил товар, который физически лежал в Новосибирске — это +1 к локализации. Если приехал с Коледино — 0.

Зачем поднимать.

• Дешевле логистика. WB берёт меньше за доставку «локального» заказа (коэффициент КТР).
• Карточка выше в поиске региона. При высоком КРП (коэффициент региональной приоритезации) WB поднимает товар в выдаче для тех регионов, где он есть на складе.
• Быстрее доставка → выше выкуп. Покупатель не отменяет заказ за 4 дня ожидания.

Как сейчас. Колеблется около 67% последнюю неделю. Цель — 90%+. Каждая точка процента индекса = сотни тысяч рублей в месяц (точная цифра — задача Sub-project C).

Важно Колебание ±0.1 п.п. за неделю — это шум, не сигнал. Решения смотрим на горизонте 14–30 дней. Автопилот стартовал вчера.

04 · Дневной цикл — 6 этапов

Каждый день сервис проходит один и тот же цикл из 6 этапов. Все времена — по московскому времени.

05 · Алгоритм — как мы выбираем что переставить

Это сердце сервиса. Объясняю по шагам — как для человека, не как для разработчика.

Шаг 1 — перебрать все возможные перестановки

Для каждой пары (SKU + размер + склад-донор + склад-получатель) сервис задаёт вопрос: «может, стоит переставить?». На 920 артикулах × ~6 размерах × 23 склада × 23 склада это потенциально миллион пар. Большинство отсеивается сразу — нет товара на доноре, нет смысла везти на получателя, не хватает квоты направления.

После первичного отсева остаётся 700–2500 живых кандидатов в день (зависит от того, сколько SKU «съехало» с целевой локализации за сутки).

Шаг 2 — посчитать ранг каждого кандидата

Главная формула:

rank = feasibility × max(0, impact_рублей) × (1 + priority_bonus)

Три компонента:

Шаг 3 — разложить кандидатов по дорожкам (lanes A–F)

Это вторая защитная сетка: даже отранжированных кандидатов алгоритм разделяет по «дорожкам» в зависимости от текущей локализации SKU и приоритетности направления WB:

Шаг 4 — финальная сортировка

В POST идут отсортированные по: (1) Новосибирск в конец (там высокая конкуренция за квоту, не блокируем остальные направления), (2) по убыванию rank-score. Топ-N (сейчас 500) реально отправляется в WBcon.

Что меняет CEO, а что — алгоритм сам

06 · Воронка кандидатов — общая логика

Каждый день одна и та же воронка из 6 ступеней. Цифры в иллюстрации — типичные, в реальности зависят от дня (плюс-минус 30%).

Что отсеивается на каждом шаге

07 · База данных — что копится и как смотреть

17 таблиц в Supabase. Делятся на 4 функциональные группы. Для каждой ключевой таблицы — что лежит, какие колонки, пример строки, какие срезы можно делать.

Группа A — снимки WBcon (что лежит в нашем кабинете)

Главная — wbcon_task_snapshots

Активные задачи WBcon. Колонки:

external_task_id  — ID задачи в WBcon (например, 845)
normalized_status — нормализованный статус (active / in_transit / no_response)
nm_id, chrt_id    — что за товар и размер
size_name         — название размера ("S", "M")
src_id, dst_id    — ID складов донора и получателя
src_name, dst_name — их названия
qty               — сколько штук просим переставить
first_seen_at, last_seen_at  — когда впервые увидели в WBcon и когда последний раз

Срезы которые можно делать:

• «Сколько задач сейчас в очереди в Краснодаре?» — фильтр dst_name='Краснодар' AND normalized_status='active'
• «Какие задачи висят больше 7 дней без ответа?» — first_seen_at < now() - 7d AND normalized_status = 'no_response'
• «Сколько штук товара сейчас едет в Новосибирск?» — SUM(qty) GROUP BY dst_name='Новосибирск'

Главная — wbcon_in_transit_snapshots

Товар, который уже отправили, но ещё не доехал. Алгоритм использует это в формуле эффективного остатка (см. §05). Без этой таблицы он бы предлагал переставить одно и то же снова и снова.

Группа B — расчёты алгоритма (мозги сервиса)

Самая важная таблица сервиса — wb2_candidate_moves

Здесь лежат ВСЕ кандидаты которые алгоритм когда-либо рассматривал — и принятые, и отброшенные. Это и есть «черный ящик» алгоритма наружу. Колонки:

id                    — уникальный ID кандидата
run_id                — к какому прогону относится (FK на wb2_runs)
candidate_key         — уникальный ключ (cabinet|article|size|src|dst)
article, nm_id, chrt_id, size_name  — что за товар
src_warehouse_name, dst_warehouse_name — пара складов
lane                  — A/B/C/D/E/F (см. §05)
rank_score            — итоговый ранг (feasibility × impact × priority)
expected_success_probability  — вероятность что доедет
expected_localization_gain    — на сколько вырастет локализация SKU (рубли/месяц)
score_features_json   — ПОЛНАЯ диагностика scoring (см. ниже)
decision              — selected / rejected / backlog / cooldown
planned_qty           — сколько штук планируем переставить
decision_reason       — почему такое решение
created_at            — когда посчитан

Внутри score_features_json лежит scoring_diag — расшифровка каждого числа:

{
  "impact": {
    "price": 2122.12,            // цена единицы
    "current_loc": 48.9,         // текущая локализация SKU
    "projected_loc": 50.4,       // прогнозируемая после перестановки
    "monthly_orders": 45.2,      // сколько заказов в месяц
    "ktr_now": 1.2, "ktr_new": 1.1,
    "krp_now": 2.05, "krp_new": 2.05,
    "impact_ktr_rub": 361.0,     // экономия логистики, ₽/мес
    "impact_krp_rub": 0.0        // дополнительная выручка от КРП, ₽/мес
  },
  "feasibility": {
    "policy_mult": 1.0,          // разрешено
    "quota_fit": 1.0,            // помещаемся
    "success_rate": 0.85,        // историческая
    "pair_history": [0, 0]       // [успехов, попыток] — пока пусто
  },
  "priority": {
    "projected_loc_pct": 100.0,
    "bonus_primary": 0.0,
    "bonus_secondary": 0.0
  }
}

Срезы которые можно делать:

• «Покажи топ-20 кандидатов на сегодня по rank-score» — ORDER BY rank_score DESC LIMIT 20
• «Сколько кандидатов отбросилось по каждой причине?» — GROUP BY decision_reason
• «Какие SKU стабильно идут в lane A 5 дней подряд?» — WHERE lane='A' GROUP BY nm_id HAVING COUNT(DISTINCT run_id::date) >= 5
• «Сравни rank-score кандидата на прошлой неделе и сегодня» — WHERE candidate_key=... ORDER BY created_at

Группа C — аудит и история (что реально произошло)

Главная — wb2_task_outcomes

Каждая операция (POST новой задачи, DELETE устаревшей) пишет сюда строку. Это наш чёрный ящик — если что-то пошло не так, ищем здесь.

id                       — уникальный
cabinet_code             — 'ooo' или 'ip'
external_task_id         — ID задачи в WBcon (для POST=success)
candidate_move_id        — FK на wb2_candidate_moves (откуда брали)
submitted_at, resolved_at — времена постановки и завершения
resolution               — 'success' / 'unknown' / 'cancelled'
sku_loc_pct_before, sku_loc_pct_after — локализация SKU до/после
metadata_json            — request, response, error в JSON

В metadata_json — полная история: что отправили, что получили, какая ошибка. Это и есть тот неявный кэш chrt_id — sync.py при следующих POSTах смотрит сюда «а постили ли мы такой SKU раньше».

Срезы:

• «Воронка успехов за день»: GROUP BY (metadata_json->>'op'), resolution
• «Какие SKU чаще всего получают tech_fail»: фильтр на error
• «Сколько % задач WB отклонил на этой неделе»: WHERE resolution='wb_rejected'

История индекса — wb2_localization_history

+201 строка в день (по SKU из core-выборки). Поля:

snapshot_date  — дата
cabinet_code   — ooo / ip
nm_id          — SKU
loc_pct        — индекс локализации в этот день
orders_period  — заказы за расчётный период (для веса)

Это и есть та таблица, на которой будут все графики «индекс растёт?». Из неё считается средневзвешенный индекс по кабинету. И именно здесь Sub-project C будет искать каузальную связь «наши действия → рост».

08 · Склады WB + защитные правила

29 складов

Все живут в wbcon_warehouses. Разбиты по регионам (региональная группировка — для понимания, в БД её пока нет):

Двойники : Питание — отдельный режим WB, в перестановках не используется (заблокирован в защитных правилах).

12 защитных правил в wbcon_constraints

«Не навреди» — главный принцип. Правила версионируются (effective_from / effective_to), менять = политическое решение, не эксперимент алгоритма.

Настройки нашего алгоритма — wb2_rule_sets

Активный набор: phase-a-default. Это не правила WB, а наши тайминги:

{
  "cycle_evening_msk":              "22:00",     ← вечерний расчёт по МСК
  "cycle_morning_check_msk":        "07:00",     ← утренняя перепроверка
  "cycle_post_msk":                 "09:00",     ← окно WBcon открывается
  "cycle_tracker_msk":              ["12:00","15:00","18:00","21:00"],
  "cycle_digest_msk":               "21:30",     ← вечерний дайджест
  "morning_check_drift_threshold":   0.2,        ← молчим если < 20% drift
  "morning_check_replan_if_invalid_pct_gt": 0.5, ← URGENT если > 50%
  "digest_threshold_tech_fail_pct":  20,         ← порог tech-fail для дайджеста
  "digest_threshold_wb_reject_pct":  5,          ← порог отказов WB
  "duplicate_alert_window_hours":    24,         ← окно дедупа URGENT
  "lock_ttl_minutes":                60,         ← макс длительность DB-lock
  "hanging_task_ttl_days":           7           ← когда списать «зависшую» задачу
}

09 · Telegram-сообщения — на человеческом

Бот: @wookiee_alerts_bot (общий с другими сервисами Wookiee). 6 типов сообщений, переписаны на нормальный русский, без жаргона.

10 · Расписание cron — всё по Москве

Файл /etc/cron.d/wb-loc-2 на сервере timeweb. TZ=Europe/Moscow в шапке файла.

Сейчас Запущен только кабинет ООО ВУКИ. Кабинет ИП Медведева — на паузе по решению CEO.

11 · Известные проблемы и обходные пути

12 · Дорожная карта — Sub-projects B–E

13 · Интерфейс в Hub — главное меню

Сейчас всё что видит CEO — это Telegram-сообщения. Добавляем раздел в Wookiee Hub: hub.os.wookiee.shop/wb-localization.

Главное меню — новый пункт «WB Локализация»

В левой навигации Hub появляется новый раздел «WB Локализация» с 6 подпунктами:

Дальше — описание каждого экрана и mockups.

14 · Интерфейс — экран за экраном

Это первая итерация. Будем дорабатывать. Каждый экран — отдельная подстраница раздела.

Экран 1 — Главная (📊 «Лента»)

Цель. Один экран, на который CEO смотрит раз в день и понимает: всё в порядке или нет. Если красная лампочка — куда кликнуть.

Какие данные используются

• Индекс — view из wb2_localization_history (avg по дням)
• Лента батча — агрегат wb2_task_outcomes за сегодня по resolution
• Статус этапов — последние записи wb2_run_log по stage
• Экономия — будет считаться в Sub-project C; сейчас прикидка по impact_rub в candidate_moves

Экран 2 — Воронка и кандидаты (🎯)

Цель. Понять «почему сегодня всего 164, а не 700». Кликнуть на любую ступень и увидеть список отсеянных кандидатов.

Какие данные используются

• Воронка — агрегаты wb2_candidate_moves по decision + wb2_task_outcomes по resolution
• Lanes — GROUP BY lane FROM wb2_candidate_moves WHERE run_id=46
• Топ — ORDER BY rank_score DESC LIMIT 10 + расшифровка из score_features_json

Экран 3 — История задач (📋)

Цель. Полный лог всех POST/DELETE с фильтрами. Когда что-то висит — посмотреть. Когда склад жалуется на «задачу X» — найти.

Какие данные используются

• Главный источник — wb2_task_outcomes с joins на wb2_candidate_moves и wbcon_warehouses
• Drill-in (по клику) — открывает metadata_json полностью
• Фильтры используют indexes на cabinet_code, created_at, (metadata_json->>'op')

Экран 4 — Эффективность (📈)

Цель. Главный вопрос «работает ли сервис». График индекса по дням, разбивка по складам и SKU, выявить узкие места.

Какие данные используются

• Главный график — wb2_localization_history по дням, средневзвешенный
• Топ складов — JOIN wb2_localization_history с маппингом по складам через snapshot
• Узкие SKU — те, у которых current_loc < 50% AND есть кандидаты в open queue
• Атрибуция (зелёная vs синие точки) — пока корреляция, в Sub-project C превращается в каузальную атрибуцию

Экран 5 — Защитные правила (🛡)

Цель. CEO видит и при необходимости меняет: список заблокированных складов, cooldown, дневные лимиты. История изменений.

Какие данные используются

• wbcon_constraints WHERE effective_to IS NULL — все активные
• История — все строки с effective_to NOT NULL
• Edit — открывает modal, при сохранении: пишем новую строку с effective_from=now(), старую закрываем; шлём Telegram «правило X изменено» с кнопкой rollback

Экран 6 — Автоматика и логи (🤖)

Цель. Технический экран. Когда что-то не сработало — посмотреть лог. Когда нужно ручное вмешательство — кнопки запуска этапов.

Какие данные используются

• Cron статус — последние записи wb2_run_log по каждому stage
• Журнал — SELECT * FROM wb2_run_log ORDER BY started_at DESC LIMIT 20
• Kill-switch — обновляет env-переменную WB_LOC2_POST_DISABLED=1 на сервере + сообщение в Telegram
• URGENT-история — wb2_run_log WHERE stage='alert_dedup'

Что я хочу обсудить дальше

Это первая итерация. Доработаем по ходу. Главные открытые вопросы:

1. Главная — что важнее увидеть первым? Сейчас сверху индекс + цель + сегодняшний батч. Может стоит «алерты дня» поднять выше?
2. Воронка — нужен ли drill-down? Клик на ступень → список отсеянных. Или достаточно сводных цифр?
3. История задач — какие фильтры важнее? Сейчас: дата / склад / модель / статус. Что ещё?
4. Эффективность — как показывать «работает или нет»? До Sub-project C точного ответа не дадим, но что показать прямо сейчас?
5. Правила — какие можно править прямо из UI vs только через диалог в Telegram? Списки складов — да. Числовые лимиты — наверное тоже. candidate_limit — точно через диалог.
6. Карта складов на главной? Я её не добавил — нужна ли визуально или таблица в «Эффективности» достаточно?