---
name: project-rule
description: Общее описание всех ролей и правил проекта
---

# Правила проекта Telegram Helper Bot

Этот файл объединяет все правила и паттерны разработки проекта. Для получения подробной информации по каждому разделу см. соответствующие файлы в `.cursor/rules/`.

## 📋 Список правил и шаблонов

### 1. Архитектура проекта
**Файл:** `.cursor/rules/architecture.md`  
**Описание:** Архитектурные паттерны и структура проекта Telegram бота на aiogram 3.10.0  
**Применение:** `alwaysApply: true` - применяется автоматически

### 2. Стиль кода
**Файл:** `.cursor/rules/code-style.md`  
**Описание:** Стиль кода, соглашения по именованию и форматированию  
**Применение:** `alwaysApply: true` - применяется автоматически

### 3. Паттерны работы с БД
**Файл:** `.cursor/rules/database-patterns.md`  
**Описание:** Паттерны работы с базой данных, репозитории и модели  
**Применение:** Применяется к файлам `database/**/*.py` и `**/repositories/*.py`

### 4. Зависимости и утилиты
**Файл:** `.cursor/rules/dependencies-and-utils.md`  
**Описание:** Работа с зависимостями, утилитами, метриками и внешними сервисами  
**Применение:** Применяется к файлам `helper_bot/utils/**/*.py` и `helper_bot/config/**/*.py`

### 5. Обработка ошибок
**Файл:** `.cursor/rules/error-handling.md`  
**Описание:** Обработка ошибок, исключения и логирование  
**Применение:** Опционально (не всегда применяется)

### 6. Паттерны Handlers
**Файл:** `.cursor/rules/handlers-patterns.md`  
**Описание:** Паттерны для создания handlers, services и обработки событий aiogram  
**Применение:** Применяется к файлам `helper_bot/handlers/**/*.py`

### 7. Паттерны Middleware
**Файл:** `.cursor/rules/middleware-patterns.md`  
**Описание:** Паттерны создания и использования middleware в aiogram  
**Применение:** Применяется к файлам `helper_bot/middlewares/**/*.py`

### 8. Паттерны тестирования
**Файл:** `.cursor/rules/testing.md`  
**Описание:** Паттерны тестирования, структура тестов и использование pytest  
**Применение:** Применяется к файлам `tests/**/*.py` и `test_*.py`

### 9. Шаблон Release Notes
**Файл:** `.cursor/rules/release-notes-template.md`  
**Описание:** Инструкция по оформлению Release Notes  
**Применение:** Используется при создании файлов Release Notes

## 🎯 Ключевые принципы проекта

1. **Архитектура:** Repository Pattern → Service Layer → Handlers
2. **Асинхронность:** Все операции с БД и API асинхронные
3. **Типизация:** Type hints везде, где возможно
4. **Логирование:** Всегда через `logs.custom_logger.logger`
5. **Метрики:** Декораторы `@track_time`, `@track_errors`, `@db_query_time`
6. **Версия Python:** Python 3.11.9 во всех окружениях

## 📚 Как использовать

При работе над проектом агент должен:
- Следовать архитектурным паттернам из `architecture.md`
- Применять стиль кода из `code-style.md`
- Использовать соответствующие паттерны в зависимости от контекста (handlers, middleware, database, testing)
- Обрабатывать ошибки согласно `error-handling.md`
- При создании Release Notes следовать `release-notes-template.md`

Все правила автоматически применяются в зависимости от контекста редактируемых файлов благодаря настройкам `alwaysApply` и `globs` в frontmatter каждого файла.