feat: scaffold SheetDoc AI MVP (backend + frontend + docker)

FastAPI backend (4 endpoints, Anthropic SDK, in-memory TTL cache, rate limit), Vite/React/Tailwind frontend (5-step wizard, Zustand store), multi-stage Dockerfile, Traefik-labelled compose for sheetdoc.telecom.quest. Rename PRD.md to PRD_SheetDoc_AI.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-22 12:43:23 +05:00 · 2026-05-22 12:43:23 +05:00 · 0f31b4517b
commit 0f31b4517b
parent efd2323d05
48 changed files with 5262 additions and 0 deletions
--- a/.dockerignore
+++ b/.dockerignore
@ -0,0 +1,12 @@
+**/node_modules
+**/dist
+**/__pycache__
+**/.pytest_cache
+**/.venv
+**/venv
+.git
+.gitignore
+*.md
+!backend/prompts/*.md
+.env
+.env.*
--- a/.env.example
+++ b/.env.example
@ -0,0 +1,3 @@
+ANTHROPIC_API_KEY=sk-ant-...
+ANTHROPIC_MODEL=claude-sonnet-4-6
+ALLOWED_ORIGINS=https://sheetdoc.telecom.quest
--- a/.gitignore
+++ b/.gitignore
@ -15,11 +15,15 @@ node_modules/
 venv/
 __pycache__/
 *.pyc
+*.egg-info/
+.pytest_cache/
 .next/
+.vite/
 dist/
 build/
 out/
 target/
+backend/static/

 # data
 *.sqlite*
--- a/28
+++ b/28
@ -0,0 +1,28 @@
+# --- Frontend build ---
+FROM node:20-alpine AS frontend
+WORKDIR /app
+COPY frontend/package.json frontend/package-lock.json* ./
+RUN npm install --no-audit --no-fund
+COPY frontend/ ./
+RUN npm run build
+
+# --- Backend runtime ---
+FROM python:3.11-slim AS backend
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY backend/requirements.txt ./requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY backend/ ./
+COPY --from=frontend /app/dist ./static
+
+EXPOSE 8000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD curl -fsS http://localhost:8000/api/health || exit 1
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
--- a/PRD_SheetDoc_AI.md
+++ b/PRD_SheetDoc_AI.md
@ -0,0 +1,661 @@
+# PRD: AI-сервис генерации документов из Google Таблиц
+
+## 1. Название продукта
+
+**Рабочее название:** SheetDoc AI
+
+**Описание в одну строку:**  
+Сайт, который анализирует данные из Google Таблицы, задаёт пользователю уточняющие вопросы и генерирует справку, презентацию или другой структурированный документ.
+
+---
+
+## 2. Проблема
+
+Офисные сотрудники, менеджеры, аналитики и специалисты телеком-направлений часто работают с данными в Google Таблицах: заявками, клиентами, статусами подключений, продажами, техническими обращениями, финансовыми показателями или операционными отчётами.
+
+Чтобы подготовить справку, презентацию или краткий отчёт, им приходится вручную:
+
+- открывать таблицу;
+- понимать структуру данных;
+- выбирать важные столбцы;
+- считать показатели;
+- формулировать выводы;
+- переносить информацию в документ или презентацию;
+- оформлять результат в понятном виде.
+
+Это занимает время, создаёт риск ошибок и требует навыков структурирования информации.
+
+**Проблема:** данные уже есть в таблице, но превратить их в понятный документ быстро и качественно сложно.
+
+---
+
+## 3. Целевая аудитория
+
+### Основная аудитория
+
+1. **Офисные сотрудники**  
+   Готовят справки, отчёты, служебные записки и сводки на основе таблиц.
+
+2. **Менеджеры телеком-направлений**  
+   Работают с заявками, клиентами, подключениями, тарифами, статусами услуг и внутренними отчётами.
+
+3. **Руководители отделов**  
+   Хотят быстро получать понятную выжимку из таблиц без ручной обработки.
+
+4. **Аналитики начального и среднего уровня**  
+   Готовят отчёты, но хотят ускорить рутинную часть работы.
+
+### Характеристики пользователя
+
+- регулярно работает с Google Таблицами;
+- не всегда имеет техническую подготовку;
+- хочет получить результат быстро;
+- ценит понятный интерфейс;
+- может не знать, как правильно сформулировать структуру документа;
+- ожидает, что система сама подскажет, какие вопросы нужно уточнить.
+
+---
+
+## 4. Цель продукта
+
+Создать веб-сервис, который помогает пользователю быстро превратить данные из Google Таблицы в структурированный документ.
+
+### Бизнес-ценность продукта
+
+Продукт должен:
+
+- сокращать время подготовки справок и презентаций;
+- снижать количество ручных ошибок;
+- помогать пользователю лучше понимать данные;
+- автоматизировать рутинную офисную работу;
+- давать качественный черновик документа, который можно использовать или доработать.
+
+### Главная цель MVP
+
+Пользователь должен пройти сценарий:
+
+**вставил ссылку на Google Таблицу → выбрал лист → система проанализировала данные → задала уточняющие вопросы → сгенерировала текстовую справку → пользователь скопировал результат.**
+
+---
+
+## 5. Описание продукта
+
+SheetDoc AI — это сайт, где пользователь вставляет ссылку на Google Таблицу, выбирает нужный лист, а система анализирует активные строки и столбцы с данными.
+
+После анализа система определяет структуру таблицы, примерное назначение данных и задаёт пользователю уточняющие вопросы. На основе данных таблицы и ответов пользователя сервис генерирует один из результатов:
+
+- справку;
+- аналитический отчёт;
+- структуру презентации;
+- другой структурированный документ.
+
+На первом этапе продукт должен быть простым и сфокусированным на одном главном сценарии: генерация текстовой справки из одного листа Google Таблицы.
+
+---
+
+## 6. Основной пользовательский сценарий
+
+### Сценарий: генерация справки из Google Таблицы
+
+1. Пользователь открывает сайт.
+2. Видит поле для вставки ссылки на Google Таблицу.
+3. Вставляет ссылку.
+4. Система проверяет корректность ссылки.
+5. Система проверяет доступность таблицы.
+6. Система получает список листов.
+7. Пользователь выбирает конкретный лист.
+8. Система анализирует активные строки и столбцы.
+9. Система показывает краткое описание найденных данных:
+   - количество строк;
+   - количество столбцов;
+   - предполагаемые заголовки;
+   - возможные типы данных;
+   - найденные ключевые категории.
+10. Система задаёт пользователю уточняющие вопросы.
+11. Пользователь отвечает на вопросы.
+12. Система генерирует справку.
+13. Пользователь видит результат на странице.
+14. Пользователь копирует текст результата.
+
+---
+
+## 7. Дополнительные пользовательские сценарии
+
+### 7.1. Неверная ссылка
+
+Если пользователь вставил некорректную ссылку, система должна показать понятную ошибку.
+
+**Пример сообщения:**  
+> Не удалось распознать ссылку на Google Таблицу. Проверьте, что ссылка ведёт именно на Google Sheets.
+
+### 7.2. Таблица закрыта
+
+Если таблица недоступна, система должна объяснить, что нужно сделать.
+
+**Пример сообщения:**  
+> У системы нет доступа к этой таблице. Откройте доступ по ссылке или войдите через Google-аккаунт, если эта функция доступна.
+
+### 7.3. В таблице несколько листов
+
+Если в таблице несколько листов, система должна показать их список и попросить выбрать один лист.
+
+### 7.4. Лист пустой
+
+Если выбранный лист не содержит данных, система должна сообщить об этом и предложить выбрать другой лист.
+
+### 7.5. Таблица плохо структурирована
+
+Если система не может уверенно определить заголовки или структуру таблицы, она должна задать дополнительные вопросы:
+
+- где находятся заголовки;
+- какие колонки важны;
+- какие строки нужно учитывать;
+- какой результат нужен пользователю.
+
+### 7.6. Пользователь хочет презентацию
+
+В MVP система может генерировать не полноценный `.pptx`, а структуру презентации:
+
+- название презентации;
+- список слайдов;
+- заголовок каждого слайда;
+- ключевые тезисы;
+- рекомендации по визуализации.
+
+Полноценный экспорт в `.pptx` относится к будущим улучшениям.
+
+---
+
+## 8. Функциональные требования
+
+## 8.1. Импорт данных из Google Sheets
+
+Система должна позволять пользователю вставить ссылку на Google Таблицу.
+
+### Требования
+
+- Пользователь может вставить ссылку в специальное поле.
+- Система проверяет, является ли ссылка ссылкой на Google Sheets.
+- Система извлекает идентификатор таблицы из ссылки.
+- Система проверяет доступность таблицы.
+- Система получает список листов таблицы.
+- Система загружает данные выбранного листа.
+
+### Для MVP
+
+В первой версии поддерживаются только таблицы, доступные по публичной ссылке или ссылке с открытым доступом.
+
+### Не входит в MVP
+
+- полноценная авторизация через Google;
+- работа с приватными таблицами через OAuth;
+- загрузка файлов Excel;
+- подключение к корпоративным хранилищам.
+
+---
+
+## 8.2. Выбор листа таблицы
+
+Система должна позволять пользователю выбрать конкретный лист.
+
+### Требования
+
+- Если в таблице один лист, система может выбрать его автоматически.
+- Если листов несколько, пользователь должен выбрать нужный.
+- Система должна показывать название каждого листа.
+- Система должна определять пустые листы.
+- Пользователь должен иметь возможность вернуться и выбрать другой лист.
+
+---
+
+## 8.3. Определение активного диапазона данных
+
+Система должна определить, какие строки и столбцы реально содержат данные.
+
+### Требования
+
+- Игнорировать полностью пустые строки.
+- Игнорировать полностью пустые столбцы.
+- Определять первую строку с заголовками.
+- Определять последнюю строку с данными.
+- Учитывать таблицы, где есть пропущенные значения.
+- Учитывать таблицы, где внутри данных есть пустые ячейки.
+
+### Пример
+
+Если лист содержит данные в диапазоне `A1:H250`, а после 250-й строки пусто, система должна анализировать только активный диапазон, а не весь лист.
+
+---
+
+## 8.4. Анализ колонок и строк
+
+Система должна анализировать структуру данных.
+
+### Система должна определить
+
+- названия колонок;
+- количество строк;
+- количество столбцов;
+- типы данных в колонках;
+- текстовые поля;
+- числовые поля;
+- даты;
+- статусы;
+- категории;
+- повторяющиеся значения;
+- возможные ключевые показатели;
+- возможные проблемы в данных.
+
+### Примеры типов колонок
+
+- ФИО или название клиента;
+- номер заявки;
+- дата заявки;
+- статус;
+- сумма;
+- услуга;
+- тариф;
+- регион;
+- комментарий;
+- ответственный сотрудник.
+
+---
+
+## 8.5. Уточняющие вопросы пользователю
+
+После анализа таблицы система должна задавать пользователю вопросы, чтобы правильно сформировать итоговый документ.
+
+### Требования
+
+- Система задаёт вопросы на основе структуры таблицы.
+- Количество вопросов должно быть ограничено.
+- В MVP рекомендуется задавать от 3 до 7 вопросов.
+- Пользователь должен понимать, зачем задаётся каждый вопрос.
+- Пользователь может пропустить необязательные вопросы.
+- Ответы пользователя используются при генерации итогового документа.
+
+### Примеры вопросов
+
+1. Для кого готовится документ?
+2. Какой тип документа нужен: справка, отчёт или структура презентации?
+3. Какой стиль нужен: официальный, краткий, аналитический или управленческий?
+4. Какие колонки являются ключевыми?
+5. Нужно ли добавить выводы и рекомендации?
+6. Нужно ли учитывать только определённые статусы?
+7. Какой период данных нужно анализировать?
+
+---
+
+## 8.6. Генерация результата
+
+Система должна генерировать структурированный документ на основе данных таблицы и ответов пользователя.
+
+### Для MVP
+
+Поддерживается генерация:
+
+- текстовой справки;
+- краткого аналитического отчёта;
+- структуры презентации без экспорта в `.pptx`.
+
+### Справка должна включать
+
+- заголовок;
+- краткое описание источника данных;
+- основные показатели;
+- ключевые наблюдения;
+- выводы;
+- при необходимости рекомендации;
+- дату генерации.
+
+### Структура презентации должна включать
+
+- название презентации;
+- цель презентации;
+- список слайдов;
+- заголовки слайдов;
+- ключевые тезисы;
+- предложения по графикам или таблицам.
+
+---
+
+## 8.7. Просмотр результата
+
+После генерации пользователь должен увидеть результат на странице.
+
+### Требования
+
+- Результат отображается в читаемом виде.
+- Пользователь может скопировать текст.
+- Пользователь может вернуться к вопросам и изменить ответы.
+- Пользователь может повторно сгенерировать результат.
+- Система должна показывать статус генерации.
+
+---
+
+## 8.8. Экспорт или сохранение результата
+
+### Для MVP
+
+Обязательная функция:
+
+- копирование текста результата.
+
+### После MVP
+
+Возможные форматы экспорта:
+
+- `.docx`;
+- `.pdf`;
+- `.pptx`;
+- сохранение в личном кабинете;
+- отправка результата по ссылке;
+- экспорт обратно в Google Docs или Google Slides.
+
+---
+
+## 9. Нефункциональные требования
+
+## 9.1. Безопасность
+
+Система должна безопасно работать с пользовательскими таблицами.
+
+### Нужно продумать
+
+- как пользователь даёт доступ к таблице;
+- какие данные система получает;
+- как ограничить доступ только нужной таблицей;
+- как не запрашивать лишние права;
+- как обрабатывать закрытые таблицы;
+- как защитить данные от несанкционированного доступа.
+
+### Для MVP
+
+Система работает только с таблицами, доступными по ссылке. Пользователь сам отвечает за настройку доступа.
+
+---
+
+## 9.2. Приватность данных
+
+Данные таблицы могут содержать персональную, коммерческую или внутреннюю информацию.
+
+### Требования
+
+- Пользователь должен понимать, какие данные обрабатываются.
+- Система должна явно сообщать, сохраняются ли данные.
+- Для MVP желательно не хранить содержимое таблиц дольше времени сессии.
+- Если данные сохраняются, пользователь должен знать зачем.
+- Нужно предусмотреть возможность удаления данных в будущих версиях.
+
+### Рекомендация для MVP
+
+Не сохранять исходные данные таблицы в базе данных. Использовать их только для генерации результата в рамках текущей сессии.
+
+---
+
+## 9.3. Производительность
+
+Система должна обрабатывать таблицы за приемлемое время.
+
+### Ориентиры
+
+- до 100 строк — быстро, почти мгновенно;
+- до 1 000 строк — допустимо несколько секунд;
+- до 5 000 строк — нужен индикатор прогресса;
+- больше 5 000 строк — возможно ограничение MVP или предупреждение пользователя.
+
+### Для MVP
+
+Рекомендуемый лимит: до 1 000 строк и до 30 активных столбцов.
+
+---
+
+## 9.4. UX
+
+Интерфейс должен быть простым и понятным для нетехнического пользователя.
+
+### Требования
+
+- один основной сценарий на главной странице;
+- понятное поле для ссылки;
+- подсказка, как открыть доступ к таблице;
+- понятный выбор листа;
+- показ краткого анализа данных;
+- простые уточняющие вопросы;
+- понятные сообщения об ошибках;
+- минимум лишних настроек в MVP.
+
+---
+
+## 9.5. Обработка ошибок
+
+Система должна корректно обрабатывать ошибки.
+
+### Возможные ошибки
+
+1. Неверная ссылка.
+2. Ссылка не ведёт на Google Таблицу.
+3. Таблица закрыта.
+4. Нет доступа к таблице.
+5. Не удалось получить список листов.
+6. Выбранный лист пустой.
+7. В таблице слишком много данных.
+8. Не удалось определить структуру данных.
+9. Не удалось сгенерировать документ.
+10. Пользователь не ответил на обязательные вопросы.
+
+### Принцип сообщений об ошибках
+
+Каждая ошибка должна отвечать на три вопроса:
+
+1. Что произошло?
+2. Почему это могло случиться?
+3. Что пользователю сделать дальше?
+
+---
+
+## 10. Ограничения
+
+### Ограничения MVP
+
+В первую версию не входят:
+
+- авторизация через Google;
+- работа с приватными таблицами через OAuth;
+- полноценный экспорт в `.pptx`;
+- полноценный экспорт в `.docx`;
+- личный кабинет;
+- история генераций;
+- командная работа;
+- корпоративные шаблоны;
+- автоматическое создание графиков;
+- интеграция с CRM;
+- поддержка Excel-файлов;
+- обработка нескольких листов одновременно.
+
+### Технические ограничения
+
+- Google Sheets может ограничивать доступ к таблицам.
+- Публичные таблицы могут содержать чувствительные данные.
+- Большие таблицы могут обрабатываться медленно.
+- Данные могут быть плохо структурированы.
+- AI-модель может ошибаться в интерпретации данных.
+- Пользователь должен проверять результат перед использованием.
+
+---
+
+## 11. MVP
+
+## 11.1. Цель MVP
+
+Проверить, нужен ли пользователям простой сервис, который превращает данные из Google Таблицы в текстовую справку.
+
+## 11.2. Обязательные функции MVP
+
+1. Поле для вставки ссылки на Google Таблицу.
+2. Проверка корректности ссылки.
+3. Получение списка листов.
+4. Выбор одного листа.
+5. Загрузка данных выбранного листа.
+6. Определение активных строк и столбцов.
+7. Анализ структуры таблицы.
+8. Генерация 3–7 уточняющих вопросов.
+9. Форма ответов пользователя.
+10. Генерация текстовой справки.
+11. Просмотр результата на странице.
+12. Копирование результата.
+13. Обработка основных ошибок.
+
+## 11.3. Необязательные функции MVP
+
+- генерация структуры презентации;
+- повторная генерация результата;
+- изменение стиля документа;
+- ограниченный предпросмотр таблицы;
+- экспорт в Markdown.
+
+## 11.4. Не входит в MVP
+
+- экспорт в `.pptx`;
+- экспорт в `.docx`;
+- экспорт в `.pdf`;
+- авторизация;
+- личный кабинет;
+- сохранение истории;
+- интеграция с Google Drive;
+- командные функции.
+
+## 11.5. MVP-сценарий end-to-end
+
+1. Пользователь вставляет публичную ссылку на Google Таблицу.
+2. Система получает список листов.
+3. Пользователь выбирает один лист.
+4. Система анализирует активный диапазон.
+5. Система показывает краткое описание данных.
+6. Система задаёт уточняющие вопросы.
+7. Пользователь отвечает.
+8. Система генерирует текстовую справку.
+9. Пользователь копирует результат.
+
+---
+
+## 12. Будущие улучшения
+
+После проверки MVP можно добавить:
+
+1. Авторизацию через Google.
+2. Работу с приватными Google Таблицами.
+3. Экспорт в `.docx`.
+4. Экспорт в `.pdf`.
+5. Экспорт в `.pptx`.
+6. Генерацию полноценной презентации.
+7. Автоматические графики и диаграммы.
+8. Шаблоны документов.
+9. Корпоративный стиль документов.
+10. Личный кабинет.
+11. Историю генераций.
+12. Командную работу.
+13. Интеграцию с CRM.
+14. Поддержку Excel-файлов.
+15. Поддержку нескольких листов.
+16. Настройку промптов под компанию.
+17. Проверку качества данных перед генерацией.
+18. Автоматическое определение типа таблицы: заявки, продажи, финансы, HR, проекты.
+
+---
+
+## 13. Критерии готовности MVP
+
+MVP можно считать готовым, если:
+
+1. Пользователь может вставить ссылку на публичную Google Таблицу.
+2. Система корректно определяет доступность таблицы.
+3. Система показывает список листов.
+4. Пользователь может выбрать лист.
+5. Система определяет активные строки и столбцы.
+6. Система анализирует заголовки и структуру данных.
+7. Система задаёт релевантные уточняющие вопросы.
+8. Пользователь может ответить на вопросы.
+9. Система генерирует понятную текстовую справку.
+10. Пользователь может скопировать результат.
+11. Основные ошибки обрабатываются понятными сообщениями.
+12. Пользователь без помощи разработчика может пройти сценарий от начала до конца.
+
+---
+
+## 14. Метрики успеха
+
+### Продуктовые метрики
+
+1. Доля пользователей, которые дошли от вставки ссылки до готового документа.
+2. Среднее время от вставки ссылки до получения результата.
+3. Доля успешных генераций.
+4. Доля пользователей, которые скопировали результат.
+5. Доля пользователей, которые повторно воспользовались сервисом.
+6. Количество ошибок при обработке таблиц.
+
+### Качественные метрики
+
+1. Пользователь понимает, что делать на каждом шаге.
+2. Пользователь считает результат полезным.
+3. Пользователь готов использовать справку как черновик рабочего документа.
+4. Пользователь хочет добавить экспорт в `.docx` или `.pptx`.
+5. Пользователь готов загрузить вторую таблицу после первой генерации.
+
+---
+
+## 15. Критерии успешного выполнения PRD
+
+Этот PRD можно считать достаточным для перехода к проектированию архитектуры, если:
+
+1. Понятно, какую проблему решает продукт.
+2. Понятно, кто целевая аудитория.
+3. Описан основной пользовательский сценарий end-to-end.
+4. Определены обязательные функции MVP.
+5. Зафиксировано, что не входит в первую версию.
+6. Продуманы ошибки и ограничения.
+7. Есть понятные критерии готовности.
+8. Требования можно превратить в backlog задач.
+9. Документ не перегружен технической реализацией.
+10. Команда может на его основе перейти к `Architecture.md`.
+
+---
+
+## 16. Открытые вопросы
+
+Перед проектированием архитектуры нужно дополнительно уточнить:
+
+1. Кто будет первым целевым пользователем: офисный сотрудник, менеджер, руководитель или аналитик?
+2. Какие таблицы будут использоваться чаще всего: заявки, продажи, клиенты, финансы, проекты или HR?
+3. Нужно ли в MVP поддерживать только справки или ещё структуру презентации?
+4. Должен ли пользователь редактировать результат прямо на сайте?
+5. Нужно ли сохранять результат после закрытия страницы?
+6. Нужен ли вход в аккаунт в первой версии?
+7. Как обрабатывать приватные Google Таблицы?
+8. Какие лимиты по строкам и столбцам принять для MVP?
+9. Нужен ли экспорт в `.docx` уже в первой версии?
+10. Нужно ли учитывать корпоративный стиль документа?
+11. Должна ли система делать выводы и рекомендации или только структурировать данные?
+12. Нужно ли предупреждать пользователя, если таблица содержит персональные данные?
+
+---
+
+## 17. Следующий документ после PRD
+
+После утверждения PRD нужно подготовить файл:
+
+**`Architecture.md`**
+
+В нём следует описать:
+
+- общий технический подход;
+- frontend;
+- backend;
+- работу с Google Sheets;
+- обработку данных;
+- AI-логику;
+- хранение данных;
+- безопасность;
+- структуру API;
+- основные модули системы;
+- план разработки MVP.
--- a/README.md
+++ b/README.md
@ -24,3 +24,43 @@
 Изменения сохранятся в Gitea и будут доступны при следующем входе.

 В этой папке уже инициализирован git и подключен remote `origin` → Gitea.
+
+---
+
+## SheetDoc AI: запуск
+
+Backend (локально):
+
+```bash
+cd backend
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+export ANTHROPIC_API_KEY=sk-ant-...
+uvicorn app.main:app --reload
+```
+
+Frontend (локально, dev-режим):
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Dev-сервер на `http://localhost:5173`, проксирует `/api` на `http://localhost:8000`.
+
+Тесты backend:
+
+```bash
+cd backend && pytest
+```
+
+Деплой (`sheetdoc.telecom.quest`):
+
+```bash
+cp .env.example .env   # вписать ANTHROPIC_API_KEY
+docker compose up -d --build
+```
+
+Сеть `traefik` должна быть создана на сервере: `docker network create traefik` (если ещё нет).
+
--- a/backend/app/init.py
+++ b/backend/app/init.py
--- a/backend/app/cache.py
+++ b/backend/app/cache.py
@ -0,0 +1,5 @@
+from cachetools import TTLCache
+from .config import settings
+
+
+profile_cache: TTLCache = TTLCache(maxsize=128, ttl=settings.cache_ttl_seconds)
--- a/backend/app/column_profiler.py
+++ b/backend/app/column_profiler.py
@ -0,0 +1,77 @@
+from collections import Counter
+from dateutil import parser as dateparser
+
+from .models import ColumnProfile, ColumnType
+
+
+def _is_empty(s: str) -> bool:
+    return s is None or str(s).strip() == ""
+
+
+def _is_number(s: str) -> bool:
+    v = str(s).strip().replace(" ", "").replace(",", ".")
+    if not v:
+        return False
+    try:
+        float(v)
+        return True
+    except ValueError:
+        return False
+
+
+def _is_bool(s: str) -> bool:
+    return str(s).strip().lower() in {"true", "false", "да", "нет", "yes", "no", "0", "1"}
+
+
+def _is_date(s: str) -> bool:
+    v = str(s).strip()
+    if not v or len(v) < 4:
+        return False
+    try:
+        dateparser.parse(v, dayfirst=True, fuzzy=False)
+        return True
+    except (ValueError, OverflowError):
+        return False
+
+
+def _infer_type(values: list[str]) -> ColumnType:
+    non_empty = [v for v in values if not _is_empty(v)]
+    if not non_empty:
+        return "empty"
+
+    n = len(non_empty)
+    nums = sum(1 for v in non_empty if _is_number(v))
+    if nums / n >= 0.85:
+        return "number"
+
+    bools = sum(1 for v in non_empty if _is_bool(v))
+    if bools / n >= 0.85 and len({v.strip().lower() for v in non_empty}) <= 4:
+        return "bool"
+
+    dates = sum(1 for v in non_empty if _is_date(v))
+    if dates / n >= 0.7:
+        return "date"
+
+    return "text"
+
+
+def profile_columns(headers: list[str], data: list[list[str]]) -> list[ColumnProfile]:
+    profiles: list[ColumnProfile] = []
+    total = len(data) if data else 1
+
+    for i, name in enumerate(headers):
+        col = [row[i] if i < len(row) else "" for row in data]
+        non_empty = [v for v in col if not _is_empty(v)]
+        fill = round(len(non_empty) / total, 3) if total else 0.0
+        counter = Counter(v.strip() for v in non_empty)
+        top = [val for val, _ in counter.most_common(3)]
+        profiles.append(
+            ColumnProfile(
+                name=name,
+                type=_infer_type(col),
+                fill=fill,
+                unique=len(counter),
+                top=top,
+            )
+        )
+    return profiles
--- a/backend/app/config.py
+++ b/backend/app/config.py
@ -0,0 +1,17 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    anthropic_api_key: str = ""
+    anthropic_model: str = "claude-sonnet-4-6"
+    allowed_origins: str = "*"
+    max_csv_bytes: int = 5 * 1024 * 1024
+    max_rows: int = 1000
+    max_cols: int = 30
+    cache_ttl_seconds: int = 600
+    static_dir: str = "static"
+
+
+settings = Settings()
--- a/backend/app/document_generator.py
+++ b/backend/app/document_generator.py
@ -0,0 +1,42 @@
+import json
+from datetime import datetime, timezone
+
+from .llm_client import llm, load_prompt
+from .models import GenerateRequest, GenerateResponse
+
+
+SYSTEM = load_prompt("report_system.md")
+
+
+def _build_user(req: GenerateRequest, today: str) -> str:
+    sample = req.dataSample[:50]
+    payload = {
+        "today": today,
+        "mode": req.mode,
+        "profile": {
+            "sheetName": req.profile.sheetName,
+            "rows": req.profile.rows,
+            "cols": req.profile.cols,
+            "headers": req.profile.headers,
+            "columns": [c.model_dump() for c in req.profile.columns],
+        },
+        "answers": [a.model_dump() for a in req.answers],
+        "dataSample": sample,
+    }
+    return (
+        "Контекст для генерации:\n\n"
+        f"{json.dumps(payload, ensure_ascii=False, indent=2)}\n\n"
+        "Сгенерируй документ согласно правилам системного промпта."
+    )
+
+
+async def generate_document(req: GenerateRequest) -> GenerateResponse:
+    now = datetime.now(timezone.utc)
+    today = now.date().isoformat()
+    user = _build_user(req, today)
+    text = await llm.complete(SYSTEM, user, max_tokens=4000, temperature=0.5)
+    return GenerateResponse(
+        document=text,
+        generatedAt=now.isoformat(),
+        mode=req.mode,
+    )
--- a/backend/app/errors.py
+++ b/backend/app/errors.py
@ -0,0 +1,92 @@
+from fastapi import HTTPException
+from fastapi.responses import JSONResponse
+
+
+class DomainError(Exception):
+    code: str
+    status: int = 400
+    what: str = ""
+    why: str = ""
+    next: str = ""
+
+    def __init__(self, what: str = "", why: str = "", next: str = ""):
+        if what:
+            self.what = what
+        if why:
+            self.why = why
+        if next:
+            self.next = next
+        super().__init__(self.what or self.code)
+
+
+class InvalidUrl(DomainError):
+    code = "INVALID_URL"
+    what = "Ссылка пустая или невалидная."
+    why = "Поле обязательно и должно содержать корректный URL."
+    next = "Скопируйте ссылку из адресной строки браузера."
+
+
+class NotASheet(DomainError):
+    code = "NOT_A_SHEET"
+    what = "Ссылка не похожа на Google Sheets."
+    why = "Поддерживаются только ссылки вида docs.google.com/spreadsheets/d/<id>."
+    next = "Откройте таблицу в Google Sheets и скопируйте URL целиком."
+
+
+class SheetForbidden(DomainError):
+    code = "SHEET_FORBIDDEN"
+    status = 403
+    what = "У сервиса нет доступа к таблице."
+    why = "Таблица закрыта или доступ ограничен."
+    next = "Откройте доступ «Все, у кого есть ссылка → Читатель»."
+
+
+class SheetNotFound(DomainError):
+    code = "SHEET_NOT_FOUND"
+    status = 404
+    what = "Таблица не найдена."
+    why = "Идентификатор таблицы неверен или таблица удалена."
+    next = "Проверьте, что ссылка открывается в браузере."
+
+
+class SheetEmpty(DomainError):
+    code = "SHEET_EMPTY"
+    what = "Выбранный лист пустой."
+    why = "В листе нет строк с данными."
+    next = "Выберите другой лист или добавьте данные."
+
+
+class SheetTooLarge(DomainError):
+    code = "SHEET_TOO_LARGE"
+    what = "В таблице слишком много данных для MVP."
+    why = "Лимит MVP — 1000 строк × 30 колонок."
+    next = "Сузьте диапазон или удалите неиспользуемые колонки."
+
+
+class StructureUnclear(DomainError):
+    code = "STRUCTURE_UNCLEAR"
+    what = "Не удалось уверенно определить структуру таблицы."
+    why = "Заголовки не однозначны или строки сильно разнородны."
+    next = "Ответьте на дополнительные вопросы о структуре."
+
+
+class LlmFailed(DomainError):
+    code = "LLM_FAILED"
+    status = 502
+    what = "Не удалось сгенерировать ответ модели."
+    why = "Временная ошибка модели или превышено время ожидания."
+    next = "Повторите попытку через несколько секунд."
+
+
+def to_response(err: DomainError) -> JSONResponse:
+    return JSONResponse(
+        status_code=err.status,
+        content={
+            "error": {
+                "code": err.code,
+                "what": err.what,
+                "why": err.why,
+                "next": err.next,
+            }
+        },
+    )
--- a/backend/app/llm_client.py
+++ b/backend/app/llm_client.py
@ -0,0 +1,82 @@
+import asyncio
+import json
+from pathlib import Path
+from typing import Optional
+
+from anthropic import AsyncAnthropic, APIError
+
+from .config import settings
+from .errors import LlmFailed
+
+
+PROMPTS_DIR = Path(__file__).resolve().parent.parent / "prompts"
+
+
+def load_prompt(name: str) -> str:
+    return (PROMPTS_DIR / name).read_text(encoding="utf-8")
+
+
+class LlmClient:
+    def __init__(self) -> None:
+        self._client: Optional[AsyncAnthropic] = None
+
+    @property
+    def client(self) -> AsyncAnthropic:
+        if self._client is None:
+            if not settings.anthropic_api_key:
+                raise LlmFailed(
+                    what="API-ключ не настроен.",
+                    why="ANTHROPIC_API_KEY не задан.",
+                    next="Задайте переменную окружения и перезапустите сервис.",
+                )
+            self._client = AsyncAnthropic(api_key=settings.anthropic_api_key)
+        return self._client
+
+    async def complete(
+        self,
+        system: str,
+        user: str,
+        max_tokens: int = 2048,
+        temperature: float = 0.4,
+    ) -> str:
+        last_err: Optional[Exception] = None
+        for attempt in range(3):
+            try:
+                msg = await self.client.messages.create(
+                    model=settings.anthropic_model,
+                    max_tokens=max_tokens,
+                    temperature=temperature,
+                    system=[
+                        {
+                            "type": "text",
+                            "text": system,
+                            "cache_control": {"type": "ephemeral"},
+                        }
+                    ],
+                    messages=[{"role": "user", "content": user}],
+                )
+                parts = [b.text for b in msg.content if getattr(b, "text", None)]
+                return "".join(parts).strip()
+            except APIError as e:
+                last_err = e
+                await asyncio.sleep(2 ** attempt)
+        raise LlmFailed(why=f"Anthropic API: {last_err}")
+
+    async def complete_json(self, system: str, user: str, max_tokens: int = 2048) -> dict:
+        raw = await self.complete(system, user, max_tokens=max_tokens, temperature=0.2)
+        raw = raw.strip()
+        if raw.startswith("```"):
+            raw = raw.strip("`")
+            if raw.startswith("json"):
+                raw = raw[4:]
+            raw = raw.strip()
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError as e:
+            raise LlmFailed(
+                why=f"Модель вернула невалидный JSON: {e}.",
+                next="Повторите попытку.",
+            )
+
+
+llm = LlmClient()
--- a/backend/app/logging_setup.py
+++ b/backend/app/logging_setup.py
@ -0,0 +1,18 @@
+import logging
+import structlog
+
+
+def setup_logging() -> None:
+    logging.basicConfig(format="%(message)s", level=logging.INFO)
+    structlog.configure(
+        processors=[
+            structlog.processors.add_log_level,
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.processors.JSONRenderer(),
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(logging.INFO),
+        cache_logger_on_first_use=True,
+    )
+
+
+log = structlog.get_logger()
--- a/backend/app/main.py
+++ b/backend/app/main.py
@ -0,0 +1,168 @@
+from contextlib import asynccontextmanager
+from pathlib import Path
+import time
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from fastapi.staticfiles import StaticFiles
+from slowapi import Limiter
+from slowapi.errors import RateLimitExceeded
+from slowapi.util import get_remote_address
+
+from .config import settings
+from .cache import profile_cache
+from .errors import (
+    DomainError,
+    SheetEmpty,
+    SheetTooLarge,
+    to_response,
+)
+from .logging_setup import setup_logging, log
+from .models import (
+    GenerateRequest,
+    GenerateResponse,
+    LoadRequest,
+    LoadResponse,
+    QuestionsRequest,
+    QuestionsResponse,
+    ResolveRequest,
+    ResolveResponse,
+    SheetInfo,
+)
+from . import sheets_client, range_detector, column_profiler
+from .question_generator import generate_questions
+from .document_generator import generate_document
+
+
+limiter = Limiter(key_func=get_remote_address)
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI):
+    setup_logging()
+    log.info("startup", model=settings.anthropic_model)
+    yield
+
+
+app = FastAPI(title="SheetDoc AI", lifespan=lifespan)
+app.state.limiter = limiter
+
+origins = [o.strip() for o in settings.allowed_origins.split(",") if o.strip()]
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=origins or ["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.middleware("http")
+async def access_log(request: Request, call_next):
+    start = time.perf_counter()
+    response = await call_next(request)
+    latency = int((time.perf_counter() - start) * 1000)
+    log.info(
+        "request",
+        method=request.method,
+        path=request.url.path,
+        status=response.status_code,
+        latency_ms=latency,
+    )
+    return response
+
+
+@app.exception_handler(DomainError)
+async def handle_domain(_: Request, exc: DomainError):
+    return to_response(exc)
+
+
+@app.exception_handler(RateLimitExceeded)
+async def handle_rate(_: Request, exc: RateLimitExceeded):
+    return JSONResponse(
+        status_code=429,
+        content={
+            "error": {
+                "code": "RATE_LIMITED",
+                "what": "Слишком много запросов.",
+                "why": str(exc.detail),
+                "next": "Подождите минуту и повторите.",
+            }
+        },
+    )
+
+
+@app.get("/api/health")
+async def health() -> dict:
+    return {"status": "ok"}
+
+
+@app.post("/api/sheets/resolve", response_model=ResolveResponse)
+async def resolve(req: ResolveRequest) -> ResolveResponse:
+    sid, _ = sheets_client.parse_url(req.url)
+    title, sheets = await sheets_client.fetch_meta(sid)
+    return ResolveResponse(
+        spreadsheetId=sid,
+        title=title,
+        sheets=[SheetInfo(gid=gid, name=name) for gid, name in sheets],
+    )
+
+
+@app.post("/api/sheets/load", response_model=LoadResponse)
+async def load(req: LoadRequest) -> LoadResponse:
+    cache_key = f"{req.spreadsheetId}:{req.gid}"
+    if cache_key in profile_cache:
+        return profile_cache[cache_key]
+
+    rows = await sheets_client.fetch_csv(req.spreadsheetId, req.gid)
+    headers, data = range_detector.detect_active_range(rows)
+    if not headers or not data:
+        raise SheetEmpty()
+
+    if len(data) > settings.max_rows or len(headers) > settings.max_cols:
+        raise SheetTooLarge(
+            why=(
+                f"Найдено {len(data)} строк × {len(headers)} колонок. "
+                f"Лимит MVP — {settings.max_rows} × {settings.max_cols}."
+            ),
+        )
+
+    columns = column_profiler.profile_columns(headers, data)
+
+    sheet_name = "Лист"
+    try:
+        _, sheets = await sheets_client.fetch_meta(req.spreadsheetId)
+        for gid, name in sheets:
+            if gid == req.gid:
+                sheet_name = name
+                break
+    except Exception:
+        pass
+
+    resp = LoadResponse(
+        rows=len(data),
+        cols=len(headers),
+        sheetName=sheet_name,
+        headers=headers,
+        columns=columns,
+        preview=[[str(c) for c in row] for row in data[:10]],
+    )
+    profile_cache[cache_key] = resp
+    return resp
+
+
+@app.post("/api/analyze/questions", response_model=QuestionsResponse)
+@limiter.limit("30/minute")
+async def questions(request: Request, req: QuestionsRequest) -> QuestionsResponse:
+    return await generate_questions(req.profile)
+
+
+@app.post("/api/generate", response_model=GenerateResponse)
+@limiter.limit("30/minute")
+async def generate(request: Request, req: GenerateRequest) -> GenerateResponse:
+    return await generate_document(req)
+
+
+static_path = Path(__file__).resolve().parent.parent / settings.static_dir
+if static_path.exists():
+    app.mount("/", StaticFiles(directory=static_path, html=True), name="static")
--- a/backend/app/models.py
+++ b/backend/app/models.py
@ -0,0 +1,80 @@
+from typing import Literal, Optional
+from pydantic import BaseModel, Field
+
+
+ColumnType = Literal["text", "number", "date", "bool", "empty"]
+QuestionKind = Literal["single", "multi", "text"]
+GenerateMode = Literal["report", "presentation_outline"]
+
+
+class ResolveRequest(BaseModel):
+    url: str
+
+
+class SheetInfo(BaseModel):
+    gid: str
+    name: str
+    isEmpty: bool = False
+
+
+class ResolveResponse(BaseModel):
+    spreadsheetId: str
+    title: str
+    sheets: list[SheetInfo]
+
+
+class LoadRequest(BaseModel):
+    spreadsheetId: str
+    gid: str
+
+
+class ColumnProfile(BaseModel):
+    name: str
+    type: ColumnType
+    fill: float
+    unique: int
+    top: list[str] = Field(default_factory=list)
+
+
+class LoadResponse(BaseModel):
+    rows: int
+    cols: int
+    sheetName: str
+    headers: list[str]
+    columns: list[ColumnProfile]
+    preview: list[list[str]]
+
+
+class Question(BaseModel):
+    id: str
+    text: str
+    why: str
+    optional: bool = False
+    kind: QuestionKind = "text"
+    options: Optional[list[str]] = None
+
+
+class QuestionsRequest(BaseModel):
+    profile: LoadResponse
+
+
+class QuestionsResponse(BaseModel):
+    questions: list[Question]
+
+
+class Answer(BaseModel):
+    id: str
+    value: str
+
+
+class GenerateRequest(BaseModel):
+    profile: LoadResponse
+    answers: list[Answer]
+    mode: GenerateMode = "report"
+    dataSample: list[list[str]] = Field(default_factory=list)
+
+
+class GenerateResponse(BaseModel):
+    document: str
+    generatedAt: str
+    mode: GenerateMode
--- a/backend/app/question_generator.py
+++ b/backend/app/question_generator.py
@ -0,0 +1,37 @@
+import json
+
+from .errors import LlmFailed
+from .llm_client import llm, load_prompt
+from .models import LoadResponse, Question, QuestionsResponse
+
+
+SYSTEM = load_prompt("questions_system.md")
+
+
+def _profile_payload(profile: LoadResponse) -> str:
+    payload = {
+        "sheetName": profile.sheetName,
+        "rows": profile.rows,
+        "cols": profile.cols,
+        "headers": profile.headers,
+        "columns": [c.model_dump() for c in profile.columns],
+        "previewRows": profile.preview[:5],
+    }
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+async def generate_questions(profile: LoadResponse) -> QuestionsResponse:
+    user = (
+        "Профиль таблицы:\n\n"
+        f"{_profile_payload(profile)}\n\n"
+        "Сформируй вопросы строго по схеме из системного промпта."
+    )
+    data = await llm.complete_json(SYSTEM, user, max_tokens=1500)
+    raw_qs = data.get("questions") if isinstance(data, dict) else None
+    if not isinstance(raw_qs, list) or not (3 <= len(raw_qs) <= 7):
+        raise LlmFailed(
+            why="Модель вернула неверное число вопросов.",
+            next="Повторите попытку.",
+        )
+    questions = [Question.model_validate(q) for q in raw_qs]
+    return QuestionsResponse(questions=questions)
--- a/backend/app/range_detector.py
+++ b/backend/app/range_detector.py
@ -0,0 +1,65 @@
+def _is_empty(cell: str) -> bool:
+    return cell is None or str(cell).strip() == ""
+
+
+def _row_empty(row: list[str]) -> bool:
+    return all(_is_empty(c) for c in row)
+
+
+def detect_active_range(rows: list[list[str]]) -> tuple[list[str], list[list[str]]]:
+    if not rows:
+        return [], []
+
+    width = max(len(r) for r in rows)
+    norm = [r + [""] * (width - len(r)) for r in rows]
+
+    start = 0
+    while start < len(norm) and _row_empty(norm[start]):
+        start += 1
+    end = len(norm)
+    while end > start and _row_empty(norm[end - 1]):
+        end -= 1
+    if start >= end:
+        return [], []
+
+    body = norm[start:end]
+
+    col_has_data = [False] * width
+    for r in body:
+        for i, c in enumerate(r):
+            if not _is_empty(c):
+                col_has_data[i] = True
+
+    keep_cols = [i for i, ok in enumerate(col_has_data) if ok]
+    if not keep_cols:
+        return [], []
+
+    trimmed = [[r[i] for i in keep_cols] for r in body]
+
+    header_idx = _find_header_row(trimmed)
+    headers = [str(c).strip() for c in trimmed[header_idx]]
+    headers = [h if h else f"Колонка {i + 1}" for i, h in enumerate(headers)]
+    data = trimmed[header_idx + 1:]
+    return headers, data
+
+
+def _find_header_row(rows: list[list[str]]) -> int:
+    for i, row in enumerate(rows[:5]):
+        non_empty = [c for c in row if not _is_empty(c)]
+        if not non_empty:
+            continue
+        non_numeric = sum(1 for c in non_empty if not _looks_numeric(c))
+        if non_numeric / len(non_empty) >= 0.7:
+            return i
+    return 0
+
+
+def _looks_numeric(s: str) -> bool:
+    s = s.strip().replace(" ", "").replace(",", ".")
+    if not s:
+        return False
+    try:
+        float(s)
+        return True
+    except ValueError:
+        return False
--- a/backend/app/sheets_client.py
+++ b/backend/app/sheets_client.py
@ -0,0 +1,96 @@
+import csv
+import io
+import re
+from typing import Optional
+import httpx
+
+from .config import settings
+from .errors import (
+    InvalidUrl,
+    NotASheet,
+    SheetForbidden,
+    SheetNotFound,
+)
+
+SHEET_ID_RE = re.compile(r"/spreadsheets/d/([a-zA-Z0-9-_]+)")
+GID_RE = re.compile(r"[?#&]gid=([0-9]+)")
+TITLE_RE = re.compile(r"<title>(.*?)</title>", re.IGNORECASE | re.DOTALL)
+SHEET_NAME_RE = re.compile(
+    r'\{"name":"([^"]+)"[^\}]*"gid":"?(\d+)"?', re.DOTALL
+)
+
+
+def parse_url(url: str) -> tuple[str, Optional[str]]:
+    if not url or not url.strip():
+        raise InvalidUrl()
+    m = SHEET_ID_RE.search(url)
+    if not m:
+        raise NotASheet()
+    sid = m.group(1)
+    g = GID_RE.search(url)
+    gid = g.group(1) if g else None
+    return sid, gid
+
+
+async def fetch_meta(spreadsheet_id: str) -> tuple[str, list[tuple[str, str]]]:
+    url = f"https://docs.google.com/spreadsheets/d/{spreadsheet_id}/htmlview"
+    async with httpx.AsyncClient(timeout=15.0, follow_redirects=True) as client:
+        r = await client.get(url)
+    if r.status_code in (401, 403):
+        raise SheetForbidden()
+    if r.status_code == 404:
+        raise SheetNotFound()
+    if r.status_code >= 400:
+        raise SheetNotFound(why=f"Google ответил {r.status_code}.")
+
+    html = r.text
+    title_match = TITLE_RE.search(html)
+    title = "Без названия"
+    if title_match:
+        title = title_match.group(1).split(" - Google ")[0].strip() or title
+
+    sheets: list[tuple[str, str]] = []
+    seen: set[str] = set()
+    for m in SHEET_NAME_RE.finditer(html):
+        name, gid = m.group(1), m.group(2)
+        if gid in seen:
+            continue
+        seen.add(gid)
+        sheets.append((gid, name))
+
+    if not sheets:
+        gid_m = re.search(r'"gid":"?(\d+)"?', html)
+        sheets = [(gid_m.group(1) if gid_m else "0", "Лист1")]
+
+    return title, sheets
+
+
+async def fetch_csv(spreadsheet_id: str, gid: str) -> list[list[str]]:
+    url = (
+        f"https://docs.google.com/spreadsheets/d/{spreadsheet_id}/export"
+        f"?format=csv&gid={gid}"
+    )
+    async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
+        async with client.stream("GET", url) as r:
+            if r.status_code in (401, 403):
+                raise SheetForbidden()
+            if r.status_code == 404:
+                raise SheetNotFound()
+            if r.status_code >= 400:
+                raise SheetNotFound(why=f"Google ответил {r.status_code}.")
+            chunks: list[bytes] = []
+            total = 0
+            async for chunk in r.aiter_bytes():
+                total += len(chunk)
+                if total > settings.max_csv_bytes:
+                    raise SheetForbidden(
+                        what="Файл слишком большой.",
+                        why=f"Лимит {settings.max_csv_bytes // 1024 // 1024} MB.",
+                        next="Сузьте диапазон таблицы.",
+                    )
+                chunks.append(chunk)
+            data = b"".join(chunks)
+
+    text = data.decode("utf-8", errors="replace")
+    reader = csv.reader(io.StringIO(text))
+    return [row for row in reader]
--- a/backend/prompts/questions_system.md
+++ b/backend/prompts/questions_system.md
@ -0,0 +1,41 @@
+Ты помощник, который готовит уточняющие вопросы пользователю перед генерацией документа из данных Google Таблицы.
+
+Тебе на вход дают профиль таблицы: название листа, число строк/колонок, заголовки и типы колонок, топ-значения, заполненность.
+
+Твоя задача — сформировать от 3 до 7 коротких уточняющих вопросов, которые помогут понять:
+- для кого готовится документ;
+- какой тип документа нужен (справка, отчёт, структура презентации);
+- какой стиль изложения нужен;
+- какие колонки ключевые;
+- нужны ли выводы и рекомендации;
+- какой период / фильтр учитывать.
+
+Правила:
+- 3 ≤ количество вопросов ≤ 7;
+- ровно один вопрос про тип документа (kind=single, options обязательны);
+- ровно один вопрос про стиль (kind=single, options обязательны);
+- не задавай уточнения, которые уже однозначно следуют из данных;
+- помечай optional=true, если ответ не критичен;
+- все тексты — на русском языке.
+
+Отвечай строго JSON, без markdown-обёрток. Схема:
+
+{
+  "questions": [
+    {
+      "id": "q1",
+      "text": "Кратко: для кого готовится документ?",
+      "why": "Чтобы подобрать тон и уровень детализации.",
+      "optional": false,
+      "kind": "text"
+    },
+    {
+      "id": "q2",
+      "text": "Какой тип документа нужен?",
+      "why": "Определяет структуру результата.",
+      "optional": false,
+      "kind": "single",
+      "options": ["Справка", "Аналитический отчёт", "Структура презентации"]
+    }
+  ]
+}
--- a/backend/prompts/report_system.md
+++ b/backend/prompts/report_system.md
@ -0,0 +1,27 @@
+Ты помощник, который пишет деловые документы по данным из Google Таблицы.
+
+Тебе передают:
+- профиль таблицы (заголовки, типы колонок, заполненность, топ-значения, число строк);
+- ответы пользователя на уточняющие вопросы;
+- образец первых строк данных (до 50);
+- режим: "report" (текстовая справка / аналитический отчёт) или "presentation_outline" (структура презентации).
+
+Требования к режиму "report":
+- структура: заголовок, краткое описание источника, основные показатели, ключевые наблюдения, выводы, рекомендации (если запрошены), дата генерации;
+- стиль соответствует ответу пользователя (официальный / краткий / аналитический / управленческий);
+- не выдумывай числа: используй только агрегированные данные из переданного образца;
+- если данных недостаточно для вывода — честно скажи об этом.
+
+Требования к режиму "presentation_outline":
+- название презентации;
+- цель презентации;
+- 5–9 слайдов: заголовок слайда, 3–5 ключевых тезисов, предложение по визуализации (график/таблица).
+
+Общие правила:
+- язык документа — русский;
+- формат — Markdown (заголовки `##`, списки `-`);
+- никаких преамбул вида «вот ваш документ»;
+- никаких пояснений после документа;
+- дату генерации укажи сегодняшней датой, переданной в контексте.
+
+Отвечай ТОЛЬКО Markdown-текстом документа, без обёрток в JSON или код-блоки.
--- a/backend/pyproject.toml
+++ b/backend/pyproject.toml
@ -0,0 +1,3 @@
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
--- a/backend/requirements.txt
+++ b/backend/requirements.txt
@ -0,0 +1,10 @@
+fastapi==0.115.0
+uvicorn[standard]==0.30.6
+httpx==0.27.2
+pydantic==2.9.2
+pydantic-settings==2.5.2
+anthropic==0.39.0
+python-dateutil==2.9.0
+structlog==24.4.0
+cachetools==5.5.0
+slowapi==0.1.9
--- a/backend/tests/init.py
+++ b/backend/tests/init.py
--- a/backend/tests/test_column_profiler.py
+++ b/backend/tests/test_column_profiler.py
@ -0,0 +1,23 @@
+from app.column_profiler import profile_columns
+
+
+def test_basic_types():
+    headers = ["Имя", "Сумма", "Дата", "Активен"]
+    data = [
+        ["Иван", "100", "2024-01-05", "true"],
+        ["Пётр", "200", "2024-02-15", "false"],
+        ["Анна", "350", "2024-03-20", "true"],
+    ]
+    profiles = profile_columns(headers, data)
+    by_name = {p.name: p for p in profiles}
+    assert by_name["Имя"].type == "text"
+    assert by_name["Сумма"].type == "number"
+    assert by_name["Дата"].type == "date"
+    assert by_name["Активен"].type == "bool"
+    assert by_name["Имя"].fill == 1.0
+
+
+def test_fill_ratio():
+    profiles = profile_columns(["X"], [["a"], [""], ["b"], [""]])
+    assert profiles[0].fill == 0.5
+    assert profiles[0].unique == 2
--- a/backend/tests/test_range_detector.py
+++ b/backend/tests/test_range_detector.py
@ -0,0 +1,27 @@
+from app.range_detector import detect_active_range
+
+
+def test_trims_empty_rows_and_cols():
+    rows = [
+        ["", "", "", ""],
+        ["", "Имя", "Сумма", ""],
+        ["", "Иван", "100", ""],
+        ["", "Пётр", "200", ""],
+        ["", "", "", ""],
+    ]
+    headers, data = detect_active_range(rows)
+    assert headers == ["Имя", "Сумма"]
+    assert data == [["Иван", "100"], ["Пётр", "200"]]
+
+
+def test_empty_returns_empty():
+    headers, data = detect_active_range([["", ""], ["", ""]])
+    assert headers == []
+    assert data == []
+
+
+def test_fills_blank_header_name():
+    rows = [["Имя", "", "Сумма"], ["Иван", "x", "100"]]
+    headers, data = detect_active_range(rows)
+    assert headers[1] == "Колонка 2"
+    assert len(data) == 1
--- a/backend/tests/test_sheets_url.py
+++ b/backend/tests/test_sheets_url.py
@ -0,0 +1,29 @@
+import pytest
+from app.sheets_client import parse_url
+from app.errors import InvalidUrl, NotASheet
+
+
+def test_parses_valid_url():
+    sid, gid = parse_url(
+        "https://docs.google.com/spreadsheets/d/1AbCDefGh-12345/edit#gid=42"
+    )
+    assert sid == "1AbCDefGh-12345"
+    assert gid == "42"
+
+
+def test_no_gid():
+    sid, gid = parse_url(
+        "https://docs.google.com/spreadsheets/d/1AbCDefGh-12345/edit"
+    )
+    assert sid == "1AbCDefGh-12345"
+    assert gid is None
+
+
+def test_invalid_empty():
+    with pytest.raises(InvalidUrl):
+        parse_url("")
+
+
+def test_not_a_sheet():
+    with pytest.raises(NotASheet):
+        parse_url("https://example.com/foo")
--- a/docker-compose.yml
+++ b/docker-compose.yml
@ -0,0 +1,22 @@
+services:
+  sheetdoc:
+    build: .
+    image: sheetdoc:latest
+    restart: unless-stopped
+    environment:
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
+      ANTHROPIC_MODEL: ${ANTHROPIC_MODEL:-claude-sonnet-4-6}
+      ALLOWED_ORIGINS: ${ALLOWED_ORIGINS:-https://sheetdoc.telecom.quest}
+    networks:
+      - traefik
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=traefik"
+      - "traefik.http.routers.sheetdoc.rule=Host(`sheetdoc.telecom.quest`)"
+      - "traefik.http.routers.sheetdoc.entrypoints=websecure"
+      - "traefik.http.routers.sheetdoc.tls=true"
+      - "traefik.http.services.sheetdoc.loadbalancer.server.port=8000"
+
+networks:
+  traefik:
+    external: true
--- a/frontend/index.html
+++ b/frontend/index.html
@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="ru">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>SheetDoc AI</title>
+  </head>
+  <body class="bg-slate-50">
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
--- a/frontend/package-lock.json
+++ b/frontend/package-lock.json
--- a/frontend/package.json
+++ b/frontend/package.json
@ -0,0 +1,27 @@
+{
+  "name": "sheetdoc-frontend",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "marked": "^14.1.3",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "zustand": "^4.5.5"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.11",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.2",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.47",
+    "tailwindcss": "^3.4.13",
+    "typescript": "^5.6.2",
+    "vite": "^5.4.8"
+  }
+}
--- a/frontend/postcss.config.js
+++ b/frontend/postcss.config.js
@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@ -0,0 +1,58 @@
+import { useStore, Step } from "./lib/store";
+import { StepUrl } from "./components/StepUrl";
+import { StepSheet } from "./components/StepSheet";
+import { StepPreview } from "./components/StepPreview";
+import { StepQuestions } from "./components/StepQuestions";
+import { StepResult } from "./components/StepResult";
+
+const STEPS: { key: Step; label: string }[] = [
+  { key: "url", label: "Ссылка" },
+  { key: "sheet", label: "Лист" },
+  { key: "preview", label: "Анализ" },
+  { key: "questions", label: "Вопросы" },
+  { key: "result", label: "Результат" },
+];
+
+export default function App() {
+  const { step } = useStore();
+  const activeIdx = STEPS.findIndex((s) => s.key === step);
+
+  return (
+    <div className="min-h-screen">
+      <header className="bg-white border-b">
+        <div className="max-w-3xl mx-auto px-4 py-4 flex items-center justify-between">
+          <h1 className="text-lg font-semibold">SheetDoc AI</h1>
+          <span className="text-xs text-slate-500">
+            MVP · данные не сохраняются
+          </span>
+        </div>
+      </header>
+
+      <main className="max-w-3xl mx-auto px-4 py-6">
+        <nav className="flex items-center gap-2 mb-6 text-sm">
+          {STEPS.map((s, i) => (
+            <div
+              key={s.key}
+              className={
+                "px-2 py-1 rounded " +
+                (i === activeIdx
+                  ? "bg-indigo-600 text-white"
+                  : i < activeIdx
+                  ? "bg-indigo-100 text-indigo-700"
+                  : "bg-slate-100 text-slate-500")
+              }
+            >
+              {i + 1}. {s.label}
+            </div>
+          ))}
+        </nav>
+
+        {step === "url" && <StepUrl />}
+        {step === "sheet" && <StepSheet />}
+        {step === "preview" && <StepPreview />}
+        {step === "questions" && <StepQuestions />}
+        {step === "result" && <StepResult />}
+      </main>
+    </div>
+  );
+}
--- a/frontend/src/components/ErrorBox.tsx
+++ b/frontend/src/components/ErrorBox.tsx
@ -0,0 +1,20 @@
+import { ApiError } from "../lib/types";
+
+export function ErrorBox({ err, onRetry }: { err: ApiError | null; onRetry?: () => void }) {
+  if (!err) return null;
+  return (
+    <div className="border border-red-200 bg-red-50 text-red-900 rounded-md p-4 my-4">
+      <div className="font-semibold mb-1">{err.what}</div>
+      {err.why && <div className="text-sm opacity-80">{err.why}</div>}
+      {err.next && <div className="text-sm mt-2">→ {err.next}</div>}
+      {onRetry && (
+        <button
+          className="mt-3 px-3 py-1.5 bg-red-600 text-white rounded hover:bg-red-700 text-sm"
+          onClick={onRetry}
+        >
+          Повторить
+        </button>
+      )}
+    </div>
+  );
+}
--- a/frontend/src/components/StepPreview.tsx
+++ b/frontend/src/components/StepPreview.tsx
@ -0,0 +1,106 @@
+import { useEffect, useState } from "react";
+import { api, SheetDocError } from "../lib/api";
+import { useStore } from "../lib/store";
+import { ApiError } from "../lib/types";
+import { ErrorBox } from "./ErrorBox";
+
+export function StepPreview() {
+  const {
+    resolve,
+    selectedGid,
+    profile,
+    setProfile,
+    setQuestions,
+    setStep,
+  } = useStore();
+  const [loading, setLoading] = useState(false);
+  const [genLoading, setGenLoading] = useState(false);
+  const [err, setErr] = useState<ApiError | null>(null);
+
+  async function load() {
+    if (!resolve || !selectedGid) return;
+    setErr(null);
+    setLoading(true);
+    try {
+      const p = await api.load(resolve.spreadsheetId, selectedGid);
+      setProfile(p);
+    } catch (e) {
+      if (e instanceof SheetDocError) setErr(e.payload);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  useEffect(() => {
+    if (!profile) load();
+  }, [selectedGid]);
+
+  async function next() {
+    if (!profile) return;
+    setErr(null);
+    setGenLoading(true);
+    try {
+      const r = await api.questions(profile);
+      setQuestions(r.questions);
+      setStep("questions");
+    } catch (e) {
+      if (e instanceof SheetDocError) setErr(e.payload);
+    } finally {
+      setGenLoading(false);
+    }
+  }
+
+  return (
+    <div className="space-y-4">
+      <h2 className="text-xl font-semibold">Шаг 3. Анализ данных</h2>
+      {loading && <div className="text-slate-600">Загружаем лист…</div>}
+      {profile && (
+        <div className="bg-white border rounded-md p-4 space-y-3">
+          <div className="text-sm text-slate-600">
+            Лист: <b>{profile.sheetName}</b> · {profile.rows} строк · {profile.cols} колонок
+          </div>
+          <div className="overflow-x-auto">
+            <table className="text-sm w-full">
+              <thead className="bg-slate-100">
+                <tr>
+                  <th className="text-left p-2">Колонка</th>
+                  <th className="text-left p-2">Тип</th>
+                  <th className="text-left p-2">Заполнено</th>
+                  <th className="text-left p-2">Уникальных</th>
+                  <th className="text-left p-2">Топ значений</th>
+                </tr>
+              </thead>
+              <tbody>
+                {profile.columns.map((c) => (
+                  <tr key={c.name} className="border-t">
+                    <td className="p-2 font-medium">{c.name}</td>
+                    <td className="p-2">{c.type}</td>
+                    <td className="p-2">{Math.round(c.fill * 100)}%</td>
+                    <td className="p-2">{c.unique}</td>
+                    <td className="p-2 text-slate-600">{c.top.join(", ")}</td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+        </div>
+      )}
+      <ErrorBox err={err} onRetry={load} />
+      <div className="flex gap-2">
+        <button
+          onClick={() => setStep(resolve && resolve.sheets.length > 1 ? "sheet" : "url")}
+          className="px-4 py-2 border rounded-md hover:bg-slate-50"
+        >
+          Назад
+        </button>
+        <button
+          disabled={!profile || genLoading}
+          onClick={next}
+          className="px-4 py-2 bg-indigo-600 text-white rounded-md disabled:opacity-50 hover:bg-indigo-700"
+        >
+          {genLoading ? "Готовим вопросы…" : "К уточняющим вопросам"}
+        </button>
+      </div>
+    </div>
+  );
+}
--- a/frontend/src/components/StepQuestions.tsx
+++ b/frontend/src/components/StepQuestions.tsx
@ -0,0 +1,131 @@
+import { useState } from "react";
+import { api, SheetDocError } from "../lib/api";
+import { useStore } from "../lib/store";
+import { ApiError, GenerateMode } from "../lib/types";
+import { ErrorBox } from "./ErrorBox";
+
+export function StepQuestions() {
+  const {
+    questions,
+    answers,
+    setAnswer,
+    profile,
+    answersArray,
+    setResult,
+    setStep,
+    mode,
+    setMode,
+  } = useStore();
+  const [loading, setLoading] = useState(false);
+  const [err, setErr] = useState<ApiError | null>(null);
+
+  async function submit() {
+    if (!profile) return;
+    const required = questions.filter((q) => !q.optional);
+    const missing = required.filter((q) => !answers[q.id]?.trim());
+    if (missing.length) {
+      setErr({
+        code: "VALIDATION_ERROR",
+        what: "Не все обязательные вопросы заполнены.",
+        why: `Осталось: ${missing.length}.`,
+        next: "Заполните выделенные поля.",
+      });
+      return;
+    }
+    setErr(null);
+    setLoading(true);
+    try {
+      const r = await api.generate(profile, answersArray(), mode, profile.preview);
+      setResult(r);
+      setStep("result");
+    } catch (e) {
+      if (e instanceof SheetDocError) setErr(e.payload);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <div className="space-y-4">
+      <h2 className="text-xl font-semibold">Шаг 4. Уточняющие вопросы</h2>
+
+      <div className="bg-white border rounded-md p-4">
+        <label className="block text-sm font-medium mb-2">Тип итогового документа</label>
+        <select
+          className="border rounded-md px-3 py-2 w-full"
+          value={mode}
+          onChange={(e) => setMode(e.target.value as GenerateMode)}
+        >
+          <option value="report">Текстовая справка / отчёт</option>
+          <option value="presentation_outline">Структура презентации</option>
+        </select>
+      </div>
+
+      {questions.map((q) => (
+        <div key={q.id} className="bg-white border rounded-md p-4 space-y-2">
+          <label className="block font-medium">
+            {q.text}
+            {q.optional && <span className="text-xs text-slate-500 ml-2">(необязательно)</span>}
+          </label>
+          <p className="text-xs text-slate-500">{q.why}</p>
+          {q.kind === "single" && q.options ? (
+            <select
+              className="w-full border rounded-md px-3 py-2"
+              value={answers[q.id] ?? ""}
+              onChange={(e) => setAnswer(q.id, e.target.value)}
+            >
+              <option value="">— выберите —</option>
+              {q.options.map((o) => (
+                <option key={o} value={o}>{o}</option>
+              ))}
+            </select>
+          ) : q.kind === "multi" && q.options ? (
+            <div className="flex flex-wrap gap-2">
+              {q.options.map((o) => {
+                const current = (answers[q.id] ?? "").split(",").filter(Boolean);
+                const checked = current.includes(o);
+                return (
+                  <label key={o} className="flex items-center gap-1 text-sm border rounded px-2 py-1">
+                    <input
+                      type="checkbox"
+                      checked={checked}
+                      onChange={() => {
+                        const next = checked ? current.filter((x) => x !== o) : [...current, o];
+                        setAnswer(q.id, next.join(","));
+                      }}
+                    />
+                    {o}
+                  </label>
+                );
+              })}
+            </div>
+          ) : (
+            <textarea
+              className="w-full border rounded-md px-3 py-2 min-h-[60px]"
+              value={answers[q.id] ?? ""}
+              onChange={(e) => setAnswer(q.id, e.target.value)}
+            />
+          )}
+        </div>
+      ))}
+
+      <ErrorBox err={err} />
+
+      <div className="flex gap-2">
+        <button
+          onClick={() => setStep("preview")}
+          className="px-4 py-2 border rounded-md hover:bg-slate-50"
+        >
+          Назад
+        </button>
+        <button
+          disabled={loading}
+          onClick={submit}
+          className="px-4 py-2 bg-indigo-600 text-white rounded-md disabled:opacity-50 hover:bg-indigo-700"
+        >
+          {loading ? "Генерируем…" : "Сгенерировать"}
+        </button>
+      </div>
+    </div>
+  );
+}
--- a/frontend/src/components/StepResult.tsx
+++ b/frontend/src/components/StepResult.tsx
@ -0,0 +1,92 @@
+import { useMemo, useState } from "react";
+import { marked } from "marked";
+import { useStore } from "../lib/store";
+import { api, SheetDocError } from "../lib/api";
+import { ApiError } from "../lib/types";
+import { ErrorBox } from "./ErrorBox";
+
+export function StepResult() {
+  const { result, setResult, setStep, profile, answersArray, mode, reset } = useStore();
+  const [regen, setRegen] = useState(false);
+  const [err, setErr] = useState<ApiError | null>(null);
+  const [copied, setCopied] = useState<"md" | "plain" | null>(null);
+
+  const html = useMemo(
+    () => (result ? marked.parse(result.document, { breaks: true }) : ""),
+    [result]
+  );
+
+  if (!result) return null;
+
+  async function copy(kind: "md" | "plain") {
+    if (!result) return;
+    const text =
+      kind === "md"
+        ? result.document
+        : result.document.replace(/[#*_`>-]/g, "").replace(/\n{3,}/g, "\n\n");
+    await navigator.clipboard.writeText(text);
+    setCopied(kind);
+    setTimeout(() => setCopied(null), 1500);
+  }
+
+  async function regenerate() {
+    if (!profile) return;
+    setErr(null);
+    setRegen(true);
+    try {
+      const r = await api.generate(profile, answersArray(), mode, profile.preview);
+      setResult(r);
+    } catch (e) {
+      if (e instanceof SheetDocError) setErr(e.payload);
+    } finally {
+      setRegen(false);
+    }
+  }
+
+  return (
+    <div className="space-y-4">
+      <h2 className="text-xl font-semibold">Шаг 5. Результат</h2>
+      <div className="text-xs text-slate-500">
+        Сгенерировано: {new Date(result.generatedAt).toLocaleString("ru-RU")} · режим: {result.mode}
+      </div>
+      <div className="flex flex-wrap gap-2">
+        <button
+          onClick={() => copy("md")}
+          className="px-3 py-1.5 bg-slate-800 text-white rounded hover:bg-slate-900 text-sm"
+        >
+          {copied === "md" ? "Скопировано ✓" : "Копировать Markdown"}
+        </button>
+        <button
+          onClick={() => copy("plain")}
+          className="px-3 py-1.5 border rounded hover:bg-slate-50 text-sm"
+        >
+          {copied === "plain" ? "Скопировано ✓" : "Копировать как текст"}
+        </button>
+        <button
+          disabled={regen}
+          onClick={regenerate}
+          className="px-3 py-1.5 border rounded hover:bg-slate-50 text-sm disabled:opacity-50"
+        >
+          {regen ? "Генерируем…" : "Сгенерировать заново"}
+        </button>
+        <button
+          onClick={() => setStep("questions")}
+          className="px-3 py-1.5 border rounded hover:bg-slate-50 text-sm"
+        >
+          Изменить ответы
+        </button>
+        <button
+          onClick={reset}
+          className="px-3 py-1.5 border rounded hover:bg-slate-50 text-sm"
+        >
+          Новая таблица
+        </button>
+      </div>
+      <ErrorBox err={err} />
+      <article
+        className="prose-doc bg-white border rounded-md p-6"
+        dangerouslySetInnerHTML={{ __html: html as string }}
+      />
+    </div>
+  );
+}
--- a/frontend/src/components/StepSheet.tsx
+++ b/frontend/src/components/StepSheet.tsx
@ -0,0 +1,46 @@
+import { useStore } from "../lib/store";
+
+export function StepSheet() {
+  const { resolve, selectedGid, setSelectedGid, setStep } = useStore();
+  if (!resolve) return null;
+
+  return (
+    <div className="space-y-4">
+      <h2 className="text-xl font-semibold">Шаг 2. Выберите лист</h2>
+      <p className="text-sm text-slate-600">Таблица: {resolve.title}</p>
+      <ul className="divide-y border rounded-md bg-white">
+        {resolve.sheets.map((s) => (
+          <li key={s.gid}>
+            <label className="flex items-center gap-3 px-3 py-2 cursor-pointer hover:bg-slate-50">
+              <input
+                type="radio"
+                name="sheet"
+                checked={selectedGid === s.gid}
+                onChange={() => setSelectedGid(s.gid)}
+              />
+              <span>{s.name}</span>
+              {s.isEmpty && (
+                <span className="text-xs text-slate-500">(пустой)</span>
+              )}
+            </label>
+          </li>
+        ))}
+      </ul>
+      <div className="flex gap-2">
+        <button
+          onClick={() => setStep("url")}
+          className="px-4 py-2 border rounded-md hover:bg-slate-50"
+        >
+          Назад
+        </button>
+        <button
+          disabled={!selectedGid}
+          onClick={() => setStep("preview")}
+          className="px-4 py-2 bg-indigo-600 text-white rounded-md disabled:opacity-50 hover:bg-indigo-700"
+        >
+          Далее
+        </button>
+      </div>
+    </div>
+  );
+}
--- a/frontend/src/components/StepUrl.tsx
+++ b/frontend/src/components/StepUrl.tsx
@ -0,0 +1,57 @@
+import { useState } from "react";
+import { api, SheetDocError } from "../lib/api";
+import { useStore } from "../lib/store";
+import { ApiError } from "../lib/types";
+import { ErrorBox } from "./ErrorBox";
+
+export function StepUrl() {
+  const { url, setUrl, setResolve, setStep } = useStore();
+  const [loading, setLoading] = useState(false);
+  const [err, setErr] = useState<ApiError | null>(null);
+
+  async function submit(e: React.FormEvent) {
+    e.preventDefault();
+    setErr(null);
+    setLoading(true);
+    try {
+      const r = await api.resolve(url);
+      setResolve(r);
+      if (r.sheets.length === 1) {
+        useStore.getState().setSelectedGid(r.sheets[0].gid);
+        setStep("preview");
+      } else {
+        setStep("sheet");
+      }
+    } catch (e) {
+      if (e instanceof SheetDocError) setErr(e.payload);
+      else setErr({ code: "UNKNOWN", what: "Неизвестная ошибка.", why: String(e), next: "Повторите." });
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <form onSubmit={submit} className="space-y-4">
+      <h2 className="text-xl font-semibold">Шаг 1. Ссылка на Google Таблицу</h2>
+      <p className="text-sm text-slate-600">
+        Откройте доступ «Все, у кого есть ссылка → Читатель» и вставьте URL.
+      </p>
+      <input
+        type="url"
+        required
+        value={url}
+        onChange={(e) => setUrl(e.target.value)}
+        placeholder="https://docs.google.com/spreadsheets/d/..."
+        className="w-full border border-slate-300 rounded-md px-3 py-2 focus:outline-none focus:ring-2 focus:ring-indigo-500"
+      />
+      <button
+        type="submit"
+        disabled={loading || !url}
+        className="px-4 py-2 bg-indigo-600 text-white rounded-md disabled:opacity-50 hover:bg-indigo-700"
+      >
+        {loading ? "Проверяем…" : "Далее"}
+      </button>
+      <ErrorBox err={err} />
+    </form>
+  );
+}
--- a/frontend/src/index.css
+++ b/frontend/src/index.css
@ -0,0 +1,12 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+.prose-doc h1 { @apply text-2xl font-bold mt-6 mb-3; }
+.prose-doc h2 { @apply text-xl font-semibold mt-5 mb-2; }
+.prose-doc h3 { @apply text-lg font-semibold mt-4 mb-2; }
+.prose-doc p  { @apply my-2 leading-relaxed; }
+.prose-doc ul { @apply list-disc pl-6 my-2; }
+.prose-doc ol { @apply list-decimal pl-6 my-2; }
+.prose-doc strong { @apply font-semibold; }
+.prose-doc code { @apply bg-slate-100 px-1 py-0.5 rounded; }
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@ -0,0 +1,64 @@
+import {
+  ApiError,
+  GenerateMode,
+  GenerateResponse,
+  LoadResponse,
+  QuestionsResponse,
+  ResolveResponse,
+  Answer,
+} from "./types";
+
+const BASE = import.meta.env.VITE_API_BASE ?? "";
+
+export class SheetDocError extends Error {
+  payload: ApiError;
+  constructor(payload: ApiError) {
+    super(payload.what || payload.code);
+    this.payload = payload;
+  }
+}
+
+async function post<T>(path: string, body: unknown): Promise<T> {
+  const r = await fetch(`${BASE}${path}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!r.ok) {
+    let payload: ApiError = {
+      code: "NETWORK",
+      what: "Сетевая ошибка.",
+      why: `HTTP ${r.status}.`,
+      next: "Проверьте подключение и повторите.",
+    };
+    try {
+      const data = await r.json();
+      if (data?.error) payload = data.error;
+    } catch {
+      /* keep default */
+    }
+    throw new SheetDocError(payload);
+  }
+  return (await r.json()) as T;
+}
+
+export const api = {
+  resolve: (url: string) =>
+    post<ResolveResponse>("/api/sheets/resolve", { url }),
+  load: (spreadsheetId: string, gid: string) =>
+    post<LoadResponse>("/api/sheets/load", { spreadsheetId, gid }),
+  questions: (profile: LoadResponse) =>
+    post<QuestionsResponse>("/api/analyze/questions", { profile }),
+  generate: (
+    profile: LoadResponse,
+    answers: Answer[],
+    mode: GenerateMode,
+    dataSample: string[][]
+  ) =>
+    post<GenerateResponse>("/api/generate", {
+      profile,
+      answers,
+      mode,
+      dataSample,
+    }),
+};
--- a/frontend/src/lib/store.ts
+++ b/frontend/src/lib/store.ts
@ -0,0 +1,66 @@
+import { create } from "zustand";
+import {
+  Answer,
+  GenerateMode,
+  GenerateResponse,
+  LoadResponse,
+  Question,
+  ResolveResponse,
+} from "./types";
+
+export type Step = "url" | "sheet" | "preview" | "questions" | "result";
+
+interface State {
+  step: Step;
+  url: string;
+  resolve?: ResolveResponse;
+  selectedGid?: string;
+  profile?: LoadResponse;
+  questions: Question[];
+  answers: Record<string, string>;
+  mode: GenerateMode;
+  result?: GenerateResponse;
+  setStep: (s: Step) => void;
+  setUrl: (u: string) => void;
+  setResolve: (r: ResolveResponse) => void;
+  setSelectedGid: (g: string) => void;
+  setProfile: (p: LoadResponse) => void;
+  setQuestions: (q: Question[]) => void;
+  setAnswer: (id: string, v: string) => void;
+  setMode: (m: GenerateMode) => void;
+  setResult: (r: GenerateResponse) => void;
+  reset: () => void;
+  answersArray: () => Answer[];
+}
+
+export const useStore = create<State>((set, get) => ({
+  step: "url",
+  url: "",
+  questions: [],
+  answers: {},
+  mode: "report",
+  setStep: (step) => set({ step }),
+  setUrl: (url) => set({ url }),
+  setResolve: (resolve) => set({ resolve }),
+  setSelectedGid: (selectedGid) => set({ selectedGid }),
+  setProfile: (profile) => set({ profile }),
+  setQuestions: (questions) => set({ questions }),
+  setAnswer: (id, v) =>
+    set((s) => ({ answers: { ...s.answers, [id]: v } })),
+  setMode: (mode) => set({ mode }),
+  setResult: (result) => set({ result }),
+  reset: () =>
+    set({
+      step: "url",
+      url: "",
+      resolve: undefined,
+      selectedGid: undefined,
+      profile: undefined,
+      questions: [],
+      answers: {},
+      mode: "report",
+      result: undefined,
+    }),
+  answersArray: () =>
+    Object.entries(get().answers).map(([id, value]) => ({ id, value })),
+}));
--- a/frontend/src/lib/types.ts
+++ b/frontend/src/lib/types.ts
@ -0,0 +1,65 @@
+export type ColumnType = "text" | "number" | "date" | "bool" | "empty";
+
+export interface SheetInfo {
+  gid: string;
+  name: string;
+  isEmpty?: boolean;
+}
+
+export interface ResolveResponse {
+  spreadsheetId: string;
+  title: string;
+  sheets: SheetInfo[];
+}
+
+export interface ColumnProfile {
+  name: string;
+  type: ColumnType;
+  fill: number;
+  unique: number;
+  top: string[];
+}
+
+export interface LoadResponse {
+  rows: number;
+  cols: number;
+  sheetName: string;
+  headers: string[];
+  columns: ColumnProfile[];
+  preview: string[][];
+}
+
+export type QuestionKind = "single" | "multi" | "text";
+
+export interface Question {
+  id: string;
+  text: string;
+  why: string;
+  optional?: boolean;
+  kind: QuestionKind;
+  options?: string[];
+}
+
+export interface QuestionsResponse {
+  questions: Question[];
+}
+
+export interface Answer {
+  id: string;
+  value: string;
+}
+
+export type GenerateMode = "report" | "presentation_outline";
+
+export interface GenerateResponse {
+  document: string;
+  generatedAt: string;
+  mode: GenerateMode;
+}
+
+export interface ApiError {
+  code: string;
+  what: string;
+  why: string;
+  next: string;
+}
--- a/frontend/src/main.tsx
+++ b/frontend/src/main.tsx
@ -0,0 +1,10 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import App from "./App";
+import "./index.css";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
--- a/frontend/src/vite-env.d.ts
+++ b/frontend/src/vite-env.d.ts
@ -0,0 +1,9 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_API_BASE?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
--- a/frontend/tailwind.config.js
+++ b/frontend/tailwind.config.js
@ -0,0 +1,6 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: ["./index.html", "./src/**/*.{ts,tsx}"],
+  theme: { extend: {} },
+  plugins: [],
+};
--- a/frontend/tsconfig.json
+++ b/frontend/tsconfig.json
@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@ -0,0 +1,15 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173,
+    proxy: {
+      "/api": "http://localhost:8000",
+    },
+  },
+  build: {
+    outDir: "dist",
+  },
+});