Files
WishKing/README.md
T
2026-08-18 19:56:41 +03:00

1231 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Wishlist — Roadmap
Self-hosted сервис для создания, публикации и совместного использования вишлистов с поддержкой резервирования подарков и Secret Santa.
## 1. Project Vision
Основные цели проекта:
* Self-hosted deployment.
* Адаптивный интерфейс для Desktop / Tablet / Mobile.
* Поддержка нескольких СУБД: SQLite, PostgreSQL, MySQL/MariaDB.
* Локальная аутентификация, OIDC и LDAP.
* Публичные и приватные вишлисты.
* Резервирование подарков.
* Совместная покупка одного подарка несколькими людьми.
* Secret Santa («Дед Мороз»).
* Простое развёртывание через Docker.
---
# 2. Tech Stack
## Frontend
* [ ] Vite
* [ ] TypeScript
* [ ] React
* [ ] React Router
* [ ] TanStack Query
* [ ] Tailwind CSS
* [ ] Zod
## Backend
* [ ] Go
* [ ] HTTP API
* [ ] REST
* [ ] OpenAPI
* [ ] Repository / Service architecture
## Database
* [ ] SQLite
* [ ] PostgreSQL
* [ ] MySQL / MariaDB
## Infrastructure
* [ ] Docker
* [ ] Docker Compose
* [ ] Multi-stage builds
* [ ] Persistent volumes
* [ ] Health checks
* [ ] Environment-based configuration
---
# 3. Development Roadmap
## Phase 0 — Project Planning
**Цель:** зафиксировать архитектуру и требования до начала активной разработки.
* [ ] Финализировать Product Requirements
* [ ] Финализировать функциональные требования
* [ ] Определить MVP
* [ ] Описать User Stories
* [ ] Описать Use Cases
* [ ] Спроектировать доменную модель
* [ ] Спроектировать ER-диаграмму
* [ ] Спроектировать API
* [ ] Определить модель авторизации
* [ ] Определить правила Secret Santa
* [ ] Определить структуру проекта
* [ ] Создать Architecture Decision Records (ADR)
---
# 4. Phase 1 — Project Bootstrap
**Цель:** получить минимальный запускаемый проект.
### Repository
* [ ] Создать Git repository
* [ ] Настроить `.gitignore`
* [ ] Создать `.env.example`
* [ ] Создать README
* [ ] Настроить Git hooks
* [ ] Настроить CI
### Frontend
* [ ] Создать Vite project
* [ ] Настроить TypeScript
* [ ] Настроить React
* [ ] Настроить ESLint
* [ ] Настроить formatter
* [ ] Настроить Tailwind CSS
* [ ] Создать базовую структуру компонентов
### Backend
* [ ] Создать Go module
* [ ] Настроить HTTP server
* [ ] Настроить router
* [ ] Настроить configuration
* [ ] Настроить logger
* [ ] Настроить error handling
* [ ] Создать `/health`
### Docker
* [ ] Создать Dockerfile
* [ ] Создать `.dockerignore`
* [ ] Создать Docker Compose
* [ ] Настроить development environment
* [ ] Настроить production build
---
# 5. Phase 2 — Database Layer
**Цель:** создать абстракцию над СУБД и основу для миграций.
### Database Core
* [ ] Database interface
* [ ] Repository interface
* [ ] Transaction abstraction
* [ ] Database migrations
* [ ] UUID identifiers
* [ ] Foreign keys
* [ ] Indexes
* [ ] Database health check
### SQLite
* [ ] SQLite driver
* [ ] SQLite migrations
* [ ] SQLite integration tests
### PostgreSQL
* [ ] PostgreSQL driver
* [ ] PostgreSQL migrations
* [ ] PostgreSQL integration tests
### MySQL / MariaDB
* [ ] MySQL driver
* [ ] MySQL migrations
* [ ] MySQL integration tests
### Compatibility
* [ ] Общий набор integration tests для всех БД
* [ ] Проверить CRUD на SQLite
* [ ] Проверить CRUD на PostgreSQL
* [ ] Проверить CRUD на MySQL/MariaDB
---
# 6. Phase 3 — Authentication Core
**Цель:** создать систему пользователей и локальную аутентификацию.
### User
* [ ] User model
* [ ] User repository
* [ ] User service
* [ ] User API
* [ ] Profile API
### Local Authentication
* [ ] Registration
* [ ] Login
* [ ] Logout
* [ ] Password hashing
* [ ] Session management
* [ ] Authentication middleware
* [ ] `/api/me`
* [ ] Password change
### Security
* [ ] Rate limiting
* [ ] Input validation
* [ ] Secure cookies
* [ ] CSRF protection
* [ ] Security headers
* [ ] Request size limits
---
# 7. Phase 4 — Identity & External Authentication
**Цель:** добавить OIDC и LDAP без привязки пользователя к конкретному auth provider.
### Identity Model
* [ ] Создать `Identity`
* [ ] Связать Identity с User
* [ ] Поддержать несколько identities на одного User
* [ ] Account linking
* [ ] Account unlinking
### OIDC
* [ ] OIDC configuration
* [ ] Authorization flow
* [ ] Callback
* [ ] Token validation
* [ ] User provisioning
* [ ] User mapping
* [ ] Provider configuration
* [ ] Multiple OIDC providers
### LDAP
* [ ] LDAP configuration
* [ ] LDAP connection
* [ ] User lookup
* [ ] Password authentication
* [ ] User provisioning
* [ ] LDAP attribute mapping
* [ ] Active Directory compatibility
### Administration
* [ ] Auth provider configuration
* [ ] Enable/disable providers
* [ ] Provider health check
* [ ] Documentation for Keycloak
* [ ] Documentation for Authentik
* [ ] Documentation for OpenLDAP
* [ ] Documentation for Active Directory
---
# 8. Phase 5 — Wishlist Core
**Цель:** реализовать основной объект приложения.
### Wishlist
* [ ] Wishlist model
* [ ] Create wishlist
* [ ] Read wishlist
* [ ] Update wishlist
* [ ] Delete wishlist
* [ ] Ownership validation
* [ ] Wishlist slug
* [ ] Wishlist description
### Visibility
* [ ] Private
* [ ] Unlisted
* [ ] Public
### Sharing
* [ ] Generate public URL
* [ ] Copy share URL
* [ ] Disable public access
* [ ] Regenerate access token
---
# 9. Phase 6 — Wishlist Items
**Цель:** реализовать добавление желаний.
### Item
* [ ] Item model
* [ ] Create item
* [ ] Read item
* [ ] Update item
* [ ] Delete item
* [ ] Reorder items
### Item Properties
* [ ] Title
* [ ] Description
* [ ] URL
* [ ] Image URL
* [ ] Price
* [ ] Currency
* [ ] Quantity
* [ ] Priority
* [ ] Position
### Future
* [ ] Categories
* [ ] Tags
* [ ] Image upload
* [ ] Automatic metadata extraction
* [ ] Price tracking
---
# 10. Phase 7 — Frontend Foundation
**Цель:** создать единый responsive UI.
### Design System
* [ ] Colors
* [ ] Typography
* [ ] Spacing
* [ ] Buttons
* [ ] Inputs
* [ ] Selects
* [ ] Checkbox
* [ ] Modal
* [ ] Dropdown
* [ ] Toast
* [ ] Tooltip
* [ ] Card
* [ ] Avatar
* [ ] Skeleton
* [ ] Empty state
* [ ] Error state
### Responsive Design
Проверить минимум:
* [ ] 320px
* [ ] 375px
* [ ] 640px
* [ ] 768px
* [ ] 1024px
* [ ] 1280px
* [ ] 1440px
* [ ] 1920px
### Themes
* [ ] Light theme
* [ ] Dark theme
* [ ] System theme
---
# 11. Phase 8 — Authentication UI
* [ ] Login page
* [ ] Registration page
* [ ] Logout
* [ ] Session restoration
* [ ] Protected routes
* [ ] OIDC login
* [ ] LDAP login
* [ ] Account settings
* [ ] Linked identities
* [ ] Password change
* [ ] Authentication error states
---
# 12. Phase 9 — Dashboard
**Цель:** основная рабочая область пользователя.
* [ ] Dashboard
* [ ] Wishlist list
* [ ] Wishlist card
* [ ] Create wishlist
* [ ] Edit wishlist
* [ ] Delete wishlist
* [ ] Empty state
* [ ] Search
* [ ] Sorting
* [ ] Responsive layout
Пример структуры:
```text
Dashboard
├── Header
├── User menu
├── Wishlist list
│ ├── Wishlist card
│ ├── Wishlist card
│ └── Wishlist card
└── Create wishlist
```
---
# 13. Phase 10 — Wishlist Editor
* [ ] Wishlist header
* [ ] Item grid
* [ ] Add item
* [ ] Edit item
* [ ] Delete item
* [ ] Reorder items
* [ ] Drag & drop
* [ ] Wishlist settings
* [ ] Visibility settings
* [ ] Share dialog
* [ ] Copy public URL
---
# 14. Phase 11 — Public Wishlist
**Цель:** пользователь без аккаунта может посмотреть wishlist.
* [ ] Public wishlist route
* [ ] Public wishlist layout
* [ ] Item cards
* [ ] Item details
* [ ] External product link
* [ ] Responsive design
* [ ] OpenGraph metadata
* [ ] Social preview
* [ ] Reservation UI
---
# 15. Phase 12 — Gift Reservation
**Цель:** позволить посетителю зарезервировать подарок.
### Basic Reservation
* [ ] Reservation model
* [ ] Reserve item
* [ ] Cancel reservation
* [ ] Reservation status
* [ ] Anonymous reservation
* [ ] Reservation token
* [ ] Reservation expiration
### Privacy
* [ ] Владелец wishlist не видит, кто зарезервировал подарок
* [ ] Публичный пользователь видит только статус
* [ ] Reservation token нельзя использовать для просмотра приватных данных
### States
```text
OPEN
RESERVED
CANCELLED
EXPIRED
```
---
# 16. Phase 13 — Shared Gift Reservation
**Цель:** несколько людей могут совместно купить один подарок.
### Shared Reservation
* [ ] Создание совместной резервации
* [ ] Join reservation
* [ ] Leave reservation
* [ ] Participant management
* [ ] Anonymous participants
* [ ] Reservation progress
* [ ] Target amount
* [ ] Participant amount
* [ ] Currency support
### Example
```text
Sony WH-1000XM6
Target: €600
Ivan €200
Peter €150
Anna €250
Progress: €600 / €600
Status: FULL
```
### Privacy
* [ ] Wishlist owner не видит участников
* [ ] Wishlist owner не видит внесённые суммы
* [ ] Участники видят только необходимую информацию
* [ ] Нельзя раскрыть личность других участников через API
### States
```text
OPEN
FULL
CANCELLED
COMPLETED
```
---
# 17. Phase 14 — Secret Santa
**Цель:** реализовать полноценный режим «Дед Мороз».
### Event
* [ ] Create Secret Santa
* [ ] Edit event
* [ ] Delete event
* [ ] Event description
* [ ] Event dates
* [ ] Event status
### Participants
* [ ] Add participant
* [ ] Remove participant
* [ ] Invite participant
* [ ] Accept invitation
* [ ] Decline invitation
* [ ] Participant list
* [ ] Participant status
### Invitations
* [ ] Invitation model
* [ ] Invitation token
* [ ] Invitation expiration
* [ ] Accept invitation
* [ ] Cancel invitation
* [ ] Resend invitation
### Drawing
* [ ] Generate assignments
* [ ] Prevent self-assignment
* [ ] Exclusion rules
* [ ] Previous-year restrictions
* [ ] Validate possible assignment
* [ ] Secure randomization
* [ ] Lock assignment after draw
### Assignment
* [ ] Giver sees receiver
* [ ] Giver sees receiver wishlist
* [ ] Receiver doesn't see giver
* [ ] Other participants cannot see assignment
* [ ] Organizer cannot accidentally reveal assignments
### Event Lifecycle
```text
DRAFT
INVITING
READY
DRAWN
ACTIVE
FINISHED
```
---
# 18. Phase 15 — Secret Santa Advanced
После базовой реализации:
* [ ] Exclude specific participants
* [ ] Exclude previous matches
* [ ] Budget limit
* [ ] Gift preferences
* [ ] Anonymous questions
* [ ] Event chat
* [ ] Gift confirmation
* [ ] Event statistics
* [ ] Re-run draw
* [ ] Draw audit log
---
# 19. Phase 16 — API
**Цель:** предоставить стабильный API для frontend и будущих интеграций.
### Authentication
```text
POST /api/auth/register
POST /api/auth/login
POST /api/auth/logout
GET /api/auth/oidc/:provider
GET /api/auth/oidc/:provider/callback
GET /api/me
```
### Users
```text
GET /api/users/me
PATCH /api/users/me
GET /api/users/me/identities
DELETE /api/users/me/identities/:id
```
### Wishlists
```text
GET /api/wishlists
POST /api/wishlists
GET /api/wishlists/:id
PATCH /api/wishlists/:id
DELETE /api/wishlists/:id
```
### Items
```text
POST /api/wishlists/:id/items
GET /api/wishlists/:id/items
PATCH /api/items/:id
DELETE /api/items/:id
```
### Public
```text
GET /api/public/wishlists/:slug
POST /api/public/items/:id/reserve
POST /api/public/reservations/:id/join
DELETE /api/public/reservations/:id
```
### Secret Santa
```text
GET /api/secret-santas
POST /api/secret-santas
GET /api/secret-santas/:id
PATCH /api/secret-santas/:id
DELETE /api/secret-santas/:id
POST /api/secret-santas/:id/invitations
POST /api/secret-santas/:id/draw
GET /api/secret-santas/:id/participants
GET /api/secret-santas/:id/assignment
```
### API Documentation
* [ ] OpenAPI specification
* [ ] Swagger UI
* [ ] API versioning
* [ ] Error format
* [ ] Pagination
* [ ] Filtering
* [ ] Sorting
---
# 20. Phase 17 — Authorization
**Цель:** централизованно управлять доступом.
### Roles
```text
USER
ADMIN
```
### Wishlist permissions
```text
wishlist.read
wishlist.write
wishlist.delete
wishlist.share
```
### Reservation permissions
```text
reservation.create
reservation.join
reservation.cancel
```
### Secret Santa permissions
```text
secretsanta.create
secretsanta.manage
secretsanta.invite
secretsanta.draw
secretsanta.participate
secretsanta.view_assignment
```
### Admin
* [ ] User management
* [ ] Auth provider management
* [ ] System settings
* [ ] Health information
* [ ] Audit logs
---
# 21. Phase 18 — Testing
## Backend
* [ ] Unit tests
* [ ] Service tests
* [ ] Repository tests
* [ ] API tests
* [ ] Authentication tests
* [ ] Authorization tests
* [ ] Reservation tests
* [ ] Secret Santa tests
## Database
Каждая бизнес-функция должна проходить тесты минимум на:
* [ ] SQLite
* [ ] PostgreSQL
* [ ] MySQL/MariaDB
## Frontend
* [ ] Component tests
* [ ] API integration tests
* [ ] E2E tests
* [ ] Authentication E2E
* [ ] Wishlist E2E
* [ ] Reservation E2E
* [ ] Secret Santa E2E
## Security
* [ ] Authentication bypass tests
* [ ] Authorization bypass tests
* [ ] CSRF tests
* [ ] Rate limit tests
* [ ] Input validation tests
* [ ] Token security tests
* [ ] Public/private data isolation tests
---
# 22. Phase 19 — Docker & Deployment
### Production Image
* [ ] Multi-stage build
* [ ] Minimal runtime image
* [ ] Non-root user
* [ ] Healthcheck
* [ ] Graceful shutdown
### SQLite
* [ ] Persistent `/data`
* [ ] Database initialization
* [ ] Backup documentation
### PostgreSQL
* [ ] Docker Compose example
* [ ] Persistent volume
* [ ] Healthcheck
* [ ] Automatic migrations
### MySQL/MariaDB
* [ ] Docker Compose example
* [ ] Persistent volume
* [ ] Healthcheck
* [ ] Automatic migrations
### Configuration
```env
APP_ENV=production
APP_PORT=8080
DATABASE_DRIVER=postgres
DATABASE_URL=...
SESSION_SECRET=...
PUBLIC_URL=https://wishlist.example.com
LOG_LEVEL=info
```
---
# 23. Phase 20 — CI/CD
* [ ] Frontend lint
* [ ] Frontend tests
* [ ] Backend lint
* [ ] Backend tests
* [ ] Build backend
* [ ] Build frontend
* [ ] Build Docker image
* [ ] Database integration tests
* [ ] Security scanning
* [ ] Release pipeline
* [ ] Version tags
* [ ] GitHub Releases
---
# 24. Phase 21 — Documentation
### User Documentation
* [ ] Installation
* [ ] Docker installation
* [ ] SQLite configuration
* [ ] PostgreSQL configuration
* [ ] MySQL configuration
* [ ] First launch
* [ ] Creating wishlist
* [ ] Sharing wishlist
* [ ] Reservations
* [ ] Shared reservations
* [ ] Secret Santa
### Administrator Documentation
* [ ] Environment variables
* [ ] OIDC configuration
* [ ] LDAP configuration
* [ ] Reverse proxy
* [ ] HTTPS
* [ ] Backups
* [ ] Restore
* [ ] Database migrations
* [ ] Upgrade procedure
* [ ] Troubleshooting
### Developer Documentation
* [ ] Architecture
* [ ] Domain model
* [ ] Database architecture
* [ ] API
* [ ] Development environment
* [ ] Testing
* [ ] Contribution guide
* [ ] ADRs
---
# 25. Phase 22 — MVP Release
## MVP Definition
MVP считается готовым, если пользователь может:
* [ ] Запустить приложение через Docker
* [ ] Создать аккаунт
* [ ] Войти в систему
* [ ] Создать wishlist
* [ ] Добавить подарок
* [ ] Изменить подарок
* [ ] Удалить подарок
* [ ] Настроить visibility
* [ ] Получить публичную ссылку
* [ ] Открыть wishlist без авторизации
* [ ] Зарезервировать подарок
* [ ] Отменить reservation
* [ ] Запустить приложение с SQLite
* [ ] Запустить приложение с PostgreSQL
* [ ] Использовать приложение на mobile
* [ ] Использовать приложение на desktop
---
# 26. Version Roadmap
## v0.1 — Foundation
* [ ] Project setup
* [ ] Backend
* [ ] Frontend
* [ ] Database abstraction
* [ ] Docker
* [ ] CI
* [ ] Basic architecture
## v0.2 — Authentication
* [ ] Users
* [ ] Local authentication
* [ ] Sessions
* [ ] Security foundation
## v0.3 — Wishlist
* [ ] Wishlist CRUD
* [ ] Items
* [ ] Dashboard
* [ ] Responsive UI
## v0.4 — Public Wishlist
* [ ] Public URLs
* [ ] Sharing
* [ ] Public UI
* [ ] Basic reservations
## v0.5 — Multi-Database
* [ ] SQLite
* [ ] PostgreSQL
* [ ] MySQL/MariaDB
* [ ] Integration test matrix
## v0.6 — External Authentication
* [ ] OIDC
* [ ] LDAP
* [ ] Identity linking
## v0.7 — Shared Reservations
* [ ] Group reservations
* [ ] Participants
* [ ] Amount tracking
* [ ] Privacy
## v0.8 — Secret Santa
* [ ] Events
* [ ] Invitations
* [ ] Participants
* [ ] Drawing
* [ ] Assignments
* [ ] Wishlist integration
## v0.9 — Production Hardening
* [ ] Security audit
* [ ] Performance testing
* [ ] Backup/restore
* [ ] Monitoring
* [ ] Logging
* [ ] Documentation
## v1.0 — First Stable Release
* [ ] Feature freeze
* [ ] Full regression testing
* [ ] Migration testing
* [ ] Docker release
* [ ] Documentation complete
* [ ] Release notes
* [ ] Stable API
* [ ] Production-ready release
---
# 27. Post-v1 Roadmap
## Wishlist
* [ ] Categories
* [ ] Tags
* [ ] Attachments
* [ ] Image upload
* [ ] Automatic product metadata
* [ ] Price tracking
* [ ] Import from Amazon / shops
* [ ] JSON import/export
## Social
* [ ] Shared wishlists
* [ ] Collaborators
* [ ] Comments
* [ ] Reactions
* [ ] Friends
## Secret Santa
* [ ] Email notifications
* [ ] Telegram notifications
* [ ] Anonymous questions
* [ ] Budgets
* [ ] Advanced matching
* [ ] Recurring events
## Platform
* [ ] PWA
* [ ] Offline mode
* [ ] Public API
* [ ] API tokens
* [ ] Webhooks
* [ ] Plugin system
---
# 28. Architecture Principles
Проект должен следовать следующим принципам:
### Database independence
Бизнес-логика не должна зависеть от конкретной СУБД.
```text
Business Logic
Repository Interface
Database Adapter
SQLite / PostgreSQL / MySQL
```
### Authentication independence
Бизнес-логика не должна зависеть от способа аутентификации.
```text
Local ─┐
OIDC ─┼─> Identity ─> User
LDAP ─┘
```
### Privacy by design
Особенно для подарков и Secret Santa:
* владелец wishlist не должен знать, кто зарезервировал подарок;
* участники Secret Santa не должны видеть чужие assignments;
* приватные данные не должны попадать в public API;
* frontend не должен получать данные, которые пользователь не имеет права видеть.
### API-first
Frontend взаимодействует с backend только через API.
```text
React
HTTP API
Go
Domain
Repository
Database
```
### Self-hosted first
Приложение должно оставаться работоспособным без обязательных внешних SaaS-сервисов.
---
# 29. MVP Priority
При разработке использовать приоритеты:
| Priority | Значение |
| -------- | ----------------------- |
| P0 | Обязательно для MVP |
| P1 | Важно для первой версии |
| P2 | После MVP |
| P3 | Nice to have |
### P0
* Authentication
* Users
* Wishlist
* Wishlist Items
* Public Wishlist
* Basic Reservation
* SQLite
* PostgreSQL
* Docker
* Responsive UI
### P1
* OIDC
* LDAP
* MySQL/MariaDB
* Shared Reservation
* OpenAPI
* Backup/Restore
* Dark mode
### P2
* Secret Santa
* Categories
* Tags
* Import/Export
* PWA
* Notifications
### P3
* Integrations
* Price tracking
* Bots
* Plugin system
* Advanced social features
---
# 30. Definition of Done
Feature считается завершённой, если:
* [ ] Реализована backend логика
* [ ] Реализован API
* [ ] Реализован frontend
* [ ] Есть loading state
* [ ] Есть error state
* [ ] Есть empty state, если применимо
* [ ] Проверена responsive верстка
* [ ] Добавлены unit tests
* [ ] Добавлены integration tests, если необходимо
* [ ] Проверены права доступа
* [ ] Проверены privacy requirements
* [ ] Обновлена документация
* [ ] Обновлена OpenAPI спецификация
* [ ] Feature работает в Docker
* [ ] Feature проверена на поддерживаемых БД, если она использует database layer
---
# 31. Current Status
### Foundation
* [ ] Architecture
* [ ] Repository structure
* [ ] CI/CD
* [ ] Docker
### Backend
* [ ] Database layer
* [ ] Authentication
* [ ] Authorization
* [ ] Wishlist
* [ ] Items
* [ ] Reservations
* [ ] Secret Santa
### Frontend
* [ ] Design system
* [ ] Authentication
* [ ] Dashboard
* [ ] Wishlist editor
* [ ] Public wishlist
* [ ] Reservations
* [ ] Secret Santa
### Infrastructure
* [ ] SQLite
* [ ] PostgreSQL
* [ ] MySQL/MariaDB
* [ ] Docker Compose
* [ ] Backups
* [ ] Monitoring
### Documentation
* [ ] User documentation
* [ ] Admin documentation
* [ ] Developer documentation
* [ ] API documentation
---
# 32. Long-term Goal
Создать лёгкий, расширяемый и полностью self-hosted сервис, который можно развернуть одной Docker-командой и использовать как для личных вишлистов, так и для семейных/дружеских мероприятий:
```text
Wishlist
┌────────────┼────────────┐
│ │ │
Wishlist Reservations Secret Santa
│ │ │
│ │ │
Public Shared Events
Private Gifts Matching
│ │ │
└────────────┼────────────┘
Self-hosted
┌─────────┼─────────┐
│ │ │
SQLite PostgreSQL MySQL
```
**Основная цель v1.0:** простой deployment, хороший UX, независимость от инфраструктуры и корректная работа с приватностью подарков.