kodyffy/WishKing
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3efdf8f1e60533cbc369599cb7a3f7f14ebca950
WishKing/README.md
T
Admin 3efdf8f1e6 Road Map
2026-08-18 19:56:41 +03:00

24 KiB
Raw Blame History

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

Пример структуры:

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

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

Sony WH-1000XM6

Target: €600

Ivan       €200
Peter      €150
Anna       €250

Progress: €600 / €600
Status: FULL

Privacy

  • Wishlist owner не видит участников
  • Wishlist owner не видит внесённые суммы
  • Участники видят только необходимую информацию
  • Нельзя раскрыть личность других участников через API

States

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

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

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

GET    /api/users/me
PATCH  /api/users/me
GET    /api/users/me/identities
DELETE /api/users/me/identities/:id

Wishlists

GET    /api/wishlists
POST   /api/wishlists
GET    /api/wishlists/:id
PATCH  /api/wishlists/:id
DELETE /api/wishlists/:id

Items

POST   /api/wishlists/:id/items
GET    /api/wishlists/:id/items
PATCH  /api/items/:id
DELETE /api/items/:id

Public

GET    /api/public/wishlists/:slug
POST   /api/public/items/:id/reserve
POST   /api/public/reservations/:id/join
DELETE /api/public/reservations/:id

Secret Santa

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

USER
ADMIN

Wishlist permissions

wishlist.read
wishlist.write
wishlist.delete
wishlist.share

Reservation permissions

reservation.create
reservation.join
reservation.cancel

Secret Santa permissions

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

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

Бизнес-логика не должна зависеть от конкретной СУБД.

Business Logic
      ↓
Repository Interface
      ↓
Database Adapter
      ↓
SQLite / PostgreSQL / MySQL

Authentication independence

Бизнес-логика не должна зависеть от способа аутентификации.

Local ─┐
OIDC  ─┼─> Identity ─> User
LDAP  ─┘

Privacy by design

Особенно для подарков и Secret Santa:

  • владелец wishlist не должен знать, кто зарезервировал подарок;
  • участники Secret Santa не должны видеть чужие assignments;
  • приватные данные не должны попадать в public API;
  • frontend не должен получать данные, которые пользователь не имеет права видеть.

API-first

Frontend взаимодействует с backend только через API.

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-командой и использовать как для личных вишлистов, так и для семейных/дружеских мероприятий:

                    Wishlist
                       │
          ┌────────────┼────────────┐
          │            │            │
       Wishlist    Reservations   Secret Santa
          │            │            │
          │            │            │
       Public       Shared        Events
       Private      Gifts         Matching
          │            │            │
          └────────────┼────────────┘
                       │
                  Self-hosted
                       │
             ┌─────────┼─────────┐
             │         │         │
           SQLite   PostgreSQL  MySQL

Основная цель v1.0: простой deployment, хороший UX, независимость от инфраструктуры и корректная работа с приватностью подарков.

Reference in New Issue View Git Blame Copy Permalink