phase-3: BIT_FlightDeck CFE — HTTPService bfd_IntegrationAPI with 11 GET endpoints

- Configuration.xml: AddOn extension, prefix bfd_, compat Version8_3_14 - CommonModule bfd_IntegrationAPIHelpers (server, privileged): JSON response, ISO date parse, UUID, email extractor, limit parser - HTTPService bfd_IntegrationAPI (rootURL=bfd-api): 11 templates - /v1/health, /v1/employees, /v1/works (+modified_since, +limit) - /v1/projects, /v1/stages, /v1/work_types, /v1/dictionaries - /v1/dept_history (+modified_since), /v1/project_register (+modified_since for MVP-3) - /v1/eva_mapping/projects, /v1/eva_mapping/clients (best-effort from BIT.RA registers) - README with step-by-step instructions for 1C developer - cfe-validate: 0 errors / 0 warnings (13/13 checks)
2026-05-14 19:27:15 +05:00
parent c0e2856412
commit 7da9d9dae1
8 changed files with 1268 additions and 0 deletions
@@ -0,0 +1,225 @@
+# 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
+
+```bash
+# 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`
+
+```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`