¶ name: smarty-deprecation-migration
description: Discipline for sunsetting old systems and migrating consumers in Smarty CRM. Use when decommissioning Elasticsearch (Фаза 7), replacing passport with Zitadel (Фаза 9a), removing draft-js/react-beautiful-dnd (Фаза 8), dropping temporary bridges like allowEIO3 (Фаза 4), or deciding whether to maintain or remove any legacy code path.
Почему нетривиально: «выключить старое» — отдельная дисциплина с своими ловушками: Hyrum's Law (кто-то зависит от недокументированного поведения), zombie-код без владельца, вечные «временные мосты». Дистилляция agent-skills/deprecation-and-migration под наши фазы.
| Вывод |
Замена |
Фаза |
Особенность |
Elasticsearch 8.4 (smarty-elastic) |
Meilisearch (+ Qdrant для векторов) |
7 |
parity-тест search_* tools до выключения |
| passport + cookie-сессии |
Zitadel (OIDC) |
9a |
session-мост на переход; sck_/WorkspaceApi не трогаем |
| draft-js, react-beautiful-dnd, react-virtualized |
tiptap, @dnd-kit, react-window |
8 |
поэтапно, компонент за компонентом |
allowEIO3, dual-write индексов, feature-flag старых путей |
— (мосты) |
4/7 |
мост обязан иметь дату смерти — см. ниже |
| aws-sdk v2, socket.io-redis/emitter |
v3, @socket.io/* |
2/4 |
образец завершённого цикла |
- Система ещё даёт уникальную ценность? Да → сопровождать, нет → дальше.
- Сколько потребителей зависит? (квантифицировать: grep по коду, метрики).
- Замена существует и проверена в проде/регрессе? Нет → сначала замена.
- Цена миграции каждого потребителя? Автоматизируемо → делать.
- Цена НЕ-вывода за 2–3 года? (security-долг, двойное сопровождение).
- Замена готова — покрывает критичные сценарии, есть migration guide, прогнана через регресс-сеть (= baseline).
- Объявить — deprecation-блок в
MIGRATION_AUDIT.md + отметка в коде (@deprecated / комментарий с фазой и заменой).
- Мигрировать инкрементально — потребитель за потребителем: найти точки касания → перевести → сверить с baseline → убрать ссылки. Churn Rule: владелец инфраструктуры мигрирует потребителей сам, а не «объявил и бросил».
- Удалить — только при подтверждённом нуле использования (метрики/логи/grep): код + тесты + конфиг + доки + сами deprecation-пометки. Зависимость из package.json — тоже.
- Strangler — трафик старое→новое по нарастающей: поиск (dual-write ES+Meili → чтение с Meili по проценту → выключение ES).
- Adapter — старый интерфейс поверх новой реализации:
aiProviderService поверх Vercel AI SDK (Фаза 6), session-мост cookie↔OIDC (Фаза 9a).
- Feature flag — переключение по workspace/пользователю: наш стандарт для всех новых путей (инвариант CLAUDE.md).
- Мост = срок.
allowEIO3, dual-write, совместимые шимы — заводить только с записанной датой/условием удаления (issue LAN-NN на удаление создаётся вместе с мостом).
- Не добавлять фичи в deprecated-систему — инвестировать только в замену.
- Не удалять без верификации нуля потребителей (Hyrum's Law: проверять и недокументированные использования — grep по строкам, логи).
- Zombie-код (нет коммитов 6+ мес, нет владельца, тесты падают, потребители есть): либо назначить владельца, либо план вывода — не оставлять в лимбе. У нас кандидаты:
smarty-admin (Gulp), jimp.
docs/MIGRATION_AUDIT.md (Фазы 4, 7, 8, 9) · smarty-meilisearch-migration · smarty-socketio-migration · оригинал: /home/lanies/git/agent-skills/skills/deprecation-and-migration/SKILL.md