# 🏢 Портал Сотрудника — RuspetPortal
**Корпоративная CRM-система для управления сотрудниками, задачами и процессами согласования**





---
## 📋 Содержание
- [О проекте](#о-проекте)
- [Архитектура](#архитектура)
- [Сервисы](#сервисы)
- [Технологический стек](#технологический-стек)
- [Структура проекта](#структура-проекта)
- [Быстрый старт](#быстрый-старт)
- [Конфигурация](#конфигурация)
- [База данных](#база-данных)
- [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