B2B-кабінет компаній та аналітика Viatec
Погоджені вимоги станом на 06.09.2026. Поточний тестовий конструктор працює локально в браузері; централізований реєстр, багатокористувацький доступ та API нижче ще не реалізовані.
Послідовність розвитку
| Етап | Результат | Статус |
|---|---|---|
| 1. Каталог та генерація | Solis, перевірки AC/DC, помісячні профілі PVGIS, графік і таблиця у КП. | Реалізується в тестовому проекті |
| 2. Торгові специфікації | Окремий режим без автоматичного підбору системи: товари, ручні матеріали та роботи, кількість, роздрібна ціна, знижка, ПДВ, доставка/монтаж, PDF; імпорт рядків Excel. | Реалізовано в тестовому проєкті: торгова форма. Імпорт з Excel через CSV; прямий XLSX — наступний крок. |
| 3. B2B-кабінет | Вхід через самописний портал Viatec, компанії, співробітники, власний бренд у КП, централізоване збереження. | Архітектура підготовлена |
| 4. Аналітика та синхронізація | Загальний реєстр Viatec, експорт специфікацій за період, тренди, виробничі каталоги та ERP-ціни/залишки. | Після погодження API та джерел |
| Резервування | Політики строків, лімітів, пріоритетів і підтвердження ERP. | Відкладено; операції резерву не входять у поточний контракт |
Ізоляція компаній та загальний доступ Viatec
Єдина авторизація через B2B-портал. Сервер перевіряє підпис, строк дії та призначення токена і визначає членство користувача в компанії. Переданий браузером company_id сам по собі не надає доступу.
| Роль | Сфера видимості | Дії |
|---|---|---|
| Співробітник партнера | Пропозиції та клієнти своєї компанії | Створення, редагування за правилами компанії, експорт КП; знижки від роздрібної ціни. |
| Адміністратор партнера | Вся своя компанія | Співробітники, логотип, реквізити, контакти, шаблони, доступ до пропозицій своєї компанії. |
| Аналітик Viatec | Реєстр усіх компаній | Фільтри, специфікації, агрегати й експорт за період; без зміни пропозицій партнерів за замовчуванням. |
| Адміністратор Viatec | Усі компанії та системні налаштування | Підключення/блокування компаній, ролі Viatec, каталог, правила, аудит; явні права для адміністративних змін. |
Кожен об’єкт, запит, файл, пошук та експорт обмежується компанією на сервері. Доступ Viatec до всього реєстру надається окремим дозволом, а не відсутністю company_id. Події перегляду та вивантаження реєстру журналюються.
На створенні пропозиції зберігається знімок логотипа, реквізитів, контактів і шаблону компанії. Подальша зміна бренду не переписує видані КП. Завантажені логотипи перевіряються за типом і розміром, зберігаються ізольовано; PDF формується з перевірених локальних ресурсів.
Загальний реєстр, тренди та форекаст
Всі збережені на сервері пропозиції потрапляють до реєстру Viatec, включно з чернетками. Розрізи: компанія, автор, клієнт/проект, область, бренд, SKU, кількість, потужність AC/PV, енергія АКБ, сума, валюта, статус, дата створення, дата останньої зміни та очікуваний місяць закупівлі.
| Вивантаження | Правило |
|---|---|
| Створені за період | Фільтр за created_at; початок включно, кінець виключно. Календарні межі Europe/Kyiv переводяться сервером у UTC. |
| Стан портфеля на дату | Остання релевантна версія кожної пропозиції на заданий момент; активні та архівні статуси показуються окремо. |
| Товарні специфікації | Один рядок = позиція конкретної версії КП. Зовнішні ID компанії, проекту, пропозиції, версії, SKU; кількість, одиниця, роздрібна ціна, знижка, сума без/з ПДВ, дата закупівлі. |
| Варіанти одного проекту | Спільний opportunity_id; альтернативні конфігурації не сумуються. Для форекасту використовується вибраний варіант; невибрані показуються окремо. |
| Форекаст | Попит за SKU та очікуваним місяцем закупівлі; зважений сценарій = кількість × погоджена ймовірність етапу. Видане КП не прирівнюється до замовлення. |
| Підсумки | Валюти не сумуються без зафіксованого курсу/дати. ПДВ і знижки мають окремі поля. Ручні позиції без SKU виділяються окремо. Видалені/програні КП не враховуються як активний попит. |
Експорт CSV/XLSX: фонове завдання, перевірка прав при створенні і завантаженні, посилання з обмеженим строком, однакові фільтри в інтерфейсі та файлі. Текстові значення захищаються від виконання формул у таблицях. Контакти кінцевих клієнтів додаються тільки за відповідним дозволом.
Роздрібні ціни та довільні знижки партнера
База партнера — роздрібна ціна Viatec. Закупівельна ціна партнера та внутрішня маржа Viatec в цей контракт не входять. Партнер задає знижку у відсотках або фіксованою сумою; додаткове погодження скидки зараз не запроваджується.
| Рівень | Розрахунок |
|---|---|
| Рядок | base = round(qty × retail_unit_price). Відсоток: discount = round(base × percent / 100). Фіксована знижка задається на весь рядок, не на одну одиницю. line_net = base − discount. |
| Специфікація | Необов’язкова загальна знижка після рядкових знижок; застосування до обладнання/матеріалів або всіх рядків задається явно. Відсоток та фіксована сума — взаємовиключні режими. |
| Обмеження математики | 0–100% або сума від 0 до бази знижки; від’ємний підсумок неможливий. Довільна знижка не означає довільний некоректний відсоток. Грошові суми зберігаються в копійках/decimal. |
| ПДВ | Зберігаються базис ціни, ставка, режим оподаткування і дата. Ціна з ПДВ спершу нормалізується; ПДВ не додається вдруге. Загальна знижка розподіляється по податкових базах з узгодженим правилом округлення. |
| Історія | Видана версія КП фіксує ціни, джерело, час і валюту. Оновлення прайсу не змінює старі КП: менеджер явно створює нову редакцію з оновленими цінами. |
Торгова специфікація не заявляє працездатності системи. Інженерна перевірка запускається окремою кнопкою, якщо позиції можна зіставити з конфігурацією; фінансові й кількісні перевірки обов’язкові для кожного документа.
Межі інтеграцій
| Джерело | Що отримуємо | Потік та контроль |
|---|---|---|
| B2B-портал Viatec | Обліковий запис, компанія, членство, ролі, блокування | SSO з серверною перевіркою; точний протокол і обмін відкликанням доступу погоджуються з командою порталу. |
| Виробники | Модель, характеристики з одиницями, datasheet, фото, ревізія, сумісність | Адаптер API, якщо доступний, або офіційний файл/каталог → проміжна зона → зміни полів → перевірка → затверджена версія каталогу. API у виробників наразі не надані. |
| ERP / прайс Viatec | SKU, роздрібна ціна, валюта, базис ПДВ, активність товару, залишки по складах, часові мітки | Лише читання на першому етапі. Доступність визначається ERP; фізичний залишок не дорівнює вільному. При помилці показується вік даних і статус недоступності. |
| PVGIS | Генерація та параметри метеоданих | Зараз — зафіксовані регіональні профілі та імпорт PVcalc JSON. Майбутній серверний адаптер: запит по координатах/геометрії, кеш, ліміти, журнал джерела. Прямі AJAX-запити PVGIS не підтримує. |
| ERP-резервування | Не запитується | Відкладено. Збереження, видання або експорт КП не створює резерв і не змінює залишки. |
Пріоритет джерел по полях: виробник — паспорт; Viatec — локальний SKU, ціна, доступність; компанія — власні реквізити та кінцева пропозиція. Невідома характеристика залишається невідомою. Ревізії моделей не зливаються лише за брендом і потужністю.
Фото та datasheet зберігають оригінальну адресу, дату отримання, контрольну суму, ревізію і прив’язку до моделі. Заміна паспорта не переписує історичні КП. Відмінності критичних полів — напруга, струм, PV, паралель, BMS — потребують підтвердження перед використанням у підборі. Ключі інтеграцій залишаються на сервері.
Сутності та пропонований API
Пропонований контракт для обговорення з командою самописного порталу. Це не діючі адреси API.
| Сутність | Основні поля |
|---|---|
| Company / Membership | ID Viatec, назва, реквізити, logo_asset_id; user_id, company_id, роль, стан доступу. |
| Opportunity / Proposal | company_id, клієнт, область, expected_purchase_month; opportunity_id, author_id, режим system/trade, статус, номер, дати. |
| ProposalVersion / Line | Номер редакції, попередня версія, знімок бренду, каталог/ціни, розрахунок генерації з параметрами; SKU або ручна позиція, кількість, одиниця, гроші та знижка. |
| ProductRevision / Asset | Стабільний SKU, manufacturer_model_id, регіон/ревізія, нормалізовані параметри та джерело кожного поля; файл, hash, версія. |
| AuditEvent / IntegrationRun | Хто, компанія, дія, об’єкт/версія, час, correlation_id; адаптер, cursor, результат, помилки і статистика змін. |
| Контракт | Призначення |
|---|---|
GET /v1/me | Перевірений користувач і доступні компанії. |
GET/PATCH /v1/company/branding | Бренд і реквізити своєї компанії; PATCH лише адміністратору компанії. |
GET /v1/catalog | Версія каталогу, джерела, retail price snapshot та availability freshness. |
POST /v1/proposalsGET/PATCH /v1/proposals/{id} | Збереження в межах компанії. PATCH з очікуваною версією; конфлікт → 409, без тихого перезапису. |
POST /v1/proposals/{id}/versionsPOST /v1/proposals/{id}/pdf | Незмінна редакція та PDF за конкретною версією; повторний запит з idempotency key не створює дубль. |
GET /v1/viatec/proposalsPOST /v1/viatec/exports | Загальний реєстр і фоновий експорт для ролей Viatec; фільтри й область дозволів фіксуються. |
GET /v1/generation | Майбутній серверний розрахунок; дозволені параметри, кеш та метадані PVGIS. |
Критерії приймання наступного етапу
- Два користувачі однієї компанії працюють зі спільним реєстром; інша компанія не читає її КП, файли чи експорт навіть за відомим ID.
- Viatec бачить і вивантажує всі дозволені компанії. Партнер не може сам призначити роль Viatec або передати company_id для обходу прав.
- Зміна логотипа, каталогу, роздрібної ціни або генерації не змінює вже видану редакцію КП.
- Однакові вхідні дані дають однакові гроші у формі, JSON, CSV/XLSX і PDF; перевіряються знижки %, фіксована сума, ПДВ та округлення.
- Одночасне редагування виявляє конфлікт; повторний запит не подвоює пропозиції або версії.
- Форекаст не сумує альтернативи й редакції одного проекту; межі періоду перевірені на переходах літнього часу Europe/Kyiv.
- Втрата ERP/API не перетворює невідомі ціну або залишок на нуль; критичні зміни datasheet потрапляють на перевірку.
- Резервування та замовлення залишаються відключеними до окремого погодження правил.
Для початку інтеграції потрібні: схема авторизації порталу, відповідальний технічний контакт, тестове середовище, приклади company/user/SKU/retail/stock, правила доступу Viatec до клієнтських полів та статуси проектів для форекасту.