ruspet_portal_back/README.md

658 lines
27 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 🏢 Портал Сотрудника — RuspetPortal
<div align="center">
**Корпоративная 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)
</div>
---
## 📋 Содержание
- [О проекте](#о-проекте)
- [Архитектура](#архитектура)
- [Сервисы](#сервисы)
- [Технологический стек](#технологический-стек)
- [Структура проекта](#структура-проекта)
- [Быстрый старт](#быстрый-старт)
- [Конфигурация](#конфигурация)
- [База данных](#база-данных)
- [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 ./...
```
---
## 📄 Лицензия
Проект является внутренней разработкой и не предназначен для открытого распространения.
---
<div align="center">
<sub>Разработано для внутреннего использования · RuspetPortal</sub>
</div>