Завершить ETL-проект и документацию

docs/prompts.md

@@ -0,0 +1,498 @@
+# Исходные промпты проекта
+
+Запросы приведены в порядке их появления в чате. Пометки в квадратных скобках обозначают пропущенные команды терминала.
+
+## Оглавление
+
+1. [Постановка задачи и правила работы](#stage-1)
+2. [План реализации и модель данных](#stage-2)
+3. [Генерация синтетических данных](#stage-3)
+4. [Чтение и очистка заказов](#stage-4)
+5. [Проверка модулей и расширение тестов](#stage-5)
+6. [Уточнение аналитики и пути экспорта](#stage-6)
+7. [Статистика качества и экспорт](#stage-7)
+8. [Транзакционная загрузка и сборка пайплайна](#stage-8)
+9. [SQL-запросы и отчёт по выручке](#stage-9)
+10. [Финальная проверка и подготовка к публикации](#stage-10)
+11. [Сбор исходных промптов](#stage-11)
+12. [Проверка перед сдачей](#stage-12)
+
+<a id="stage-1"></a>
+
+## 1. Постановка задачи и правила работы
+
+Ты выступаешь в роли опытного Senior Data Engineer и помогаешь мне выполнить тестовое задание на позицию Data Engineer и разобраться в принятых решениях.
+
+Задание:
+Построить простой и надёжный ETL-пайплайн:
+CSV > очистка > агрегация выручки по дням и категориям > SQLite.
+
+Необходимо:
+1. Обработать дубли, пропуски и разные форматы дат.
+2. Показать количество отброшенных строк и причины.
+3. Подготовить три SQL-запроса с результатами: топ категорий, динамика выручки, аномалии.
+4. Обеспечить идемпотентность: повторный запуск не дублирует данные.
+5. Подготовить README, готовую базу и лог работы с ИИ.
+Технологии:
+- Python 3.11+.
+- Стандартная библиотека: csv, sqlite3, decimal и другие необходимые модули.
+- pytest для тестов.
+- Дополнительные зависимости — только при обоснованной необходимости.
+
+Общие правила:
+- Создавай и изменяй реальные файлы в рабочей папке.
+- Сначала изучай существующие файлы и применимые инструкции.
+- Не переписывай готовые части без необходимости.
+- Не создавай интерфейс, сервер, Docker и сложную архитектуру.
+- Не выполняй git commit и git push без отдельного указания.
+- Не выдумывай результаты тестов, показатели качества, ошибки ИИ и затраченное время.
+- Явно отмечай допущения и синтетическое происхождение данных.
+- Не изменяй исходный CSV при обработке.
+- Объясняй важные решения простым языком.
+- Работай только над текущим этапом, не переходи к следующему самостоятельно.
+- В конце этапа кратко сообщай: что создано, что проверено, какие ограничения остались.
+- Если запуск проверки недоступен, прямо сообщай об этом.
+
+Веди docs/ai_work_log.md по реальной истории:
+- мои запросы;
+- принятые решения;
+- обнаруженные ошибки и изменения;
+- фактически выполненные проверки.
+Не придумывай историю работы.
+
+main.py остаётся в корне и только объединяет этапы.
+Необходимые функции размещаются в src/.
+Пути к ресурсам определяются относительно корня проекта, а не текущей рабочей папки.
+
+<a id="stage-2"></a>
+
+## 2. План реализации и модель данных
+
+Изучи рабочую папку и подготовь краткий план реализации без написания кода пайплайна.
+
+Зафиксируй модель данных:
+- Одна строка — один заказ с одним товаром.
+- order_id — положительное целое число.
+- order_date — дата заказа.
+- category — категория товара.
+- quantity — положительное целое число.
+- unit_price — цена единицы в рублях.
+- Выручка = quantity × unit_price.
+- Все заказы завершены.
+- Возвраты, скидки, бесплатные товары и несколько валют не рассматриваются.
+
+Правила обработки:
+1. Все поля обязательны, кроме category.
+2. Пустую category заменять на «Не указана».
+3. Категории очищать от внешних и повторяющихся пробелов, приводить к единому регистру.
+4. Даты принимать только в форматах YYYY-MM-DD и DD.MM.YYYY.
+5. Итоговый формат даты — YYYY-MM-DD.
+6. quantity должна быть целой и строго положительной.
+7. unit_price должна быть строго положительной.
+8. Цену разбирать через Decimal, разрешая точку или запятую как десятичный разделитель, без разделителей тысяч.
+9. Цены с более чем двумя знаками после разделителя отклонять.
+10. NaN, Infinity и другие неконечные числовые значения отклонять.
+11. Деньги хранить и суммировать целым числом копеек.
+12. Значения должны помещаться в целые числа SQLite, включая рассчитанную выручку.
+
+Порядок обработки дублей:
+- Сначала удалять точные дубли значений исходных полей, оставляя первое вхождение.
+- Затем нормализовать и проверить оставшиеся записи.
+- Среди валидных записей одинаковые ID с одинаковыми нормализованными значениями считать дублями.
+- Одинаковые ID с разными нормализованными значениями считать конфликтом и отклонять все записи такой группы.
+- Невалидные записи не участвуют в поиске конфликтов среди валидных.
+- Все эти правила явно описать как принятые решения.
+
+Для каждой исходной записи сохранять номер записи в CSV.
+Не путать номер записи с физической строкой файла: CSV может содержать многострочные поля.
+
+Предложи простые интерфейсы функций между модулями.
+Выбери одно место для расчёта агрегатов.
+Для SQLite используем полную перезагрузку обеих таблиц в одной транзакции.
+
+Опиши критерии готовности и возможные неоднозначности.
+Измени docs/ai_work_log.md с фактическими решениями.
+
+<a id="stage-3"></a>
+
+## 3. Генерация синтетических данных
+
+Реализуй src/generate_data.py.
+
+Требования:
+- Создать data/raw_orders.csv.
+- Ровно 1500 записей без учёта заголовка, включая дубли и ошибочные записи.
+- Поля: order_id, order_date, category, quantity, unit_price.
+- Использовать локальный генератор случайных чисел с seed=42.
+- Использовать фиксированный диапазон дат.
+- Не использовать текущую дату или случайный порядок, зависящий от окружения.
+- Повторный запуск должен создавать идентичное содержимое CSV.
+- Большая часть записей должна быть корректной.
+
+Гарантированно добавить:
+- точные дубли;
+- одинаковые заказы с разными допустимыми форматами даты;
+- конфликтующие order_id;
+- пропуски в разных полях;
+- некорректные даты;
+- пробелы и различный регистр категорий;
+- дробные, нулевые, отрицательные и нечисловые значения quantity;
+- нулевые, отрицательные и нечисловые цены;
+- цены с лишними десятичными знаками.
+
+Использовать синтетические данные без персональной информации.
+Не подгонять данные под красивые аналитические результаты.
+
+Команда запуска:
+[Команда терминала опущена.]
+
+Добавь тесты количества записей и воспроизводимости.
+Тесты должны использовать временные файлы.
+
+Запусти генератор и тесты. Сообщай только фактические результаты.
+Обнови лог работы с ИИ.
+
+<a id="stage-4"></a>
+
+## 4. Чтение и очистка заказов
+
+Реализуй src/extract.py и src/transform.py по согласованным правилам.
+
+extract.py:
+- чтение CSV;
+- проверка обязательных заголовков;
+- проверка количества полей в записях;
+- присвоение номера исходной записи;
+- понятные сообщения о проблемах файла.
+
+Отсутствующий файл, неверные заголовки и повреждённая структура CSV — критические ошибки.
+Ошибочные значения отдельных записей — причины отбраковки.
+Полностью пустую запись внутри данных не игнорировать молча.
+
+transform.py:
+- нормализация категорий и дат;
+- проверка обязательных значений;
+- проверка числовых полей;
+- обработка точных и нормализованных дублей;
+- обработка конфликтующих ID;
+- расчёт unit_price_kopecks и revenue_kopecks.
+
+Не используй float для денежных расчётов.
+Не исправляй неизвестные значения догадками.
+Не округляй некорректные цены молча.
+
+Результат:
+1. Принятые записи:
+   order_id, order_date, category, quantity,
+   unit_price_kopecks, revenue_kopecks.
+2. Отброшенные записи:
+   номер исходной записи, исходные значения и список причин.
+
+Каждая исходная запись получает ровно один итоговый статус.
+Удалённые дубли также считаются отброшенными.
+Одна отклонённая запись может иметь несколько ошибок полей.
+Не приписывай ей проверки, которые не выполнялись после более раннего исключения.
+
+Добавь тесты:
+- допустимые и некорректные даты;
+- отсутствующие поля;
+- пустая категория;
+- точный дубль;
+- дубль после нормализации;
+- конфликт ID;
+- невалидная запись с ID валидного заказа;
+- дробное количество;
+- точный расчёт денег;
+- неконечные и слишком большие числа;
+- несколько ошибок в одной записи;
+- пустой CSV с корректным заголовком.
+
+Проверь, что исходный файл не изменяется.
+Запусти тесты и обнови лог.
+
+<a id="stage-5"></a>
+
+## 5. Проверка модулей и расширение тестов
+
+Посмотри модули в src, тесты, план реализации и журнал работы с ИИ. Сделай точечные улучшения, без переписывания проекта и переименований ради стиля. SQLite и аналитику пока не реализуй.
+
+Что нужно:
+- Дополнить тесты генератора: проверить, что все запланированные дубли, конфликты, пропуски и неверные значения действительно есть в данных.
+- Проверить чтение CSV: неверную UTF-8, ошибку доступа, многострочные поля и правильную нумерацию записей.
+- Проверить очистку: точность денег, порядок обработки дублей и конфликтов, несколько причин ошибок, баланс и порядок записей.
+- Убрать дублирование списка полей CSV простым способом, без лишних модулей.
+- Уточнить план: добавить clean_orders.csv, несколько причин отбраковки, дни с нулевой выручкой и поиск аномалий по отклонению более чем на два стандартных отклонения. При числе дней меньше 7 или нулевой дисперсии аномалии не выдавать.
+
+Не меняй рабочую логику без необходимости. Если найдёшь баг, сначала воспроизведи его тестом. Недостаток тестов сам по себе не называй ошибкой реализации.
+
+Запусти тесты через существующую .venv, проверь, что raw_orders.csv не изменился, и обнови журнал фактическими результатами. Кратко перечисли изменения, результаты проверок и оставшиеся проблемы.
+
+Коммит и push не делай.
+
+<a id="stage-6"></a>
+
+## 6. Уточнение аналитики и пути экспорта
+
+Уточни план реализации и журнал работы с ИИ: аномалии будем искать отдельно по каждой категории, а динамику показывать по общей дневной выручке.
+
+Также исправь путь очищенного CSV на outputs/clean_orders.csv.
+
+В журнале зафиксируй текущее уточнение, не переписывая историю. Код пока не изменяй, коммит и push не делай.
+
+<a id="stage-7"></a>
+
+## 7. Статистика качества и экспорт
+
+Реализуй src/quality.py: формирование статистики и сохранение CSV/JSON.
+
+Создаваемые файлы:
+
+1. outputs/clean_orders.csv
+Поля:
+order_id, order_date, category, quantity,
+unit_price_kopecks, revenue_kopecks.
+
+2. outputs/rejected_rows.csv
+Номер исходной записи, исходные значения и причины отбраковки.
+Причины сохранять в однозначном формате.
+
+3. outputs/quality_report.json
+- число исходных записей;
+- число принятых;
+- число отброшенных;
+- разбивка по итоговым причинам отбраковки;
+- счётчики отдельных обнаруженных проблем;
+- доля принятых записей.
+
+Обязательно:
+- исходные = принятые + отброшенные;
+- каждая запись учитывается один раз в итоговых количествах;
+- счётчики проблем могут пересекаться — явно поясни это;
+- при пустом входном наборе долю принятых укажи как null;
+- статистика получается из реальных результатов обработки.
+
+CSV сохраняй в utf-8-sig для корректного отображения кириллицы в Excel.
+Порядок записей и причин должен быть детерминированным.
+При повторном запуске файлы перезаписываются.
+Пустые CSV должны содержать заголовки.
+
+Модуль не должен повторно очищать данные.
+Предусмотри вызов сохранения файлов после успешной загрузки БД.
+
+Добавь необходимые проверки статистики и экспорта к существующим тестам.
+Запусти их и обнови лог.
+
+<a id="stage-8"></a>
+
+## 8. Транзакционная загрузка и сборка пайплайна
+
+Реализуй sql/schema.sql, src/database.py и main.py.
+
+База: outputs/orders.db.
+
+Таблица orders:
+- order_id;
+- order_date;
+- category;
+- quantity;
+- unit_price_kopecks;
+- revenue_kopecks.
+
+Таблица daily_category_revenue:
+- order_date;
+- category;
+- order_count;
+- revenue_kopecks.
+
+Требования:
+- первичный ключ order_id для orders;
+- составной ключ «дата + категория» для агрегатов;
+- NOT NULL и CHECK для важных инвариантов;
+- значения в SQL передавать параметрами;
+- очищенные заказы и агрегаты полностью перезагружать в одной транзакции;
+- при ошибке сохранять предыдущее содержимое обеих таблиц;
+- корректно обрабатывать пустой набор принятых записей;
+- агрегацию выполнять только в одном месте.
+
+main.py должен быть коротким и вызывать функции модулей.
+
+Команда:
+[Команда терминала опущена.]
+
+Последовательность:
+1. Чтение CSV.
+2. Очистка и формирование статистики.
+3. Транзакционная запись заказов и агрегатов.
+4. Сохранение clean_orders.csv, rejected_rows.csv и quality_report.json.
+5. После следующего этапа — выполнение аналитических запросов и сохранение результатов.
+
+При критической ошибке выводить понятное сообщение и завершаться с ненулевым кодом.
+Не сообщать об успехе до завершения всех операций.
+Не скрывать неожиданные исключения общим сообщением без диагностических деталей.
+
+SQLite и отчёты не имеют общей транзакции.
+Если запись файлов не удалась после обновления БД, явно сообщать об этом.
+
+Добавь интеграционные тесты:
+- полный запуск;
+- повторный запуск даёт одинаковое содержимое обеих таблиц;
+- агрегаты совпадают с заказами;
+- clean_orders.csv совпадает с orders;
+- сбой во время загрузки откатывает изменения;
+- неверный входной файл не меняет существующую базу.
+
+Сравнивай данные таблиц, а не байты файла SQLite.
+Все тесты выполняй во временных каталогах.
+Запусти проверки и обнови лог.
+
+<a id="stage-9"></a>
+
+## 9. SQL-запросы и отчёт по выручке
+
+Реализуй три SQL-запроса и подключи их выполнение к main.py.
+Не добавляй отдельный модуль, если достаточно небольшой функции в database.py.
+
+1. sql/top_categories.sql
+Категория, число заказов, общая выручка.
+Сортировка по убыванию выручки и затем по категории.
+
+2. sql/daily_revenue.sql
+Выручка по дням.
+Включить все дни между минимальной и максимальной датой принятых заказов.
+Дни без заказов показывать с нулём.
+Сортировка по дате.
+
+3. sql/anomalies.sql
+Аномалии дневной выручки на том же календарном диапазоне.
+
+Метод:
+- отклонение от среднего более чем на два стандартных отклонения;
+- дисперсия генеральной совокупности;
+- рассчитать среднее и затем средний квадрат отклонения через AVG;
+- сравнивать квадрат отклонения с четырьмя дисперсиями;
+- не использовать STDDEV и SQRT;
+- при количестве дней меньше 7 или нулевой дисперсии аномалии не выдавать.
+
+Используй SQL стандартной SQLite и CTE для читаемости.
+Для пустой базы запросы должны возвращать пустой результат.
+
+Денежные суммы в результатах SQL оставляй целыми копейками.
+При представлении в Markdown можно выводить рубли с двумя знаками через Decimal.
+
+После [команда терминала опущена] должен появляться outputs/query_results.md:
+- краткое описание запросов;
+- фактические результаты;
+- единицы измерения;
+- пояснение метода аномалий.
+
+Если аномалий нет, прямо укажи это.
+Не изменяй данные ради получения аномалий.
+
+Объясни, что аномалия — сигнал для проверки, а не доказанная ошибка.
+Укажи ограничения: короткая выборка, влияние выбросов и отсутствие учёта сезонности.
+Нулевые дни внутри диапазона считаем днями без заказов — это допущение, а не подтверждение полноты исходных данных.
+
+Добавь тесты запросов на маленьких контрольных наборах с известными результатами.
+Проверь явный выброс, постоянную выручку, пропущенный день и пустую базу.
+Не изменяй итоговую базу во время тестов.
+
+Запусти проверки и обнови лог.
+
+<a id="stage-10"></a>
+
+## 10. Финальная проверка и подготовка к публикации
+
+Проведи финальную проверку проекта и подготовь его к ручной публикации.
+
+README.md должен содержать:
+1. Назначение проекта.
+2. Указание, что данные синтетические.
+3. Быстрый запуск в Windows PowerShell:
+   создание виртуального окружения, установка pytest,
+   генерация данных, запуск пайплайна, запуск тестов.
+4. Структуру проекта и назначение модулей.
+5. Этапы обработки.
+6. Правила очистки, дублей и конфликтов.
+7. Схему таблиц и единицы денежных значений.
+8. Фактические результаты качества.
+9. Описание SQL-запросов и ссылку на результаты.
+10. Механизм идемпотентности.
+11. Ограничения и допущения.
+
+Проверь наличие артефактов:
+- data/raw_orders.csv;
+- outputs/clean_orders.csv;
+- outputs/rejected_rows.csv;
+- outputs/quality_report.json;
+- outputs/orders.db;
+- outputs/query_results.md;
+- docs/ai_work_log.md.
+
+Исходные синтетические данные и готовые артефакты включаем в репозиторий.
+В .gitignore исключаем виртуальное окружение, кэши, секреты и временные файлы.
+Не исключай готовую SQLite-базу общим правилом *.db.
+
+Проверь:
+- генератор воспроизводим;
+- исходный CSV не изменяется при обработке;
+- баланс строк сходится;
+- деньги считаются точно;
+- CSV и база содержат одинаковые очищенные заказы;
+- агрегаты соответствуют заказам;
+- повторный запуск не меняет данные;
+- SQL выполняется;
+- инструкция запуска соответствует реализации.
+
+Запусти полный набор тестов и финальный пайплайн.
+Проверку чистого окружения выполни, если среда позволяет; иначе явно укажи, что она не проводилась.
+
+Обнови лог ИИ по фактической истории. Не придумывай ошибки и исправления.
+Не создавай коммиты и не выполняй push.
+
+В финале кратко сообщи:
+- что создано;
+- что фактически проверено;
+- результаты обработки и тестов;
+- что осталось незавершённым;
+
+<a id="stage-11"></a>
+
+## 11. Сбор исходных промптов
+
+Создай docs/prompts.md с исходными промптами, которые я использовал при работе над проектом.
+
+Бери тексты из доступной истории чата. Сохраняй формулировки, разбей по этапам и добавь оглавление. Не включай ответы ИИ и команды терминала.
+
+Если полный текст запроса недоступен, не восстанавливай его по догадкам или журналу. Укажи, что оригинал не сохранился; краткое изложение явно пометь как пересказ.
+
+В docs/ai_work_log.md добавь ссылку на prompts.md. Остальную историю, код и результаты проверок не меняй. Коммит и push не делай.
+
+<a id="stage-12"></a>
+
+## 12. Проверка перед сдачей
+
+Проведи финальную подготовку проекта к сдаче по заданию Data Engineer.
+
+Проверь, что на месте и согласованы:
+- код загрузки, очистки, агрегации и записи в SQLite;
+- исходный CSV, очищенные данные, отбраковка и отчёт качества;
+- готовая база;
+- три SQL-запроса и фактические результаты;
+- README, журнал ИИ и исходные промпты.
+
+Не расширяй функциональность и не переименовывай файлы ради стиля.
+Если найдёшь ошибку, сначала воспроизведи её, затем исправь минимально.
+
+Запусти тесты и проверь повторный запуск пайплайна. Убедись, что исходный CSV не изменился, данные не дублируются, суммы заказов и агрегатов совпадают, а clean_orders.csv соответствует базе.
+
+В README добавь фактический результат тестов и проверенные версии Python, SQLite и pytest. Проверь команды запуска и ссылки. Кратко укажи ограничения, включая раздельное обновление базы и отчётов и особенности поиска аномалий.
+
+Проверь доступность результатов для обычного пользователя Windows.
+
+Обнови журнал только реальными действиями.
+
+В конце сообщи:
+- что исправлено;
+- что проверено и с каким результатом;
+
+