|
Deploy / deploy (push) Successful in 17s
Details
Reviewed-on: https://72.56.235.246.nip.io/gitea/romanskijdev/ruspet_portal_back/pulls/131 |
||
|---|---|---|
| .gitea/workflows | ||
| core | ||
| service | ||
| .gitignore | ||
| .golangci.yml | ||
| LТ | ||
| README.md | ||
| build_core.sh | ||
| communication_system.txt | ||
| deploy.sh | ||
| go.work | ||
| go.work.sum | ||
| update-go-and-deps.sh | ||
README.md
🏢 Портал Сотрудника — RuspetPortal
📋 Содержание
- О проекте
- Архитектура
- Сервисы
- Технологический стек
- Структура проекта
- Быстрый старт
- Конфигурация
- База данных
- API
- Telegram Bot
- Разработка
🎯 О проекте
Портал Сотрудника — это внутренняя корпоративная платформа, объединяющая в себе:
- 📊 Управление сотрудниками и их профилями
- ✅ Систему согласований через 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 |
Выполнение задач после согласования |
Добавление новой темы согласования
- Добавить запись в таблицы
approval_topic_categoriesиapproval_topics - Создать файл
telegram_service/handlers/approval/topics/{name}/topic.go - Реализовать интерфейс
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 } - Зарегистрировать в
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
🔧 Разработка
Добавление нового сервиса
- Создайте директорию
new_service/ - Добавьте
cmd/main.goс инициализацией - Подключите
coreчерезgo.workилиgo.mod replace - Зарегистрируйте в
docker-compose.yml
Добавление нового метода в core
- Добавьте модель в
core/typescore/models.go - Добавьте константу таблицы в
core/db/table_names/ - Создайте файл
core/db/dbcore/{entity}.goс реализацией интерфейса - Добавьте в
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 ./...
📄 Лицензия
Проект является внутренней разработкой и не предназначен для открытого распространения.