Go to file
romanskijdev 9e41c9edd7 Added daily reminder 2026-07-13 10:25:13 +03:00
.gitea/workflows temp disabled balancer deployment 2026-06-18 10:50:33 +03:00
core Updated approval revocation. Needed to approve now 2026-07-13 09:29:51 +03:00
service Added daily reminder 2026-07-13 10:25:13 +03:00
.gitignore Added config injecting to deploy action 2026-05-05 10:19:44 +03:00
.golangci.yml Add project files 2026-04-22 16:28:01 +03:00
README.md Test: deploy workflow 2026-06-17 13:58:16 +03:00
build_core.sh Add project files 2026-04-22 16:28:01 +03:00
deploy.sh updated service generation type for system_service 2026-06-18 13:48:42 +03:00
go.work Updated application verion to 0.9 2026-06-15 09:37:56 +03:00
go.work.sum Added admin service 2026-06-15 13:14:29 +03:00
update-go-and-deps.sh Add project files 2026-04-22 16:28:01 +03:00

README.md

🏢 Портал Сотрудника — RuspetPortal

Корпоративная CRM-система для управления сотрудниками, задачами и процессами согласования

Go PostgreSQL Redis gRPC Telegram


📋 Содержание


🎯 О проекте

Портал Сотрудника — это внутренняя корпоративная платформа, объединяющая в себе:

  • 📊 Управление сотрудниками и их профилями
  • ✅ Систему согласований через Telegram (отпуска, отгулы, закупки, расходы и др.)
  • 📦 Управление заявками на заказ товаров
  • 🔔 Уведомления об отсутствующих сотрудниках и ВРИО
  • 📋 Систему задач и поручений
  • 🔐 Авторизацию и управление правами доступа

Проект построен на микросервисной архитектуре — каждый сервис решает строго определённую задачу и общается с другими через gRPC или REST API.


🏗️ Архитектура

┌─────────────────────────────────────────────────────────────────┐
│                         Клиенты                                 │
│              Web App              Telegram Bot                  │
└────────────────┬─────────────────────────┬──────────────────────┘
                 │ REST                    │ Bot API (SOCKS5/HTTP)
                 ▼                         ▼
┌────────────────────────┐      ┌─────────────────────────────────┐
│   rest_user_service    │      │       telegram_service          │
│   rest_admin_service   │      │  (Система согласований)         │
└────────┬───────────────┘      └──────────────┬──────────────────┘
         │ gRPC                                │ gRPC
         ▼                                     ▼
┌─────────────────┐        ┌──────────────────────────────────────┐
│  auth_service   │        │           tasks_service              │
│  user_service   │        │        goods_order_service           │
└────────┬────────┘        └──────────────┬───────────────────────┘
         │                                │
         ▼                                ▼
┌─────────────────────────────────────────────────────────────┐
│                          core                               │
│         Типы • БД-методы • Утилиты • Библиотеки             │
└──────────────────────────────┬──────────────────────────────┘
                               │
              ┌────────────────┼─────────────────┐
              ▼                ▼                 ▼
         PostgreSQL          Redis         system_service
                                          (Миграции / Фоновые задачи)

📦 Сервисы

core — Ядро системы

Общая библиотека, используемая всеми сервисами. Содержит:

  • typescore/ — все модели данных (User, Approval, Role, Department и др.)
  • db/dbcore/ — методы работы с PostgreSQL (pgx + squirrel)
  • utilscore/ — вспомогательные функции
  • db/table_names/ — константы названий таблиц
  • db/dbutils/ — утилиты для построения запросов (GenerateInsertRequest, ScanRowsToStructRows и др.)

⚠️ Изменения в core затрагивают все сервисы. Вносить с осторожностью.


auth_service — Авторизация

gRPC-сервис авторизации. Обрабатывает:

  • Вход по логину/паролю
  • Генерацию и валидацию JWT-токенов
  • Обновление токенов (refresh)
  • Связан с rest_user_service для проверки прав

