25.12.2024 11:45
vladilenm 3 2900 Источник

Привет, Хабр! В этой статье-инструкции вы узнаете, как с нуля сделать свою собственную Telegram-тапалку на современном стеке. Важный дисклеймер: тапалка, кликер и прочее — это всего лишь форма. Цель статьи — дать всеобъемлющий практикум по современному стеку и деплою проектов в облако.

Внутри статьи — полноценный Serverless-подход, разработка бота на Node и полный цикл создания FE-приложения. А еще комментарии по архитектурным и тактическим решениям, чтобы вы прокачали уровень программирования и насмотренности. Подробности под катом!

Зачем изучать


Для начинающих. Вы сможете окунуться в полный цикл разработки приложений, увидеть пошаговое появление и соединение технологий.

Для более опытных (Junior+). В целом, тот же смысл. А также вы сможете изучить Vue, Telegram SDK, Supabase и Ubuntu setup.


Какое приложение получится по итогу статьи.

На выходе у вас получится на 98% production ready приложение и шаблон, который вы можете адаптировать под свою игру, бизнес-приложение или сервис.

Полный технологический стек, который мы будем использовать: Vue 3, Supabase, Firebase Deploy, Pinia, Docker, виртуальные серверы Selectel, Node.js, Telegram Mini Apps, Lodash, Telegraf.

Функционал, который мы создадим: Single Page Application (SPA) для Telegram на Vue 3, реферальная система, выполнение заданий.

С введением закончили — давайте приступать к действию!



Качаем исходный код со стилями


Для начала подготовим шаблон интерфейса тапалки: загрузим стили, создадим главную страницу и настроим отображение текущего счета. Полный код проекта из предыдущего видео расположен в репозитории на GitHub.

Клонируйте из репозитория исходный код со стилями в свою папку, затем выполните две команды в консоли:

​​​​npm install ​​​​
​​​​npm run dev​​​​

Делаем главную страницу и счет


Следующим шагом необходимо создать главную страницу и отображение текущего счета. Для этого понадобится вычислить текущий уровень игры и набранный счет, а также найти формулу по подсчету уровня.

Вычисление уровня: store/score.js


// базовый счет первого уровня
const baseLevelScore = 25

// формула по вычислению уровней и сколько нужно очков для каждого
const levels = new Array(15)
  .fill(0)
  .map((_, i) => baseLevelScore * Math.pow(2, i))

// вычисляем сумму, сколько нужно суммарно очков на каждый уровень
const levelScores = levels.map((_, level) => {
  let sum = 0
  for (let [index, value] of levels.entries()) {
    if (index >= level) {
      return sum + value
    }
    sum += value
  }
  return sum
})

// вычисляем уровень в зависимости от текущего счета
function computeLevelByScore(score) {
  for (let [index, value] of levelScores.entries()) {
    if (score <= value) {
      return {
        level: index,
        value: levels[index],
      }
    }
  }
}


Организация store: store/score.js


export const useScoreStore = defineStore('score', {
  state: () => ({
    score: 0, // базовый уровень, после будем получать по API
  }),
  getters: {
    level(state) {
      return computeLevelByScore(state.score)
    },
    // этот счет нужен для отображения текущего прогресса
    currentScore(state) { 
      if (this.level.level === 0) {
        return state.score
      }
      return state.score - levelScores[this.level.level - 1]
    },
  },
  actions: {
    add(score = 1) {
      this.score += score
    },
    setScore(score) {
      this.score = score
    },
  },
})


Главная страница: HomeView.vue


<template>
  <div class="game-container">
    <ScoreProgress />
    <div class="header">
      <img src="../assets/coin.png" alt="coin" />
      <h2 class="score" id="score">{{ store.score }}</h2>
    </div>
    <div class="circle">
      <img @click="increment" ref="img" id="circle" :src="imgSrc" />
    </div>
  </div>
</template>

<script setup>
import { ref, computed } from 'vue'
import frog from '../assets/frog.png'
import lizzard from '../assets/lizzard.png'
import { useScoreStore } from '@/stores/score'
import ScoreProgress from '@/components/ScoreProgress.vue'

// получаем текущий счет
const store = useScoreStore()

// если счет больше 25 меняем картинку. Первый уровень
const imgSrc = computed(() => (store.score > 25 ? lizzard : frog))
const img = ref(null)

