Frontend Debugging Guide - Saga Project¶

БЫСТРАЯ ДИАГНОСТИКА¶

Этот гид поможет агентам и разработчикам быстро диагностировать и решать frontend проблемы в проекте Saga.

ИНСТРУМЕНТЫ ДИАГНОСТИКИ¶

1. SimpleDevDashboard - Первичная Диагностика¶

Где найти: Открыть любое приложение в development режиме - user-app: http://app.saga.local:8080/ (dashboard в top-right) - admin-app: http://admin.saga.local:8080/ (dashboard в top-left)

Как использовать:

Нажать кнопку "🔧 Dev" для открытия dashboard
Проверить статус всех систем:
⚛️ React: ✅/❌ - инициализирован ли React runtime
🌐 Web3: ✅/⚠️ - доступен ли ethereum provider
🔐 Auth: 🔐/👤/❓ - статус аутентификации
📡 Network: 🌐/📴 - онлайн connectivity

Интерпретация результатов:

# Все зеленое - система работает нормально
React: ✅, Web3: ✅, Auth: 🔐, Network: 🌐

# React проблема - требует ReactRuntimeFix анализа  
React: ❌, Web3: ✅, Auth: 👤, Network: 🌐

# Web3 проблема - MetaMask не найден или недоступен
React: ✅, Web3: ⚠️, Auth: 👤, Network: 🌐

2. Browser Console Analysis¶

Для React проблем (user-app):

// Проверить работу ReactRuntimeFix
// Искать сообщения:
"🔧 ReactRuntimeFix: React не инициализирован, начинаем исправление..."
"✅ ReactRuntimeFix: React успешно инициализирован из модуля"
"🎉 ReactRuntimeFix: SUCCESS! React успешно инициализирован программно!"

// Проверить результат
console.log('React доступен:', !!window.React)
console.log('React версия:', window.React?.version)

Для Web3 проблем:

// Проверить ethereum provider
console.log('Ethereum provider:', !!window.ethereum)
console.log('Provider details:', window.ethereum?.isMetaMask, window.ethereum?.selectedAddress)

// Проверить Wagmi статус
console.log('Wagmi config:', window.__WAGMI_CONFIG__)

3. Network Tab Analysis¶

Что проверять:

# Static assets loading
/_next/static/chunks/         # ← Должны загружаться 200 OK
/_next/static/css/           # ← CSS файлы
/_next/static/media/         # ← Images, fonts

# API calls
/api/auth/                   # ← Authentication endpoints
/api/health                  # ← System health check
/api/user/                   # ← User data endpoints

Типичные проблемы: - 404 на static files → проблема с Docker static serving - CORS errors → backend/frontend domain mismatch - 401 на API calls → JWT токен отсутствует или недействителен

ОСНОВНЫЕ ПРОБЛЕМЫ И РЕШЕНИЯ¶

ПРОБЛЕМА 1: React не инициализируется¶

Симптомы: - SimpleDevDashboard показывает React: ❌ - Console ошибки: "React is not defined" - UI компоненты не рендерятся

Диагностика:

// В browser console
console.log('React:', window.React)
console.log('ReactDOM:', window.ReactDOM)

// Проверить webpack chunks
console.log('Webpack chunks:', Object.keys(window.__webpack_require__.cache || {}))

Решение:

ReactRuntimeFix должен сработать автоматически (user-app only)
Проверить console logs от ReactRuntimeFix
Если не сработал - проблема с webpack chunks или static export

Manual Fix (если ReactRuntimeFix не помог):

// Ручная инициализация React
import React from 'react'
import ReactDOM from 'react-dom'
window.React = React
window.ReactDOM = ReactDOM

ПРОБЛЕМА 2: Web3 Connection Failed¶

Симптомы: - SimpleDevDashboard показывает Web3: ⚠️ - Кнопка "Connect Wallet" не работает - MetaMask не подключается

Диагностика:

// Проверить ethereum provider
if (!window.ethereum) {
  console.log('❌ MetaMask не установлен')
} else {
  console.log('✅ Ethereum provider найден:', window.ethereum.isMetaMask)
}

// Проверить UnifiedWeb3Provider
console.log('Wagmi provider status:', window.__WAGMI_CONFIG__)

Решения:

Установить MetaMask (если provider отсутствует)
Проверить network ID: Должен быть 1337 (Anvil localhost)
Restart UnifiedWeb3Provider: Перезапустить приложение

ПРОБЛЕМА 3: Auth Token Issues¶

