WB Localization Service — Редизайн v2 (финал)

Дата: 2026-04-17

Статус: ✅ Реализовано, готово к ревью

Ветка: feature/localization-redesign (11 коммитов, 107/107 тестов PASS)

---

TL;DR — что изменилось

Было: сервис считал ИЛ/ИРП и перестановки, но выдавал «сухие» листы без контекста. Справочник — минимальная таблица. Экономика — 3 сценария. Прогноза не было.

Стало: единый модульный сервис с автоматическим прогнозом улучшений на 13 недель вперёд, градацией сценариев 30–90% локализации, и полной визуальной документацией всех формул WB в справочнике.

Ключевая фишка: теперь можно спросить «а если начнём перестановки сегодня — через сколько недель пересечём порог 60% и сколько сэкономим?» — и сервис ответит числом, построенным на реальных данных артикулов.

---

Что получит пользователь в Google Sheets

После запуска появится 10 листов в целевой таблице (было 8):

#	Лист	Что показывает
1	Справочник	Полная документация WB: формула логистики, таблицы КТР/КРП, склады с лимитами, логика перестановок, инерция скользящего окна
2	Сводка {кабинет}	Ключевые метрики за период
3	Экономика сценариев {кабинет} 🆕	Градация 30–90% локализации: что будет с расходами на каждом уровне + топ-15 артикулов, которые тянут индекс вниз
4	Перестановки Roadmap {кабинет} 🆕	14 недель понедельного прогноза: когда пересечём 60% (КРП→0), когда достигнем 80% (КТР=0.80), сколько сэкономим
5	ИЛ Анализ {кабинет}	Детальный per-article ИЛ/ИРП
6	Регионы {кабинет}	Разбивка по 6 ФО
7	Проблемные SKU {кабинет}	Топ проблемных артикулов
8	Допоставки {кабинет}	Рекомендации по допоставкам со своего склада
9	История	Append-only журнал запусков
10	Обновление	Dashboard со статусом

🆕 — новые листы. Остальные расширены или сохранены.

---

Лист 1: «Справочник» (расширенный)

Цель: одностраничная инструкция — читают один раз, потом ссылаются.

8 тематических блоков

1. Обложка + оглавление — заголовок на тёмно-синем фоне, ссылки на блоки

2. Основная формула логистики:

Логистика = (База × Коэф.склада × ИЛ) + (Цена × ИРП%)

+ пример на реальных числах (цена 1000₽, объём 3л, разные уровни ИЛ)

3. Индекс локализации (ИЛ) — определение «локального заказа», формула, 20-строчная таблица КТР с цветовой градацией:

🟢 95–75%: КТР 0.50–0.90 (скидка)
🟡 75–60%: КТР 1.00 (нейтрально)
🔴 60–0%: КТР 1.05–2.20 (штраф)

4. Индекс распределения продаж (ИРП) — формула, ключевой порог 60% (резкий переход с 2.00% на 0.00%), таблица КРП с цветом

5. Исключения — КГТ, СГТ, КБТ, FBS; правило 35%

6. Перестановки:

Комиссия +0.5% на все продажи (!)
Lock-in 90 дней (нельзя отключить)
Таблица 29 складов с лимитами: Котовск 499 300 шт/день, Шушары 200 шт/день
Callout «Экономика перестановок»: точка окупаемости

7. Скользящее окно 13 недель:

Формула инерции: loc(t) = ((13-t)×старое + t×новое) / 13
Таблица «недель до порога 60%»:
С 40% → 8-9 недель
С 50% → 5-6 недель
С 55% → 2-3 недели
Призыв: «начинать СЕЙЧАС, эффект отложенный»

8. Наш расчёт vs WB — честная пометка о различиях (календарные дни vs ISO-недели, расхождение ≤ 3 п.п.)

---

Лист 2: «Экономика сценариев» (градация 30–90%)

Цель: показать как меняется вся экономика кабинета при разных уровнях локализации. На реальных артикулах, с цветовой heat-map.

Структура

