Accessibility Analyzer

Chrome расширение для анализа доступности веб-приложений.

Возможности

• Автоматический анализ доступности с помощью axe-core
• AI-рекомендации по улучшению доступности от бэкенда
• Визуальная подсветка проблемных элементов на странице
• Детальные отчеты с классификацией по уровням критичности
• Подсказки с описанием проблем и способами их решения

Стек технологий

• Backend: Go, gin
• Frontend: JavaScript, HTML, CSS (Chrome Extension)
• AI: OPENAI API + GROQ : Модели – qwen3-32b
• Анализ доступности: axe-core
• Контейнеризация: Docker

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

├── backend/                  # Backend сервер (Go)
│   ├── cmd/                  # Точка входа приложения
│   ├── internal/             # Внутренние пакеты
│   ├── Dockerfile            # Docker образ
│   ├── docker-compose.yml    # Docker Compose конфигурация
│   ├── install.sh            # Скрипт установки
│   └── README.md             # Документация backend
├── frontend/                 # Chrome Extension
│   ├── manifest.json         # Манифест расширения
│   ├── background/           # Background service worker
│   ├── popup/                # Popup окно расширения
│   ├── content/              # Content scripts для подсветки
│   ├── results/              # Страница результатов анализа
│   ├── utils/                # Утилиты
│   ├── icons/                # Иконки расширения
│   ├── libs/                 # Внешние библиотеки (axe-core)
│   ├── install.sh            # Скрипт установки
│   └── README.md             # Документация frontend
├── files/                    # Примеры данных
│   └── axe_response_demo.json
└── README.md                 # Главная документация

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

1. Запуск Backend

cd backend
# С Docker Compose
docker-compose up -d

# Или локально
go run ./cmd/server/main.go

Подробнее см. backend/README.md

2. Установка Frontend (Chrome Extension)

cd frontend
chmod +x install.sh
./install.sh

Затем:

1. Откройте chrome://extensions/
2. Включите "Режим разработчика"
3. Нажмите "Загрузить распакованное расширение"
4. Выберите папку frontend

Подробнее см. frontend/README.md

3. Настройка

Откройте frontend/background/background.js и укажите URL backend:

const API_URL = 'http://localhost:3001/api/v1/analyze';

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

Анализ страницы

1. Откройте веб-страницу для анализа
2. Нажмите на иконку расширения
3. Нажмите "Analyze Page"
4. Дождитесь результатов

Визуализация проблем

На странице результатов:

• Нажмите "Show Highlights" для подсветки проблемных элементов
• Каждый элемент будет обведен цветом по уровню критичности:
  • Critical - критические проблемы
  • Serious - серьезные проблемы
  • Moderate - умеренные проблемы
  • Minor - незначительные проблемы
• При наведении появится tooltip с описанием проблемы

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

Основные эндпоинты

• POST /api/v1/analyze - Запуск анализа доступности
• GET /api/v1/status/:task_id - Получение статуса задачи
• GET /api/v1/report/:report_id - Получение полного отчета
• GET /api/v1/report/:report_id/pdf - Скачивание PDF-отчета
• GET /api/v1/health - Проверка состояния сервиса

Подробное описание всех эндпоинтов, моделей запросов и ответов находится в файле API.md.

Масштабируемость и расширяемость бэкенда

Масштабируемость

Текущая реализация бэкенда предназначена для демонстрационных и локальных целей. При большом количестве запросов могут возникнуть ограничения, связанные с лимитами API используемой AI-модели. Для масштабирования рекомендуется:

• Внедрить механизм очередей для обработки запросов.
• Оптимизировать взаимодействие с AI API.
• Рассмотреть переход на более производительные тарифные планы AI-сервиса.

Расширяемость

Бэкенд спроектирован с возможностью расширения:

• Добавление новых моделей анализа: Логика взаимодействия с AI инкапсулирована. Вы можете добавить поддержку новых моделей или сервисов, реализовав соответствующий клиент в пакете internal/.
• Изменение логики: Основная бизнес-логика находится в internal/. Вы можете изменять ее для поддержки новых функций или улучшения существующих.

