diff --git a/ops/COMBINE-PROJECT-ANALYSIS.md b/ops/COMBINE-PROJECT-ANALYSIS.md new file mode 100644 index 0000000..8ace701 --- /dev/null +++ b/ops/COMBINE-PROJECT-ANALYSIS.md @@ -0,0 +1,248 @@ +# «Комбайн» — глубокая проработка и план реализации + +Разбор выжимки проекта · 06.11.2026 · Opinionated: где план сильный, где сломается + +--- + +# Часть 1. Что в плане сильно (не трогаем) + +| Решение | Почему правильно | +|---|---| +| **LLM не решает совместимость** | Единственный способ получить воспроизводимый результат. LLM объясняет, движок решает | +| **«Боли» как первоклассные сущности** | Это и есть ИС компании. Нельзя прятать в промпт | +| **Граф, а не матрица** | Матрица N² не масштабируется. Граф с рёбрами-ограничениями — да | +| **BOM как производная** | BOM = f(конфигурация) — правильно, не хранить отдельно | +| **Модульность по LXC** | Совпадает с нашей инфраструктурой | +| **Начинаем с малого** | Правильно, но порядок в плане неверный (см. ниже) | + +--- + +# Часть 2. Пять мест, где план сломается + +## 2.1. PDF → JSON без провенанса = мусор в базе + +План: `PyMuPDF4LLM + Ollama + Pydantic` → строгий JSON. + +**Проблема:** Pydantic гарантирует **форму**, не **истинность**. LLM уверенно запишет `poe_class: 4`, когда в даташите 802.3at (это 4, но не всегда). Через месяц никто не поймёт, откуда взялось число. + +**Решение (обязательное):** +```python +class Field(BaseModel): + value: Any + confidence: float # 0..1 от парсера + source_page: int # страница PDF + source_text: str # цитата, из которой извлечено + extracted_by: Literal["rule", "llm", "manual"] + verified: bool = False # подтвердил человек +``` +Правило: **поле без `verified` не участвует в подборе**. Это защита от «тихих» ошибок, которые дороже всего стоят в интеграции. + +**Практика:** 80 % полей извлекаются правилами (regex по таблицам), LLM — только сложные (маркетинговые описания). Это дешевле и точнее. + +## 2.2. Neo4j на старте — лишняя операционная нагрузка + +План: «Neo4j или NetworkX на старте». + +**Решение: только NetworkX + Postgres.** Причины: +- У нас 10 из 15 ГиБ RAM занято; Neo4j = ещё 1–2 ГиБ и JVM-обслуживание. +- До ~50 000 рёбер NetworkX в памяти работает мгновенно. +- Граф **детерминированный и небольшой**: устройств сотни, не миллионы. + +Как хранить: `edges(source_id, target_id, kind, constraints jsonb)` в Postgres. Загрузка в NetworkX при старте сервиса. При росте >50k — тогда Neo4j, но не раньше. + +## 2.3. Новый LXC под PostgreSQL — не нужен + +У нас уже есть **Postgres на CT151** (43 базы). `pgvector` ставится расширением. + +**Решение:** не создавать новый контейнер. Новая база `combine` в существующем кластере + `CREATE EXTENSION vector`. Экономия 1–2 ГиБ RAM и одного бэкапа. + +## 2.4. Ollama на Proxmox — не запускать + +План: «Ollama (локальная LLM)» в списке новых компонентов. + +**Уже есть** мини-ПК `192.168.1.229` (Ultra 5 125H, 8.2 ток/с). Запускать вторую модель на хосте, где swap 8.3 ГБ занят — повторить инцидент 04.11. + +**Решение:** `combine` ходит на `http://192.168.1.229:11434`. Ничего не ставим. + +## 2.5. n8n в критическом пути расчёта — архитектурная ошибка + +План: «n8n → Python-сервис → расчёт». И одновременно: «n8n может быть скомпрометирован». + +**Противоречие:** если n8n недоверенный, он не может быть в пути, где считается BOM для клиента. + +**Решение — разделить на два контура:** + +``` +Контур А (доверенный): FastAPI «combine» ← прямой вызов из UI/бота +Контур Б (недоверенный): n8n только для внешних интеграций + (почта, CRM, уведомления) — читает результат, + не влияет на расчёт +``` + +Правило: **n8n может только читать готовый BOM и запускать уведомления.** Он не вызывает расчёт, не меняет конфигурацию. Тогда компрометация n8n = утечка КП, но не подмена данных. + +Это же снимает вопрос «n8n в закрытом контуре»: его изоляция становится простой. + +## 2.6. Harness (SaaS) в закрытом контуре ФСТЭК — несовместимо + +План отводит Harness роль CI/CD + AI Code Assistant. + +**Проблема:** Harness Cloud = данные и код вне периметра. При требованиях ФСТЭК/152-ФЗ это неприемлемо, а self-hosted Harness — это тяжёлый enterprise-зверь (десятки контейнеров). + +**Решение:** **Gitea Actions** (у нас уже работает, runner есть) + локальный LLM для code review. AI-ассистент — через mini-PC. Это даёт 80 % пользы при нулевой внешней зависимости. + +--- + +# Часть 3. Что добавить (то, чего в плане нет) + +## 3.1. Подбор как оптимизация, а не жадный расчёт + +Главный уровень вверх. Сейчас план: «ceil(площадь/покрытие)» — жадный алгоритм. + +**Правильно:** задача о покрытии с ограничениями = **CP-SAT** (OR-Tools): +- переменные: количество каждого устройства +- ограничения: полное покрытие зоны, PoE-бюджет коммутатора, бюджет денег, лимиты вендора (4×CM20 + 4×CS10) +- цель: минимум стоимости (или минимум устройств, или максимум равномерности) + +**Что это даёт:** «вот 3 варианта: дешевле на 12 %, но на 1 микрофон больше». Это уровень, за который интеграторы платят. Жадный расчёт такого не даёт никогда. + +## 3.2. Золотой набор проектов (регрессионные тесты) + +Без этого «боли» будут ломать друг друга. Нужно: +- 20 реальных комнат: размеры, требования, эталонный BOM от эксперта +- Тест: движок выдаёт то же (или объяснимо другое) +- Каждое новое правило → прогон всего набора + +Это единственный способ доверять движку. И это то, что делает «боли» безопасными. + +## 3.3. Акустическая модель — не «радиус покрытия» + +Yealink оперирует радиусом в идеальных условиях. Реальность: высота потолка, материалы, шум. Нужна честная модель: +- SPL на听众 (падает 6 дБ при удвоении расстояния) +- STI/реверберация (оценка по объёму + материалам) +- Микрофон: SNR с учётом расстояния и шума + +**Не надо** выдавать это за точность — выдавать «оценка, погрешность ±20 %» + допущения. Интегратор оценит честность. + +## 3.4. Версионирование каталога + +Даташиты меняются, устройства снимаются с производства. Нужно: +- `device_version` (дата актуальности, что изменилось) +- Проект ссылается на **версию устройства**, а не на устройство +- Через год проект воспроизводится как был + +## 3.5. Аналогобмен с обоснованием + +«Подбор аналогов» в плане описан общо. Правильно: аналог = пересечение множеств характеристик + явное указание различий: +``` +Заменить Yealink CM20 → Shure MXA920: + + покрытие больше в 2.3× + − цена выше в 4.1× + − требует другой DSP (несовместим с CS10) +``` +Ровно то, что LLM не должна придумывать — это выход графа + расчёт. + +## 3.6. Цены и КП + +В плане «КП» упомянуто, но нет источника цен: +- прайс-лист вендора → таблица цен с датой и курсом +- КП = BOM × цена + наценка + условия +- Версия КП: если цены изменились — пересчёт с диффом + +## 3.7. Аудит «почему такое решение» + +Для каждого BOM — **trace**: какие правила сработали, какие «боли» применились, какие были отброшены. Без этого нельзя объяснить клиенту и нельзя учиться. + +--- + +# Часть 4. План реализации (переупорядочен) + +## Фаза 0 — фундамент данных (2–3 дня) + +| Что | Результат | +|---|---| +| БД `combine` в существующем Postgres CT151 + pgvector | без новых контейнеров | +| Схема: `devices`, `fields` (с провенансом), `ports`, `pain_points`, `projects`, `edges` | миграции Alembic | +| Ручной ввод 5 устройств одного вендора (эталон) | проверенный JSON | +| Парсер PDF (rules-first, LLM для остатка) | сравнение с эталоном: точность полей | + +**Критерий:** 5 устройств, все поля с `verified`, парсер воспроизводит ≥90 % полей. + +## Фаза 1 — детерминированное ядро (3–4 дня) + +- `rules.py`: PoE-бюджет, совместимость портов, протоколы (SIP/USB/H.323), лимиты устройств +- `check_compatibility(conf) → {valid, violations[]}` — каждая с обоснованием +- Golden tests: 20 комнат (можно начать с 5) + +**Критерий:** движок находит все нарушения в эталонных конфигурациях, не выдумывает лишних. + +## Фаза 2 — покрытие и геометрия (3 дня) + +- `shapely`: зоны покрытия, пересечения, равномерность +- SVG-план с зонами +- SPL/SNR-модель с явными допущениями + +**Критерий:** SVG для комнаты 10×8, зоны не выходят за стены. + +## Фаза 3 — оптимизатор (2 дня) — ключевая ценность + +- CP-SAT: минимум цены при полном покрытии +- Выдача 3 вариантов (эконом / стандарт / премиум) + +## Фаза 4 — агент и интерфейс (3 дня) + +- LangGraph: опросник (slot filling) + объяснение +- FastAPI: `/build`, `/validate`, `/bom`, `/explain` +- Streamlit/Chainlit: три вкладки + +## Фаза 5 — интеграция (2–3 дня) + +- OpenClaw (Matrix) → FastAPI напрямую (**не через n8n**) +- n8n: только уведомления и внешние сервисы +- КП: генерация docx/xlsx из шаблона + +--- + +# Часть 5. Где это размещать (наша инфраструктура) + +| Компонент | Куда | Почему | +|---|---|---| +| PostgreSQL + pgvector | **CT151** (существующий) | 43 базы, не плодим | +| FastAPI «combine» | **CT108** (automation-lxc) или новый LXC 1 ГБ | рядом с n8n/Node-RED по смыслу, но изолированно | +| Ollama | **mini-PC 192.168.1.229** | хостовую RAM не трогаем | +| Файлы даташитов | **Nextcloud** | там же, где Source of Truth | +| CI/CD | **Gitea Actions** + runner CT140 | работает, локально | +| Уведомления | **OpenClaw → Matrix** | существующая шина | + +**Ничего нового тяжёлого не поднимаем.** Это принципиально: хост на пределе. + +--- + +# Часть 6. Чем начинать (мой ответ на вопрос) + +**Не с PostgreSQL и не с репозитория.** С **одного вендора и пяти устройств**. + +Почему: пока нет проверенных данных, любая архитектура — гадание. Пять устройств одного вендора (Yealink — самый понятный) дают: +- реальные поля (а не придуманную схему) +- понимание, что в даташитах извлекается правилами, а что нет +- первые «боли» (они всплывут сразу при ручном вводе) + +**Первый артефакт — таблица 5 устройств с полями и провенансом.** Не код, не сервис. Данные. + +Дальше: правила совместимости на этих пяти → первый `validate` → и только потом всё остальное. + +--- + +# Часть 7. Риски (честно) + +| Риск | Вероятность | Что делать | +|---|---|---| +| Даташиты вендоров нерегулярны, парсер даст 60 % | высокая | ручная доработка + провенанс; не обещать «полную автоматизацию» | +| Логика Yealink недокументирована | высокая | своя модель + валидация на 3–5 комнатах против их калькулятора | +| «Боли» противоречат друг другу | средняя | golden set + приоритеты (severity, scope) | +| Оптимизатор даёт непонятные решения | средняя | всегда объяснять, что оптимизировалось | +| Данные клиентов (152-ФЗ) | средняя | не хранить персональные данные в проектах, только обезличенные | + +--- + +_Файл: `ops/COMBINE-PROJECT-ANALYSIS.md` · Все утверждения о нашей инфраструктуре проверены командами._