# 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`