# GREENFOOD Crew - Документація

**Версія**: 1.0.0  
**Дата**: 2025-11-18  
**Статус**: Ready for Development

---

## Огляд

GREENFOOD Crew — це команда з 13 спеціалізованих AI-агентів для управління ERP-системою крафтових виробників продуктів харчування. Система забезпечує повний цикл від onboarding виробника до доставки товару покупцю та фінансових розрахунків.

---

## Архітектура

### Головний оркестратор

**GREENFOOD Assistant** — єдина точка входу для всіх користувачів системи. Розпізнає роль користувача, виявляє намір та делегує завдання відповідним доменним агентам.

### 12 доменних агентів

Агенти організовані за функціональними доменами:

#### 🏭 Операційні агенти (Operations)
1. **Product & Catalog Agent** - Каталог товарів
2. **Batch & Quality Agent** - Партії та контроль якості
3. **Warehouse Agent** - Управління складами
4. **Logistics & Delivery Agent** - Логістика та доставка

#### 💼 Продажі та підтримка (Sales & Support)
5. **Seller Agent** - Менеджер з продажу
6. **Customer Care Agent** - Служба підтримки

#### 💰 Фінанси (Finance)
7. **Finance & Pricing Agent** - Бухгалтерія та ціноутворення

#### 📢 Маркетинг (Marketing)
8. **SMM & Campaigns Agent** - Соціальні мережі та кампанії
9. **SEO & Web Experience Agent** - SEO та веб-досвід

#### 📊 Аналітика та governance (Analytics & Governance)
10. **Analytics & BI Agent** - Аналітика даних
11. **Compliance & Audit Agent** - Аудит та compliance

#### 🚀 Успіх клієнтів (Success)
12. **Vendor Success Agent** - Менеджер успіху комітентів

---

## Ролі та відповідальність агентів

### 1. GREENFOOD Assistant
**Роль**: Фронтовий оркестратор  
**Мета**: Розуміти користувача, виявляти намір, делегувати завдання  
**Ключові функції**:
- Ідентифікація ролі користувача (комітент, складський, логіст, бухгалтер, маркетолог, покупець)
- Перетворення запиту на чітку дію
- Координація роботи доменних агентів
- Формування зрозумілих результатів для користувача

**Делегування**: Так (може делегувати іншим агентам)

---

### 2. Product & Catalog Agent
**Роль**: Менеджер каталогу товарів  
**Мета**: Підтримувати чистий, структурований каталог без дублів  
**Ключові функції**:
- Створення та редагування карточок товарів
- Перевірка дублікатів
- Управління атрибутами (вага, склад, алергени, строк придатності)
- Управління медіа (фото, відео)

**Інструменти (TODO)**:
- ProductCatalogAPI
- ImageUploadTool
- DuplicateDetectorTool

---

### 3. Batch & Quality Agent
**Роль**: Менеджер партій та якості  
**Мета**: Забезпечити трасованість партій та контроль якості  
**Ключові функції**:
- Створення та відстеження партій товарів
- Контроль строків придатності
- Управління статусами партій (на складі, в дорозі, реалізована, прострочена)
- Фіксація інцидентів якості та рекламацій

**Інструменти (TODO)**:
- BatchTrackingAPI
- QualityCheckTool
- ExpiryAlertTool

---

### 4. Vendor Success Agent
**Роль**: Менеджер успіху комітентів  
**Мета**: Швидкий запуск та зростання виробників  
**Ключові функції**:
- Onboarding нових комітентів (чеклісти, документи)
- Виявлення слабких місць (порожній каталог, відсутні фото)
- Проактивні рекомендації для покращення
- Моніторинг метрик успіху

**Інструменти (TODO)**:
- VendorOnboardingAPI
- ChecklistTool
- RecommendationEngine

---

### 5. Warehouse Agent
**Роль**: Начальник складу  
**Мета**: Коректні та актуальні залишки товарів  
**Ключові функції**:
- Управління залишками товарів
- Фіксація руху товарів (прихід, переміщення, відвантаження)
- Структурування складу (зони, стелажі, температурні зони)
- Сигналізація про критичні залишки

**Інструменти (TODO)**:
- WarehouseAPI
- InventoryTool
- StockMovementTool
- ZoneManagementTool

---

### 6. Logistics & Delivery Agent
**Роль**: Логіст і диспетчер  
**Мета**: Мінімальні затримки та витрати на доставку  
**Ключові функції**:
- Створення маршрутів доставки
- Управління статусами доставок
- Інтеграція з перевізниками (API)
- Формування трек-номерів

**Інструменти (TODO)**:
- LogisticsAPI
- DeliveryTrackerTool
- CourierIntegrationTool

---