function increment(event) {
  // при клике увеличиваем счет
  store.add(1)

  // дальше логика анимации из прошлого ролика
  // https://youtu.be/vT-XwvcK2NI
  const rect = event.target.getBoundingClientRect()

  const offfsetX = event.clientX - rect.left - rect.width / 2
  const offfsetY = event.clientY - rect.top - rect.height / 2

  const DEG = 40

  const tiltX = (offfsetY / rect.height) * DEG
  const tiltY = (offfsetX / rect.width) * -DEG

  img.value.style.setProperty('--tiltX', `${tiltX}deg`)
  img.value.style.setProperty('--tiltY', `${tiltY}deg`)

  setTimeout(() => {
    img.value.style.setProperty('--tiltX', `0deg`)
    img.value.style.setProperty('--tiltY', `0deg`)
  }, 300)

  const plusOne = document.createElement('div')
  plusOne.classList.add('plus-one')
  plusOne.textContent = '+1'
  plusOne.style.left = `${event.clientX - rect.left}px`
  plusOne.style.top = `${event.clientY - rect.top}px`

  img.value.parentElement.appendChild(plusOne)

  setTimeout(() => plusOne.remove(), 2000)
}
</script>

И добавляем визуальное отображение прогресса в ScoreProgress.vue.

components/ScoreProgress.vue


<template>
  <div class="progress">
    <h4 class="progress-level">
      <span>{{ store.currentScore }}/{{ store.level.value }}</span>
      <span>{{ store.level.level + 1 }}</span>
    </h4>
    <div class="progress-container">
      <div class="progress-value" :style="{ width: progress + '%' }"></div>
    </div>
  </div>
</template>

<script setup>
import { useScoreStore } from '@/stores/score'
import { computed } from 'vue'
  
const store = useScoreStore()

const progress = computed(() => (100 * store.currentScore) / store.level.value)
</script>


Страница задач и друзей-рефералов


Деплоим фронтенд


Прежде зальем приложения на Firebase — в данном случае платформа выступит в роли бесплатного и удобного хостинга для фронтенда.

firebase init
firebase deploy

По итогу получаем url приложения.

Создаем бота на Node.js


Бот нам понадобится для реализации реферальной программы.

1. Получаем API-токен в боте @BotFather через команду ​​​​/newbot​​​​.

2. Далее устанавливаем telegraf и описываем базовую настройку бота в файле bot/app.js:

/bot/app.js
import { Telegraf, Markup } from 'telegraf'

const token = 'YOUR TELEGRAM TOKEN'
const webAppUrl = 'APP REMOTE URL'

const bot = new Telegraf(token)

bot.command('start', (ctx) => {
  ctx.reply(
    'Привет! Нажми, чтоб запустить',
    Markup.inlineKeyboard([
      Markup.button.webApp(
        'Открыть мини-приложение',
        `${webAppUrl}?ref=${ctx.payload}` // Здесь в параметре ref передаем реферала в мини-приложение
      ),
    ])
  )
})

bot.launch()

Для запуска бота используем команду:

node app

Деплой бота на сервер


Сейчас бот запущен на компьютере. Однако если вы хотите, чтобы кликер был доступен круглосуточно, придется поддерживать его бесперебойную работу и непрерывное соединение с интернетом. Оптимальный вариант — перенести бота в облако.

Будем деплоить бота в Docker — для этого добавим два файла:

Dockerfile
FROM node:16-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
ENV PORT=3000
EXPOSE $PORT
CMD ["node", "app.js"]


Makefile
build:
        docker build -t tgbot .
run:
        docker run -d -p 3000:3000 --name tgbot --rm tgbot

Далее зальем весь проект в GitHub-репозиторий, чтобы можно было легко перенести проект на сервер — без использования FTP и scp. Перейдем к следующему этапу.

1. Переходим в раздел Облачная платформа внутри панели управления.


2. Создаем сервер. Для работы нашего приложения не нужно много мощностей, поэтому достаточно одного ядра vCPU с долей 20% и 512 МБ оперативной памяти. И обязательно добавляем публичный IP-адрес, чтобы к серверу можно подключиться через интернет.

3. Авторизуемся на сервере через консоль посредством команды ssh root@. Публичный адрес виртуальной машины можно посмотреть в разделе Порты.


4. После подключения к серверу обновляем систему и устанавливаем Git:

apt update
apt install git

5. Устанавливаем Node.js — полная инструкция доступна в Академии Selectel.

curl -o- <https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh> | bash
source ~/.bashrc 
nvm install 20 
nvm use 20 
npm -v 
node -v

6. Устанавливаем на сервере Docker — для этого тоже можно воспользоваться инструкцией.

7. Клонируем код с нашего предварительно созданного репозитория на GitHub:

apt install git
git clone REPO_URL

8. Запускаем проект:

cd PROJECT_NAME
make build
make run

Готово — бот c Telegram Mini Apps запущен.

Разработка функционала


Разработка функционала тапалки — многоуровневый процесс, который сложно полностью отразить в текстовом формате. Если у вас на каком-то из шагов возникли вопросы, обратитесь к видео на YouTube — там все показано и разбито на таймкоды.