Порт: настраивается в конфиге
Протокол: gRPC


rest_user_service — API для клиентского приложения

REST API для веб/мобильного клиента:

  • Профиль пользователя
  • Список сотрудников
  • Уведомления
  • Заявки и задачи

Порт: настраивается в конфиге
Протокол: HTTP/REST (Gin)


rest_admin_service — API для административной панели

REST API для внутренней администрации:

  • Управление пользователями и ролями
  • Управление отделами
  • Настройка иерархий согласования
  • Управление правами доступа (permissions)
  • Просмотр и управление всеми заявками

Порт: настраивается в конфиге
Протокол: HTTP/REST (Gin)


tasks_service — Сервис задач

gRPC-сервис управления задачами и поручениями:

  • Создание задач
  • Назначение исполнителей
  • Отслеживание статусов
  • Интеграция с системой согласований

Протокол: gRPC


system_service — Системный сервис

Фоновый сервис без внешних точек доступа:

  • Миграции БД — запускаются при старте, поддерживают схему в актуальном состоянии
  • Фоновые задачи — периодические задания (планировщики, чистка данных, напоминания)
  • Планировщик уведомлений о делегировании прав
  • Планировщик отчётов об отсутствующих сотрудниках

telegram_service — Telegram Bot

Ключевой сервис системы согласований через Telegram:

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

  • 📋 Многоуровневая система согласований (до N шагов)
  • 🌳 Гибкие деревья тем (отгулы, отпуска, больничные, закупки, расходы и др.)
  • 👥 Дополнительные согласующие
  • 🔄 Возврат на доработку с комментарием
  • 📁 Прикрепление файлов к заявкам
  • 💬 Комментарии от согласующих/наблюдателей/исполнителей
  • 👁️ Наблюдатели с уведомлениями
  • 🎯 Задачи для исполнителей после согласования
  • 🔀 Делегирование прав согласования
  • 📊 Отчёты по согласованиям
  • 📢 Ежедневные отчёты об отсутствующих в группу с ВРИО
  • 💡 Предложения и пожелания (диалог инициатор ↔ директор)

Прокси: поддержка SOCKS5 и HTTP прокси (обязательно для работы в РФ)


user_service — Профиль пользователя

gRPC-сервис управления профилями:

  • Данные сотрудника
  • Отдел и должность
  • Роли и права
  • История активности

goods_order_service — Заявки на заказ товаров

Сервис обработки заявок на заказ:

  • Создание заявок на месяц и дополнительных
  • Процесс согласования
  • Назначение исполнителей
  • Отслеживание статусов

🛠️ Технологический стек

Категория Технология Версия Назначение
Язык Go 1.21+ Основной язык разработки
БД PostgreSQL 15+ Основная реляционная БД
Кэш Redis 7+ Сессии, состояния флоу, кэш
RPC gRPC + protobuf latest Межсервисное взаимодействие
HTTP chi v5 REST API сервисы
БД-драйвер pgx/v5 v5 PostgreSQL драйвер
Query Builder squirrel latest Построение SQL-запросов
Telegram go-telegram-bot-api v5 Telegram Bot API
Прокси golang.org/x/net latest SOCKS5 прокси для Telegram
Логирование logrus latest Структурированные логи
Конфиг embed / envconfig latest Конфигурация из env/файлов
Миграции gorm latest Управление схемой БД

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

