food-market/docs/migration-runbook.md

Рунбук «День перехода» — МойСклад → ALL MARKET

Решение владельца 09.10.2026: перенести ВСЁ из МойСклада с историей и продолжить работу в ALL MARKET. Этот документ — пошаговый регламент перехода, кто что делает, как откатиться и что проверить после. Фискализации/маркировки нет (не блокеры).

• Источник: аккаунт МойСклад, орг «FOOD MARKET» (bb8f74d4-5eb6-11ef-0a80-106e00048af9). Только чтение.
• Приёмник: ALL MARKET, орг «FOOD MARKET» на стенде (простой режим), admin foodmarket-migr@food-market.local. Демо-магазин и «Магазин у дома» НЕ трогаем.
• Токен МойСклада — ~/.food-market-secrets/moysklad.env (в МойСклад ничего не писать).

---

Фаза A. Заранее (за несколько дней до перехода)

1. Полный перенос истории (один раз, многочасовой). Запускать ПОСЛЕДОВАТЕЛЬНО (одна орг, гонка остатков при параллельном запуске):
   • Справочники: товары, группы, контрагенты (несут MoySkladExternalId).
   • Документы (хронология, МСК→UTC, суммы ÷100, авторы/статусы): supply → enter → loss → purchasereturn → retaildemand → retailsalesreturn → inventory.
   • Деньги + плуг балансов: type=money (платежи/ордера/внесения/выплаты + OpeningBalance).
   • Эндпоинт: POST /api/admin/moysklad/import-supplies?type=<T>[&offset=N].
2. Сверка (scripts/migration/reconcile.py → docs/migration-reconciliation.md): число документов, остатки товар×склад, выручка+чеки по месяцам, балансы счетов, долги. Все расхождения = 0 или объяснены построчно.
3. Включить дельту (scripts/migration/delta_sync.py, cron раз в 10–15 мин) с момента окончания полного переноса: подтягивает только изменения updated>=lastSync. Проверить, что свежие чеки из МойСклада появляются в ALL MARKET в течение интервала.

Фаза B. День перехода (час X)

Шаг	Кто	Действие
B1	Владелец	Объявить стоп-кассе в МойСкладе: последний чек пробит, новые продажи приостановлены на ~15 мин.
B2	Инженер	Остановить cron дельты (чтобы зафиксировать окно).
B3	Инженер	Финальная дельта вручную: python3 scripts/migration/delta_sync.py — подтянет последние чеки/платежи за минуты.
B4	Инженер	Обработать удаления из отчёта дельты (lastDeletions в состоянии): удалить соответствующие документы в ALL MARKET по регламенту (сверять по MoySkladExternalId).
B5	Инженер	Прогнать сверку reconcile.py. Убедиться: документы, остатки, выручка, балансы = 0 расхождений (долги — см. ограничение токена ниже).
B6	Владелец+Инженер	Контрольная ручная проверка в UI: 3–5 товаров (остаток), 2–3 поставщика (долг), баланс кассы и расчётного счёта, выручка за вчера.
B7	Владелец	Переключить персонал/кассы на ALL MARKET (POS → адрес нового сервера, логины кассиров).
B8	Владелец	Возобновить продажи в ALL MARKET. МойСклад переводится в режим «только архив» (не продавать).

Фаза C. После перехода (контроль)

• Первый день: следить за остатками/выручкой в ALL MARKET, сверять итоги дня с ожиданиями.
• Держать аккаунт МойСклада доступным на чтение ≥1 месяц (архив истории, разбор спорных).
• Не удалять токен/данные МойСклада, пока переход не признан успешным.

---

Откат (rollback) — вернуться на МойСклад

Переход спроектирован как неразрушающий для источника: в МойСклад мы НИЧЕГО не писали, поэтому откат = продолжить работать в МойСкладе.

1. Владелец объявляет возврат на МойСклад; кассиры переключают POS обратно на МойСклад/старую кассу.
2. Продажи, совершённые в ALL MARKET за время после часа X, переносятся в МойСклад вручную (их немного — окно короткое) ИЛИ принимается, что они останутся только в ALL MARKET как параллельный период (по решению владельца).
3. Орг ALL MARKET на стенде остаётся как есть (данные не удаляются) — для повторной попытки.
4. Причина отката фиксируется; дефект устраняется; повторный день перехода назначается заново.

Критерий «не откатываемся»: сверка B5 = 0 расхождений (или объяснены) и ручная проверка B6 совпала. Если расходится критично (остатки/деньги) — откат по пунктам выше.

---

Надёжность и производительность (Part 6)

• Идемпотентность: повторный запуск любого типа пропускает уже перенесённое по MoySkladExternalId (дублей нет). Проверено на приёмках/оприходованиях/списаниях.
• Резюмируемость: падение/рестарт в середине — продолжить с ?offset=N (N ≈ число уже перенесённых минус 200 для перекрытия); идемпотентность убирает повтор.
• Устойчивость к сбоям: каждый документ — отдельный SaveChanges + ChangeTracker.Clear (в т.ч. в catch), поэтому ошибка одного документа не роняет прогон и не каскадит.
• Лимиты МойСклада: 45 запросов/3с, таймаут 130с, Accept-Encoding: gzip, 429 с повтором по X-RateLimit-Retry-TimeInterval. Страница 100 док., order=moment,asc.

Известные ограничения (объяснённые расхождения)

• Долги контрагентов: отчёт МойСклада report/counterparty недоступен выданным read-only токеном (403 — нет права на взаиморасчёты). Долги в ALL MARKET формируются из перенесённых первичных документов; итоговую цифру сверять вручную в UI МойСклада (шаг B6) или временно выдать токену право на отчёт для авто-сверки reconcile.py (секция 5).
• Балансы счетов: розничная наличность/движения кассовых смен до перехода не материализуются подокументно; баланс сводится «плугом» OpeningBalance = баланс МойСклада (report/money/byaccount) − Σ перенесённых проводок. Текущий баланс счёта в ALL MARKET точно совпадает с МойСкладом; подробная история доналичных движений остаётся в архиве МойСклада.
• Нулевые остатки: report/stock/all не отдаёт нулевые позиции — товар без строки считается остатком 0 (сверка это учитывает).