Архитектура

Поток работы

1. Frontend (Popup → Background Script)

   • Назначение: Инициация анализа.
   • background.js внедряет axe-core на страницу и получает JSON-отчет о проблемах доступности.
   • Ключевая логика: Отправка сырого JSON от axe-core на бэкенд для глубокого анализа.

2. Backend API

   • Назначение: Прием отчета и запуск фоновой задачи.
   • Ключевая логика: Сервер подтверждает прием отчета, выдает уникальный номер задачи (task_id) и запускает обработку с ИИ в фоновом режиме. Отчет сохраняется для последующей обработки.

3. AI-сервис (Gemini API)

   • Назначение: Генерация рекомендаций.
   • Ключевая логика: Бэкенд отправляет технические данные о проблемах в Gemini. ИИ генерирует человекочитаемое описание, рекомендации по исправлению и примеры кода.

4. Frontend (Results Page)

   • Назначение: Отображение финального отчета.
   • Ключевая логика: После получения task_id страница результатов периодически опрашивает (поллинг) бэкенд о статусе задачи. Когда задача выполнена, страница получает и отображает полный отчет с рекомендациями от ИИ.

5. Frontend (Content Script)

   • Назначение: Визуализация проблем на исходной странице.
   • По команде со страницы результатов скрипт подсвечивает элементы, где были найдены проблемы.

Компоненты

• Popup - начальное окно с кнопкой анализа
• Background Script - координация между компонентами
• Content Script - визуализация проблем на странице
• Results Page - полноэкранная страница с результатами
• Chrome Storage - хранение данных анализа

Разработка

Структура файлов

frontend/
├── manifest.json              # Конфигурация расширения
├── popup/
│   ├── popup.html            # UI popup окна
│   ├── popup.css             # Стили popup
│   └── popup.js              # Логика popup
├── background/
│   └── background.js         # Background service worker
├── content/
│   ├── content.js           # Подсветка элементов
│   └── highlight.css        # Стили подсветки
└── results/
    ├── results.html         # UI страницы результатов
    ├── results.css          # Стили результатов
    └── results.js           # Логика отображения

Добавление новых функций

1. Изменение UI - редактируйте HTML/CSS файлы
2. Изменение логики - редактируйте соответствующие JS файлы
3. Добавление прав - обновите manifest.json
4. Перезагрузка - обновите расширение на chrome://extensions/

Важная информация о миграции

Backend

Все файлы для запуска backend находятся в папке backend/:

• backend/Dockerfile
• backend/docker-compose.yml
• backend/.dockerignore
• backend/.env.example

Frontend

Все файлы для установки frontend находятся в папке frontend/:

• frontend/install.sh
• Обновлены пути в install.sh

Проверка работы

Backend

cd backend
# Проверка сборки
go build ./cmd/server

# Проверка тестов
go test ./...

# Проверка Docker
docker compose config

Frontend

cd frontend
# Проверка install.sh
./install.sh

# Загрузка в Chrome
# chrome://extensions/ → "Загрузить распакованное расширение" → выбрать папку frontend

Troubleshooting

Расширение не работает

• Проверьте консоль (F12 → Console)
• Убедитесь, что axe-core загружен
• Проверьте права в manifest.json

Подсветка не работает

• Проверьте, что content script загружен
• Посмотрите ошибки в консоли
• Перезагрузите расширение

Ошибка связи с бэкендом

• Проверьте, что бэкенд запущен
• Убедитесь в правильности URL
• Проверьте CORS на бэкенде

📄 Лицензия

Этот проект лицензирован под лицензией MIT - подробности см. в файле LICENSE.

👥 Команда

• Backend: Narotan
• Frontend: Dreamer0iQ
• DevOps: Kefircheggg
• UX/UI: MrSnickersRUS

Создано для улучшения доступности веб-приложений 🌐