📊 Google Sheets Report Generator

Автоматическая генерация форматированных отчётов в Google Таблицах через Service Account API

📖 О проекте

Python-приложение для автоматизации создания бизнес-отчётов в Google Таблицах:

• 🔐 Безопасное подключение через Service Account (JSON-ключ)
• 📝 CRUD-операции с Google Sheets через официальный API v4
• 🎨 Автоформатирование: цвета, шрифты, объединение ячеек, границы, форматы чисел
• 🖥️ GUI на tkinter для удобной генерации отчётов
• 🛡️ Защита от formula injection — автоматическая санитизация данных
• 📑 Новый лист создаётся при каждой генерации с уникальным именем

Разработано как учебный проект в рамках курса по автоматизации бизнес-процессов.

✨ Возможности

Модуль google_sheets.py

Категория	Методы
CRUD	read_range, write_range, update_cell, append_row, clear_range
Листы	get_sheet_names, create_sheet
Форматирование	merge_cells, format_cells, set_column_width, set_borders
Безопасность	sanitize_value — защита от formula injection

GUI report_generator.py

• Ввод параметров: период отчёта, менеджер, количество строк
• Генерация случайных данных (имитация реальных сделок)
• Автоматическое форматирование отчёта
• Обработка ошибок с понятными сообщениями

🎯 Структура отчёта

┌─────────────────────────────────────────────────────┐
│        АВТОМАТИЧЕСКИЙ ОТЧЁТ (синий фон)             │
├─────────────────────────────────────────────────────┤
│ Период: 01.01.2024 - 31.12.2024                     │
│ Менеджер/Отдел: Иванов И.И.                         │
│ Дата генерации: 26.12.2024 14:30:22                 │
├───────┬───────────┬─────────┬──────────┬────────────┤
│ Дата  │ Клиент    │Сделка № │ Статус   │ Сумма      │ ← серый фон
├───────┼───────────┼─────────┼──────────┼────────────┤
│ 15.03 │ Клиент 42 │ №4521   │ Закрыта  │ 125 000 ₽  │
│ 22.05 │ Клиент 17 │ №4522   │ В работе │  87 500 ₽  │
│ ...   │    ...    │   ...   │   ...    │     ...    │
├───────┴───────────┴─────────┴──────────┼────────────┤
│ ИТОГО:                                  │ 1 523 450 ₽│ ← жёлтый фон
└─────────────────────────────────────────┴────────────┘

🚀 Быстрый старт

Требования

• Python 3.11+
• Google Cloud Project с включённым Google Sheets API
• Service Account с JSON-ключом
• Доступ Service Account к целевой таблице (роль: Editor)

Установка

1. Клонируй репозиторий:

   git clone https://github.com/yourusername/google-sheets-report-generator.git
   cd google-sheets-report-generator

2. Создай виртуальное окружение:

   # Windows
   py -3.11 -m venv .venv
   .\.venv\Scripts\activate
   
   # macOS/Linux
   python3.11 -m venv .venv
   source .venv/bin/activate

3. Установи зависимости:

   pip install -r requirements.txt

4. Настрой переменные окружения:

   Создай файл .env в корне проекта:

   GSHEETS_CREDENTIALS_PATH=your-service-account-key.json
   GSHEETS_SPREADSHEET_ID=your-spreadsheet-id

   Скопируй JSON-ключ Service Account в корень проекта.

5. Выдай доступ Service Account к таблице:

   • Открой Google Таблицу
   • Нажми "Настройки доступа" (Share)
   • Добавь email из JSON-ключа (поле client_email)
   • Выбери роль: Редактор

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

Тест модуля API:

python google_sheets.py

Выведет список листов и данные из диапазона A1:Z10.

Запуск GUI:

python report_generator.py

Заполни поля и нажми "Сгенерировать отчёт".

📁 Структура проекта

google-sheets-report-generator/
├── google_sheets.py      # Модуль для работы с Google Sheets API
├── report_generator.py   # GUI-приложение (tkinter)
├── requirements.txt      # Python зависимости
├── .env.example          # Шаблон переменных окружения
├── .gitignore            # Исключения для git
├── .cursorrules          # Правила для Cursor IDE
├── README.md             # Этот файл
└── *.json                # JSON-ключ Service Account (НЕ коммитится!)

🔐 Безопасность

⚠️ ВАЖНО

• Никогда не коммитьте JSON-ключи Service Account
• Никогда не коммитьте файл .env
• Используйте .gitignore для исключения секретов
• Service Account имеет доступ только к конкретным таблицам (через Share)

Защита от Formula Injection

Все строковые значения автоматически проходят санитизацию перед записью в таблицу:

# Строки начинающиеся с = + - @ получают апостроф
"+7 (999) 123-45-67" → "'+7 (999) 123-45-67"
"=SUM(A1:A10)"       → "'=SUM(A1:A10)"

Это предотвращает выполнение нежелательных формул и появление ошибок #ERROR!.

🛠️ Технологии

Технология	Назначение
Python 3.11+	Основной язык
google-api-python-client	Официальный клиент Google Sheets API v4
google-auth	Аутентификация через Service Account
python-dotenv	Управление переменными окружения
tkinter	GUI (встроена в Python)

📚 Документация

• Google Sheets API Reference
• Service Account Authentication
• Spreadsheet Formatting Guide

🐛 Известные проблемы

Проблема	Причина	Решение
#ERROR! в ячейках	Строки начинаются с +, =, -, @	Автоматически решено через sanitize_value()
403 PERMISSION_DENIED	Service Account не имеет доступа	Добавьте email через Share с ролью Editor
FileNotFoundError	JSON-ключ не найден	Проверьте .env и наличие файла

📸 Скриншоты

Показать скриншоты

1. Google Cloud Console — Enabled API
2. Service Account
3. Google Sheets — Настройки доступа
4. Cursor — Структура проекта
5. Терминал — Тест API
6. GUI + Результат

🤝 Лицензия

MIT License — см. файл LICENSE

👨‍💻 Автор

Георгий Белянин (Georgy Belyanin) — Python Developer

📧 Email: georgy.belyanin@gmail.com

---

⭐ Если проект был полезен, поставь звёздочку!