Сервис заявок для Telegram Mini App

Important

ПРАВИЛА ДЛЯ РАЗРАБОТЧИКОВ:

1. Вся документация по данному приложению ведется исключительно на русском языке.
2. Комментарии в коде должны быть подробными и на русском языке.
3. Любые изменения или дополнения функционала должны обязательно отражаться как в текстовой документации (README.md, FEATURES.md), так и в графических блок-схемах (docs/DIAGRAMS.md).
4. Соблюдение структуры и профессионального уровня документации является обязательным.

Система управления заявками сотрудников с интеграцией Telegram Mini App для 5000+ пользователей.

🚀 Возможности

7 блоков форм

1. МТО (Материально-техническое обеспечение)

   • Заказа спецодежды и формы
   • Получение документов, удостоверений и бейджей

2. Лицензирование

   • Лицензии охранника и разрешения на оружие
   • Медицинские книжки и допуски

3. Финансы

   • Вопросы по зарплате (удержания/начисления)
   • Получение справок (2-НДФЛ, для банка и т.д.)

4. Кадры (HR)

   • Кадровые вопросы (отпуска, переводы)
   • Бытовые условия (общежитие, питание, транспорт)

5. Подработки

   • Заявка на конкретную смену (доска заказов)
   • Общая заявка (готовность подрабатывать)

6. Анонимные сообщения

   • Сообщения о нарушениях, коррупции, безопасности
   • Полная конфиденциальность

7. График

   • Обмен сменами
   • Управление рабочим временем

Ключевые функции

• ✅ Умное автозаполнение - ФИО, табельный номер, объект и телефон подтягиваются из профиля
• ✅ Свободный ввод - Текстовые поля для комментариев на каждом этапе
• ✅ Вложение файлов - Загрузка фото, видео, аудио и документов (до 5 файлов по 5 МБ)
• ✅ Статусы заявок - Принято, В работе, Решено, Связаться
• ✅ Приоритет по телефону - Кнопка "Связаться" для срочных вопросов
• ✅ Валидация форм - Проверка обязательных полей
• ✅ Отзывчивый дизайн - Оптимизация для мобильных устройств

📁 Структура проекта

src/
├── app/
│   ├── api/
│   │   └── requests/
│   │       ├── route.ts           # CRUD операций с заявками
│   │       └── [id]/route.ts    # Операции с конкретной заявкой
│   └── page.tsx                 # Главная страница Mini App
├── components/
│   ├── forms/
│   │   ├── RequestForm.tsx       # Универсальный компонент формы
│   │   ├── MTOForms.tsx          # Формы блока МТО
│   │   ├── LicensingFinanceForms.tsx  # Формы лицензирования и финансов
│   │   ├── HRGigAnonymousForms.tsx   # Формы HR, подработок и анонимных сообщений
│   │   └── ScheduleForms.tsx     # Формы графика
│   └── ui/                      # shadcn/ui компоненты
├── lib/
│   └── db.ts                    # Prisma клиент
└── prisma/
    └── schema.prisma             # Схема базы данных

🛠️ Технологии

• Frontend: Next.js 16, React 18, TypeScript 5
• UI Library: shadcn/ui с Lucide icons
• Styling: Tailwind CSS 4
• Database: Prisma ORM + SQLite (можно переключить на PostgreSQL/MySQL)
• API: Next.js API Routes

📦 Установка и запуск

1. Установить зависимости

bun install

2. Настроить базу данных

bun run db:push

3. Запустить сервер разработки

bun run dev

Приложение будет доступно по адресу http://localhost:3000

🔌 API Endpoints

Заявки

GET /api/requests

Получить заявки пользователя

Query параметры:

• userId - ID пользователя (опционально)
• telegramId - Telegram ID пользователя (опционально)

Ответ:

{
  "requests": [
    {
      "id": "string",
      "block": "string",
      "category": "string",
      "status": "pending | in_progress | resolved | priority",
      "title": "string",
      "description": "string",
      "fullName": "string",
      "personnelNumber": "string",
      "currentObject": "string",
      "phone": "string",
      "formData": "string (JSON)",
      "response": "string",
      "responseLink": "string",
      "respondedAt": "string (ISO 8601)",
      "createdAt": "string (ISO 8601)",
      "updatedAt": "string (ISO 8601)",
      "attachments": [...]
    }
  ]
}

