# OKKA Business OS — Product Blueprint v0.1
**Дата:** 6 листопада 2026  
**Статус:** концепція та демонстраційний прототип; НЕ робоча інтеграція з OKKA.  
**Перший клієнт:** OKKA Security — сервісні послуги Charlotte / Matthews, NC.  
**Довгострокова ідея:** white-label / multi-tenant Business OS для локальних сервісних компаній у США.

## 1. Продуктова обіцянка
Одна зрозуміла панель, яка показує власнику **клієнтів, гроші, роботу, ризики й одну наступну дію**. Система автоматизує рутинні переходи, повідомлення, збір даних, звіти й підготовку рішень. Фінансово важливі, юридично значущі та клієнтські дії залишаються під контролем людини.

**Три питання для власника:**
1. Що відбувається з моїм бізнесом?
2. Де я втрачаю клієнтів, час або гроші?
3. Яку одну дію варто підтвердити зараз?

**Цільове позиціювання:** не «ще одна CRM», а *AI Operations Copilot for Service Businesses*. Це робоча гіпотеза, унікальність і готовність платити потребують перевірки з покупцями.

## 2. Життєвий цикл клієнта
**Потреба → Пошук → Довіра → Заявка → Кваліфікація → Діагностика → Презентація рішення → Заперечення → Кошторис → Схвалення → Замовлення обладнання → Планування → Монтаж → Тести / акт приймання → Рахунок / оплата → Підтримка → Відгук → Повторний продаж / рекомендація.**

Для кожного переходу система має зберігати час, виконавця, статус, автоматичні події, наступний крок та винятки (немає відповіді, відмова, відсутнє обладнання, рекламація, прострочена оплата).

## 3. Модулі, вимоги та пріоритети
| Модуль | MVP (перша перевірка) | Після підтвердження процесу |
|---|---|---|
| Owner Dashboard | виручка, валовий прибуток (лише якщо є собівартість), ліди, прострочення, next actions | прогноз грошового потоку, динамічні KPI |
| CRM / Pipeline | картки клієнтів; статуси; історія; відповідальний; джерело; контроль строків | дублікати, scoring, кілька бізнес-ліній |
| Sales | діагностика потреб, шаблони estimate, ручне затвердження, follow-up | e-signature, каталоги й пакетні пропозиції |
| Procurement / Jobs | кошторис → замовлення → закупівлі → графік → чекліст монтажу → завершення | склад, постачальники, бригади, маршрути |
| Invoicing | рахунок, статус і облік оплати; контроль неоплаченого | платіжний провайдер, бухгалтерська синхронізація |
| Customer Success | контроль якості, відгук, сервіс, повторне звернення | плани обслуговування, рекомендації |
| SEO & Local Marketing | структура сторінок послуг і міст, ключові слова, Google Business Profile, Search Console | AI drafts, content calendar, SEO experiments |
| Ads | відмітка джерела ліда, UTM, ручний бюджет | Google Ads/Meta OAuth API, conversion upload після consent |
| Attribution / Analytics | first/last known source, ROI за підтвердженими продажами | складніші attribution models, cohort/LTV |
| AI Advisory | підготовка текстів; пояснення вузьких місць; next-best-action, лише після перевірки | керована автоматизація рекомендованих дій |
| Integrations | безпечні імпорти/експорти, журнал синхронізації | OAuth, webhooks, Google/Meta/Telegram/API |
| White-label | брендинг, назва компанії, місто, перелік послуг | multi-tenant із фізичною/логічною ізоляцією даних, тарифи |
| Security | ролі, audit log, backup, MFA, least privilege, sandbox/staging | розширені політики retention, SOC2-підготовка |

## 4. Один клік для людини: приклади
- **Новий лід:** система класифікує заявку й готує відповідь → власник натискає **Approve reply** → надсилання тільки через дозволений канал, із журналом.
- **Кошторис готовий:** система перевіряє наявність обов'язкових даних → власник натискає **Approve estimate** → відправлення та постановка наступного завдання.
- **Оплачений контракт:** після підтвердженої оплати автоматично створити job checklist і чернетку закупівель → власник/диспетчер підтверджує.
- **Реклама:** AI пропонує зменшити витрати на неефективну кампанію → власник натискає **Approve budget change**; жорсткий максимальний бюджет, журнал, можливість відкоту.
- **Відгук:** після позитивного підтвердження виконання — дозволений, ненав'язливий запит відгуку, не пов'язуючи його з оцінкою або винагородою.