### 7. Seller Agent
**Роль**: Менеджер з продажу  
**Мета**: Допомога в оформленні замовлень та підборі товарів  
**Ключові функції**:
- Формування кошика замовлення
- Пропозиції альтернатив, апсели, крос-сели
- Перевірка можливості виконання замовлення
- Розуміння контексту клієнта (роздріб/опт, новий/постійний)

**Інструменти (TODO)**:
- SalesAPI
- BasketTool
- RecommendationEngine
- PricingTool

---

### 8. Customer Care Agent
**Роль**: Служба підтримки  
**Мета**: Швидко вирішувати проблеми клієнтів  
**Ключові функції**:
- Ідентифікація клієнта та його замовлення
- Відповіді на питання (статус, доставка, повернення)
- Фіксація рекламацій та причин повернень
- Пропозиція наступних кроків

**Інструменти (TODO)**:
- SupportAPI
- OrderLookupTool
- ComplaintTool
- TicketingTool

---

### 9. Finance & Pricing Agent
**Роль**: Бухгалтер і фінансовий стратег  
**Мета**: Прозорі взаєморозрахунки та здорова економіка  
**Ключові функції**:
- Ведення балансів учасників
- Моделі ціноутворення (опт, роздріб, акції, промокоди)
- Розрахунок комісій та виплат
- Робота з токенами (DAAR/DAARION) та фіатом

**Інструменти (TODO)**:
- FinanceAPI
- PricingEngine
- BalanceTool
- PayoutCalculator

---

### 10. SMM & Campaigns Agent
**Роль**: Маркетолог та контент-агент  
**Мета**: Просування товарів через цифрові канали  
**Ключові функції**:
- Створення контенту для соцмереж, розсилок, банерів
- Перевірка наявності товарів перед промо
- Планування кампаній з чіткою метою
- Честна комунікація без маніпуляцій

**Інструменти (TODO)**:
- ContentGeneratorTool
- CampaignAPI
- SocialMediaTool
- ImageGeneratorTool

---

### 11. SEO & Web Experience Agent
**Роль**: SEO-оптимізатор  
**Мета**: Видимість в пошуку та зрозумілість для користувачів  
**Ключові функції**:
- Оптимізація заголовків, описів, метаданих
- Покращення структури контенту
- Використання реальних даних про товари
- Блоки довіри, FAQ, structured data

**Інструменти (TODO)**:
- SEOAnalyzerTool
- MetaGeneratorTool
- ContentStructureTool

---

### 12. Analytics & BI Agent
**Роль**: Аналітик даних  
**Мета**: Перетворення даних на actionable insights  
**Ключові функції**:
- Формування зрозумілих звітів
- Виявлення трендів, сезонності, аномалій
- Пропозиції варіантів дій із вказанням ризиків
- Роз'яснення в простих термінах

**Інструменти (TODO)**:
- AnalyticsAPI
- ReportGeneratorTool
- TrendAnalyzerTool
- ForecastingTool

---

### 13. Compliance & Audit Agent
**Роль**: Внутрішній аудитор  
**Мета**: Відповідність політикам та здоровій бізнес-логіці  
**Ключові функції**:
- Аналіз логів подій (зміни цін, списання, повернення)
- Виявлення ризикових операцій
- Формування попереджень та рекомендацій
- Нейтральний, фактичний стиль

**Інструменти (TODO)**:
- AuditLogTool
- RiskDetectorTool
- ComplianceCheckerTool

---

## Команди (Crews) для бізнес-сценаріїв

### 1. Onboard Vendor Crew
**Мета**: Запуск нового комітента (виробника)  
**Агенти**: GREENFOOD Assistant, Vendor Success, Product & Catalog, Warehouse, Finance & Pricing  
**Етапи**:
1. Привітання та збір інформації
2. Створення карточок товарів
3. Налаштування складу та партій
4. Налаштування фінансів та ціноутворення
5. Чекліст успішного запуску

**Виклик**:
```python
from services.greenfood.crew.greenfood_crews import GREENFOOD_CREWS, GREENFOOD_TASK_CREATORS

vendor_data = {
    "name": "Еко Мед Карпати",
    "products": ["Гірський мед", "Мед з липи", "Мед з акації"],
    "contact": "...",
}

tasks = GREENFOOD_TASK_CREATORS["onboard_vendor"](vendor_data)
crew = GREENFOOD_CREWS["onboard_vendor"]
crew.tasks = tasks
result = crew.kickoff()
```

---

### 2. Fulfill Order Crew
**Мета**: Виконання замовлення від прийняття до доставки  
**Агенти**: GREENFOOD Assistant, Seller, Warehouse, Logistics, Customer Care, Finance & Pricing  
**Етапи**:
1. Прийняття замовлення
2. Формування та підтвердження кошика
3. Резервація товарів на складі
4. Створення маршруту доставки
5. Фінансові проводки
6. Повідомлення клієнта

