Skip to content

# 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)

1. Seller Agent - Менеджер з продажу
2. Customer Care Agent - Служба підтримки

#### 💰 Фінанси (Finance)

1. Finance & Pricing Agent - Бухгалтерія та ціноутворення

#### 📢 Маркетинг (Marketing)

1. SMM & Campaigns Agent - Соціальні мережі та кампанії
2. SEO & Web Experience Agent - SEO та веб-досвід

#### 📊 Аналітика та governance (Analytics & Governance)

1. Analytics & BI Agent - Аналітика даних
2. Compliance & Audit Agent - Аудит та compliance

#### 🚀 Успіх клієнтів (Success)

1. 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. Чекліст успішного запуску

Виклик:

    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. Повідомлення клієнта

Виклик:

    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. Персоналізовані рекомендації комітентам

Виклик:

    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

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

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

    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