🔒 Конфиденциальный документСерле документ

📋 СодержаниеЭчтәлек

Обзор системыСистема күзәтүе
Кабинет владельца — аналитикаХуҗа кабинеты — аналитика
Управление пользователямиКулланучылар белән идарә итү
Начисление и списание балловБалларны исәпләү һәм чыгару
Антифрод-системаАнтифрод системасы
Отчёты через Telegram-ботTelegram-бот аша хисаплар
Горячие предложения (акции)Кайнар тәкъдимнәр (акцияләр)
Техническая архитектураТехник архитектура
API документацияAPI документациясе

1. Обзор системыСистема күзәтүе

ИРИС — программа лояльности для магазинов ИРИС (с. Салаусь) и Лайсан (с. Бурбаш). Одна система, два магазина, единый баланс для покупателей.ИРИС — ИРИС (Салаусь авылы) һәм Лайсан (Бурбаш авылы) кибетләре өчен тугрылык программасы. Бер система, ике кибет, сатып алучылар өчен уртак баланс.

МагазиныКибетләр

УровниДәрәҗәләр

Макс. кэшбэкМакс. кэшбэк

Макс. списаниеМакс. чыгару

50%

Компоненты системыСистема компонентлары

СайтСайт — iris-shop.ru (PWA, работает как приложение)iris-shop.ru (PWA, кушымта кебек эшли)
Telegram-ботTelegram-бот — @iris_laysan_shop_bot
Android APKAndroid APK — скачивание с сайтасайттан йөкләп алу
Кабинет владельцаХуҗа кабинеты — iris-shop.ru/owner
Инструкции сотрудниковХезмәткәрләр кулланмалары — iris-shop.ru/staff
API — iris-shop.ru/api/docs (OpenAPI/Swagger)

2. Кабинет владельцаХуҗа кабинеты

Панель аналитики — обзор KPIАналитика панеле — KPI күзәтүе

Доступ:Керү: iris-shop.ru/owner (требуется роль admin)(admin роле кирәк)

2.1. Панель «Обзор»«Күзәтү» панеле

KPI-метрикиKPI-метрикалар

ВыручкаКерем — общая сумма транзакций за периодчор эчендә операцияләрнең гомуми суммасы
ТранзакцииОперацияләр — количество и средний чексаны һәм уртача чек
Кэшбэк начисленКэшбэк исәпләнде — сумма начисленных бонусовисәпләнгән бонусларның суммасы
Кэшбэк списанКэшбэк чыгарылды — сумма использованных бонусовкулланылган бонусларның суммасы
ПользователиКулланучылар — всего / активных / новых за периодбарлыгы / актив / чор эчендә яңалар

2.2. Панель «Графики»«Графиклар» панеле

Выручка и транзакцииКерем һәм операцияләр — комбинированный график (столбцы + линия) по днямкөннәр буенча кушма график (баганалар + сызык)
Новые пользователиЯңа кулланучылар — рост аудитории по днямкөннәр буенча аудиториянең үсеше
Фильтр по периоду: 7 / 30 / 90 / 365 днейЧор буенча фильтр: 7 / 30 / 90 / 365 көн

2.3. Быстрые действияТиз гамәлләр

➕ Начислить баллыБаллар исәпләү — ввести адрес электронной почты и суммуэлектрон почта адресын һәм сумманы кертү
➖ Списать баллыБаллар чыгару — ввести адрес электронной почты и суммуэлектрон почта адресын һәм сумманы кертү
📤 Экспорт CSVCSV экспорты — выгрузка всех транзакцийбарлык операцияләрне йөкләп чыгару

3. Управление пользователямиКулланучылар белән идарә итү

Таблица пользователейКулланучылар таблицасы

Панель «👥 Пользователи» показывает:«👥 Кулланучылар» панеле күрсәтә:

Имя, email, роль (customer / manager / admin)Исем, email, роль (customer / manager / admin)
Текущий уровень (Дерево → Золото)Хәзерге дәрәҗә (Агач → Алтын)
Баланс бонусовБонуслар балансы
Общая сумма покупокСатып алуларның гомуми суммасы
Поиск по адресу электронной почты или имениЭлектрон почта адресы яки исем буенча эзләү

3.1. Роли пользователейКулланучылар рольләре

