bit-flight-deck/bitra-patch

Доработка BIT.RA — read-only REST API для bit-flight-deck

Доработка самой конфигурации BIT.RA (не расширение). Добавляются 3 объекта метаданных + 1 пользователь + публикация на Apache.

Объекты для добавления в конфигурацию

1. Общий модуль bfd_IntegrationAPIHelpers

Путь в дереве: Общие → Общие модули → Добавить.

Свойства модуля (на вкладке свойств):

Свойство	Значение
Имя	bfd_IntegrationAPIHelpers
Синоним	BFD: API helpers
Глобальный	Ложь
Сервер	Истина
Вызов сервера	Истина
Клиент (управляемое приложение)	Ложь
Клиент (обычное приложение)	Ложь
Внешнее соединение	Истина
Привилегированный	Истина ⚠️ важно
Повторное использование возвращаемых значений	Не использовать

Код модуля — вставить целиком из CommonModules/bfd_IntegrationAPIHelpers/Module.bsl.

2. HTTP-сервис bfd_IntegrationAPI

Путь в дереве: Общие → HTTP-сервисы → Добавить.

Свойства сервиса:

Свойство	Значение
Имя	bfd_IntegrationAPI
Синоним	BFD: Integration API
Корневой URL	bfd-api
Повторное использование сессий	Не использовать

Шаблоны URL и методы. Внутри HTTP-сервиса добавляем 11 шаблонов URL. Для каждого:

1. Правой кнопкой на сервис → Добавить → Шаблон URL.
2. Задать имя шаблона и URL (см. таблицу).
3. Внутри шаблона: правой кнопкой → Добавить → Метод. Имя — Get, HTTP-метод — GET, Обработчик — имя функции (автодополнится по <ИмяШаблона><ИмяМетода>).

Имя шаблона	URL	Имя метода	HTTP	Обработчик (функция в модуле HTTP-сервиса)
Health	/v1/health	Get	GET	HealthGet
Employees	/v1/employees	Get	GET	EmployeesGet
Works	/v1/works	Get	GET	WorksGet
Projects	/v1/projects	Get	GET	ProjectsGet
Stages	/v1/stages	Get	GET	StagesGet
WorkTypes	/v1/work_types	Get	GET	WorkTypesGet
Dictionaries	/v1/dictionaries	Get	GET	DictionariesGet
DeptHistory	/v1/dept_history	Get	GET	DeptHistoryGet
ProjectRegister	/v1/project_register	Get	GET	ProjectRegisterGet
EvaMappingProjects	/v1/eva_mapping/projects	Get	GET	EvaMappingProjectsGet
EvaMappingClients	/v1/eva_mapping/clients	Get	GET	EvaMappingClientsGet

Код модуля HTTP-сервиса — открыть «Модуль» сервиса и вставить целиком из HTTPServices/bfd_IntegrationAPI/Module.bsl.

3. Роль bfd_API_Чтение

Путь в дереве: Общие → Роли → Добавить.

Свойства роли:

Свойство	Значение
Имя	bfd_API_Чтение
Синоним	BFD: API чтение

Права на объекты (в таблице прав отметить галочки):

Объект	Чтение	Просмотр	Использование
Справочник.Пользователи	✓	✓	—
Справочник.Подразделение	✓	✓	—
Справочник.Офис	✓	✓	—
Справочник.Менеджеры	✓	✓	—
Справочник.Клиенты	✓	✓	—
Справочник.Проекты	✓	✓	—
Справочник.ЭтапыПроектов	✓	✓	—
Справочник.Конфигурации	✓	✓	—
Справочник.Договоры	✓	✓	—
Справочник.СценарииПланирования	✓	✓	—
Документ.Работы	✓	✓	—
РегистрСведений.ПодразделениеСотрудников	✓	—	—
РегистрНакопления.ОборотыПроектныхПоказателей_v2	✓	—	—
РегистрСведений.СоответствиеПроектовEVA_РА	✓	—	—
РегистрСведений.СоответствиеКонтрагентовEVA_РА	✓	—	—
Перечисление.ВидыРабот	✓	—	—
HTTPСервис.bfd_IntegrationAPI	—	—	✓
ОбщийМодуль.bfd_IntegrationAPIHelpers	—	—	✓
Запуск тонкого клиента / толстого / веб-клиента	—	—	(по необходимости)

Важно: в свойствах роли отметить «Устанавливать права для новых объектов» = Ложь (роль строго ограниченная).

4. Пользователь bfd_api_user

В режиме Предприятие (или Конфигуратор → Администрирование → Пользователи) создать:

Поле	Значение
Имя	bfd_api_user
Полное имя	BFD: API service user
Аутентификация 1С:Предприятия	✓ (для Basic auth)
Пароль	сгенерировать криптостойкий 16+ символов, передать в команду N8N
Аутентификация ОС	—
Запрещено изменять пароль	✓
Запрещено восстанавливать пароль	✓
Запрет интерактивного входа	✓ (если есть такая настройка)
Роли	bfd_API_Чтение + минимальная роль для входа (БазовыеПрава или эквивалент в BIT.RA)

Публикация на Apache

Конфигуратор → Администрирование → Публикация на веб-сервере...

Настройки:

• Веб-сервер: Apache 2.4.
• Каталог: имя публикации, например bitra (будет частью URL).
• HTTP-сервисы: галочкой включить bfd_IntegrationAPI.
• Публиковать HTTP-сервисы по умолчанию (если есть такая опция) — можно не включать, поскольку отметили вручную.

После Save — Apache перезапустить.

Итоговый URL базовый:

http://<host>/<publication-name>/hs/bfd-api/v1/

Пример (если host=server.local, publication=bitra):

http://server.local/bitra/hs/bfd-api/v1/health

Тестирование через curl

