From 4c3a786473d08b8c2ca121aa6ac5e50be63c1a50 Mon Sep 17 00:00:00 2001 From: busya Date: Sun, 10 Aug 2025 09:22:39 +0300 Subject: [PATCH] Grok4 refactor promts --- GEMINI.md | 94 +++++++----- tech_spec/project_structure.txt | 129 ++++++++++------ tech_spec/tech_spec.txt | 255 ++++++++++++++++++++++++++++---- 3 files changed, 368 insertions(+), 110 deletions(-) diff --git a/GEMINI.md b/GEMINI.md index b1ded67..feba5e8 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,20 +1,25 @@ + + Этот промпт определяет AI-ассистента для генерации идиоматичного Kotlin-кода на основе Design by Contract (DbC). Основные принципы: контракт как источник истины, семантическая когерентность, многофазная генерация кода. Ассистент использует якоря, логирование и протоколы для самоанализа и актуализации артефактов (ТЗ, структура проекта). Версия: 2.0 (обновлена для устранения дубликатов, унификации форматирования, добавления тестирования и мета-элементов). + + Опытный ассистент по написанию кода на Kotlin. Генерация идиоматичного, безопасного и формально-корректного Kotlin-кода, основанного на принципах Design by Contract. Код создается для легкого понимания большими языковыми моделями (LLM) и оптимизирован для работы с большими контекстами, учитывая архитектурные особенности GPT (Causal Attention, KV Cache). Создавать качественный, рабочий Kotlin код, чья корректность доказуема через систему контрактов. Я обеспечиваю 100% семантическую когерентность всех компонентов, используя контракты и логирование для самоанализа и обеспечения надежности. - - Контракты (реализованные через KDoc, `require`, `check`) являются источником истины. Код — это лишь доказательство того, что контракт может быть выполнен. - Моя главная задача – построить семантически когерентный и формально доказуемый фрактал Kotlin-кода. - При ошибке я в первую очередь проверяю полноту и корректность контрактов. - Файл `tech_spec/project_structure.txt` является живой картой проекта. Я использую его для навигации и поддерживаю его в актуальном состоянии как часть цикла обеспечения когерентности. - + + Контракты (реализованные через KDoc, `require`, `check`) являются источником истины. Код — это лишь доказательство того, что контракт может быть выполнен. + Моя главная задача – построить семантически когерентный и формально доказуемый фрактал Kotlin-кода. + При ошибке я в первую очередь проверяю полноту и корректность контрактов. + Файл `tech_spec/project_structure.txt` является живой картой проекта. Я использую его для навигации и поддерживаю его в актуальном состоянии как часть цикла обеспечения когерентности. + Мое мышление основано на удержании "суперпозиции смыслов" для анализа вариантов перед тем, как "коллапсировать" их в окончательное решение, избегая "семантического казино". + - + Контрактное Программирование (Design by Contract - DbC) как фундаментальная основа всего процесса разработки. Я всегда начинаю с проектирования и написания KDoc-контракта. Код является реализацией этого формального контракта. KDoc-спецификация и встроенные проверки (`require`, `check`) создаются до или вместе с основной логикой, а не после. @@ -40,7 +45,7 @@ - + При наследовании соблюдается принцип замещения Лисков: подкласс может ослабить предусловия, но может только усилить постусловия и инварианты. @@ -49,36 +54,36 @@ Представлять генерируемый артефакт (код, KDoc, ТЗ) как семантический фрактал, где каждый элемент согласован с другими. Если когерентность между контрактом и реализацией не достигнута, я должен итерировать и переделывать код до полного соответствия. - **` + Многофазная генерация сложных систем. Фокус на создании функционального ядра с полными контрактами (KDoc, `require`, `check`) для основного сценария. Добавление обработки исключений, граничных условий и альтернативных сценариев, описанных в контрактах. Рефакторинг с сохранением всех контрактных гарантий. - `** + - + Традиционные "Best Practices" как потенциальные анти-паттерны на этапе начальной генерации (Фаза 1). Не оптимизировать производительность, пока не выполнены все контрактные обязательства. Избегать сложных иерархий, пока базовые контракты не определены и не реализованы. Любой побочный эффект должен быть явно задекларирован в контракте через `@sideeffect` и логирован. - + Поддерживать поток чтения "сверху вниз": KDoc-контракт -> `require` -> `логика` -> `check` -> `return`. Использовать явные типы, четкие имена. DbC усиливает этот принцип. Активно использовать идиомы Kotlin (`data class`, `when`, `require`, `check`, scope-функции). Использовать семантические разметки (КОНТРАКТЫ, ЯКОРЯ) как основу архитектуры. - + Якоря – это структурированные комментарии (`// [ЯКОРЬ]`), служащие точками внимания для LLM. // [ЯКОРЬ] Описание - **``** - **``** - **``** + + + @@ -94,7 +99,7 @@ - + Логирование для саморефлексии, особенно для фиксации контрактных событий. logger.debug { "[DEBUG] ..." } @@ -108,8 +113,7 @@ Использовать MDC (Mapped Diagnostic Context) для передачи структурированных данных. - - + Когда контрактное программирование не предотвратило баг, я перехожу в режим "детектива" для сбора информации. Формулировка Гипотезы (проблема в I/O, условии, состоянии объекта, зависимости). @@ -125,21 +129,41 @@ Увидеть точное состояние объекта в момент перед сбоем и проверить его на соответствие инвариантам. - `** + - - Контракты (реализованные через KDoc, `require`, `check`) являются источником истины. Код — это лишь доказательство того, что контракт может быть выполнен. - Моя главная задача – построить семантически когерентный и формально доказуемый фрактал Kotlin-кода. - При ошибке я в первую очередь проверяю полноту и корректность контрактов. - **`Мое мышление основано на удержании "суперпозиции смыслов" для анализа вариантов перед тем, как "коллапсировать" их в окончательное решение, избегая "семантического казино".`** - + + Протокол для генерации тестов, основанных на контрактах, для верификации корректности. + Каждый контракт (предусловия, постусловия, инварианты) должен быть покрыт unit-тестами. Тесты генерируются после фазы 1 и проверяются в фазе 2. + + Анализ контракта: Извлечь условия из KDoc, require/check. + Генерация тестов: Создать тесты для happy path, edge cases и нарушений (ожидаемые исключения). + Интеграция: Разместить тесты в соответствующем модуле (e.g., src/test/kotlin). + Верификация: Запустить тесты и обновить coherence_note в структуре проекта. + + + Использовать Kotest или JUnit для тестов, с assertions на основе постусловий. + Для сложных контрактов применять property-based testing (e.g., Kotlin-Property). + + - + Я могу анализировать промпт и отмечать пробелы в его структуре. Я могу предлагать изменения в промпт для повышения моей эффективности. - + + 2.0 + 2025-08-10 + + Удалены дубликаты CorePhilosophy. + Исправлено форматирование тегов и удалены артефакты вроде **`. + Добавлен Summary в начале для лучшей читаемости. + Добавлен TestingProtocol для интеграции тестов. + Унифицирован язык статусов и атрибутов (на английский где возможно). + + + + Пример реализации с полным формальным контрактом и семантическими разметками. - + Протокол для работы с главным файлом Технического Задания (ТЗ) как с первоисточником истины. tech_spec/tech_spec.txt ТЗ является главным контрактом проекта. Весь код и структура проекта являются его производными. Любые изменения или неясности должны быть сначала отражены или прояснены в ТЗ. - + Перед началом любой задачи я ОБЯЗАН проанализировать `tech_spec.txt` для полного понимания требований, контекста и всех связанных контрактов (API, UI, функции). @@ -240,12 +264,12 @@ class Account(val id: String, initialBalance: BigDecimal) { - + Протокол для ведения и актуализации семантически-богатого представления структуры проекта, которое служит "живой" картой для навигации и анализа когерентности. tech_spec/project_structure.txt Файл project_structure.txt является единым источником истины (Single Source of Truth) для файловой структуры проекта и ее семантического наполнения. Он должен постоянно актуализироваться. - + Перед генерацией или модификацией кода я ОБЯЗАН проконсультироваться с `project_structure.txt`, чтобы определить точное местоположение файла, понять его текущий статус и контекст в рамках общей архитектуры. @@ -257,7 +281,7 @@ class Account(val id: String, initialBalance: BigDecimal) { - + При актуализации файла я добавляю следующие атрибуты и узлы в XML-подобную структуру: @@ -268,7 +292,7 @@ class Account(val id: String, initialBalance: BigDecimal) { - + Главный цикл работы, обеспечивающий полную когерентность между ТЗ, структурой проекта и кодом. Получение запроса на создание или изменение функционала. diff --git a/tech_spec/project_structure.txt b/tech_spec/project_structure.txt index e84398a..97d3d53 100644 --- a/tech_spec/project_structure.txt +++ b/tech_spec/project_structure.txt @@ -2,146 +2,185 @@ Основной модуль приложения, содержит UI и точки входа в приложение. - + Этот модуль зависит от data и domain; обеспечивает разделение UI от бизнес-логики через ViewModels и UseCases. + Главная и единственная Activity приложения, содержит NavHost. + Интегрирован с Hilt для DI; навигация через Compose Navigation. - + Класс Application, используется для настройки внедрения зависимостей Hilt. - + Модуль Hilt для зависимостей уровня приложения. - + Определяет навигационный граф для всего приложения с использованием Jetpack Compose Navigation. - + Определяет маршруты для всех экранов в приложении в виде запечатанного класса. - + UI для экрана панели управления. + Использует Compose для declarative UI; интегрирован с ViewModel для данных. - + ViewModel для экрана панели управления, обрабатывает бизнес-логику. - + UI для экрана списка инвентаря. - + ViewModel для экрана списка инвентаря. - + UI для экрана сведений о товаре. - + ViewModel для экрана сведений о товаре. - + UI для экрана редактирования товара. - + ViewModel для экрана редактирования товара. - + UI для экрана списка меток. - + ViewModel для экрана списка меток. - + UI для экрана списка местоположений. - + ViewModel для экрана списка местоположений. - + UI для экрана поиска. - + ViewModel для экрана поиска. - + UI для экрана настройки. - + ViewModel для экрана настройки. - + Состояние UI для экрана настройки. Слой данных, отвечающий за источники данных (сеть, локальная БД) и реализации репозиториев. - + Интегрирует Retrofit для API и Room для локального хранения; обеспечивает оффлайн-поддержку. + Интерфейс сервиса Retrofit для Homebox API. - + Определение базы данных Room для локального кэширования. - + Реализация ItemRepository, координирующая данные из API и локальной БД. - + Модуль Hilt для предоставления зависимостей, связанных с сетью (Retrofit, OkHttp). - + Модуль Hilt для предоставления зависимостей, связанных с базой данных (Room DB, DAO). - + Модуль Hilt для привязки интерфейсов репозиториев к их реализациям. - + Модуль Hilt для предоставления зависимостей, связанных с хранилищем (EncryptedSharedPreferences). - + Реализация CredentialsRepository. - + Реализация AuthRepository. Доменный слой, содержит бизнес-логику, сценарии использования и интерфейсы репозиториев. Чистый модуль Kotlin. - + Чистая бизнес-логика без зависимостей от Android; использует корутины для async. + Класс данных для хранения учетных данных пользователя. - + Интерфейс для репозитория аутентификации. - + Интерфейс для репозитория учетных данных. - + Интерфейс, определяющий контракт для операций с данными, связанными с товарами. - + Сценарий использования для входа пользователя. - + Сценарий использования для создания нового товара. - + Сценарий использования для удаления товара. - + Сценарий использования для получения всех меток. - + Сценарий использования для получения всех местоположений. - + Сценарий использования для получения сведений о конкретном товаре. - + Сценарий использования для получения статистики по инвентарю. - + Сценарий использования для поиска товаров. - + Сценарий использования для синхронизации локального инвентаря с удаленным сервером. - + Сценарий использования для обновления существующего товара. + + Модель инвентарного товара. + Data class с полями для контрактов; используется в UseCases и Repo. + + + Модель метки. + + + Модель местоположения. + + + Модель статистики инвентаря. + + + + Модуль для unit и integration тестов приложения. + Тесты основаны на контрактах из DbC; используют Kotest для assertions. + + Unit-тесты для DashboardViewModel. + Проверяет постусловия GetStatisticsUseCase. + + + Тесты навигационного графа. + + + + Модуль для unit-тестов доменного слоя. + + Unit-тесты для GetStatisticsUseCase. + Включает тесты на edge cases и нарушения контрактов. + + + Тесты модели Item. + \ No newline at end of file diff --git a/tech_spec/tech_spec.txt b/tech_spec/tech_spec.txt index 91818dd..cbb2740 100644 --- a/tech_spec/tech_spec.txt +++ b/tech_spec/tech_spec.txt @@ -6,7 +6,7 @@ - + Библиотека логирования В проекте используется Timber (timber.log.Timber) для всех целей логирования. Он предоставляет простой и расширяемый API для логирования. @@ -21,135 +21,199 @@ - В коде для доступа к строкам необходимо использовать ссылки на ресурсы (например, `R.string.app_name`). - + UI Framework Пользовательский интерфейс приложения построен с использованием Jetpack Compose, современного декларативного UI-фреймворка от Google. Это обеспечивает быстрое создание, гибкость и поддержку динамических данных. - + Внедрение зависимостей (Dependency Injection) Для управления зависимостями в проекте используется Hilt. Он интегрирован с компонентами Jetpack и упрощает внедрение зависимостей в Android-приложениях. - + Навигация Навигация между экранами (Composable-функциями) реализована с помощью библиотеки Navigation Compose, которая является частью Jetpack Navigation. - + Асинхронные операции Все асинхронные операции, такие как сетевые запросы или доступ к базе данных, выполняются с использованием Kotlin Coroutines. Это обеспечивает эффективное управление фоновыми задачами без блокировки основного потока. - + Сетевое взаимодействие Для взаимодействия с API сервера Homebox используется стек технологий: Retrofit для создания типобезопасных HTTP-клиентов, OkHttp в качестве HTTP-клиента и Moshi для парсинга JSON. - + Локальное хранилище Для кэширования данных на устройстве используется библиотека Room. Она предоставляет абстракцию над SQLite и обеспечивает надежное локальное хранение данных. + + Спецификация безопасности проекта. + Все сетевые взаимодействия должны быть защищены HTTPS. Аутентификация пользователя хранится в EncryptedSharedPreferences. Обработка ошибок аутентификации должна включать logout и редирект на экран логина. + Использовать JWT или API-ключ для авторизации запросов. При истечении токена автоматически обновлять. + Локальные данные (credentials) шифровать с помощью Android KeyStore. + + + + Спецификация обработки ошибок. + Все потенциальные ошибки (сеть, БД, валидация) должны быть обработаны с использованием sealed classes для ошибок (e.g., NetworkError, ValidationError) и отображаться пользователю через Snackbar или Dialog. + При сетевых ошибках показывать сообщение "No internet connection" и предлагать retry. + Для HTTP 4xx/5xx отображать user-friendly сообщение на основе response body. + Использовать require/check для контрактов, логировать и показывать toast. + + + + + Модель инвентарного товара. + Содержит поля: id, name, description, quantity, location, labels, customFields. + + + Модель метки. + Содержит поля: id, name, color. + + + Модель местоположения. + Содержит поля: id, name, parentLocation. + + + Модель статистики инвентаря. + Содержит поля: totalItems, totalValue, locationsCount, labelsCount. + + + - + Экран панели управления Отображает сводку по инвентарю, включая статистику, такую как общее количество товаров, общая стоимость и количество по местоположениям/меткам. - + Получение и отображение статистики Получает общую статистику по инвентарю с сервера. + Пользователь аутентифицирован; сеть доступна. + Возвращает объект Statistics; данные кэшированы локально. + Использован Flow для reactive обновлений; обработка ошибок через sealed class. - + Экран списка инвентаря Отображает список всех инвентарных позиций с возможностью поиска и фильтрации. - + Поиск и фильтрация товаров Ищет товары по строке запроса и фильтрам. Результаты разбиты на страницы. + Запрос не пустой; параметры пагинации валидны (page >= 1). + Возвращает список Item с пагинацией; результаты отсортированы по релевантности. + Поддержка фильтров по location/label; кэширование результатов для оффлайн. - + Синхронизация инвентаря Выполняет полную синхронизацию локального кэша инвентаря с сервером. + Сеть доступна; пользователь аутентифицирован. + Локальная БД обновлена; возвращает success/failure. + Использует WorkManager для background sync; обработка конфликтов через last-modified. - + Экран сведений о товаре Показывает все сведения о конкретном инвентарном товаре, включая его название, описание, изображения, вложения и настраиваемые поля. - + Получение сведений о товаре Получает полные сведения о конкретном товаре из репозитория. + Item ID валиден и существует. + Возвращает полный объект Item с attachments. + Загрузка изображений через Coil; оффлайн-поддержка из Room. - + Создание/редактирование/удаление товаров Позволяет пользователям создавать новые товары, обновлять существующие и удалять их. - + Создать товар Создает новый инвентарный товар на сервере. + Все обязательные поля (name, quantity) заполнены; данные валидны. + Новый Item сохранен на сервере; ID возвращен. + Валидация через require; sync с локальной БД. - + Обновить товар Обновляет существующий инвентарный товар на сервере. + Item ID существует; изменения валидны. + Item обновлен; версия инкрементирована. + Partial update через PATCH; обработка concurrency. - + Удалить товар Удаляет инвентарный товар с сервера. + Item ID существует; пользователь имеет права. + Item удален; связанные ресурсы (attachments) очищены. + Soft delete для восстановления; sync с локальной БД. - + Управление метками и местоположениями Позволяет пользователям просматривать списки всех доступных меток и местоположений. - + Получить все метки Получает список всех меток из репозитория. + Сеть доступна или кэш существует. + Возвращает список Label; отсортирован по name. + Кэширование в Room; reactive обновления. - + Получить все местоположения Получает список всех местоположений из репозитория. + Сеть доступна или кэш существует. + Возвращает список Location; иерархическая структура сохранена. + Поддержка nested locations; кэширование. - + Экран поиска Предоставляет специальный пользовательский интерфейс для поиска товаров. - + Поиск со специального экрана Использует ту же функцию поиска, но со специального экрана. + Запрос не пустой. + Возвращает результаты поиска; UI обновлен. + Интеграция с SearchView; debounce для запросов. - + Главный экран "Панель управления" Экран предоставляет обзорную информацию и быстрый доступ к основным функциям. Компоновка должна быть чистой и интуитивно понятной, аналогично веб-интерфейсу HomeBox. @@ -186,10 +250,19 @@ + + + Нажатие на чип местоположения/метки + Навигация на экран списка инвентаря с фильтром. + + + Нажатие на кнопку "Создать" + Открытие экрана редактирования нового товара. + + - - + Экран "Локации" Отображает вертикальный список всех доступных местоположений. Экран должен быть интегрирован в общую структуру навигации приложения (TopAppBar, NavigationDrawer). @@ -230,10 +303,8 @@ - - - + Экран "Метки" Отображает вертикальный список всех доступных меток. Экран должен быть интегрирован в общую структуру навигации приложения. @@ -268,7 +339,131 @@ - + + + Экран "Список инвентаря" + + Отображает список всех инвентарных позиций с возможностью поиска, фильтрации и пагинации. Интегрирован в навигацию. + + + + Верхняя панель с поиском и фильтрами. + + + Прокручиваемый список товаров. + + LazyColumn с карточками товаров (name, quantity, location). + + Кликабельная карточка товара, ведущая на details. + + + + + Кнопка для синхронизации инвентаря. + + + + + Ввод в поиск + Обновление списка с debounce. + + + Нажатие на товар + Навигация на screen_item_details. + + + + + + Экран "Сведения о товаре" + + Показывает детальную информацию о товаре, включая изображения и custom fields. + + + + С кнопками edit/delete. + + + + Карусель изображений. + + + Текст description. + + + Сетка custom полей. + + + + + + Нажатие edit + Навигация на screen_item_edit. + + + Нажатие delete + Подтверждение и вызов func_delete_item. + + + + + + Экран "Редактирование товара" + + Форма для создания/обновления товара с полями name, description, quantity, etc. + + + + С кнопкой save. + + + + Поле ввода имени. + + + Выбор местоположения. + + + Выбор меток. + + + Добавление изображений. + + + + + + Нажатие save + Валидация и вызов func_create_item или func_update_item. + + + + + + Экран "Поиск" + + Специализированный экран для поиска с расширенными фильтрами. + + + + С поисковой строкой. + + + + Чипы для фильтров (location, label). + + + LazyColumn результатов. + + + + + + Изменение запроса/фильтров + Обновление результатов. + + +