## 5. Атрибуція доходу
Рекомендовані зв'язки: `visit/session → campaign/utm → lead_id → contact_id → estimate_id → job_id → invoice_id → payment_id → cost lines`. Зберігаємо невідомі джерела як `unknown`; не вигадуємо ключове слово, якщо платформа його не передала. SEO-запити Search Console — переважно агреговані дані, їх не можна безпомилково приписати окремому клієнтові. Власнику показуємо **величини з чітко названим знаменником і періодом**.

## 6. Модель даних — мінімальні сутності
`tenants`, `users`, `roles`, `customers`, `leads`, `lead_events`, `campaigns`, `traffic_sources`, `estimates`, `estimate_items`, `jobs`, `job_tasks`, `inventory_items`, `purchase_orders`, `invoices`, `payments`, `reviews`, `service_plans`, `automations`, `action_approvals`, `integration_accounts`, `sync_logs`, `audit_logs`.

Кожна бізнес-сутність у multi-tenant версії має контроль `tenant_id`. Проста зміна логотипа **не** перетворює CRM на безпечний SaaS: потрібні ізоляція, ролі, onboarding, білінг, розподіл інтеграцій і налаштування приватності.

## 7. Технічна стратегія
**Не переробляємо production без аналізу коду.** Наявний сайт OKKA, за словами власника, має кастомну CRM у бек-офісі; її актуальний вихідний код ще не перевірено. У файлах знайдено конфігурацію `.htaccess` для домену OKKA; окремий документ із назвою CRM стосується **On Time Flooring**, а не OKKA, і не є підтвердженням реалізації OKKA. Починаємо зі staging-копії та міграцій, зберігаючи дані й форму заявок.

**Початкова технічна гіпотеза:** якщо поточний код PHP/MySQL підтримуваний, еволюційно розширюємо його. Дорогий SaaS, сервери, n8n, платні AI API та створення власної рекламної платформи не є вимогою першої версії. Якщо код непридатний для підтримки, після аудиту обираємо міграцію з експортом історії й тестуванням.

## 8. Спринти й критерії завершення
**Спринт 0 — аудит і безпека:** резервна копія сайту і БД; локальна/staging-копія; схема БД; карта інтеграцій; перевірка відправки тестової заявки; жодної публічної зміни без дозволу.

**Спринт 1 — наскрізна заявка:** форма → lead_id → contact → статус → відповідальний → чернетка estimate → approved/lost; без втрати лідів. Критерій: тестовий сценарій відпрацьовує та пише audit log.

**Спринт 2 — виконання:** estimate → job → закупівлі → чекліст → рахунок → оплата → запит відгуку; контроль винятків. Критерій: повна тестова угода без ручного дублювання даних.

**Спринт 3 — маркетинг і аналітика:** UTM та джерела, публічний SEO-аудит, GA4/GSC read-only, dashboard, базовий conversion rate. Критерій: кожен тестовий продаж видно у звіті із фактично відомим джерелом або `unknown`.

**Спринт 4 — AI advisory:** drafts, one-click approval, вибір пріоритетної дії; жодного автоматичного списання грошей чи небажаних повідомлень. Критерій: owner може пояснити, чому система рекомендувала дію, і скасувати її.

**Спринт 5 — white-label:** тестовий tenant з іншим брендом, ізольованими записами й окремими інтеграціями. Критерій: tenant A не бачить жодних даних tenant B, перевірено тестами авторизації.

## 9. Дані, потрібні для розробки без ризику
1. **Актуальна копія вихідного коду** OKKA (архів із cPanel або репозиторію), з видаленими паролями, токенами, ключами, файлами клієнтів та особистими даними.
2. **Лише структура MySQL** (`CREATE TABLE` / schema-only), без реальних записів, або тестова БД із вигаданими даними.
3. Список наявних інтеграцій і де вони налаштовані, без секретів.
4. 3–5 **вигаданих** або знеособлених сценаріїв заявок із сумою, статусом і джерелом.
5. Пізніше — підключення до аналітики через офіційний OAuth з мінімальними правами; спочатку read-only. Рекламні витрати й публікації — лише після окремого підтвердження.

## 10. Комерційний тест
Гіпотеза сегмента: локальні сервісні бізнеси (security, low-voltage, HVAC, plumbing, electrical). Спочатку тестуємо OKKA як живий внутрішній кейс, потім показуємо демо 5–10 власникам. Перевіряємо, які процеси вони готові довірити, які метрики їм потрібні та реальну готовність платити. Платні тарифи й заяви про економію вводимо тільки після виміряних результатів.

