3de3c8cb36
- matrix-gateway: POST /internal/matrix/presence/online endpoint - usePresenceHeartbeat hook with activity tracking - Auto away after 5 min inactivity - Offline on page close/visibility change - Integrated in MatrixChatRoom component
464 lines
17 KiB
Markdown
464 lines
17 KiB
Markdown
# 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*
|
||
|