Перейти к содержанию

Руководство программиста

Это руководство описывает полный цикл доработки платформы: от подготовки окружения до отправки изменений на проверку.

1. Подготовка окружения

  1. Установите необходимые инструменты:
  2. Git для работы с репозиторием.
  3. Node.js версии не ниже 18.13.0 и npm.
  4. Python 3.11 с pip.
  5. Склонируйте репозиторий: bash git clone https://github.com/<ваш_форк>/platform.git cd platform
  6. Установите зависимости фронтенда: bash npm install Если установка зависимостей вызывает ошибки выполнения скриптов, используйте npm install --ignore-scripts.
  7. Настройте виртуальное окружение для бэкенда и установите зависимости: bash python -m venv venv source venv/bin/activate pip install -r backend/requirements.txt

2. Создание ветки

  1. Перед началом работ создайте отдельную ветку: bash git checkout -b feature/my-change
  2. Работайте только в созданной ветке, не коммитите напрямую в main.

3. Внесение изменений

  1. Фронтенд хранится в каталоге src/ и написан на Svelte и TypeScript.
  2. Бэкенд находится в backend/ и реализован на FastAPI.
  3. Добавляйте комментарии и описания функций прямо в коде, следуя существующим примерам.
  4. При добавлении новых зависимостей обновляйте соответствующие файлы (package.json, backend/requirements.txt).

4. Линтинг и форматирование

Перед коммитом обязательно запустите автоматические проверки:

npm run format           # форматирование фронтенда и документации
npm run format:backend   # форматирование Python-кода
npm run lint             # общая проверка проекта
npm run check            # проверка типов и Svelte-компонентов

5. Тестирование

  1. Запустите тесты фронтенда: bash npm run test:frontend
  2. При наличии тестов бэкенда выполните: bash pytest
  3. Убедитесь, что все проверки завершаются без ошибок.

6. Обновление документации

  1. При изменении поведения системы обновляйте Markdown-файлы в docs/.
  2. Для локального просмотра документации используйте: bash mkdocs serve

7. Коммиты и Pull Request

  1. Сформируйте коммит с понятным сообщением: bash git commit -am "feat: описание изменения"
  2. Отправьте ветку в свой форк: bash git push origin feature/my-change
  3. Создайте Pull Request в основной репозиторий. В описании укажите цель изменения, связанные задачи и тесты.
  4. После одобрения PR не забудьте удалить рабочую ветку.

8. Collabora Online

Платформа использует контейнер Collabora Online для просмотра и редактирования офисных документов. Сервис запускается в отдельном Docker-контейнере (collabora), обычно доступном по порту 9980.

Базовый URL Collabora передаётся во фронтенд через переменную окружения VITE_COLLABORA_ONLINE_URL. Компонент CollaboraViewer открывает интерфейс Collabora во встроенном <iframe> и взаимодействует с нашим бэкендом через протокол WOPI.

Бэкенд реализует WOPI-хост: выдаёт документы по запросу, принимает изменения и обеспечивает авторизацию. Логи контейнера (docker logs collabora) помогают отлаживать обмен.

Такая архитектура позволяет разработчикам локально поднимать Collabora и сразу видеть рендеринг офисных файлов в браузере.

Следуя этому процессу, вы сможете вносить улучшения в платформу системно и предсказуемо.