**Виклик**:
```python
order_data = {
    "customer_name": "Іван Петренко",
    "items": [{"product_id": "123", "quantity": 2}],
    "delivery_address": "м. Львів, вул. Шевченка 1",
}

tasks = GREENFOOD_TASK_CREATORS["fulfill_order"](order_data)
crew = GREENFOOD_CREWS["fulfill_order"]
crew.tasks = tasks
result = crew.kickoff()
```

---

### 3. Monthly Settlement Crew
**Мета**: Місячні звіряння та розрахунки  
**Агенти**: GREENFOOD Assistant, Finance & Pricing, Analytics & BI, Compliance & Audit, Vendor Success  
**Етапи**:
1. Ініціація процесу звіряння
2. Формування аналітичних звітів
3. Розрахунок фінансових показників та актів звіряння
4. Audit та виявлення ризиків
5. Персоналізовані рекомендації комітентам

**Виклик**:
```python
period_data = {
    "period": "2025-11",
    "vendors": ["vendor_1", "vendor_2"],
}

tasks = GREENFOOD_TASK_CREATORS["monthly_settlement"](period_data)
crew = GREENFOOD_CREWS["monthly_settlement"]
crew.tasks = tasks
result = crew.kickoff()
```

---

### 4. Marketing Campaign Crew (додатковий)
**Мета**: Запуск маркетингової кампанії  
**Агенти**: GREENFOOD Assistant, Warehouse, SMM & Campaigns, SEO & Web, Finance & Pricing, Analytics & BI  
**Етапи**:
1. Прийняття запиту на кампанію
2. Перевірка наявності товарів
3. Створення контенту
4. SEO-оптимізація посадкових сторінок
5. Налаштування цін та промокодів
6. Налаштування відстеження KPI

---

## Зв'язки між агентами

### Найчастіші взаємодії

```
GREENFOOD Assistant (центральний хаб)
    ├── Product & Catalog ←→ Batch & Quality
    ├── Warehouse ←→ Logistics & Delivery
    ├── Warehouse ←→ Batch & Quality
    ├── Seller ←→ Warehouse
    ├── Seller ←→ Finance & Pricing
    ├── Customer Care ←→ Logistics
    ├── SMM & Campaigns ←→ Warehouse
    ├── SMM & Campaigns ←→ SEO & Web
    ├── Analytics & BI ←→ (всі агенти)
    ├── Compliance & Audit ←→ (всі агенти)
    └── Vendor Success ←→ (всі агенти)
```

---

## Інтеграція з DAGI Router

### Додавання в router-config.yml

```yaml
agents:
  greenfood:
    description: "GREENFOOD Assistant - ERP orchestrator"
    default_llm: local_qwen3_8b
    system_prompt: |
      Ти — GREENFOOD Assistant, фронтовий оркестратор ERP-системи...
```

### Виклик через Router

```python
from router_client import send_to_router

response = await send_to_router({
    "mode": "crew",
    "agent": "greenfood",
    "message": "Онбордь нового комітента 'Еко Мед Карпати'",
    "metadata": {
        "scenario": "onboard_vendor",
        "vendor_data": {...},
    },
})
```

---

## Файлова структура

```
services/greenfood/
├── __init__.py
└── crew/
    ├── __init__.py
    ├── greenfood_prompts.py      # 13 системних промтів
    ├── greenfood_agents.py       # 13 агентів
    └── greenfood_crews.py        # 4 crews + task creators
```

---

## Наступні кроки

### Фаза 1: Базова інтеграція
- [ ] Підключити GREENFOOD Assistant до DAGI Router
- [ ] Протестувати базовий діалог
- [ ] Додати інструменти (tools) для агентів

### Фаза 2: Інструменти та API
- [ ] Реалізувати ProductCatalogAPI
- [ ] Реалізувати WarehouseAPI
- [ ] Реалізувати FinanceAPI
- [ ] Додати інтеграції з зовнішніми сервісами

### Фаза 3: Crews та workflows
- [ ] Протестувати onboard_vendor_crew
- [ ] Протестувати fulfill_order_crew
- [ ] Протестувати monthly_settlement_crew
- [ ] Додати monitoring та logging

### Фаза 4: UI та UX
- [ ] Web-інтерфейс для комітентів
- [ ] Дашборди для різних ролей
- [ ] Mobile app для складських та логістів
- [ ] Інтеграція з Telegram для швидких запитів

---

## Контакти та підтримка

**Репозиторій**: `/Users/apple/github-projects/microdao-daarion`  
**Модуль**: `services/greenfood/crew`  
**Версія crewAI**: 0.28.0+  
**Python**: 3.11+

---

*Документ створено: 2025-11-18*  
*Останнє оновлення: 2025-11-18*