Roman Chesnokov
7da9d9dae1
- 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)
226 lines
12 KiB
Markdown
226 lines
12 KiB
Markdown
# 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`
|