diff --git a/bitra-cfe/CommonModules/bfd_IntegrationAPIHelpers.xml b/bitra-cfe/CommonModules/bfd_IntegrationAPIHelpers.xml deleted file mode 100644 index 448dd97..0000000 --- a/bitra-cfe/CommonModules/bfd_IntegrationAPIHelpers.xml +++ /dev/null @@ -1,23 +0,0 @@ - - - - - bfd_IntegrationAPIHelpers - - - ru - BFD: API helpers - - - - false - false - true - false - false - true - false - DontUse - - - diff --git a/bitra-cfe/Configuration.xml b/bitra-cfe/Configuration.xml deleted file mode 100644 index 3410e74..0000000 --- a/bitra-cfe/Configuration.xml +++ /dev/null @@ -1,73 +0,0 @@ - - - - - - 9cd510cd-abfc-11d4-9434-004095e12fc7 - 617fa0c0-9a19-4f15-bebd-1858bb176245 - - - 9fcd25a0-4822-11d4-9414-008048da11f9 - 12af5411-d422-4db1-aebd-095700acce53 - - - e3687481-0a87-462c-a166-9f34594f9bba - 2911c4d3-5fce-4d58-bcbe-b656f73272a9 - - - 9de14907-ec23-4a07-96f0-85521cb6b53b - f3a0b9ca-ad92-40f7-a543-1728863ba9a5 - - - 51f2d5d8-ea4d-4064-8892-82951750031e - e371da3e-ae95-4395-b867-456aaadbe66c - - - e68182ea-4237-4383-967f-90c1e3370bc7 - b7783cb4-7160-4c0b-a329-f7679c9f9bed - - - fb282519-d103-4dd3-bc12-cb271d631dfc - bf401d2b-0f97-4ebe-b962-ef712d65db37 - - - - Adopted - BIT_FlightDeck - - - ru - BIT Flight Deck Read-Only API - - - - AddOn - true - bfd_ - Version8_3_14 - ManagedApplication - - PlatformApplication - - Russian - - Role.bfd_ОсновнаяРоль - - bit-flight-deck - 1.0.0.1 - Language.Русский - - - - - - TaxiEnableVersion8_2 - - - Русский - bfd_ОсновнаяРоль - bfd_IntegrationAPIHelpers - bfd_IntegrationAPI - - - \ No newline at end of file diff --git a/bitra-cfe/HTTPServices/bfd_IntegrationAPI.xml b/bitra-cfe/HTTPServices/bfd_IntegrationAPI.xml deleted file mode 100644 index 4027626..0000000 --- a/bitra-cfe/HTTPServices/bfd_IntegrationAPI.xml +++ /dev/null @@ -1,317 +0,0 @@ - - - - - bfd_IntegrationAPI - - - ru - BFD: Integration API - - - - bfd-api - DontUse - 20 - - - - - Dictionaries - - - ru - Dictionaries - - - - - - - - Get - - - ru - Get - - - GET - DictionariesGet - - - - - - - EvaMappingClients - - - ru - Eva mapping clients - - - - - - - - Get - - - ru - Get - - - GET - EvaMappingClientsGet - - - - - - - Stages - - - ru - Stages - - - - - - - - Get - - - ru - Get - - - GET - StagesGet - - - - - - - Projects - - - ru - Projects - - - - - - - - Get - - - ru - Get - - - GET - ProjectsGet - - - - - - - DeptHistory - - - ru - Dept history - - - - - - - - Get - - - ru - Get - - - GET - DeptHistoryGet - - - - - - - WorkTypes - - - ru - Work types - - - - - - - - Get - - - ru - Get - - - GET - WorkTypesGet - - - - - - - EvaMappingProjects - - - ru - Eva mapping projects - - - - - - - - Get - - - ru - Get - - - GET - EvaMappingProjectsGet - - - - - - - Employees - - - ru - Employees - - - - - - - - Get - - - ru - Get - - - GET - EmployeesGet - - - - - - - ProjectRegister - - - ru - Project register - - - - - - - - Get - - - ru - Get - - - GET - ProjectRegisterGet - - - - - - - Health - - - ru - Health - - - - - - - - Get - - - ru - Get - - - GET - HealthGet - - - - - - - Works - - - ru - Works - - - - - - - - Get - - - ru - Get - - - GET - WorksGet - - - - - - - diff --git a/bitra-cfe/Languages/Русский.xml b/bitra-cfe/Languages/Русский.xml deleted file mode 100644 index 626f509..0000000 --- a/bitra-cfe/Languages/Русский.xml +++ /dev/null @@ -1,13 +0,0 @@ - - - - - - Adopted - Русский - - eb0c1f80-0194-40b4-8447-89fd07487e25 - ru - - - \ No newline at end of file diff --git a/bitra-cfe/README.md b/bitra-cfe/README.md deleted file mode 100644 index 14fa174..0000000 --- a/bitra-cfe/README.md +++ /dev/null @@ -1,225 +0,0 @@ -# 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:////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 - -```bash -# health (без auth тоже работает, но Basic auth нужна для остальных) -curl -u bfd_api_user: http://server.local/bitra/hs/bfd-api/v1/health - -# Сотрудники -curl -u bfd_api_user: http://server.local/bitra/hs/bfd-api/v1/employees | head -c 500 - -# Работы за вчера -curl -u bfd_api_user: "http://server.local/bitra/hs/bfd-api/v1/works?modified_since=$(date -d 'yesterday' '+%Y-%m-%d')" - -# Проекты -curl -u bfd_api_user: http://server.local/bitra/hs/bfd-api/v1/projects | head -c 1000 - -# Этапы -curl -u bfd_api_user: http://server.local/bitra/hs/bfd-api/v1/stages | head -c 500 - -# Виды работ -curl -u bfd_api_user: http://server.local/bitra/hs/bfd-api/v1/work_types - -# Справочники (одним запросом) -curl -u bfd_api_user: http://server.local/bitra/hs/bfd-api/v1/dictionaries | head -c 2000 - -# История подразделений -curl -u bfd_api_user: "http://server.local/bitra/hs/bfd-api/v1/dept_history?modified_since=2024-01-01" | head -c 500 - -# Маппинг EVA проектов (может быть пустым — пользователь подтвердил что интеграция мёртвая) -curl -u bfd_api_user: http://server.local/bitra/hs/bfd-api/v1/eva_mapping/projects -``` - -### 6. Передать команде N8N (роль владельца проекта) - -После успешной публикации передать: -- `BITRA_BASE_URL` — `http:////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` - -```json -[ - { - "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` - -```json -[ - { - "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 - } - ] - } -] -``` - -### Ошибки - -При исключении внутри обработчика возвращается: -```json -{ "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/specs/2026-05-13-mvp1-workload-design.md) -- План: [`../docs/superpowers/plans/2026-05-13-mvp1-workload.md`](../docs/superpowers/plans/2026-05-13-mvp1-workload.md) — Phase 3 -- Решения по транспорту: см. memory `architecture_transport_decisions` diff --git a/bitra-cfe/Roles/bfd_ОсновнаяРоль.xml b/bitra-cfe/Roles/bfd_ОсновнаяРоль.xml deleted file mode 100644 index 6bab539..0000000 --- a/bitra-cfe/Roles/bfd_ОсновнаяРоль.xml +++ /dev/null @@ -1,10 +0,0 @@ - - - - - bfd_ОсновнаяРоль - - - - - \ No newline at end of file diff --git a/bitra-cfe/CommonModules/bfd_IntegrationAPIHelpers/Ext/Module.bsl b/bitra-patch/CommonModules/bfd_IntegrationAPIHelpers/Module.bsl similarity index 90% rename from bitra-cfe/CommonModules/bfd_IntegrationAPIHelpers/Ext/Module.bsl rename to bitra-patch/CommonModules/bfd_IntegrationAPIHelpers/Module.bsl index c13f4fd..3c1caae 100644 --- a/bitra-cfe/CommonModules/bfd_IntegrationAPIHelpers/Ext/Module.bsl +++ b/bitra-patch/CommonModules/bfd_IntegrationAPIHelpers/Module.bsl @@ -1,10 +1,14 @@ //////////////////////////////////////////////////////////////////////////////// -// bfd_IntegrationAPIHelpers +// Общий модуль bfd_IntegrationAPIHelpers // -// Назначение: вспомогательные процедуры/функции для bfd_IntegrationAPI +// Назначение: вспомогательные процедуры/функции для HTTP-сервиса bfd_IntegrationAPI // (read-only REST API для проекта bit-flight-deck). // -// Context: Server, Privileged. +// Свойства модуля (выставить в Конфигураторе): +// Сервер = Истина +// Вызов сервера = Истина +// Внешнее соединение = Истина (для всякого случая) +// Привилегированный = Истина (важно — позволяет читать всё в обход RLS) //////////////////////////////////////////////////////////////////////////////// #Область ПрограммныйИнтерфейс diff --git a/bitra-cfe/HTTPServices/bfd_IntegrationAPI/Ext/Module.bsl b/bitra-patch/HTTPServices/bfd_IntegrationAPI/Module.bsl similarity index 98% rename from bitra-cfe/HTTPServices/bfd_IntegrationAPI/Ext/Module.bsl rename to bitra-patch/HTTPServices/bfd_IntegrationAPI/Module.bsl index aeeb005..db65a0b 100644 --- a/bitra-cfe/HTTPServices/bfd_IntegrationAPI/Ext/Module.bsl +++ b/bitra-patch/HTTPServices/bfd_IntegrationAPI/Module.bsl @@ -1,11 +1,12 @@ //////////////////////////////////////////////////////////////////////////////// // HTTPService bfd_IntegrationAPI — read-only REST API для bit-flight-deck. // -// Корневой URL после публикации: http:////hs/bfd-api/v1/... +// Корневой URL (RootURL) — bfd-api +// После публикации: http:////hs/bfd-api/v1/... // // Все методы GET. Аутентификация Basic (пользователь bfd_api_user). // Ошибки → JSON {"error":"..."} с HTTP-кодом 500. -// Все ID объектов сериализуются как строковый UUID (без префикса класса). +// Все ID объектов сериализуются как строковый UUID без префикса класса. //////////////////////////////////////////////////////////////////////////////// #Область ОбработчикиЗапросов @@ -126,7 +127,7 @@ КонецФункции -// GET /v1/projects?modified_since= +// GET /v1/projects // Функция ProjectsGet(Запрос) Экспорт @@ -234,7 +235,7 @@ КонецФункции -// GET /v1/work_types — значения Enum.ВидыРабот. +// GET /v1/work_types // Функция WorkTypesGet(Запрос) Экспорт @@ -254,7 +255,7 @@ КонецФункции -// GET /v1/dictionaries — справочники с редким обновлением. +// GET /v1/dictionaries // Функция DictionariesGet(Запрос) Экспорт diff --git a/bitra-patch/README.md b/bitra-patch/README.md new file mode 100644 index 0000000..6a371fa --- /dev/null +++ b/bitra-patch/README.md @@ -0,0 +1,274 @@ +# Доработка 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`](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`](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:////hs/bfd-api/v1/ +``` + +Пример (если host=server.local, publication=bitra): +``` +http://server.local/bitra/hs/bfd-api/v1/health +``` + +## Тестирование через curl + +```bash +# Health (Basic auth обязательна для HTTP-сервисов 1С) +curl -u bfd_api_user: http://server.local/bitra/hs/bfd-api/v1/health + +# Сотрудники +curl -u bfd_api_user: http://server.local/bitra/hs/bfd-api/v1/employees | head -c 500 + +# Работы за вчера +curl -u bfd_api_user: "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: http://server.local/bitra/hs/bfd-api/v1/projects | head -c 1000 + +# Виды работ (быстро проверить что аутентификация работает + перечисление читается) +curl -u bfd_api_user: http://server.local/bitra/hs/bfd-api/v1/work_types + +# Справочники одним запросом +curl -u bfd_api_user: http://server.local/bitra/hs/bfd-api/v1/dictionaries | head -c 2000 + +# История подразделений +curl -u bfd_api_user: "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:////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` + +```json +[ + { + "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` + +```json +[ + { + "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 + } + ] + } +] +``` + +### Ошибки + +При исключении внутри обработчика возвращается: +```json +{ "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](CommonModules/bfd_IntegrationAPIHelpers/Module.bsl) — модуль помощников (вставить целиком в одноимённый общий модуль). +- [HTTPServices/bfd_IntegrationAPI/Module.bsl](HTTPServices/bfd_IntegrationAPI/Module.bsl) — модуль HTTP-сервиса (вставить целиком в «Модуль» HTTP-сервиса). + +## Связанные документы + +- Спецификация: [`../docs/superpowers/specs/2026-05-13-mvp1-workload-design.md`](../docs/superpowers/specs/2026-05-13-mvp1-workload-design.md) +- План: [`../docs/superpowers/plans/2026-05-13-mvp1-workload.md`](../docs/superpowers/plans/2026-05-13-mvp1-workload.md) — Phase 3 +- Северная звезда: [`../docs/superpowers/PROJECT_GOAL.md`](../docs/superpowers/PROJECT_GOAL.md)