РольРоль	ОписаниеТасвирлама	ВозможностиМөмкинлекләр
customer	ПокупательСатып алучы	QR, баланс, история, списаниеQR, баланс, тарих, чыгару
manager	Кассир / ПродавецКассир / Сатучы	Сканирование, начисление, списание (2FA)Сканерлау, исәпләү, чыгару (2FA)
admin	РуководительҖитәкче	Всё + аналитика, управление пользователями, экспортБарысы + аналитика, кулланучылар белән идарә итү, экспорт

⚠️ Назначение ролейРольләрне билгеләү Роль manager назначается через кабинет владельца. Назначайте её только проверенным сотрудникам.manager роле хуҗа кабинеты аша билгеләнә. Аны бары тик ышанычлы хезмәткәрләргә генә билгеләгез.

4. Начисление и списание балловБалларны исәпләү һәм чыгару

4.1. Уровни и ставкиДәрәҗәләр һәм ставкалар

УровеньДәрәҗә	КэшбэкКэшбэк	Макс. списаниеМакс. чыгару	ПорогБусага
Лайсан (Бурбаш):Лайсан (Бурбаш):
🥉 БронзаБронза	1%	20%	0 — 14 999 ₽
🥈 СереброКөмеш	2%	30%	15 000 — 44 999 ₽
🥇 ЗолотоАлтын	3%	50%	от 45 000 ₽45 000 ₽ дан
ИРИС (Салаусь):ИРИС (Салаусь):
🥉 БронзаБронза	2%	20%	0 — 34 999 ₽
🥈 СереброКөмеш	3%	30%	35 000 — 59 999 ₽
🥇 ЗолотоАлтын	4%	50%	от 60 000 ₽60 000 ₽ дан

4.2. Категории и множителиКатегорияләр һәм тапкырлагычлар

КатегорияКатегория	МножительТапкырлагыч	ПримерыМисаллар
🍞 ЕДААЗЫК	×1.0	Продовольственные товарыАзык-төлек товарлары
🧹 ХОЗТОВАРЫХУҖАЛЫК ТОВАРЛАРЫ	×1.5	Непродовольственные хоз. товарыАзык-төлек булмаган хуҗалык товарлары
🧴 БЫТХИМКӨНКҮРЕШ ХИМИЯСЕ	×1.2	Бытовая химияКөнкүреш химиясе

4.3. Пороговые скидкиБусага ташламалары

СуммаСумма	СкидкаТашлама	Пример экономииЯнга калу мисалы
от 3 000 ₽3 000 ₽ дан	3%	−90 ₽
от 5 000 ₽5 000 ₽ дан	5%	−250 ₽
от 10 000 ₽10 000 ₽ дан	7%	−700 ₽

📐 ФормулаФормула Скидка → кэшбэк на остаток → автообновление уровня.
Бонусы = (Сумма − Скидка) × Ставка_уровня × Множитель_категорииТашлама → калдыкка кэшбэк → дәрәҗәне автомат яңарту.
Бонуслар = (Сумма − Ташлама) × Дәрәҗә_ставкасы × Категория_тапкырлагычы

5. Антифрод-системаАнтифрод системасы

ПравилоКагыйдә	ОписаниеТасвирлама
⏰ Кулдаун 24ч24 сәгать кулдаун	Не более 1 транзакции на клиента в 24 часа24 сәгатькә бер клиентка 1 операциядән артык түгел
🔢 Круглые суммыТүгәрәк суммалар	Суммы кратные 500₽ — повышенный контроль500 ₽ га кабатлы суммалар — көчәйтелгән контроль
👤 Привязка к кассируКассирга бәйләү	Система отслеживает частоту операций кассираСистема кассир операцияләренең ешлыгын күзәтә
✅ 2FA списание2FA чыгару	Списание только с подтверждением клиентаЧыгару бары тик клиент раславы белән генә
🔐 QR TTLQR TTL	QR действует 120 секунд — нельзя переиспользоватьQR 120 секунд эшли — кабат кулланып булмый
🛡️ Rate limitingRate limiting	Ограничение частоты запросов к APIAPI га сорауларның ешлыгын чикләү

🚨 При подозрении на мошенничествоАлдау шиге булганда Если кассир начисляет бонусы без покупок или подозрительно часто — система пришлёт алерт в Telegram. Панель «🛡️ Фрод-монитор» в кабинете показывает все подозрительные события.Әгәр кассир сатып алуларсыз яки шикле еш бонуслар исәпләсә — система Telegram га хәбәр җибәрә. Кабинеттагы «🛡️ Фрод-монитор» панеле барлык шикле вакыйгаларны күрсәтә.

6. Отчёты через Telegram-ботTelegram-бот аша хисаплар

Команды администратораАдминистратор командалары

