Ku6epXBOCTuK/twitch-panels
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add improvement plans

Browse Source
This commit is contained in:
Ku6epXBOCTuK
2026-02-07 23:26:01 +05:00
parent 2eab18569e
commit 50c95c46a5
2 changed files with 775 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plans/COMPREHENSIVE_IMPROVEMENT_PLAN.md
+620
View File
@@ -0,0 +1,620 @@
# Comprehensive Improvement Plan for Twitch Panels Project
**Analysis Date**: 2025-02-07
**Project**: Twitch Panels Creator
**Tech Stack**: Svelte 5, TypeScript, SvelteKit, Konva, Vitest
---
## Executive Summary
This plan outlines all necessary improvements for the Twitch Panels project, categorized by priority and impact. The project has a solid foundation with Svelte 5 runes, proper error handling, and good component structure, but critical gaps exist in **image upload functionality** and **test coverage** that must be addressed.
**Key Focus Areas**:
1. **Complete image loading system** (upload, crop, preview)
2. **Rewrite and expand test suite** (currently broken/incomplete)
3. **Architectural refinements** (service layer, state management)
4. **Code quality** (type safety, error handling, accessibility)
---
## 🔴 CRITICAL PRIORITY (Must Fix Before Production)
### 1. Image Loading System - INCOMPLETE
**Current State**:
- `ImageManager.svelte` has UI buttons but no functionality
- `CropInline.svelte` exists but is not integrated
- `imageConfig.svelte.ts` has hardcoded default image load
- No actual image upload handlers (drag-drop, paste, URL)
- Missing image service layer
**Required Implementation**:
#### 1.1 Create Image Service (`src/services/imageService.ts`)
```typescript
export class ImageService {
// Upload from file (drag-drop, paste, file input)
async uploadFromFile(file: File): Promise<ImageResult>;
// Upload from URL
async uploadFromURL(url: string): Promise<ImageResult>;
// Validate image (size, format, dimensions)
validateImage(file: File): ValidationResult;
// Process image (resize, compress if needed)
processImage(image: HTMLImageElement): ProcessedImage;
// Set as background
setBackground(image: ProcessedImage): void;
// Reset to default
resetToDefault(): void;
}
```
#### 1.2 Implement ImageUpload Component
Create `src/components/image/ImageUpload.svelte` with:
- Drag-and-drop zone with visual feedback
- Paste from clipboard (Ctrl+V)
- URL input field with validation
- File input fallback
- Loading states and error messages
#### 1.3 Integrate Cropper.js
- Create `src/components/image/ImageCropper.svelte` wrapper
- Integrate with `CropInline.svelte` or replace it
- Add crop controls (aspect ratio 16:5 for panels)
- Handle crop completion and update background
#### 1.4 Wire Up ImageManager.svelte
Add onclick handlers to buttons:
- "Загрузить" → Open file picker or show upload options
- "Редактировать" → Activate crop mode
- "Сбросить" → Reset to default background
#### 1.5 Remove Hardcoded Default
- Move default image loading to a proper initialization
- Make it configurable or lazy-loaded
- Add fallback if default image fails to load
---
### 2. Test Suite - BROKEN/INCOMPLETE
**Current State**:
- `downloadService.test.ts` has **syntax errors** (line 92: `[{ ...id: "test-panel-2" }]`)
- Tests reference **non-existent methods** (`handleDownload`, `downloadPanels`)
- Only 2 test files exist (errorHandler.test.ts is good, downloadService is broken)
- **Zero component tests**
- **Zero integration tests**
- Test coverage is effectively 0%
**Required Fixes**:
#### 2.1 Fix downloadService.test.ts
```typescript
// CURRENT BROKEN CODE (line 92):
let panels = [{ ...id: "test-panel-2" }]; // Syntax error!
// SHOULD BE:
let panels: DownloadItem[] = [{
filename: "test-panel-2",
stage: mockKonvaStage
}];
```
Remove or fix tests that call non-existent methods:
- `handleDownload` → should be `downloadPanel`
- `downloadPanels` → should be `downloadAll`
#### 2.2 Expand Test Coverage
**Unit Tests Needed**:
- `src/services/downloadService.test.ts` (fix existing)
- `src/services/imageService.test.ts` (new, after creating service)
- `src/lib/utils/errorUtils.test.ts` (expand existing)
- `src/states/*.svelte.ts.test.ts` (all state files)
- `src/lib/utils/panelStorage.test.ts` (if exists)
**Component Tests Needed**:
- `src/components/image/ImageManager.test.ts`
- `src/components/image/ImageUpload.test.ts` (after creation)
- `src/components/image/ImageCropper.test.ts` (after creation)
- `src/components/text/TextManager.test.ts`
- `src/components/text/TextConfig.test.ts`
- `src/components/panel/PreviewManager.test.ts`
- `src/components/panel/Preview.svelte.test.ts`
**Integration Tests**:
- Full user flow: upload image → crop → add texts → preview → download
- Error scenarios: invalid image, network failure, disk full
#### 2.3 Test Quality Standards
- **Target Coverage**: 80% overall, 100% for critical paths
- **Mocking**: Properly mock external dependencies (file-saver, jszip, cropperjs)
- **Assertions**: Test both success and failure cases
- **Cleanup**: Ensure proper test isolation
---
## 🟡 HIGH PRIORITY (Important for Quality)
### 3. Architectural Improvements
#### 3.1 Service Layer Completion
**Problem**: Only `downloadService.ts` exists. Implementation plan references `imageService`, `panelService`, `exportService` that don't exist.
**Solution**: Create missing services:
- `src/services/imageService.ts` (as described above)
- `src/services/panelService.ts` - manage panel creation, validation, metadata
- Consider merging `downloadService` into `exportService` or keep as is
**Benefits**:
- Clear separation of concerns
- Easier testing (services can be unit tested)
- Reusable business logic
#### 3.2 State Management Review
**Current State**: Multiple state files using Svelte 5 runes - this is good!
- `imageConfig.svelte.ts` - image state
- `textConfig.svelte.ts` - text styling state
- `texts.svelte.ts` - text list state
- `konvaStage.svelte.ts` - single stage
- `konvaAllStages.svelte.ts` - array of stages
**Issues**:
- `imageConfig.svelte.ts:94` hardcodes default image load - should be in component
- `textConfig.svelte.ts:35` has bug: `state.fontFamily = this.fontFamily` should be `state.fontFamily = fontFamily`
- State files mix state creation with side effects
**Required Fixes**:
1. Fix `textConfig.svelte.ts` setter bug
2. Remove hardcoded image load from `imageConfig.svelte.ts` - move to component
3. Consider consolidating related states (e.g., image + crop = imageManagerState)
4. Add proper cleanup in state destructors if needed
#### 3.3 Component Structure Alignment
**Problem**: Documentation (`COMPONENT_ORGANIZATION.md`) references components that don't exist:
- `ImageUpload.svelte` (doesn't exist, should be created)
- `ImageCropper.svelte` (doesn't exist, should be created)
- `PanelPreview.svelte` (exists as `Preview.svelte`)
- `PanelsList.svelte` (doesn't exist, functionality in `PreviewManager.svelte`)
**Solution Options**:
- **Option A**: Create missing components to match documentation
- **Option B**: Update documentation to match reality
- **Recommended**: Hybrid - create essential missing components (ImageUpload, ImageCropper), update docs to reflect actual structure
---
### 4. Missing Features & UX Improvements
#### 4.1 Panel Persistence
**Current State**: No localStorage or persistence. Refresh loses all data.
**Required**:
- Implement `panelStorage.ts` utility (referenced in docs but missing)
- Auto-save to localStorage on state changes
- Load saved panels on app initialization
- Add "Clear All" button with confirmation
#### 4.2 User Feedback System
**Missing**:
- Loading indicators during image upload/crop
- Success notifications (toast) after download
- Error messages displayed to user (currently only console.log)
- Progress bar for batch downloads
**Implementation**:
- Create `src/components/feedback/Toast.svelte` or use simple notification
- Add UI state for loading/error/success
- Use errorUtils to format user-friendly messages
#### 4.3 Accessibility (WCAG 2.1)
**Current Gaps**:
- No ARIA labels on buttons
- No keyboard navigation support
- No screen reader announcements
- Color contrast may not meet AA standards
**Required**:
- Add `aria-label` to all icon-only buttons
- Ensure keyboard navigation works (tab order, focus states)
- Add `role="alert"` for error messages
- Test with screen readers
- Add high contrast mode support if needed
#### 4.4 Internationalization
**Problem**: Mixed Russian/English in UI and error messages.
**Solution**:
- Standardize on Russian (current UI language)
- Or implement i18n system (e.g., svelte-i18n)
- Ensure all user-facing text is consistent
- Keep error codes in English for debugging
---
## 🟢 MEDIUM PRIORITY (Polish & Optimization)
### 5. Code Quality & Type Safety
#### 5.1 TypeScript Improvements
- Add stricter tsconfig settings (`strict: true`, `noImplicitAny: true`)
- Define proper return types for all functions
- Use `satisfies` operator for type-safe object literals
- Add `// @ts-expect-error` only with justification comments
#### 5.2 Error Handling Consistency
**Current**: Good error type hierarchy exists (`AppError`, `ImageError`, etc.)
**Issues**:
- Not all errors are properly typed
- Some errors throw strings instead of Error objects
- Error messages in Russian but codes in English - this is actually good!
**Required**:
- Audit all `throw` statements - should throw `AppError` subclasses
- Use `createError` utility consistently
- Add error context/details where helpful
#### 5.3 Code Documentation
- Add JSDoc comments to all public functions and classes
- Document complex logic (especially image processing)
- Add inline comments for non-obvious code
- Update README with setup and usage instructions
#### 5.4 Component Prop Validation
- Add proper prop types with defaults
- Use `svelte-check` to catch type errors
- Consider runtime validation for user inputs
---
### 6. Performance Optimization
#### 6.1 Image Optimization
- Compress uploaded images (use canvas to resize/compress)
- Convert to appropriate format (WebP for smaller size)
- Implement lazy loading for background preview
- Add image caching strategy
#### 6.2 Konva Rendering Optimization
- Currently creates new Stage for each panel - this is expensive
- Consider reusing stages or optimizing layer updates
- Debounce rapid text changes
- Use `shouldComponentUpdate` patterns if available
#### 6.3 Bundle Size
- Check bundle analyzer (vite-bundle-analyzer)
- Remove unused dependencies
- Enable code splitting for large libraries (cropperjs, jszip)
- Consider dynamic imports for non-critical features
---
### 7. Build & Development Experience
#### 7.1 Build Configuration
- Add bundle analysis to build script
- Configure proper source maps for debugging
- Set up environment variable handling
- Add build size reporting
#### 7.2 Development Tools
- Add ESLint with Svelte and TypeScript rules
- Add Prettier for consistent formatting
- Configure husky + lint-staged for pre-commit hooks
- Add commit message linting (conventional commits)
#### 7.3 CI/CD (if deploying)
- GitHub Actions for test automation
- Automated build and deployment
- Coverage reporting to Codecov or similar
- Dependency vulnerability scanning
---
## 📋 DETAILED TASK BREAKDOWN
### Phase 1: Critical Fixes (Week 1-2)
#### Task 1.1: Fix Broken Tests (Day 1)
- [ ] Fix syntax error in `downloadService.test.ts:92`
- [ ] Remove tests for non-existent methods
- [ ] Run test suite and ensure all pass
- [ ] Add missing mocks for file-saver, jszip
#### Task 1.2: Complete Image Upload UI (Day 2-3)
- [ ] Create `ImageUpload.svelte` component
- [ ] Implement drag-drop, paste, URL input
- [ ] Add file validation (size, type)
- [ ] Add loading states
- [ ] Wire up ImageManager button handlers
#### Task 1.3: Implement Image Cropping (Day 4-5)
- [ ] Create `ImageCropper.svelte` wrapper for cropperjs
- [ ] Integrate with CropInline or replace
- [ ] Add crop aspect ratio constraints (16:5)
- [ ] Handle crop completion and update state
- [ ] Add crop cancellation
#### Task 1.4: Create Image Service (Day 6-7)
- [ ] Implement `imageService.ts` with all methods
- [ ] Add proper error handling
- [ ] Write unit tests for imageService
- [ ] Integrate service with components
#### Task 1.5: Remove Hardcoded Default (Day 8)
- [ ] Move default image loading to component
- [ ] Add fallback if default fails
- [ ] Make default configurable
---
### Phase 2: Testing Expansion (Week 3)
#### Task 2.1: Component Test Infrastructure (Day 1-2)
- [ ] Set up `@testing-library/svelte` properly
- [ ] Create test utilities for component rendering
- [ ] Write test for `TextManager.svelte`
- [ ] Write test for `TextConfig.svelte`
#### Task 2.2: Image Component Tests (Day 3-4)
- [ ] Test `ImageManager.svelte`
- [ ] Test `ImageUpload.svelte`
- [ ] Test `ImageCropper.svelte`
- [ ] Test error scenarios
#### Task 2.3: Panel Component Tests (Day 5-6)
- [ ] Test `Preview.svelte`
- [ ] Test `PreviewManager.svelte`
- [ ] Test download functionality
- [ ] Test navigation
#### Task 2.4: Integration Tests (Day 7-10)
- [ ] Set up Playwright or use Testing Library for full flow
- [ ] Test complete user journey
- [ ] Test error recovery
- [ ] Achieve 80% coverage target
---
### Phase 3: Architecture & Quality (Week 4-5)
#### Task 3.1: State Management Cleanup (Day 1-2)
- [ ] Fix `textConfig.svelte.ts:35` bug
- [ ] Review all state files for similar issues
- [ ] Add proper cleanup where needed
- [ ] Consider state consolidation
#### Task 3.2: Create Missing Services (Day 3-4)
- [ ] Create `panelService.ts` for panel management
- [ ] Refactor panel logic from components to service
- [ ] Write tests for panelService
- [ ] Update components to use service
#### Task 3.3: Implement Persistence (Day 5-6)
- [ ] Create `panelStorage.ts` utility
- [ ] Implement auto-save on state changes
- [ ] Load saved state on app init
- [ ] Add migration logic for schema changes
- [ ] Write tests for storage
#### Task 3.4: User Feedback System (Day 7-8)
- [ ] Create Toast notification component
- [ ] Add loading states to all async operations
- [ ] Display errors to users (not just console)
- [ ] Add success confirmations
#### Task 3.5: Accessibility (Day 9-10)
- [ ] Add ARIA labels to all interactive elements
- [ ] Implement keyboard navigation
- [ ] Test with screen readers
- [ ] Add focus management
- [ ] Verify color contrast
---
### Phase 4: Polish & Optimization (Week 6)
#### Task 4.1: Code Quality (Day 1-3)
- [ ] Enable strict TypeScript mode
- [ ] Add ESLint + Prettier
- [ ] Fix all linting errors
- [ ] Add JSDoc documentation
- [ ] Update README
#### Task 4.2: Performance (Day 4-5)
- [ ] Implement image compression
- [ ] Add lazy loading
- [ ] Optimize Konva rendering
- [ ] Analyze and reduce bundle size
#### Task 4.3: Final Testing & Bug Fixes (Day 6-7)
- [ ] Cross-browser testing
- [ ] Mobile responsiveness check
- [ ] Performance profiling
- [ ] Fix any remaining issues
---
## 📊 SUCCESS METRICS
### Testing
- ✅ 80%+ code coverage overall
- ✅ 100% coverage for critical paths (download, image upload)
- ✅ All tests passing consistently
- ✅ No broken or skipped tests
### Code Quality
- ✅ Zero TypeScript errors in strict mode
- ✅ Zero ESLint errors (or justified exceptions)
- ✅ All public APIs documented
- ✅ Consistent error handling
### Functionality
- ✅ Image upload works (drag-drop, paste, URL)
- ✅ Image cropping works with proper constraints
- ✅ All download functions work (single, batch)
- ✅ State persists across page refreshes
- ✅ No memory leaks
### User Experience
- ✅ Loading states for all async operations
- ✅ Clear error messages displayed to users
- ✅ Keyboard navigation works
- ✅ Screen reader compatible
- ✅ Responsive design
---
## 🎯 QUICK WINS (Can Do Immediately)
These are small improvements that can be done quickly while working on larger tasks:
1. **Fix the obvious test bug** (line 92 in downloadService.test.ts) - 5 minutes
2. **Add onclick handlers** to ImageManager buttons (even if just console.log for now) - 10 minutes
3. **Fix textConfig.svelte.ts bug** (line 35) - 2 minutes
4. **Remove hardcoded default image** from state file - 5 minutes
5. **Add basic error display** in components (show error state) - 30 minutes
6. **Add loading spinners** to buttons during async operations - 1 hour
7. **Add ARIA labels** to all buttons - 1 hour
8. **Update README** with project description - 30 minutes
---
## 📚 REFERENCE MATERIAL
### Existing Plans (Already Created)
- `plans/TECHNICAL_DEBT_ANALYSIS.md` - Good analysis of debt categories
- `plans/implementation-plan.md` - Original implementation tasks
- `plans/PROJECT_PLAN.md` - MVP requirements (in Russian)
- `plans/CRITICAL_ISSUES_REMEDIATION_PLAN.md` - Similar to this plan
### This Plan Builds Upon
- All existing plans are still valid
- This plan provides **specific, actionable tasks** with file references
- Focuses on **immediate critical issues** (image loading, tests)
- Provides **concrete implementation details**
---
## 🚀 IMPLEMENTATION ORDER
**Recommended Order** (based on dependencies):
1. **Fix broken tests** → Establish baseline
2. **Complete image upload** → Core feature is broken
3. **Create image service** → Needed for testable architecture
4. **Expand test coverage** → While implementing features
5. **Fix state bugs** → Prevents future issues
6. **Add persistence** → Improves UX significantly
7. **User feedback system** → Better UX
8. **Accessibility** → Compliance and usability
9. **Code quality** → Polish
10. **Performance** → Final optimization
---
## ⚠️ RISKS & MITIGATIONS
| Risk | Impact | Mitigation |
| ----------------------- | ------ | ------------------------------------------------------------------------- |
| Image upload complexity | High | Break into small tasks, use proven libraries (cropperjs already included) |
| Test time investment | Medium | Prioritize critical path tests first, expand gradually |
| State management bugs | Medium | Write tests for states before fixing |
| Accessibility oversight | Medium | Use automated tools (axe) + manual testing |
| Performance issues | Low | Profile before optimizing, focus on bottlenecks |
---
## 📝 NOTES
- **Svelte 5 runes** are being used correctly - keep this pattern
- **Error handling** infrastructure is well-designed - reuse it
- **Component structure** is mostly good - just needs completion
- **TypeScript** usage is decent - improve with strict mode
- **Dependencies** are appropriate - no need to change
---
**Next Steps**:
1. Review this plan with the team
2. Prioritize tasks based on resources
3. Start with Phase 1, Task 1.1 (fix broken tests)
4. Create GitHub issues for each task
5. Track progress against success metrics
plans/IMPROVEMENTS_PLAN.md
+155
View File
@@ -0,0 +1,155 @@
# План улучшений проекта Twitch Panels
## 🚨 Критические улучшения (Приоритет 1)
### 1. Реализация функции downloadAll
**Проблема**: Функция не реализована, но кнопка уже есть в UI
**Решение**:
- Использовать компонент PreviewAll для рендеринга всех панелей
- Создать массив Konva Stage из всех компонентов
- Реализовать сохранение всех панелей в ZIP-архив с помощью jszip
- Добавить прогресс-индикатор для массового скачивания
### 2. Завершение загрузки изображений
**Проблема**: ImageManager и CropInline не полностью реализованы
**Решение**:
- Реализовать загрузку изображений через drag-drop, paste и URL
- Добавить интеграцию с cropperjs для обрезки
- Реализовать сохранение обрезанного изображения
- Добавить валидацию форматов и размеров изображений
- Реализовать фильтры яркости/контраста
### 3. Исправление бага в textConfig.svelte.ts
**Проблема**: В строке 35 `this.fontFamily` вместо `fontFamily`
**Решение**: Исправить setter для fontFamily
## ⚠️ Важные улучшения (Приоритет 2)
### 4. Улучшение состояния konvaAllStages
**Проблема**: Простая массив без методов управления
**Решение**:
- Добавить методы для добавления/удаления Stage
- Добавить валидацию перед добавлением
- Реализовать автоматическую очистку при удалении текстов
### 5. Добавление валидации входных данных
**Проблема**: Отсутствует валидация текстов и изображений
**Решение**:
- Добавить валидацию длины текста (MAX_TEXT_LENGTH уже есть в константах)
- Валидировать URL изображений перед загрузкой
- Проверять размер файлов (MAX_FILE_SIZE уже есть в константах)
- Валидировать форматы изображений
### 6. Улучшение обработки ошибок
**Проблема**: Не все ошибки обрабатываются корректно
**Решение**:
- Добавить error boundaries в Svelte компоненты
- Создать централизованный компонент для отображения ошибок
- Добавить уведомления об ошибках в UI (toast notifications)
- Улучшить логирование ошибок с контекстом
### 7. Оптимизация производительности
**Проблема**: Потенциальные проблемы с производительностью при большом количестве панелей
**Решение**:
- Добавить виртуализацию списка панелей
- Оптимизировать рендеринг Konva Stage
- Добавить ленивую загрузку изображений
- Оптимизировать перерисовку при изменении настроек
## 🔧 Средние улучшения (Приоритет 3)
### 8. Улучшение UX/UI
**Проблема**: Некоторые элементы интерфейса можно улучшить
**Решение**:
- Добавить загрузочные индикаторы для долгих операций
- Улучшить визуальную обратную связь при действиях
- Добавить tooltips для кнопок без текста
- Улучшить мобильную адаптивность
### 9. Добавление сохранения/загрузки проектов
**Проблема**: Нет возможности сохранить и загрузить проект
**Решение**:
- Реализовать сохранение конфигурации в localStorage
- Добавить экспорт/импорт конфигурации в JSON
- Добавить возможность сохранения нескольких проектов
### 10. Улучшение PreviewAll
**Проблема**: Компонент отображается за пределами экрана без контроля
**Решение**:
- Добавить флаг для управления видимостью
- Оптимизировать создание Stage только при необходимости
- Добавить автоматическую очистку при закрытии
### 11. Улучшение Button компонента
**Проблема**: Дублирование стилей в btn-danger
**Решение**:
- Вынести общие стили в базовый класс
- Унифицировать подход к стилизации разных типов кнопок
## 📚 Документация и тесты (Приоритет 4)
### 12. Улучшение документации
**Проблема**: Недостаточно документации
**Решение**:
- Добавить JSDoc комментарии к функциям
- Документировать типы и интерфейсы
- Создать README с инструкциями по разработке
- Добавить примеры использования компонентов
### 13. Переписывание тестов
**Проблема**: Тесты устарели и не покрывают весь функционал
**Решение**:
- Обновить тесты для Svelte 5 runes
- Добавить тесты для всех состояний (states)
- Добавить тесты для компонентов
- Добавить тесты для downloadService
- Добавить интеграционные тесты
- Улучшить покрытие кода тестами
### 14. Добавление E2E тестов
**Проблема**: Нет E2E тестов для критических путей пользователя
**Решение**:
- Создать E2E тесты для основного workflow
- Тестировать загрузку изображений
- Тестировать создание и редактирование панелей
- Тестировать скачивание панелей
## 🎨 Дополнительные улучшения (Приоритет 5)
### 15. Добавление анимаций
**Решение**:
- Добавить плавные анимации при добавлении/удалении панелей
- Анимировать переключение тем
- Добавить микро-взаимодействия
### 16. Улучшение доступности (a11y)
**Решение**:
- Добавить ARIA labels
- Улучшить keyboard navigation
- Проверить контрастность цветов
- Добавить поддержку screen readers
### 17. Локализация
**Решение**:
- Вынести все текстовые строки в отдельный файл
- Добавить поддержку нескольких языков
- Реализовать переключение языков
## 📊 Метрики для отслеживания
Для оценки эффективности улучшений предлагаю отслеживать следующие метрики:
- Время загрузки страницы
- Время создания панели
- Покрытие тестами (целевой минимум 80%)
- Количество ошибок в production
- Пользовательский NPS
## 🎯 Рекомендуемый порядок реализации
1. **Неделя 1**: Критические улучшения (1-3)
2. **Неделя 2**: Важные улучшения (4-7)
3. **Неделя 3**: Средние улучшения (8-11)
4. **Неделя 4**: Документация и тесты (12-14)
5. **Неделя 5**: Дополнительные улучшения (15-17)
Этот план поможет вам систематически улучшать проект, начиная с самых критических проблем и постепенно переходя к более продвинутым функциям.