From 662e496d7a60fdc60e225ed4e2933e05efc4e1ff Mon Sep 17 00:00:00 2001 From: romanskijdev Date: Tue, 5 May 2026 11:04:16 +0300 Subject: [PATCH] Added readme.md file --- README.md | 659 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 658 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7782779..531142c 100644 --- a/README.md +++ b/README.md @@ -1 +1,658 @@ -# Project Init +# 🏢 Портал Сотрудника — 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 +
\ No newline at end of file