квест 1 Сферический конь в вакууме

Архитектурный Квест №1: Сферический Конь в Вакууме

Статус: #active Теги: #architecture #python #clean-code #domain-driven-design #practice Связи: (заметки создам потом) Hexagonal Architecture, Dependency Inversion

🛑 Проблема: Код, который "слишком много знает"

Мы часто пишем код, который намертво приклеен к своему окружению.

  • Если это скрипт, то логика перемешана с print() и input().
  • Если это бот, то бизнес-правила живут внутри хендлеров aiogram.
  • Если это веб, то расчеты лежат внутри view функций.

Последствие: Вы не можете взять эту логику и перенести её в другое место (например, сделать из CLI-утилиты Telegram-бота), не переписывая половину кода. Ваш код — это не чистый механизм, а спагетти.

🎯 Цель Квеста

Научиться выделять Domain Layer (Доменный слой). Это "Сферический конь в вакууме" — чистая бизнес-логика, которая понятия не имеет, где она работает: в консоли, на сервере NASA или в умном тостере. Ей плевать на базу данных и интернет. Она оперирует только данными и правилами.

Главный навык: Писать код, который управляет состоянием, но не взаимодействует с внешним миром напрямую.

⚔️ Задание: "Кофейный Автомат"

Время выполнения: 30–40 минут. Стек: Python 3.10+, pytest.

Сюжет

Вы пишете мозги для кофейного автомата нового поколения. Ваша задача — написать класс, который управляет процессом, но не умеет общаться с пользователем напрямую.

Правила (Hardcore Mode)

  1. Создайте файл coffee_machine.py.
  2. Напишите класс CoffeeMachine.
  3. ЗАПРЕЩЕНО использовать:
    • print() (вывод на экран)
    • input() (чтение с клавиатуры)
    • import json/sqlite (работа с диском)
  4. Взаимодействие только через аргументы методов и возвращаемые значения (return или raise).

Техническое задание (Spec)

У автомата есть состояние:

  • water (мл)
  • beans (гр)
  • coins (деньги)

Реализуйте методы:

  • insert_coin(amount: float) — внести деньги.
  • select_drink(drink_type: str) — выбрать напиток (например, "espresso" или "americano").

Логика:

  • Если денег не хватает — кидайте ошибку (например, кастомный NotEnoughMoneyError) или возвращайте объект-результат с ошибкой.
  • Если воды/зерен не хватает — ошибка.
  • Если всё ок — списываем ресурсы и возвращаем объект Coffee.

Проверка (Test)

Создайте файл test_coffee.py. Напишите тест на pytest, который покупает кофе. Если для проверки работы класса вам нужно запустить скрипт и смотреть глазами в консоль — вы проиграли. Тест должен проверять атрибуты класса.

🏆 Условие Победы (Win Condition)

Вы прошли квест, если можете утвердительно ответить на вопрос:

"Могу ли я скопировать файл coffee_machine.py в папку с Telegram-ботом, импортировать класс и заставить его работать, не меняя ни одной строчки кода внутри самого класса?"

Если да — у вас получилось Чистое Ядро.

🗺️ Что дальше? (Roadmap)

Зачем мы это делаем? Этот квест — фундамент для построения сложных, неубиваемых систем (например, AI Agents).

  1. Квест 1 (Этот): Чистое Ядро. Мы изолировали логику от ввода/вывода.
  2. Квест 2: Двуликий Янус (Ports & Adapters). Мы научим это ядро сохранять данные в базу, при этом не зная про базу. (Внедрение Гексагональной архитектуры).
  3. Квест 3: Вертикальные Срезы. Мы научимся масштабировать функционал через плагины, чтобы добавление новой фичи не ломало старые.

Начинайте с кофе. ☕