Блок 1. Паспорт отчёта — дата, период, текущий ИЛ, текущие расходы

Блок 2. Сводная таблица сценариев (главная «кислотная» таблица):

Сценарий	Целевая лок.%	КТР	КРП%	Логистика ₽/мес	ИРП ₽/мес	Итого ₽/мес	Δ vs Сейчас	Δ vs Худший
🔴 30% (критично)	30%	1.60	2.15%	…	…	…	+…	0
🔴 40% (плохо)	40%	1.30	2.10%	…	…	…	…	…
🟠 50% (слабо)	50%	1.10	2.05%	…	…	…	…	…
🟡 Сейчас	(ваш)	…	…	…	…	…	0	…
🟢 60% (порог КРП→0)	60%	1.00	0.00%	…	0	…	−…	…
🟢 70% (ок)	70%	1.00	0.00%	…	0	…	−…	…
🟢 80% (цель)	80%	0.80	0.00%	…	0	…	−…	…
🟢 90% (топ)	90%	0.60	0.00%	…	0	…	−…	…

Каждая колонка имеет строку-описание под заголовком (серый italic 9pt), поясняющую метрику.

Блок 3. KPI-плитки — три крупные визуальные плитки:

┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐

│ СЕЙЧАС ПЛАТИТЕ │ │ МАКС. ПОТЕНЦИАЛ │ │ ЧИСТАЯ ВЫГОДА │

│ X ₽/мес │ │ −Y ₽/мес │ │ +Z ₽/мес │

│ логистика + ИРП │ │ при ИЛ 80% │ │ после вычета комисс.│

└─────────────────────┘ └─────────────────────┘ └─────────────────────┘

Блок 4. Топ-15 артикулов, тянущих индекс вниз:

#	Артикул	Лок.%	КТР	КРП%	Заказов/мес	Логистика ₽/мес	ИРП ₽/мес	Вклад в ИЛ	Экономия при 80%	Статус

Сортировка: по колонке «Экономия при 80%» descending. Сразу видно, на какие артикулы давить в первую очередь.

Блок 5. Экономика перестановок — таблица с вводом:

Метрика	Значение	Описание
Оборот кабинета ₽/мес	…	Из данных о заказах
Комиссия (+0.5%)	…	Платится пока опция включена
Точка окупаемости	= комиссия	Экономия должна быть выше
Макс. экономия при 80%	…	Из сводной таблицы
ЧИСТАЯ ВЫГОДА	+Z ₽/мес ✅	Макс. экономия − комиссия
Lock-in период	90 дней	Нельзя отключить раньше

---

Лист 3: «Перестановки Roadmap» (прогноз на 13 недель)

Цель: ответить на вопрос «если начнём перестановки сегодня — когда увидим эффект?» на реальных данных.

Структура

Блок 1. Как работают перестановки — краткое пояснение + ссылка на Справочник

Блок 2. Паспорт прогноза:

Параметр	Значение
Текущий ИЛ кабинета	…
Текущая логистика ₽/мес	…
Реалистичный % лимитов	30% (настраивается)
Артикулов требуют перестановок	… из 84
Всего единиц к перемещению	… шт
Комиссия перестановок (+0.5%)	… ₽/мес

Блок 3. Понедельный roadmap (главная таблица, 14 строк):

Неделя	Дата	Перемещено (кум.)	% плана	ИЛ прогноз	КТР взв.	Логистика ₽/мес	Экономия vs Сейчас	Статус
0	17.04	0	0%	55.2%	1.05	140 500	0	🟡 Сейчас
1	24.04	320	8%	56.8%	1.04	138 200	−2 300	🟡 В процессе
2	01.05	640	15%	58.1%	1.03	135 800	−4 700	🟡 В процессе
3	08.05	960	23%	59.5%	1.02	133 400	−7 100	🟡 Почти 60%
4	15.05	1 280	30%	🎯 60.8%	1.00	120 000	−20 500	🟢 ПОРОГ 60%! КРП→0
5	22.05	1 600	38%	62.3%	1.00	120 000	−20 500	🟢 Стабильно
…	…	…	…	…	…	…	…	…
9	19.06	3 000	70%	🎯 80.1%	0.80	96 000	−44 500	🟢 ЦЕЛЬ 80%!
10	26.06	3 300	78%	82.5%	0.80	96 000	−44 500	🟢 Выше цели
…	…	…	…	…	…	…	…	…
13	17.07	4 200	100%	85.0%	0.70	84 000	−56 500	🟢 Максимум