POST /api/requests

Создать новую заявку

Тело запроса:

{
  "block": "MTO | LICENSING | FINANCE | HR | GIG | ANONYMOUS | SCHEDULE",
  "category": "string",
  "title": "string",
  "description": "string",
  "formData": {},
  "attachments": [
    {
      "file": File,
      "preview": "string"
    }
  ],
  "telegramId": "string",
  "fullName": "string",
  "personnelNumber": "string",
  "currentObject": "string",
  "phone": "string"
}

Ответ:

{
  "requestId": "string",
  "request": {...},
  "message": "string"
}

PATCH /api/requests/[id]

Обновить заявку

Тело запроса:

{
  "status": "pending | in_progress | resolved | priority",
  "response": "string",
  "responseLink": "string",
  "userId": "string",
  "telegramId": "string"
}

GET /api/requests/[id]

Получить заявку по ID

Ответ:

{
  "request": {
    ...,
    "user": {
      "id": "string",
      "name": "string",
      "personnelNumber": "string",
      "phone": "string"
    }
  }
}

📊 База данных

User

• id - Уникальный ID
• telegramId - Telegram ID (уникальный)
• email - Email (уникальный)
• name - ФИО
• personnelNumber - Табельный номер (уникальный)
• phone - Телефон
• currentObject - Текущий объект
• position - Должность
• district - Район города
• isAnonymous - Признак анонимного пользователя

Request

• id - Уникальный ID
• userId - ID пользователя (опционально для анонимных заявок)
• anonymousId - ID для анонимных заявок
• block - Блок заявки
• category - Категория
• status - Статус
• title - Заголовок
• description - Описание
• formData - Данные формы (JSON)
• response - Ответ менеджера
• responseLink - Ссылка на документ
• Автозаполняемые поля: fullName, personnelNumber, currentObject, phone

RequestAttachment

• id - Уникальный ID
• requestId - ID заявки
• fileName - Имя файла
• fileUrl - URL файла
• fileType - Тип файла
• fileSize - Размер в байтах

GigApplication

• Заявки на подработки
• type - specific (конкретная смена) или general (общая заявка)
• Поля для конкретных смен: gigObjectId, gigObjectName
• Поля для общих заявок: availability, district

ShiftExchange

• Обмен сменами
• shiftDateTime - Дата/время смены
• reason - Причина
• status - Статус
• foundReplacement - ID замены

🎨 UI Компоненты

RequestForm

Универсальный компонент для всех форм с поддержкой:

• Выпадающих списков (select)
• Текстовых полей (text, number, textarea)
• Даты (date)
• Загрузки файлов (file)
• Условного отображения полей
• Автозаполнения данных профиля

Дизайн

• Адаптивный для мобильных устройств
• Темная тема
• Стилизованные с помощью Tailwind CSS
• Иконки от Lucide

🔒 Безопасность

• Валидация данных на клиенте и сервере
• Проверка прав доступа при обновлении заявок
• Анонимные сообщения не связываются с пользователем
• Загрузка файлов с ограничением размера и типа

🚧 TODO (В разработке)

• WebSocket сервис для реального времени
• Загрузка файлов в облачное хранилище
• Admin-панель для обработки заявок
• Интеграция Telegram Mini Apps SDK
• Push-уведомления
• Фильтрация и поиск заявок
• Экспорт заявок в Excel/PDF

📝 Интеграция с Telegram

Для полноценной работы с Telegram Mini App:

1. Установите Telegram Web App SDK:

bun install @telegram-apps/sdk

2. Инициализируйте приложение:

import WebApp from "@telegram-apps/sdk";

const webApp = WebApp();
webApp.ready();

3. Получите данные пользователя:

const initData = webApp.initDataUnsafe;
const telegramId = initData.user?.id;

4. Используйте хедер Telegram для навигации и цветов

📄 Лицензия

MIT

👥 Поддержка

Для вопросов и предложений создайте issue в репозитории проекта.