Calendar Application with CRON Events

1. Назначение проекта

CalendarApp — это консольное приложение на C# для управления событиями с поддержкой CRON-выражений. Приложение позволяет создавать, просматривать, удалять и отслеживать события, которые срабатывают по заданному расписанию в формате CRON.

Основная цель проекта — предоставить удобный инструмент для планирования повторяющихся задач с автоматическими уведомлениями. Приложение периодически проверяет активные события и выводит в консоль уведомления, когда наступает время их выполнения согласно CRON-расписанию. Все события сохраняются в JSON-файл (events.json), что обеспечивает сохранность данных между запусками.

Проект демонстрирует практическое применение CRON-выражений в .NET-приложениях, реализует паттерн сервисного слоя, работу с файловым хранилищем и асинхронными операциями. Это учебный проект, который может быть расширен для интеграции с внешними системами уведомлений (email, Telegram, Slack) или использован как основа для более сложных планировщиков задач.

2. Основные модули/папки и их ответственность

CalendarApp/

Корневая папка проекта, содержащая все исходные файлы и конфигурацию.

CalendarApp/Models/

Содержит классы сущностей предметной области.

• CalendarEvent.cs — основная сущность "Событие календаря". Определяет свойства события: уникальный идентификатор (Guid), заголовок, описание, CRON-выражение, время последнего срабатывания, дата создания и статус активности. Класс включает методы для валидации и сериализации/десериализации в JSON.

CalendarApp/Services/

Содержит бизнес-логику и сервисы приложения.

• CalendarService.cs — центральный сервис, управляющий событиями. Отвечает за периодическую проверку событий (через таймер), вызов обработчиков при срабатывании событий и предоставление API для работы с событиями (добавление, удаление, получение списка).
• CronService.cs — сервис для работы с CRON-выражениями. Использует библиотеку NCrontab для парсинга выражений, проверки их валидности, вычисления следующего времени срабатывания и получения описания расписания на человеческом языке.

CalendarApp/Storage/

Содержит логику хранения данных.

• EventStorage.cs — класс для работы с файловым хранилищем событий. Обеспечивает загрузку и сохранение списка событий в JSON-файл (events.json), обработку ошибок ввода-вывода и сериализацию/десериализацию данных.

Корневые файлы проекта

• Program.cs — точка входа приложения. Содержит главное меню, обработку пользовательского ввода, инициализацию сервисов и координацию работы всех компонентов.
• CalendarApp.csproj — файл проекта .NET, определяющий целевую платформу, зависимости (NCrontab) и настройки компиляции.
• events.json — файл данных, в котором хранятся все события в формате JSON (создаётся автоматически при первом запуске).

3. Ключевые сущности и термины (мини-глоссарий)

• Событие (CalendarEvent) — основная сущность приложения, представляющая запланированную задачу. Содержит заголовок, описание, CRON-выражение для определения расписания, время последнего срабатывания и статус активности.

• CRON-выражение — строка из пяти полей (минуты, часы, день месяца, месяц, день недели), определяющая расписание повторения события. Например, 0 9 * * * означает "ежедневно в 9:00 утра".

• NCrontab — сторонняя библиотека .NET для парсинга и вычисления CRON-выражений. Используется в проекте для определения следующего времени срабатывания событий.

• EventStorage — компонент, отвечающий за сохранение событий в файловой системе. Реализует паттерн репозитория, абстрагируя детали хранения от бизнес-логики.

• CalendarService — основной сервис приложения, который запускает фоновую проверку событий по таймеру и генерирует уведомления при наступлении времени срабатывания.

• CronService — сервис-обёртка над NCrontab, предоставляющий удобные методы для работы с CRON-выражениями: валидация, получение следующего времени срабатывания, человеко-читаемое описание.

• JSON-сериализация — процесс преобразования объектов C# в формат JSON для сохранения в файл и обратного преобразования при загрузке. В проекте используется System.Text.Json.

4. При помощи какого AI агента ведётся разработка приложения

Разработка приложения ведётся при помощи SourceCraft Code Assistant Agent — AI-агента, специализирующегося на программной инженерии. Агент обладает глубокими знаниями в области языков программирования (включая C#), фреймворков, паттернов проектирования и лучших практик разработки.

SourceCraft Code Assistant Agent помогает в:

• Анализе структуры существующего кода
• Создании и модификации файлов проекта
• Рефакторинге и оптимизации кода
• Написании документации (включая README.md)
• Отладке и решении проблем

Агент работает в режиме 💻 Code, что позволяет ему непосредственно редактировать исходный код, выполнять команды в терминале, читать и записывать файлы, а также использовать другие инструменты для эффективного выполнения задач разработки.

5. Правила и скиллы для AI-агента

В проекте используется система правил и скиллов для управления процессом разработки AI-агентом. Все правила и скиллы находятся в директории .codeassistant/.

Правила (rules/)

Правила определяют ограничения и требования к изменениям кода, обеспечивая сохранение критической логики и согласованность проекта.

• logic_protection.yaml — защита критических компонентов приложения:

  • Запрет на изменение логики текстового меню в Program.cs
  • Сохранение последовательности инициализации сервисов
  • Защита формата консольного вывода
  • Защита номеров команд меню и их функций

• assumption_management.yaml — управление допущениями при реализации:

  • Обязательное документирование допущений
  • Стандартизированный формат представления допущений
  • Типы допустимых и запрещённых допущений
  • Проверка допущений перед реализацией
  • Требования к комментированию кода, связанного с допущениями

• Примеры сценариев (scenario_*.yaml) — типовые примеры реализации задач с соблюдением правил:

  • scenario_adding_functionality.yaml — добавление новой функциональности (команда меню для поиска событий)
  • scenario_test_coverage.yaml — покрытие модуля тестами (модульные тесты для EventStorage)
  • scenario_refactoring.yaml — рефакторинг без изменения поведения (улучшение читаемости метода AddEvent)

Скиллы (skills/)

Скиллы предоставляют инструкции для выполнения конкретных типов задач, стандартизируя подход к разработке.

• clarifying_questions.md — руководство по задаванию уточняющих вопросов для сбора необходимой информации
• unified_code_style.md — единые стандарты оформления кода для проекта
• unified_validation.md — стандартизированный подход к валидации данных и обработке ошибок

Использование правил и скиллов

AI-агент автоматически проверяет применимость скиллов к каждой задаче и загружает соответствующие инструкции. Правила применяются для валидации всех изменений кода, предотвращая нарушение защищённой логики и обеспечивая документирование допущений.

Эта система позволяет поддерживать высокое качество кода, предсказуемость изменений и эффективное взаимодействие между разработчиками и AI-агентом.

6. Запуск приложения

Для запуска приложения необходимо:

1. Установить .NET Core SDK
2. Скачать и распаковать архив с исходным кодом
3. Открыть терминал в папке с проектом
4. Выполнить команду dotnet run

Приложение будет запущено и готово к использованию. Работа с приложением производится при попомощи выбора пунктов текстового меню и ввода ответов в терминале.