Ключевые вехи подсвечиваются жирной рамкой:

🎯 Неделя пересечения порога 60% (КРП обнуляется)
🎯 Неделя достижения 80% (максимальная скидка КТР)

Блок 4. Placeholder для chart'а — будет линейный график в следующей итерации

Блок 5. Детальный план перестановок (12 колонок):

#	Приоритет	Артикул	Размер	Лок.%	Откуда (ФО + склад)	Куда (ФО + склад)	Шт	Импакт на ИЛ	Экономия ₽/мес	Лимит?	Неделя

Сортировка: по экономии ₽/мес. Сразу видно что двигать в первую очередь.

Математика прогноза (ключевое)

Формула инерции 13-недельного окна:

move_fraction(t) = перемещено_единиц_к_неделе_t / общий_сток_артикула

effective_new = loc_before × (1 − move_fraction) + loc_after × move_fraction

blended_loc(t) = ((13 − t) × loc_before + t × effective_new) / 13

Почему это важно: индекс считается за скользящие 13 недель. Если сегодня 45%, и с завтра все заказы станут локальными — на неделе 1 только 1/13 окна «новая», остальные 12/13 — старые с 45%. Полный эффект виден только через 13 недель.

Реалистичные допущения:

Доля получаемых слотов складов: 30% (параметр настраиваемый) — по исследованию, слоты популярных складов перехватывают быстро
Целевая локализация артикула после переноса: 85% (не 100% — консервативная оценка)
Жадное распределение по неделям: приоритет по экономическому импакту

---

Что поменялось в архитектуре

Было

services/wb_localization/

├── sheets_export.py ← монолит 59KB, ~1100 строк

└── calculators/

├── il_irp_analyzer.py

└── economic_analyzer.py ← только 3 сценария

Стало

services/wb_localization/

├── calculators/ ← ЧИСТЫЕ ФУНКЦИИ (без I/O)

│ ├── il_irp_analyzer.py ✅ existing

│ ├── economic_analyzer.py ✅ existing (legacy, сохранён)

│ ├── scenario_engine.py 🆕 градация 30–90%

│ ├── relocation_forecaster.py 🆕 13-нед. прогноз

│ └── reference_builder.py 🆕 структура справочника

│

├── sheets_export/ 🆕 ПАКЕТ (заменил монолит)

│ ├── __init__.py фасад export_to_sheets()

│ ├── formatters.py + SHEET_COLUMN_DOCS (описания колонок)

│ ├── core_sheets.py Перемещения/Допоставки/Сводка/Регионы/Проблемы

│ ├── analysis_sheets.py ИЛ Анализ + legacy Экономика

│ ├── reference_sheet.py 🆕 расширенный Справочник

│ ├── scenario_sheet.py 🆕 Экономика сценариев

│ └── roadmap_sheet.py 🆕 Перестановки Roadmap

│

├── history.py 🔧 +weekly_snapshots таблица

└── run_localization.py 🔧 +4 CLI-флага, +3 шага

Ключевые принципы:

Независимость модулей — каждый калькулятор можно вызвать отдельно
Pipeline опциональных шагов — любой можно выключить флагом CLI
Backward-compat — старая таблица reports не трогается, legacy write_economics_sheet сохранён как fallback

---

Новые CLI-флаги