ruspetportal/
│
├── core/                           # Общее ядро
│   ├── typescore/                  # Модели данных
│   │   └── models.go               # User, Approval, Role, Department...
│   ├── db/
│   │   ├── dbcore/                 # Реализации методов БД
│   │   │   ├── user.go
│   │   │   ├── approval.go
│   │   │   └── ...
│   │   ├── table_names/            # Константы имён таблиц
│   │   └── dbutils/                # Утилиты для работы с БД
│   └── utilscore/                  # Вспомогательные функции
│
├── auth_service/                   # Сервис авторизации
│   ├── cmd/main.go
│   ├── handlers/
│   └── proto/
│
├── rest_user_service/              # REST API для клиента
│   ├── cmd/main.go
│   ├── handlers/
│   ├── middleware/
│   └── routes/
│
├── rest_admin_service/             # REST API для админки
│   ├── cmd/main.go
│   ├── handlers/
│   ├── middleware/
│   └── routes/
│
├── tasks_service/                  # Сервис задач
│   ├── cmd/main.go
│   ├── handlers/
│   └── proto/
│
├── system_service/                 # Системный сервис
│   ├── cmd/main.go
│   ├── migrations/                 # SQL-миграции
│   │   ├── 000001_init.up.sql
│   │   └── ...
│   └── scheduler/                  # Фоновые задачи
│
├── telegram_service/               # Telegram Bot
│   ├── cmd/main.go
│   ├── common/
│   │   └── update/                 # Обработчик обновлений
│   ├── handlers/
│   │   ├── approval/               # Система согласований
│   │   │   ├── handler.go
│   │   │   ├── decision.go
│   │   │   ├── helpers.go
│   │   │   ├── revision.go
│   │   │   ├── comment.go
│   │   │   ├── executor.go
│   │   │   ├── delegation.go
│   │   │   ├── observer_selection.go
│   │   │   ├── first_approver_selection.go
│   │   │   └── topics/             # Деревья тем согласований
│   │   │       ├── timeoff/        # Отгулы
│   │   │       ├── vacation/       # Отпуска
│   │   │       ├── sick_leave/     # Больничные
│   │   │       ├── free/           # Свободные темы
│   │   │       ├── returns/        # Возвраты
│   │   │       ├── client_changes/ # Изменения клиентов
│   │   │       ├── goods_order/    # Заказ товаров
│   │   │       ├── shipments_soh/  # Отгрузки на СОХ
│   │   │       ├── transaction_passport/ # Паспорт сделки
│   │   │       ├── rates_logistics/  # Ставки логистики
│   │   │       ├── receipts/       # Поступления
│   │   │       └── non_budget*/    # Внебюджетные расходы
│   │   ├── suggestion/             # Предложения и пожелания
│   │   ├── acting/                 # ВРИО
│   │   └── start/                  # Стартовый обработчик
│   ├── approvalflow/               # Движок флоу согласований
│   │   └── flow.go                 # FlowNode, FindNode
│   ├── keyboard/                   # Построители клавиатур
│   ├── scheduler/                  # Планировщики
│   │   ├── delegation_checker.go   # Проверка делегирований
│   │   └── absence_reporter.go     # Отчёты об отсутствующих
│   ├── state/                      # Управление состояниями (Redis)
│   └── types/                      # Внутренние типы сервиса
│
├── user_service/                   # Сервис профиля
│   ├── cmd/main.go
│   ├── handlers/
│   └── proto/
│
├── goods_order_service/            # Сервис заказов товаров
│   ├── cmd/main.go
│   └── handlers/
│
└── docker-compose.yml              # Docker Compose для локального запуска

🚀 Быстрый старт

Требования

  • Go 1.21+
  • PostgreSQL 15+
  • Redis 7+
  • Docker & Docker Compose (опционально)

1. Клонирование

git clone https://github.com/your-org/ruspetportal.git
cd ruspetportal

2. Переменные окружения

Скопируйте примеры конфигов:

cp .env.example .env

Заполните переменные (см. раздел Конфигурация).

3. Запуск через Docker Compose

# Запуск всей инфраструктуры (PostgreSQL, Redis)
docker-compose up -d postgres redis

# Запуск миграций
cd system_service && go run cmd/main.go migrate

# Запуск сервисов
go run auth_service/cmd/main.go &
go run rest_user_service/cmd/main.go &
go run rest_admin_service/cmd/main.go &
go run telegram_service/cmd/main.go &