## 11. Що навмисно не обіцяємо в v0.1
- Автоматично підключені Facebook, Instagram, Google Ads, Google Analytics, Search Console чи платежі.
- Реальний AI: у демо рекомендації імітуються простими правилами; потрібна окрема інтеграція й політика конфіденційності.
- Автоматична зміна живих кампаній або відправка SMS/email.
- Готовий production SaaS або реальні дані OKKA в демонстраційному макеті.
- Гарантія SEO-ранжування, лідів чи прибутковості.

**Наступний блокер:** потрібен саме актуальний, очищений від секретів ZIP сайту OKKA та schema-only експорт MySQL. До цього дизайн і демо можливо розвивати без доступу до сервера.


## 11. Owner Analytics Dashboard v0.2 — нові вимоги (6 листопада 2026)
**Оновлення:** створено прототип `OKKA_Business_OS_Dashboard_v2.html` з великими KPI на головній сторінці, симуляціями 7/30/90 днів, діаграмою джерел, воронкою, таблицею каналів та двома різними режимами ключових слів.

### Метрики Owner Command Center
- Advertising spend: витрати окремо Google Ads / Meta Ads та загалом, із періодом.
- New inquiries: кількість нових звернень з усіх відомих джерел.
- Won customers: кількість фактичних перших/повторних угод; окремий поділ у майбутній версії.
- Attributed revenue: виручка підтверджених продажів; **не** прибуток і не кількість оплат, якщо payment ledger відсутній.
- Cost per paid lead = витрати на платну рекламу / ліди з платних каналів; це не те саме, що витрати / всі ліди.
- Cost per paid customer = витрати на платну рекламу / підтверджені угоди, приписані платним каналам.
- Для фінансового ROI потрібна собівартість матеріалів, роботи, повернень, податків та облік фактичних платежів.

### Ключові слова: строго дві різні аналітики
1. **Paid Search / Google Ads**: кампанія, ad group, keyword, доступні search terms, покази, кліки, витрати, lead conversion та sale conversion (лише за наявності consent, коректних id і conversion mapping). Не всі пошукові запити доступні: Google застосовує обмеження звітності.
2. **Organic Search / Search Console**: query, page, clicks, impressions, CTR, average position, locality where supported. **Не** намагатися безпідставно прив'язати органічний запит до конкретної людини чи продажу. Для конверсій органіки використовувати landing page / source attribution з GA4 та CRM і вказувати точність.

### Customer journey: рівні спостереження
- Source/campaign ID та UTM з допустимою згодою → landing page/event → lead ID → estimate → job → invoice → paid/review/repeat.
- Зберігати `unknown` та `not provided` замість фальшивого «точного» ключового слова.
- Не відстежувати користувача приховано; CMP/consent, cookies, політики та privacy review перед релізом.

### UX вимоги
- Сучасна, чиста та адаптивна панель з 6 великими цифрами, датами, посиланнями в деталізацію; не більше однієї ключової дії для власника в кожному сповіщенні.
- Перемикач 7/30/90 днів, порівняння з попереднім періодом після появи даних.
- Чітко показувати статус інтеграцій та дату останньої синхронізації; якщо немає доступу, **N/A**, не 0.
- На перспективу: поновлювані alert-и «зростає CPL», «незакриті кошториси», «кампанія витрачає бюджет без продажів». AI може готувати, але не публікувати рекламу/змінювати бюджет самостійно.
- У демо KPI і keyword-table використовують **різні, явно підписані фіктивні набори** (ключові слова показані як 30-денний приклад). Жоден рядок не є живою статистикою OKKA.

### API інтеграції та виконання
1. CRM baseline: перевірка реальної схеми й статусів OKKA; уніфіковані lead/source IDs.
2. Google Search Console API + GA4 Data API + Google Business Profile (за доступними API/scope).
3. Google Ads API / Meta Marketing API із правами читання; OAuth, обмеження квот, retry/logs.
4. Match з CRM за UTM, GCLID/GBRAID/WBRAID/FBCLID лише де припустимо, conversion API тільки після перевірки consent.
5. Безпечна аналітична БД з tenant isolation, daily snapshots, збереженням валют/часових зон, власником даних і видимими границями достовірності.
6. Перевірка в staging на вигаданих даних → read-only інтеграції → валідація фінансових метрик → обмежений запуск.