mkd/backend/1c-integration-options.md

Варианты интеграции с 1С для получения данных по зарплате

Текущая ситуация

В системе уже есть:

• ✅ Обработчик файлов (CSV/XLSX) - fileProcessor.js
• ✅ Таблица employees с полем salary
• ✅ Таблица employee_accounting_data (ИНН, СНИЛС, банковские реквизиты)
• ✅ API для загрузки финансовых отчетов

Варианты интеграции

1. 📄 Импорт файлов (Excel/CSV) - РЕКОМЕНДУЕТСЯ

Сложность: ⭐ Низкая
Время внедрения: 1-2 дня
Требования: 1С может экспортировать отчеты в Excel/CSV

Как работает:

• В 1С настраивается выгрузка отчета по зарплате в Excel/CSV
• Пользователь загружает файл через веб-интерфейс
• Система автоматически парсит и обновляет данные сотрудников

Плюсы:

• ✅ Уже реализована базовая инфраструктура
• ✅ Не требует изменений в 1С
• ✅ Простое внедрение
• ✅ Работает с любой версией 1С

Минусы:

• ⚠️ Ручная загрузка файлов
• ⚠️ Нет автоматической синхронизации

Что нужно сделать:

1. Расширить fileProcessor.js для обработки зарплатных данных
2. Добавить маппинг полей из 1С отчета
3. Создать API endpoint для обновления зарплат сотрудников
4. Добавить UI для загрузки зарплатных отчетов

---

2. 🌐 REST API 1С (HTTP-сервис)

Сложность: ⭐⭐ Средняя
Время внедрения: 3-5 дней
Требования: 1С:Предприятие 8.3+ с настроенным HTTP-сервисом

Как работает:

• В 1С создается HTTP-сервис, который отдает данные по зарплате
• Node.js backend делает запросы к 1С API
• Автоматическая синхронизация по расписанию

Плюсы:

• ✅ Автоматическая синхронизация
• ✅ Актуальные данные в реальном времени
• ✅ Можно настроить расписание обновлений

Минусы:

• ⚠️ Требует настройки HTTP-сервиса в 1С
• ⚠️ Нужен доступ к серверу 1С
• ⚠️ Требуется настройка безопасности

Что нужно сделать:

1. Настроить HTTP-сервис в 1С
2. Создать модуль 1cApiClient.js для работы с API
3. Добавить endpoint /api/salary/sync-from-1c
4. Настроить cron-задачу для автоматической синхронизации

---

3. 🔌 COM/OLE соединение (Windows)

Сложность: ⭐⭐⭐ Высокая
Время внедрения: 5-7 дней
Требования: Windows сервер, 1С установлена локально

Как работает:

• Node.js использует COM-объекты для подключения к 1С
• Прямое обращение к данным через OLE

Плюсы:

• ✅ Прямой доступ к данным
• ✅ Не нужны промежуточные файлы

Минусы:

• ⚠️ Работает только на Windows
• ⚠️ Требует установленной 1С на сервере
• ⚠️ Сложная настройка
• ⚠️ Проблемы с производительностью

Не рекомендуется для веб-приложения

---

4. 🗄️ ODBC/OLE DB подключение к базе 1С

Сложность: ⭐⭐⭐ Высокая
Время внедрения: 5-7 дней
Требования: 1С на SQL Server, доступ к БД

Как работает:

• Прямое подключение к базе данных 1С через ODBC
• SQL-запросы к таблицам 1С

Плюсы:

• ✅ Прямой доступ к данным
• ✅ Можно использовать SQL-запросы

Минусы:

• ⚠️ Требует знания структуры БД 1С
• ⚠️ Зависит от версии 1С
• ⚠️ Проблемы с безопасностью
• ⚠️ Может сломаться при обновлении 1С

Не рекомендуется - хрупкое решение

---

Рекомендация

🎯 Гибридный подход: Файлы + HTTP-сервис

Этап 1 (быстрое внедрение):

• Расширить существующую систему импорта файлов для зарплатных данных
• Пользователи загружают отчеты вручную

Этап 2 (автоматизация):

• Настроить HTTP-сервис в 1С
• Добавить автоматическую синхронизацию по расписанию
• Файлы остаются как резервный вариант

---

Структура данных для зарплатного отчета

Поля, которые нужно получать из 1С:

interface SalaryReportRow {
  // Идентификация сотрудника
  employeeIdentifier: string; // ФИО, ИНН, табельный номер
  inn?: string;              // ИНН (для точного сопоставления)
  snils?: string;            // СНИЛС
  
  // Зарплатные данные
  period: string;             // Период (месяц/год)
  baseSalary: number;         // Оклад
  actualSalary: number;       // Фактическая зарплата
  bonuses?: number;           // Премии
  deductions?: number;        // Удержания
  netSalary?: number;         // К выплате
  
  // Дополнительно
  workedDays?: number;         // Отработано дней
  workedHours?: number;        // Отработано часов
  vacationDays?: number;       // Дни отпуска
  sickLeaveDays?: number;      // Дни больничного
}

---

Следующие шаги

1. Определить формат отчета из 1С:

   • Какие поля содержит отчет?
   • В каком формате экспортируется (Excel, CSV)?
   • Есть ли возможность настроить выгрузку?

2. Выбрать вариант интеграции:

   • Начать с импорта файлов (быстро)
   • Планировать HTTP-сервис (автоматизация)

3. Реализовать:

   • Расширить fileProcessor для зарплатных данных
   • Создать маппинг полей
   • Добавить UI для загрузки
   • Настроить обновление данных сотрудников