bit-flight-deck/bitra-patch/README.md

# Доработка 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://<host>/<publication-name>/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:<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`

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