Как я упростил расчет налогового резидентства: опыт создания калькулятора для правила 183 дней
В прошлой статье я рассказал о своем нелегком пути автоматизации юридической рутины с помощью AI и Python на примере ИИ-ассистента AI Alert. На этот раз хочу поделиться своей новой разработкой, которая помогает определить налоговое резидентство РФ по правилу 183 дней.
От идеи к реализации
Недавно мы с другом, который часто путешествует, пытались посчитать, успел ли он стать налоговым резидентом РФ или ещё нет. Как вы понимаете, от этого зависело возникновение у него определённых обязанностей, в том числе по предоставлению отчётности.
Казалось бы, простая задача. Но когда мы сели разбираться, выяснилось, что всё немного сложнее, чем кажется. Начали задаваться вопросами:
- Когда начинается 12-месячный период?
- Какие поездки входят в стаж, а какие нет?
- Как учитывать дни въезда и выезда?
И тогда родилась идея автоматизировать этот процесс.
Провел пару вечеров в обнимку с VSC и Codex, и в результате появился бесплатный Telegram-бот https://t.me/rule183bot или «Правило 183 дней».
Все делал с помощью промптов: объяснил Codex на базе GPT-5.0 задачу, попросил разработать план создания бота и реализовать его после утверждения. Далее дорабатывал функционал, UX/UI по вкусу.
Что делает бот на практике
Ровно одну вещь:
Бот считает, сколько дней человек провел в России за любые последние 12 месяцев на выбранную дату, и проверяет, выполняется ли порог 183 дней.
Спокойно работает и с одной короткой поездкой, и с десятками дат.
Подходит тем, кто:
- часто путешествует;
- живет между несколькими странами;
- хочет понимать свой статус на конкретную дату;
- ведет учет для личных целей.
Сам алгоритм несложный, но избавляет от рутины, ошибок и повторных пересчетов.
Как все устроено
Для тех, кому интересна разработка, вот несколько ключевых моментов, которые обеспечивают точность и удобство бота:
Стек
Бот написан на Node.js с использованием TypeScript для надежности кода и фреймворка Telegraf для взаимодействия с Telegram API.
Собственный инлайн-календарь
Чтобы максимально упростить ввод дат, я реализовал интерактивный календарь прямо на кнопках Telegram. Можно кликать по датам, а не вводить их вручную, что значительно снижает количество ошибок и делает процесс интуитивно понятным.
Умный алгоритм «скользящего окна»
Внутри бота работает продвинутый движок, который умеет:
- Корректно обрабатывать пересекающиеся интервалы поездок.
- Автоматически учитывать краткосрочные выезды на лечение или обучение (до 6 месяцев) как дни пребывания в РФ, согласно п. 2 ст. 207 НК РФ.
- Динамически пересчитывать 12-месячное окно для любой заданной даты.
Строгое тестирование
Все ключевые алгоритмы расчета покрыты unit-тестами на Vitest, что гарантирует высокую точность и надежность результатов.
Без базы данных
Даты используются только для расчёта в текущем диалоге и не записываются на сервер.
В итоге получился быстрый, компактный инструмент, который всегда под рукой – в командировке, на встрече или в переписке с клиентом.
Буду рад обратной связи и идеям, какой функционал добавить дальше! Ваши предложения помогут сделать бота ещё полезнее для профессионального сообщества.