Шаг 1. Подключение базы данных к клиенту


В качестве базы данных будем для хранения пользовательских баллов будем использовать Supabase. Это open source-аналог решения от Google.

Инициализируем проект и создаем две таблицы: User (список пользователей) и Task (список задач).


Создание таблицы User в Supabase.


Создание таблицы Task в Supabase.

На стороне инициализируем дополнительный сервис services/supabase.js:

const SUPABASE_URL = 'https://yodsvoxtwmjearffyxhj.supabase.co'
const SUPABASE_API_KEY = 'SECRET'
import { createClient } from '@supabase/supabase-js'
const supabase = createClient(SUPABASE_URL, SUPABASE_API_KEY)
export default supabase

Шаг 2. Подключение Telegram-библиотеки


Для того, чтобы соединить веб-приложение с функционалом Telegram Mini Apps, подключим библиотеку:

​​​​<script src="https://telegram.org/js/telegram-web-app.js"></script>

Чтобы ей было удобней пользоваться, делаем отдельный хук:

services/telegram.js
export function useTelegram() {
  const tg = window.Telegram.WebApp
  return { tg, user: tg.initDataUnsafe?.user }
}

Шаг 3. Создание API-запросов к базе


Опишем все запросы, которые будет отправлять наше веб приложение для взаимодействия с базой данных.

api/app.js
import supabase from '@/superbase'
import { useTelegram } from '@/telegram'
import { useScoreStore } from '../stores/score'

const { user } = useTelegram()

const MY_ID = user?.id ?? 'YOUR DEV ID' // Для разработки. В вебе нет user.id — он появляется только тогда, когда приложение запущено в рамках Telegram

// Авторизация пользователя
export async function getOrCreateUser() {
  const potentialUser = await supabase
    .from('users')
    .select()
    .eq('telegram', MY_ID)

  // Проверяем, существует ли уже текущий пользователь
  if (potentialUser.data.length !== 0) {
    return potentialUser.data[0]
  }
  
  // Если нет, то создаем нового
  const newUser = {
    telegram: MY_ID,
    friends: {},
    tasks: {},
    score: 0,
  }

  await supabase.from('users').insert(newUser)
  return newUser
}

// Добавляем обновление счета у текущего пользователя
export async function updateScore(score) {
  await supabase.from('users').update({ score }).eq('telegram', MY_ID)
}

// Завершаем задачу и начисляем бонусные баллы за ее выполнение
export async function completeTask(user, task) {
  await supabase
    .from('users')
    .update({ tasks: { ...user.tasks, [task.id]: true } })
    .eq('telegram', MY_ID)

  const score = useScoreStore()
  const newScore = score.score + task.amount
  await updateScore(newScore)
  score.setScore(newScore)
}

// Регистрируем реферала
export async function registerRef(userName, refId) {
// Получаем данные пользователя, который поделился своей реферальной ссылкой
const { data } = await supabase.from('users').select().eq('telegram', refId)

  const refUser = data[0]

  // Добавляем нас в список его рефералов, а также начисляем баллы
  await supabase
    .from('users')
    .update({
      friends: { ...refUser.friends, [MY_ID]: userName },
      score: refUser.score + 50,
    })
    .eq('telegram', refId)
}

// Получаем список всех задач (он статический)
export async function getTasks() {
  const { data } = await supabase.from('tasks').select('*')

  return data
}


Шаг 4. Создание store для приложения


Создаем еще одно хранилище данных для пользователя и задач, чтобы было удобнее с ними работать и можно было вынести логику в Pinia из самих компонентов.

stores/app.js
import { defineStore } from 'pinia'
import {
  getOrCreateUser,
  completeTask,
  registerRef,
  getTasks,
} from '@/api/app'
import { useScoreStore } from './score'
import { useTelegram } from '@/services/telegram'

const { user } = useTelegram()

export const useAppStore = defineStore('app', {
  state: () => ({
    user: {}, // настройки по умолчанию
    tasks: [],
  }),
  actions: {
    // С этого метода начинается авторизация и идентификация пользователя
    async init(ref) {
      // Получаем существующего пользователя либо создаем нового
      this.user = await getOrCreateUser()

      const score = useScoreStore()
      // Задаем данные, которые были в базе у этого пользователя
      score.setScore(this.user.score)

      // проверяем, является ли он рефералом
      if (ref && +ref !== +this.user.telegram) {
        await registerRef(user.first_name, ref)
      }
    },
    // Выполнение задачи
    async completeTask(task) {
      await completeTask(this.user, task)
    },
    // Получаем список всех задач
    async fetchTasks() {
      this.tasks = await getTasks()
    },
  },
})


Шаг 5. Запуск приложения