4. Запуск отдельного сервиса

cd telegram_service
go run cmd/main.go

⚙️ Конфигурация

Общие переменные

# PostgreSQL
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=ruspetportal
DATABASE_USER=postgres
DATABASE_PASSWORD=your_password
DATABASE_SSL_MODE=disable

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

Telegram Service

# Telegram Bot
TELEGRAM_BOT_TOKEN=your_bot_token

# Прокси (обязательно для РФ)
TELEGRAM_PROXY_URL=socks5://user:pass@proxy.host:1080
# или HTTP прокси:
# TELEGRAM_PROXY_URL=http://proxy.host:8080

Auth Service

JWT_SECRET=your_jwt_secret_key
JWT_EXPIRY=24h
JWT_REFRESH_EXPIRY=720h

Порты сервисов

AUTH_SERVICE_PORT=50051        # gRPC
USER_SERVICE_PORT=50052        # gRPC
TASKS_SERVICE_PORT=50053       # gRPC
REST_USER_SERVICE_PORT=8080    # HTTP
REST_ADMIN_SERVICE_PORT=8081   # HTTP

🗄️ База данных

Основные таблицы

Таблица Назначение
users Сотрудники
roles Роли (approver, observer, executor, director...)
user_roles Связь пользователей и ролей
departments Отделы
permissions Права доступа по ролям и темам
approval_topic_categories Категории тем согласований
approval_topics Темы согласований
approvals Заявки на согласование
approval_steps Шаги согласования
approval_files Файлы к заявкам
approval_comments Комментарии к заявкам
approval_additional_approvers Дополнительные согласующие
approval_additional_observers Дополнительные наблюдатели
approval_tasks Задачи исполнителям после согласования
approval_delegations Делегирование прав согласования
acting_assignments Назначения ВРИО
suggestions Предложения и пожелания
suggestion_messages Переписка по предложениям
user_hierarchies Иерархии согласования
group_notification_settings Настройки уведомлений в группы

Миграции

Миграции хранятся в system_service/jobs/ и применяются автоматически при старте system_service.

# Применить миграции вручную
cd system_service
go run cmd/main.go

Важные настройки в БД

Для работы системы согласований необходимо заполнить:

-- Добавить роли
INSERT INTO roles (name, code, is_approver, is_director, is_observer, is_executor)
VALUES
  ('Согласующий', 'approver', true, false, false, false),
  ('Директор', 'director', false, true, false, false),
  ('Наблюдатель', 'observer', false, false, true, false),
  ('Исполнитель', 'executor', false, false, false, true);

-- Включить флаги для тем с выбором первого согласующего
UPDATE approval_topics
SET first_approver_role_code = 'manager'
WHERE code IN ('returns_other_manager_crimea', 'returns_other_manager_krasnodar');

-- Включить флаги для тем с выбором наблюдателей
UPDATE approval_topics
SET allow_observer_selection = true
WHERE code IN ('goods_order_monthly', 'goods_order_additional');

🌐 API

REST User Service (rest_user_service)

GET    /api/v1/profile          — Профиль текущего пользователя
PUT    /api/v1/profile          — Обновление профиля
GET    /api/v1/employees        — Список сотрудников
GET    /api/v1/approvals        — Мои заявки
GET    /api/v1/tasks            — Мои задачи

REST Admin Service (rest_admin_service)

# Пользователи
GET    /api/v1/admin/users              — Список пользователей
POST   /api/v1/admin/users              — Создать пользователя
PUT    /api/v1/admin/users/:id          — Обновить пользователя
DELETE /api/v1/admin/users/:id          — Удалить пользователя

# Роли и права
GET    /api/v1/admin/roles              — Список ролей
POST   /api/v1/admin/permissions        — Выдать право доступа

# Иерархии согласования
POST   /api/v1/admin/hierarchies        — Настроить иерархию
GET    /api/v1/admin/hierarchies        — Список иерархий

