# 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, независимость от инфраструктуры и корректная работа с приватностью подарков.