Добавим код который будет инициализировать приложение и разворачивать его на весь экран, считывать параметры реферала (если новый пользователь его имеет) и загружать данные о текущем пользователе и его счете.

<template>
  <main class="game" v-if="loaded">
    <div class="page">
      <RouterView />
    </div>
    <TheMenu />
  </main>
</template>

<script setup>
import { onMounted, ref } from 'vue'
import { RouterView } from 'vue-router'
import TheMenu from './components/TheMenu.vue'
import { useAppStore } from './stores/app'
import { useTelegram } from './telegram'

const { tg } = useTelegram()

const app = useAppStore()
const loaded = ref(false)

// Получаем данные, которые нам прокинул бот по рефералам
const urlParams = new URLSearchParams(window.location.search)

// Передаем рефку в инициализацию и получаем данные пользователя
app.init(urlParams.get('ref')).then(() => {
  loaded.value = true
})

onMounted(() => {
  // Сигнализируем о том, что приложение готово
  tg.ready()
  // Разворачиваем на весь экран
  tg.expand()
})
</script>


Шаг 6. Сохранение счета в базе


Реализуем функционал, который соединит локальное изменение счета с данными в базе данных.

Для защиты от спама добавим debounce, чтоб не заспамить базу запросами. Задержку в 500 мс. Если на каждый клик отправлять запрос, это не будет эффективным решением.

npm i lodash.debounce



@/store/score
import { defineStore } from 'pinia'
import debounce from 'lodash.debounce'
import { updateScore } from '@/api/app'

const debouncedSave = debounce(updateScore, 500)

// ======= 

export const useScoreStore = defineStore('score', {
  actions: {
    add(score = 1) {
      this.score += score
      debouncedSave(this.score)
    },
    setScore(score) {
      this.score = score
    },
  },
})


Шаг 7. Создание страницы друзей


Добавим страницу друзей, на которой будем загружать список пользователей, присоединенных по реферальной ссылке текущего. Также на этой странице можно будет скопировать свою реферальную ссылку.

views/FriendView.vue
<template>
  <div class="text-content">
    <h1>Your Friends</h1>

    <div class="center">
      <button class="referal" @click="copy">{{ referalText }}</button>
    </div>

    <h3 v-if="friends.length === 0">No friends yet</h3>

    <ul class="list">
      <li class="list-item" v-for="friend in friends" :key="friend.id">
        {{ friend.name }}
        <span class="list-btn done"> 50 </span>
      </li>
    </ul>
  </div>
</template>

<script setup>
import { useTelegram } from '@/telegram'
import { useAppStore } from '@/stores/app'
import { ref, computed } from 'vue'

const { user } = useTelegram()
const app = useAppStore()

// Удобный формат для вывода в шаблон (объект -> массив)
const friends = computed(() => Object.keys(app.user.friends).map((id) => ({
  id,
  name: app.user.friends[id],
})))

const referalText = ref('Your referal')

// Копируем в буфер и меняем текст
function copy() {
  navigator.clipboard.writeText(
    'https://t.me/YOUR_BOT_NAME_IN_TELEGRAM?start=' + user?.id
  )
  referalText.value = 'Copied!'
}
</script>


Страница друзей, результат.

Шаг 8. Создание страницы задач


Добавим страницу задач, на которой будем подгружать список выполненных пользователем заданий и количество полученных очков, а также еще невыполненные задачи.

views/TasksView.vue
<template>
  <div class="text-content">
    <h1>Your tasks</h1>
    <p v-if="app.tasks.length === 0">Loading tasks...</p>
    <ul class="list">
      <li class="list-item" v-for="task in app.tasks" :key="task.id">
        {{ task.title }}

        <span>
          <a
            @click.prevent="openTask(task)"
            target="_blank"
            class="list-btn"
            :class="{ done: app.user?.tasks?.[task.id] }"
          >
            {{ task.done ? 'Done' : task.amount }}
          </a>
        </span>
      </li>
    </ul>
  </div>
</template>

<script setup>
import { useTelegram } from '@/telegram'
import { onMounted } from 'vue'
import { useAppStore } from '@/stores/app'

const app = useAppStore()
const { tg } = useTelegram()

onMounted(() => {
  // Если компонент готов, загружаем его с сервера
  app.fetchTasks()
})

function openTask(task) {
  // Запускаем цикл выполнения задачи
  app.completeTask(task)
  if (task.url.includes('t.me')) {
    // Открываем как внутреннюю ссылку
    tg.openTelegramLink(task.url)
  } else {
    // И как внешнюю
    tg.openLink(task.url)
  }
}
</script>


Страница задач, результат.

Заключение


Готово! У нас есть запущенный фронтенд, Telegram-бот и сама игра. Теперь вы можете использовать шаблон этого приложения для реализации собственных проектов.

Комментарии (3)