`bash

Полный запуск (всё включено)

python -m services.wb_localization.run_localization --cabinet both --days 30

Только обновить Справочник (быстро)

python -m services.wb_localization.run_localization --only-reference

Без прогноза/сценариев (облегчённый)

python -m services.wb_localization.run_localization --skip-scenarios --skip-forecast

Кастомный % получаемых слотов складов

python -m services.wb_localization.run_localization --realistic-limit-pct 0.5

Флаг	Что делает	Дефолт
`--skip-scenarios`	Пропустить градацию 30–90%	off
`--skip-forecast`	Пропустить 13-недельный прогноз	off
`--realistic-limit-pct`	% реально получаемых слотов	0.3
`--only-reference`	Обновить только Справочник	off

---

Верификация коэффициентов КТР

В ходе редизайна сверили таблицу КТР/КРП в коде с:

Источник истины: WB Partners → Тарифы → «Индексы локализации» (авторизованный кабинет, 27.03.2026)
Публичные seller docs (https://seller.wildberries.ru/instructions/ru/ru/material/localization-index)

Результат:

КРП: 100% совпадение
КТР: расхождение только ниже 35% (7 диапазонов) — публичные доки слегка отстают от Partners

Решение: оставили текущие значения в коде. Полный отчёт: docs/database/KTR_SYNC_VERIFICATION.md.

---

Метрики реализации

Метрика	Значение
Новых калькуляторов	3 (reference_builder, scenario_engine, relocation_forecaster)
Новых sheet writer'ов	3 (reference_sheet, scenario_sheet, roadmap_sheet)
Разбит монолит	`sheets_export.py` (59KB → 4 модуля в пакете)
Новых тестов	51 (56 baseline → 107 итого)
Тесты проходят	107 / 107 ✅
Коммитов	11 (атомарные, по задачам)
Новых таблиц в SQLite	1 (`weekly_snapshots`)
Новых CLI-флагов	4

---

Коммиты

d108ed8 docs(wb_localization): update service docs + add completion report

5d0a140 feat(wb_localization): integrate scenario + forecast + reference into pipeline

da0d732 feat(wb_localization): add roadmap_sheet writer

69c3fb8 feat(wb_localization): add scenario_sheet writer + SHEET_COLUMN_DOCS

71b3d02 feat(wb_localization): add reference_sheet writer

9baf271 feat(wb_localization): add relocation_forecaster calculator

ca0a6c6 feat(wb_localization): add weekly_snapshots table to history

fbac02c feat(wb_localization): add scenario_engine calculator

59500a9 feat(wb_localization): add reference_builder calculator

d6d9065 refactor(wb_localization): split sheets_export.py into package

65909ee docs: add КТР sync verification report

---

Известные ограничения (в backlog на следующую итерацию)

1. Chart в roadmap_sheet — пока placeholder-текст. Нужно вызвать Google Sheets addChart API для линейного графика ИЛ по неделям + reference lines 60% и 80%.

2. Cell notes (hover tooltips) — не реализованы, используются только строки-описания под заголовками.

3. Per-article target_localization — forecast использует глобальный 85%. Более точный прогноз потребует считать target per-article на основе региональной локализации.

4. Оборот кабинета для сценариев — считается из 91-дневного окна заказов. Если нужна точность для комиссии 0.5% — стоит взять revenue из отдельного источника (Finolog / БД).

5. warehouse_limit_status — сейчас всегда «OK» (placeholder). Нужно сверять запрошенное кол-во со свободной capacity склада на неделю.

---

Что дальше

Ревью этого документа ← мы здесь

После твоего ok:

1. Создаю Pull Request feature/localization-redesign → main

2. Codex + Copilot автоматический review loop (через skill pullrequest)

3. После прохождения ревью — merge в main

4. Можно запускать в prod: python -m services.wb_localization.run_localization --cabinet both

---

Ссылки

Design spec (v1, исходный): docs/superpowers/specs/2026-04-16-localization-service-redesign-design.md
План реализации: docs/superpowers/plans/2026-04-16-localization-service-redesign-plan.md
Completion report: docs/superpowers/plans/2026-04-16-localization-service-redesign-COMPLETION.md
КТР verification: docs/database/KTR_SYNC_VERIFICATION.md
Service docs: docs/agents/mp-localization.md

---

Документ v2, обновлён после полной реализации. Готов к ревью и merge.