phase-3: replace CFE with main-config patch (per user request)

User decided to patch the main BIT.RA configuration instead of installing an extension. - bitra-cfe/ removed in previous step - bitra-patch/ added with BSL files for direct copy-paste into Configurator: - CommonModules/bfd_IntegrationAPIHelpers/Module.bsl (134 lines) — privileged server helpers - HTTPServices/bfd_IntegrationAPI/Module.bsl (478 lines) — 11 GET handlers - README.md (274 lines): step-by-step Configurator instructions: - object properties (CommonModule flags, HTTPService rootURL, URL templates, methods) - role permissions matrix (15 BIT.RA objects + HTTPService + CommonModule) - user bfd_api_user creation - Apache publication - curl tests for each endpoint
2026-05-14 19:42:48 +05:00
parent 7da9d9dae1
commit f70bbf53f3
9 changed files with 287 additions and 669 deletions
@@ -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://<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)