# Health (Basic auth обязательна для HTTP-сервисов 1С)
curl -u bfd_api_user:<PASSWORD> http://server.local/bitra/hs/bfd-api/v1/health

# Сотрудники
curl -u bfd_api_user:<PASSWORD> http://server.local/bitra/hs/bfd-api/v1/employees | head -c 500

# Работы за вчера
curl -u bfd_api_user:<PASSWORD> "http://server.local/bitra/hs/bfd-api/v1/works?modified_since=$(date -d 'yesterday' '+%Y-%m-%d')" | head -c 500

# Проекты
curl -u bfd_api_user:<PASSWORD> http://server.local/bitra/hs/bfd-api/v1/projects | head -c 1000

# Виды работ (быстро проверить что аутентификация работает + перечисление читается)
curl -u bfd_api_user:<PASSWORD> http://server.local/bitra/hs/bfd-api/v1/work_types

# Справочники одним запросом
curl -u bfd_api_user:<PASSWORD> http://server.local/bitra/hs/bfd-api/v1/dictionaries | head -c 2000

# История подразделений
curl -u bfd_api_user:<PASSWORD> "http://server.local/bitra/hs/bfd-api/v1/dept_history?modified_since=2024-01-01" | head -c 500

Если что-то возвращает HTTP 500 с {"error":"..."} — посмотреть журнал регистрации 1С (там полный стек ошибки запроса).

Что передать команде N8N

После публикации:

• BITRA_BASE_URL — http://<host>/<publication>/hs/bfd-api/v1
• BITRA_USER — bfd_api_user
• BITRA_PASSWORD — пароль

Эти значения попадают в .env проекта bit-flight-deck (на стороне сервера WSL).

Список эндпоинтов (полная карта)

Метод	URL	Назначение	Параметры
GET	/v1/health	Healthcheck	—
GET	/v1/employees	Справочник.Пользователи	—
GET	/v1/works	Документ.Работы + ТЧ	modified_since, limit (по умолчанию 1000, max 10000)
GET	/v1/projects	Справочник.Проекты	—
GET	/v1/stages	Справочник.ЭтапыПроектов	—
GET	/v1/work_types	Перечисление.ВидыРабот (14 значений)	—
GET	/v1/dictionaries	Офисы/Подразделения/Менеджеры/Конфигурации/Договоры/Сценарии — одним JSON	—
GET	/v1/dept_history	РегистрСведений.ПодразделениеСотрудников	modified_since
GET	/v1/project_register	РегНак.ОборотыПроектныхПоказателей_v2 (для MVP-3)	modified_since
GET	/v1/eva_mapping/projects	РегистрСведений.СоответствиеПроектовEVA_РА (best-effort из мёртвой интеграции)	—
GET	/v1/eva_mapping/clients	РегистрСведений.СоответствиеКонтрагентовEVA_РА	—

Формат ответа

Всегда JSON, UTF-8 (без BOM), массив объектов или объект-обёртка. Все ID объектов — строковый UUID без префикса класса (8-4-4-4-12 hex).

Пример ответа /v1/employees

[
  {
    "id": "f5631644-1948-11ee-94f0-c578ab9a5932",
    "full_name": "Иванов Иван",
    "email": "iivanov@1cbit.ru",
    "eva_id": "CmfPerson:abc...",
    "office": "ЕКБ",
    "department": "Группа РП №2",
    "rate": 1500.00,
    "is_active": true,
    "should_fill_report": true
  }
]

Пример ответа /v1/works

[
  {
    "id": "...",
    "number": "WK-000123",
    "date": "2026-05-13T00:00:00",
    "employee_id": "...",
    "department": "Группа РП №2",
    "office": "ЕКБ",
    "approved": true,
    "total_hours": 8.0,
    "comment": "",
    "rows": [
      {
        "row_index": 1,
        "description": "Разработка отчёта по продажам",
        "hours": 4.0,
        "work_type": "ЛУРВ (платно)",
        "work_type_code": "ЛУРВ",
        "client_id": "...",
        "client_name": "ООО Ромашка",
        "manager_id": "...",
        "project_id": "...",
        "stage_id": "...",
        "request_number": "RQ-555",
        "lt_id": "",
        "work_done": true
      }
    ]
  }
]

Ошибки

При исключении внутри обработчика возвращается:

{ "error": "Описание ошибки 1С" }

с HTTP-кодом 500.

Безопасность и эксплуатация

• Все эндпоинты требуют Basic Auth (пользователь bfd_api_user).
• Модуль bfd_IntegrationAPIHelpers имеет Привилегированный=Истина — внутри его методов игнорируются ограничения RLS. Это намеренно — аналитический слой должен видеть всё.
• Пароль bfd_api_user хранить в .env проекта (не в git).
• Доступ к публикации Apache желательно ограничить firewall'ом до IP-адреса сервера N8N.
• Под нагрузкой полл происходит каждые 30 минут (/works, /projects), раз в сутки (справочники). Это минимальная нагрузка на BIT.RA.
• Для MVP-1 не нужны: /v1/project_register, /v1/eva_mapping/* — они подключатся в MVP-3 / при оживлении EVA-РА интеграции.

Файлы кода

• CommonModules/bfd_IntegrationAPIHelpers/Module.bsl — модуль помощников (вставить целиком в одноимённый общий модуль).
• HTTPServices/bfd_IntegrationAPI/Module.bsl — модуль HTTP-сервиса (вставить целиком в «Модуль» HTTP-сервиса).

Связанные документы

• Спецификация: ../docs/superpowers/specs/2026-05-13-mvp1-workload-design.md
• План: ../docs/superpowers/plans/2026-05-13-mvp1-workload.md — Phase 3
• Северная звезда: ../docs/superpowers/PROJECT_GOAL.md