# Темы согласований
GET    /api/v1/admin/topics             — Список тем
PUT    /api/v1/admin/topics/:id         — Обновить тему

gRPC сервисы

Proto-файлы расположены в {service_name}/proto/.


🤖 Telegram Bot

Подключение прокси

Бот обязательно требует прокси для работы в РФ. Поддерживаются:

# SOCKS5 (рекомендуется)
TELEGRAM_PROXY_URL=socks5://login:password@proxy.example.com:1080

# HTTP прокси
TELEGRAM_PROXY_URL=http://proxy.example.com:8080

# SOCKS5 без авторизации
TELEGRAM_PROXY_URL=socks5://proxy.example.com:1080

Команды бота

Команда Назначение
/start Регистрация и главное меню
/approvals Открыть список согласований
/set_report_time HH:MM Установить время отчёта (в группе)

Роли пользователей в боте

Роль Код Возможности
Сотрудник employee Создание заявок
Согласующий approver Согласование/отклонение заявок
Директор director Финальное согласование, просмотр всех
Наблюдатель observer Просмотр заявок по категориям
Исполнитель executor Выполнение задач после согласования

Добавление новой темы согласования

  1. Добавить запись в таблицы approval_topic_categories и approval_topics
  2. Создать файл telegram_service/handlers/approval/topics/{name}/topic.go
  3. Реализовать интерфейс approvalflow.Topic:
    type Topic interface {
        Code() string
        Name() string
        BuildTree() *FlowNode
        TopicCodeFromCollected(collected map[string]string) (string, error)
        FormatApproverMessage(initiator *typescore.User, collected map[string]string) string
    }
    
  4. Зарегистрировать в telegram_service/handlers/approval/registry.go

Уведомления об отсутствующих в группу

Добавьте бота в Telegram-группу — он автоматически зарегистрируется и начнёт присылать ежедневный отчёт в 09:00:

📋 Отсутствующие сотрудники — 29.04.2026

1. Иванов Иван Иванович
   📌 Отпуск
   📅 25.04.2026 — 05.05.2026
   👤 ВРИО: Петров Пётр Петрович

2. Сидорова Анна Михайловна
   📌 Больничный
   📅 29.04.2026
   👤 ВРИО: не назначен

Изменить время отчёта: /set_report_time 08:30


🔧 Разработка

Добавление нового сервиса

  1. Создайте директорию new_service/
  2. Добавьте cmd/main.go с инициализацией
  3. Подключите core через go.work или go.mod replace
  4. Зарегистрируйте в docker-compose.yml

Добавление нового метода в core

  1. Добавьте модель в core/typescore/models.go
  2. Добавьте константу таблицы в core/db/table_names/
  3. Создайте файл core/db/dbcore/{entity}.go с реализацией интерфейса
  4. Добавьте в ModuleDB в core/db/dbcore/module_db.go

Паттерн реализации методов БД

Все методы работы с БД следуют единому паттерну:

func (u *EntityDB) CreateEntityDB(
    ctx context.Context,
    tx pgx.Tx,
    obj *typescore.Entity,
    returnObj ...bool,
) (*typescore.Entity, pgx.Tx, error) {
    // 1. Проверка nil
    // 2. ExecuteTx — INSERT с RETURNING id
    // 3. Если returnObj=true — GetByID и вернуть объект
}

Состояния в Telegram боте

Все состояния флоу хранятся в Redis с TTL 30 минут. Паттерн:

// Установить состояние
h.States.Set(ctx, telegramID, flowState)

// Получить состояние  
flowState, err := h.States.Get(ctx, telegramID)

// Очистить состояние
h.States.Clear(ctx, telegramID)

Линтер и форматирование

# Форматирование
gofmt -w ./...

# Линтер
golangci-lint run ./...

📄 Лицензия

Проект является внутренней разработкой и не предназначен для открытого распространения.


Разработано для внутреннего использования · RuspetPortal
# Test deploy