bit-flight-deck/bitra-cfe

BIT_FlightDeck — расширение BIT.RA с REST API для bit-flight-deck

Расширение конфигурации (CFE) для BIT.RA (1С:Предприятие 8.3, режим совместимости Version8_3_14). Добавляет HTTP-сервис read-only для аналитического слоя проекта bit-flight-deck. Не изменяет существующие объекты конфигурации (никаких заимствований).

Состав расширения

bitra-cfe/
├── Configuration.xml                                Заголовок расширения, Purpose=AddOn, Prefix=bfd_
├── Languages/
│   └── Русский.xml                                  Язык расширения
├── Roles/
│   └── bfd_ОсновнаяРоль/                            ⚠ Дефолтная роль из cfe-init — НУЖНО НАСТРОИТЬ ПРАВА (см. ниже)
├── CommonModules/
│   └── bfd_IntegrationAPIHelpers/
│       └── Ext/Module.bsl                            Хелперы (JSON-ответ, парс даты, UUID, ИзвлечьEmail, ПарсЛимит)
└── HTTPServices/
    └── bfd_IntegrationAPI/
        └── Ext/Module.bsl                            11 обработчиков GET-эндпоинтов

Что нужно сделать 1С-разработчику (по шагам)

1. Импорт расширения в Конфигуратор

1. Открыть Конфигуратор BIT.RA.
2. Конфигурация → Расширения конфигурации → Добавить (или клавиша Insert на дереве расширений).
3. Указать имя расширения BIT_FlightDeck, назначение Дополнение, префикс bfd_.
4. В созданном расширении: Конфигурация → Загрузить конфигурацию из файлов... — указать каталог bitra-cfe/.
5. Проверить дерево объектов: должны быть bfd_IntegrationAPI (HTTP-сервис), bfd_IntegrationAPIHelpers (общий модуль), bfd_ОсновнаяРоль (роль).
6. Обновить конфигурацию базы данных (F7).

2. Настройка роли bfd_ОсновнаяРоль

Дефолтная роль из шаблона пустая. Нужно добавить права на чтение объектов, к которым обращается API:

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

Также в свойстве расширения: «Активные роли» / «Назначаемые роли» → отметить bfd_ОсновнаяРоль.

3. Создание сервисного пользователя

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

1. Создать пользователя bfd_api_user.
2. Пароль — сгенерировать криптостойкий (~16 символов), сохранить отдельно для передачи в .env файла N8N.
3. Аутентификация: Аутентификация 1С:Предприятия (для Basic auth по HTTP).
4. Запретить интерактивный вход (галка «Запрещено изменять пароль», без членства в группах с интерактивными правами).
5. Назначить роли:
   • bfd_ОсновнаяРоль (из расширения).
   • Также понадобятся базовые БСП-роли: БазовыеПрава (или эквивалент в BIT.RA), чтобы пользователь мог войти в сеанс.

4. Публикация HTTP-сервиса через Apache

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

В диалоге:

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

URL сервиса после публикации: http://<host>/<publication-name>/hs/bfd-api/v1/...

Пример (полный URL):

http://server.local/bitra/hs/bfd-api/v1/health
http://server.local/bitra/hs/bfd-api/v1/employees
http://server.local/bitra/hs/bfd-api/v1/works?modified_since=2026-05-01

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

# health (без auth тоже работает, но Basic auth нужна для остальных)
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')"

# Проекты
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/stages | head -c 500

# Виды работ
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

# Маппинг EVA проектов (может быть пустым — пользователь подтвердил что интеграция мёртвая)
curl -u bfd_api_user:<PASSWORD> http://server.local/bitra/hs/bfd-api/v1/eva_mapping/projects

6. Передать команде N8N (роль владельца проекта)

После успешной публикации передать:

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

Эти значения попадают в файл .env проекта bit-flight-deck. На стороне N8N будут настроены HTTP Request ноды с Basic-auth.

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

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

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

Всегда JSON, UTF-8 (без BOM), массив объектов или объект-обёртка.

Пример ответа /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.
• Modul bfd_IntegrationAPIHelpers помечен как Privileged=true — внутри него игнорируются ограничения RLS. Пользователь BFD_api имеет доступ ко всем строкам справочников/документов через API. Это намеренно — аналитический слой должен видеть всё.
• Пароль bfd_api_user хранится в .env проекта (не в git).
• Доступ к публикации Apache желательно ограничить firewall'ом IP-адресом N8N-сервера (или ходить через CF Tunnel/VPN внутри сети).

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

• Спецификация: ../docs/superpowers/specs/2026-05-13-mvp1-workload-design.md
• План: ../docs/superpowers/plans/2026-05-13-mvp1-workload.md — Phase 3
• Решения по транспорту: см. memory architecture_transport_decisions