Модел на лицензиране

Този документ описва модела на лицензиране на Dictaro — планове, квоти, лицензни ключове, ограничения по устройства и BYOK модел.

Типове планове

Конфигурационни параметри

Всички параметри се зареждат от environment variables с defaults:

Параметър	Env Variable	Default	Описание
Квота минути	QUOTA_MINUTES	10	Минути диктовка на цикъл (free план)
Cooldown часове	COOLDOWN_HOURS	5	Часове cooldown след изчерпване на квотата
Trial дни	TRIAL_DAYS	7	Продължителност на пробния период
Typing ratio	TYPING_RATIO	4.0	Множител за спестено време от въвеждане
Device accounts max	DEVICE_ACCOUNTS_MAX	2	Макс. акаунти на устройство в cooldown прозореца
JWT expiry	JWT_EXPIRY_DAYS	7	Валидност на JWT token в дни
Dev default plan	DEV_DEFAULT_PLAN	""	План по подразбиране за нови потребители (dev only)

Конфигурация в код (config/config.go):

QuotaMinutes:      getEnvInt("QUOTA_MINUTES", 10),
CooldownHours:     getEnvInt("COOLDOWN_HOURS", 5),
TrialDays:         getEnvInt("TRIAL_DAYS", 7),
TypingRatio:       getEnvFloat("TYPING_RATIO", 4.0),
DeviceAccountsMax: getEnvInt("DEVICE_ACCOUNTS_MAX", 2),

Free план — система на квоти

Статуси на квотата

QuotaStatus API response

Поле	Тип	Описание
status	string	"active" / "cooldown" / "unlimited" / "trial"
used_seconds	float64	Използвани секунди в текущия цикъл
quota_seconds	float64	Общо секунди квота (600 = 10 мин)
remaining_seconds	float64	Оставащи секунди (0 при cooldown)
cooldown_until	string?	ISO 8601 дата/час на край на cooldown
trial_ends_at	string?	ISO 8601 дата/час на край на trial
total_dictation_seconds	float64	Общо секунди диктовка (lifetime)
total_typing_saved_seconds	float64	Спестено време (dictation * TYPING_RATIO)

Алгоритъм за изчисляване на квота

Rolling quota механизъм (walkCycles)

Алгоритъмът walkCycles обхожда хронологично всички usage записи:

Закръгляване на cooldown (roundUpToHour):

• Cooldown краят се закръглява нагоре до следващия цял час
• Пример: ако cooldown изтича в 14:23 → закръглява се до 15:00
• Осигурява предсказуемост за потребителя

Trial план

Характеристики на trial:

• Стартира автоматично при първото записване на usage (не при регистрация)
• Продължителност: TRIAL_DAYS=7 дни
• Неограничен достъп — без квота, без cooldown
• Не изисква кредитна карта
• След изтичане → автоматичен преход към free план с квота

Pro план

Активация чрез Stripe

Описано подробно в Жизнен цикъл на абонамент.

Резултат: UPDATE users SET plan='pro', stripe_subscription_id=?

Активация чрез License Key

Характеристики на лицензни ключове:

• Формат: 32-символен ключ
• Device-bound: Свързва се с конкретен device_id при активация
• Еднократна активация: Един ключ = един потребител
• Без subscription: Не минава през Stripe
• Употреба: Reseller ключове, lifetime лицензи, промоционални активации
• Account status: Последните 4 символа на ключа се показват в GET /account/status

Модел на данните (license_keys таблица):

Поле	Тип	Описание
id	UUID	Уникален идентификатор
key	string	32-символен лицензен ключ
user_id	UUID?	Потребител, активирал ключа
device_id	string?	Устройство на активация
activated_at	timestamp?	Дата на активация
is_active	bool	Дали ключът е активен
created_at	timestamp	Дата на създаване

Ограничения по устройства

Device Account Limiting

Цел: Предотвратяване на злоупотреба с free план чрез създаване на множество акаунти на едно устройство.

Параметри:

• DEVICE_ACCOUNTS_MAX=2 — максимум 2 различни акаунта на устройство
• Прозорец: COOLDOWN_HOURS=5 часа (споделен с usage cooldown)
• retry_at = най-ранният запис в прозореца + cooldown часове

Изключения:

• Pro потребители не са ограничени — device limit се прилага само за plan == "free"
• Съществуващи (device_id, user_id) комбинации винаги са позволени

Таблица device_accounts:

Поле	Тип	Описание
device_id	string	Уникален ID на устройството
user_id	UUID	ID на потребителя
created_at	timestamp	Дата на първия login от тази комбинация

BYOK модел (Bring Your Own Key)

Принцип: Dictaro не предоставя и не таксува за AI функционалност. Потребителят въвежда свой собствен API ключ за OpenAI или Claude.

AI функции (Pro plan):

• Text cleanup — почистване и подобряване на диктувания текст
• Professional tone — формализиране на тон
• Reformulation — преструктуриране на изречения
• Grammar correction — граматична корекция

Предимства на BYOK:

• Без допълнителни разходи за Dictaro за AI infrastructure
• Потребителят контролира разходите си
• Гъвкавост при избор на модел
• API ключът остава локално в приложението

JWT Token

JWT токенът е основният носител на информация за лицензиране в клиентското приложение.

Обновяване на JWT:

• При login: нов JWT с текущ план
• При refresh (POST /auth/refresh): нов JWT от съществуващ
• При checkout success: нов JWT с plan='pro'
• Sync от Stripe: при login се извиква SyncStripeSubscription преди издаване на JWT

Валидност: JWT_EXPIRY_DAYS=7 дни (default)

Преглед на преходите между планове

Публична статистика

Endpoint GET /usage/public-stats връща агрегирана статистика:

Поле	Описание
total_users	Общ брой регистрирани потребители
total_dictation_hours	Общо часове диктовка (от stats_aggregate)
total_typing_saved_hours	Спестени часове (dictation * TYPING_RATIO)
total_dictation_count	Общ брой диктовки

Тези данни се показват на уебсайта и се обновяват при всяко записване на usage чрез upsert в stats_aggregate таблицата.