Симптомы: - SimpleDevDashboard показывает Auth: ❓ или 👤 - API calls возвращают 401 Unauthorized - User не может войти в систему

Диагностика:

// Проверить JWT токены
console.log('Cookies:', document.cookie)
console.log('LocalStorage JWT:', localStorage.getItem('jwt_token'))

// Проверить auth context
console.log('Auth state:', /* check your auth provider state */)

Решения:

Генерировать новый JWT токен:

cd ./backend
go run cmd/jwt-helper/main.go generate-admin admin@saga-test.com
go run cmd/jwt-helper/main.go generate-user user@saga-test.com

Проверить backend auth endpoints:

curl http://localhost:8080/api/auth/verify

ПРОБЛЕМА 4: Hydration Errors¶

Симптомы: - Console warnings: "Hydration failed" - UI "flash" или мигание при загрузке - Различия между server и client render

Диагностика:

# Проверить Next.js hydration warnings в console
Warning: Prop `className` did not match
Warning: Expected server HTML to contain...

Решения:

suppressHydrationWarning={true} (уже добавлено в layout.tsx)
Static export режим должен устранить большинство проблем
Client-only rendering для проблемных компонентов

AUTOMATED DEBUGGING COMMANDS¶

System Health Check¶

# Проверка статуса системы
make status

# Проверка Docker контейнера
make restart

# Быстрые smoke тесты  
make smoke

E2E Debug Tests¶

# Тесты ReactRuntimeFix
make -f makefiles/testing.mk e2e-single FILE=tests/critical-paths/react-runtime-fix-validation.spec.ts

# Тесты UnifiedWeb3Provider
make -f makefiles/testing.mk e2e-single FILE=tests/critical-paths/unified-web3-provider-validation.spec.ts

# Hydration validation
make -f makefiles/testing.mk e2e-single FILE=tests/hydration-validation.spec.ts

Manual System Validation¶

# Проверить приложения доступны
curl -s -o /dev/null -w "%{http_code}" http://admin.saga.local:8080/
curl -s -o /dev/null -w "%{http_code}" http://app.saga.local:8080/

# Проверить API endpoints
curl http://localhost:8080/api/health
curl http://localhost:8080/api/auth/verify

TROUBLESHOOTING MATRIX¶

Симптом	SimpleDevDashboard	Вероятная причина	Первое действие
Белый экран	React: ❌	ReactRuntimeFix failure	Проверить console logs
Connect Wallet не работает	Web3: ⚠️	MetaMask недоступен	Установить/активировать MetaMask
API 401 errors	Auth: 👤	JWT токен отсутствует	Генерировать новый токен
Медленная загрузка	Network: 📴	Network connectivity	Проверить интернет соединение
UI мигание	All: ✅	Hydration mismatch	suppressHydrationWarning

STEP-BY-STEP DEBUGGING WORKFLOW¶

Шаг 1: Быстрая Проверка¶

Открыть SimpleDevDashboard
Проверить все статусы (React/Web3/Auth/Network)
Если все ✅ - проблема не в основных системах

Шаг 2: Console Analysis¶

Открыть Browser DevTools → Console
Найти ERROR/WARNING сообщения
Особое внимание на ReactRuntimeFix сообщения

Шаг 3: Network Inspection¶

DevTools → Network tab
Reload страницы
Проверить failed requests (красные)

Шаг 4: Component-Level Debug¶

React DevTools → Components tab
Найти проблемный компонент
Проверить props/state/hooks

Шаг 5: Automated Tests¶

Запустить соответствующий E2E тест
Проанализировать test output
Создать минимальный репрейс

PERFORMANCE DEBUGGING¶

Медленная Загрузка¶

// Измерить время загрузки компонентов
console.time('App Load')
// ... после полной загрузки
console.timeEnd('App Load')

// Проверить размеры bundles
console.log('Webpack stats:', window.__NEXT_DATA__?.buildManifest)

Memory Leaks¶

// Мониторинг памяти
console.log('Memory usage:', performance.memory)

// Проверить EventListeners
getEventListeners(document) // Chrome DevTools only

СВЯЗАННЫЕ ДОКУМЕНТЫ¶

Frontend Architecture - общая архитектура
CLAUDE.md - принципы разработки
Testing Guidelines - см. директорию docs/guidelines/ для руководств по тестированию

Документ создан: 2025-08-25
Применимо к: Saga v1.6+ (после frontend simplification)
Автор: Claude (Ultrathink)