Напишите боту @iris_laysan_shop_bot:@iris_laysan_shop_bot ботына языгыз:

/report — статистика за период (транзакции, суммы, новые клиенты)чор статистикасы (операцияләр, суммалар, яңа клиентлар)
/broadcast ТекстТекст — рассылка всем пользователямбарлык кулланучыларга таратма

💡 Автоматические уведомленияАвтоматик хәбәрләр Бот автоматически отправляет владельцу:Бот хуҗага автоматик рәвештә җибәрә:

Ежедневный отчёт по продажамСатулар буенча көндәлек хисап
Предупреждения антифрод-системыАнтифрод системасының кисәтүләре
Уведомления о крупных списанияхЭре чыгарулар турында хәбәрләр

7. Горячие предложенияКайнар тәкъдимнәр

Примеры акцийАкция мисаллары

Двойной кэшбэк на хозтоварыХуҗалык товарларына икеләтә кэшбэк — множитель ×2 на категорию ХОЗТОВАРЫХУҖАЛЫК ТОВАРЛАРЫ категориясенә ×2 тапкырлагыч
Бонус новичкаЯңа кешегә бонус — 50 бонусов за первую покупкуберенче сатып алу өчен 50 бонус
Горячий часКайнар сәгать — повышенный кэшбэк с 10:00 до 12:0010:00 дән 12:00 гә кадәр арттырылган кэшбэк
СуперначислениеСупер исәпләү — до 70% кэшбэк на выбранные товарысайланган товарларга 70% ка кадәр кэшбэк
100% баллами100% баллар белән — оплата спец. товаров балламимахсус товарларны баллар белән түләү

Создание акции через APIAPI аша акция булдыру

POST /api/offers/ с телом:түбәндәге тән белән:

{
  "title": "Двойной кэшбэк на хозтовары",
  "description": "×2 кэшбэк на все хозтовары",
  "multiplier": 2.0,
  "category": "household",
  "active": true,
  "expires_at": "2026-05-01T23:59:59"
}

8. Техническая архитектураТехник архитектура

КомпонентКомпонент	ТехнологияТехнология	РазмещениеУрнаштыру
Бэкенд APIБэкенд API	FastAPI + SQLAlchemy (асинхронный)FastAPI + SQLAlchemy (асинхрон)	K3s, 2 репликиK3s, 2 реплика
Telegram-ботTelegram-бот	aiogram 3	K3s, 1 репликаK3s, 1 реплика
База данныхМәгълүматлар базасы	PostgreSQL 16	K3s, постоянный томK3s, даими том
КэшКэш	Redis 7	K3s, постоянный томK3s, даими том
АвторизацияАвторизация	Keycloak (OIDC)	K3s
ФронтендФронтенд	PWA (чистый JavaScript)PWA (саф JavaScript)	Nginx
Обратный проксиКире прокси	Traefik + Let's Encrypt	K3s
Резервные копииРезерв күчермәләре	Дамп PostgreSQL по расписаниюРасписание буенча PostgreSQL дампы	Каждые 6 чҺәр 6 сәгать саен

9. API документацияAPI документациясе

Основные эндпоинтыТөп эндпоинтлар

GET /api/health — проверка работоспособностиэшкә сәләтлелекне тикшерү
GET /api/loyalty/levels — текущие уровнихәзерге дәрәҗәләр
GET /api/loyalty/categories — категориикатегорияләр
GET /api/offers/ — активные акцииактив акцияләр
POST /api/offers/ — создать акциюакция булдыру
GET /api/admin/stats — статистикастатистика
GET /api/admin/stats/daily — статистика по днямкөннәр буенча статистика
GET /api/admin/users — список пользователейкулланучылар исемлеге
POST /api/admin/accrue — начислить баллыбаллар исәпләү
POST /api/admin/deduct — списать баллыбаллар чыгару
POST /api/admin/broadcast — рассылкатаратма
GET /api/admin/export/csv — экспорт данныхмәгълүматлар экспорты

📚 Интерактивная документация APIИнтерактив API документациясе Полная интерактивная документация (Swagger UI):Тулы интерактив документация (Swagger UI): iris-shop.ru/api/docs

📞 Техническая поддержкаТехник ярдәм

Администратор системы:Система администраторы: ИП Мукминов Р.Р.ЭП Мукминов Р.Р.

Электронная почта:Электрон почта: admin@iris-shop.ru

Бот:Бот: @iris_laysan_shop_bot

Сайт оператора:Оператор сайты: run-as-daemon.ru