# 🏢 Портал Сотрудника — RuspetPortal
**Корпоративная CRM-система для управления сотрудниками, задачами и процессами согласования** ![Go](https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go&logoColor=white) ![PostgreSQL](https://img.shields.io/badge/PostgreSQL-15+-4169E1?style=flat&logo=postgresql&logoColor=white) ![Redis](https://img.shields.io/badge/Redis-7+-DC382D?style=flat&logo=redis&logoColor=white) ![gRPC](https://img.shields.io/badge/gRPC-1.60+-244C5A?style=flat&logo=grpc) ![Telegram](https://img.shields.io/badge/Telegram_Bot-API-26A5E4?style=flat&logo=telegram)
--- ## 📋 Содержание - [О проекте](#о-проекте) - [Архитектура](#архитектура) - [Сервисы](#сервисы) - [Технологический стек](#технологический-стек) - [Структура проекта](#структура-проекта) - [Быстрый старт](#быстрый-старт) - [Конфигурация](#конфигурация) - [База данных](#база-данных) - [API](#api) - [Telegram Bot](#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. Клонирование ```bash git clone https://github.com/your-org/ruspetportal.git cd ruspetportal ``` ### 2. Переменные окружения Скопируйте примеры конфигов: ```bash cp .env.example .env ``` Заполните переменные (см. раздел [Конфигурация](#конфигурация)). ### 3. Запуск через Docker Compose ```bash # Запуск всей инфраструктуры (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. Запуск отдельного сервиса ```bash cd telegram_service go run cmd/main.go ``` --- ## ⚙️ Конфигурация ### Общие переменные ```env # 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 ```env # 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 ```env JWT_SECRET=your_jwt_secret_key JWT_EXPIRY=24h JWT_REFRESH_EXPIRY=720h ``` ### Порты сервисов ```env 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`. ```bash # Применить миграции вручную cd system_service go run cmd/main.go ``` ### Важные настройки в БД Для работы системы согласований необходимо заполнить: ```sql -- Добавить роли 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 ### Подключение прокси Бот обязательно требует прокси для работы в РФ. Поддерживаются: ```env # 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`: ```go 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` ### Паттерн реализации методов БД Все методы работы с БД следуют единому паттерну: ```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 минут. Паттерн: ```go // Установить состояние h.States.Set(ctx, telegramID, flowState) // Получить состояние flowState, err := h.States.Get(ctx, telegramID) // Очистить состояние h.States.Clear(ctx, telegramID) ``` ### Линтер и форматирование ```bash # Форматирование gofmt -w ./... # Линтер golangci-lint run ./... ``` --- ## 📄 Лицензия Проект является внутренней разработкой и не предназначен для открытого распространения. ---
Разработано для внутреннего использования · RuspetPortal
# Test deploy