diff --git a/README.md b/README.md index c19765c..af273f6 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # ![CRM](src/main/resources/META-INF/resources/images/logo.svg) B2B CRM +Languages: [English](README.md) | [Русский](README_ru.md) | [Deutsch](README_de.md) | [Italiano](README_it.md) | [Español](README_es.md) + `B2B CRM` is an enterprise demo application built with Jmix that showcases how to develop **production-ready** business systems including `customers`, `orders`, `invoicing`, `finance` and `analytics`.
It reflects real **ERP/CRM** scenarios and demonstrates best practices in domain modeling, UI, security, and business logic implementation. diff --git a/README_de.md b/README_de.md new file mode 100644 index 0000000..95c45ab --- /dev/null +++ b/README_de.md @@ -0,0 +1,157 @@ +# ![CRM](src/main/resources/META-INF/resources/images/logo.svg) B2B CRM + +Sprachen: [English](README.md) | [Русский](README_ru.md) | [Deutsch](README_de.md) | [Italiano](README_it.md) | [Español](README_es.md) + +`B2B CRM` ist eine Enterprise-Demoanwendung auf Basis von Jmix, die zeigt, wie **produktionsreife** Geschäftssysteme +für `Kunden`, `Aufträge`, `Rechnungsstellung`, `Finanzen` und `Analysen` entwickelt werden.
Sie bildet reale **ERP/CRM**-Szenarien ab und demonstriert +Best Practices für Domänenmodellierung, UI, Sicherheit und die Implementierung von Geschäftslogik. + +## 📑 Inhaltsverzeichnis + +- [Überblick](#-überblick) +- [Technischer Stack](#-technischer-stack) +- [Verwendete Add-ons](#-verwendete-add-ons) +- [Build und Start](#-build-und-start) +- [AI-Assistent](#-ai-assistent) +- [Demo-Daten](#-demo-daten) +- [Konten](#-anwendungskonten) +- [Domänenmodell](#-domänenmodell) +- [Rollenmodell](#-rollenmodell) + +## 📖 Überblick + +Dieses Projekt modelliert einen typischen B2B-Vertriebsablauf: + +- Produkt- und Kategorienkatalog verwalten +- Kunden und Kontakte pflegen +- Aufträge und Auftragspositionen nachverfolgen +- Rechnungen ausstellen und Zahlungen erfassen +- Einen AI-Assistenten nach geschäftlichen Erkenntnissen fragen +- Aufgaben und letzte Aktivitäten überwachen +- Vertriebsanalysen anzeigen + +## 🛠️ Technischer Stack + +- Java 21 +- Jmix 2.7 +- Spring Boot 3 +- HSQLDB + +## 🧩 Verwendete Add-ons + +- Audit +- Application settings +- Charts +- Data tools +- Dynamic attributes +- Grid export +- Local file storage +- Reports, einschließlich einer Rechnungsvorlage + +## 🚀 Build und Start + +Voraussetzungen: Java 21+ + +### Projekt starten + +1. Starte die Jmix-Run-Konfiguration [B2B CRM](.run/crm-app.run.xml) oder führe aus + + ```bash + ./gradlew bootRun + ``` + +2. [Anwendungs-URL öffnen](http://localhost:8080/b2b-crm) + +### Start per JAR + +```bash +./gradlew bootJar -Pvaadin.productionMode +``` + +```bash +java -jar build/libs/crm.jar +``` + +### Start per Docker + +```bash +docker build -t jmix-crm . +``` + +```bash +docker run --rm -p 8080:8080 jmix-crm +``` + +### Start per Docker Compose + +```bash +docker-compose up +``` + +## 🤖 AI-Assistent + +Die Anwendung enthält einen integrierten `CRM AI`-Arbeitsbereich für die natürlichsprachliche Analyse von CRM-Daten. + +Wichtige Funktionen: + +- Geschäftsfragen zu Kunden, Aufträgen, Rechnungen, Zahlungen und Vertriebsleistung stellen +- Die Datenzugriffsrechte des aktuellen Benutzers berücksichtigen und Konversationen nur für ihren Autor sichtbar halten +- Integrierte Geschäftsberichte wie `Client 360 Report` und `Category Cashflow Risk Allocation Report` verwenden +- Den Konversationsverlauf mit automatisch generierten Chat-Titeln speichern +- Dateien in die Konversation hochladen und den Assistenten unterstützte Dokumente und Bilder analysieren lassen +- Interaktive Links zu CRM-Datensätzen direkt in Antworten generieren + +Konfiguration: + +- Setze `spring.ai.openai.api-key` in [application.properties](src/main/resources/application.properties) oder stelle die Umgebungsvariable `SPRING_AI_OPENAI_APIKEY` bereit + +Nach der Aktivierung öffne den Menüpunkt `CRM AI` im Hauptmenü, um eine neue Konversation zu starten. + +## 🎲 Demo-Daten + +Das lokale Profil generiert Demo-Daten beim Start der Anwendung: + +- Die Generierung von Demo-Daten kann mit der Eigenschaft `crm.generateDemoData` + in [application.properties](src/main/resources/application.properties) deaktiviert werden +- Der Katalog wird aus [catalog.xlsx](src/main/resources/demo-data/catalog.xlsx) importiert + +## 👥 Anwendungskonten + +| Position | Benutzername | Passwort | Zugriff | +|-----------------|---------------|----------|-------------------------------------------------| +| Administrator | ```admin``` | admin | Vollzugriff auf alle Daten und Einstellungen | +| Supervisor | ```james``` | james | Manager + Katalogverwaltung + Konten zuweisen | +| Manager | ```manager``` | manager | Vollzugriff auf alle Kunden und Aufträge | +| Account Manager | ```alice``` | alice | Sieht nur Kunden, die Alice Brown zugewiesen sind | +| Account Manager | ```robert``` | robert | Sieht nur Kunden, die Robert Taylor zugewiesen sind | + +## ⚙️ Domänenmodell + +```mermaid +classDiagram + Client o-- Contact + Client o-- Order + Client o-- Invoice + Client o-- Payment + Client o-- Address + + Order *-- OrderItem + OrderItem --> CategoryItem + Category o-- CategoryItem + + Invoice o-- Payment +``` + +## 🔐 Rollenmodell + +Die Anwendung verwendet ein hierarchisches Rollenmodell: + +- `Administrator`: Vollzugriff auf alle Anwendungsfunktionen, Entitäten und Einstellungen. +- `Supervisor`: Erweitert die Manager-Rolle um zusätzliche administrative Funktionen: + - Produktkatalog verwalten, einschließlich Categories und Category Items. + - Account Managers Kunden zuweisen. +- `Manager`: Primäre Rolle für Vertriebsprozesse. + - Vollzugriff auf Clients, Contacts, Orders, Invoices und Payments. + - Lesezugriff auf den Produktkatalog. + - Eigene Tasks verwalten. +- `UI Minimal`: Minimaler Zugriff, der Anmeldung und grundlegende Navigation ermöglicht. diff --git a/README_es.md b/README_es.md new file mode 100644 index 0000000..c31bada --- /dev/null +++ b/README_es.md @@ -0,0 +1,157 @@ +# ![CRM](src/main/resources/META-INF/resources/images/logo.svg) B2B CRM + +Idiomas: [English](README.md) | [Русский](README_ru.md) | [Deutsch](README_de.md) | [Italiano](README_it.md) | [Español](README_es.md) + +`B2B CRM` es una demo de aplicación empresarial creada con Jmix que muestra cómo desarrollar sistemas de negocio **listos para su puesta en producción** +para `clientes`, `pedidos`, `facturación`, `finanzas` y `analítica`.
Refleja escenarios reales **ERP/CRM** y demuestra +buenas prácticas de modelado de dominio, UI, seguridad e implementación de lógica de negocio. + +## 📑 Índice + +- [Resumen](#-resumen) +- [Stack técnológico](#-stack-técnico) +- [Add-ons utilizados](#-add-ons-utilizados) +- [Build y ejecución](#-build-y-ejecución) +- [Asistente de IA](#-asistente-de-ia) +- [Datos demo](#-datos-demo) +- [Cuentas](#-cuentas-de-la-aplicación) +- [Modelo de dominio](#-modelo-de-dominio) +- [Modelo de roles](#-modelo-de-roles) + +## 📖 Resumen + +Este proyecto modela un flujo típico de ventas B2B para: + +- gestionar el catálogo de productos y categorías +- mantener clientes y contactos +- hacer seguimiento de pedidos y líneas de pedido +- emitir facturas y registrar pagos +- preguntar a un asistente de IA por perspectivas de negocio +- supervisar tareas y actividades recientes +- ver analítica de ventas + +## 🛠️ Stack técnológico + +- Java 21 +- Jmix 2.7 +- Spring Boot 3 +- HSQLDB + +## 🧩 Add-ons utilizados + +- Audit +- Application settings +- Charts +- Data tools +- Dynamic attributes +- Grid export +- Local file storage +- Reports, incluida una plantilla de factura + +## 🚀 Build y ejecución + +Requisitos: Java 21+ + +### Para ejecutar el proyecto + +1. Ejecuta la configuración Jmix [B2B CRM](.run/crm-app.run.xml) o ejecuta + + ```bash + ./gradlew bootRun + ``` + +2. [Abre la URL de la aplicación](http://localhost:8080/b2b-crm) + +### Ejecutar mediante JAR + +```bash +./gradlew bootJar -Pvaadin.productionMode +``` + +```bash +java -jar build/libs/crm.jar +``` + +### Ejecutar mediante Docker + +```bash +docker build -t jmix-crm . +``` + +```bash +docker run --rm -p 8080:8080 jmix-crm +``` + +### Ejecutar mediante Docker Compose + +```bash +docker-compose up +``` + +## 🤖 Asistente de IA + +La aplicación incluye un espacio de trabajo integrado `CRM AI` para el análisis de datos CRM en lenguaje natural. + +Capacidades principales: + +- Hacer preguntas de negocio sobre clientes, pedidos, facturas, pagos y rendimiento de ventas +- Respetar los permisos de acceso a datos del usuario actual y mantener las conversaciones privadas para su autor +- Usar informes de negocio integrados como `Client 360 Report` y `Category Cashflow Risk Allocation Report` +- Mantener el historial de conversación con títulos de chat generados automáticamente +- Subir archivos a la conversación y permitir que el asistente analice documentos e imágenes compatibles +- Generar enlaces interactivos a registros CRM directamente en las respuestas + +Configuración: + +- Define `spring.ai.openai.api-key` en [application.properties](src/main/resources/application.properties) o proporciona la variable de entorno `SPRING_AI_OPENAI_APIKEY` + +Cuando esté habilitado, abre el elemento `CRM AI` en el menú principal para iniciar una nueva conversación. + +## 🎲 Datos demo + +El perfil local genera datos demo al iniciar la aplicación: + +- Puedes desactivar la generación de datos demo con la propiedad `crm.generateDemoData` + en [application.properties](src/main/resources/application.properties) +- El catálogo se importa desde [catalog.xlsx](src/main/resources/demo-data/catalog.xlsx) + +## 👥 Cuentas de la aplicación + +| Puesto | Usuario | Contraseña | Acceso | +| ----------------------------------------- | --------- | ---------- | ----------------------------------------------------- | +| Administrador del sistema (Administrator) | `admin` | admin | Acceso completo a todos los datos y configuraciones | +| Supervisor | `james` | james | Manager + gestión de catálogo + asignación de cuentas | +| Manager | `manager` | manager | Acceso completo a todos los clientes y pedidos | +| Gestora de cuenta (Account Manager) | `alice` | alice | Solo ve clientes asignados a Alice Brown | +| Gestor de cuenta (Account Manager) | `robert` | robert | Solo ve clientes asignados a Robert Taylor | + +## ⚙️ Modelo de dominio + +```mermaid +classDiagram + Client o-- Contact + Client o-- Order + Client o-- Invoice + Client o-- Payment + Client o-- Address + + Order *-- OrderItem + OrderItem --> CategoryItem + Category o-- CategoryItem + + Invoice o-- Payment +``` + +## 🔐 Modelo de roles + +La aplicación usa un modelo jerárquico de roles: + +- `Administrator`: acceso completo a todas las funciones, entidades y configuraciones de la aplicación. +- `Supervisor`: como el rol Manager (ver más abajo), pero con capacidades administrativas adicionales: + - Gestiona el catálogo de productos, incluidas Categories y Category Items. + - Asigna Account Managers a Clients. +- `Manager`: rol principal para operaciones de ventas. + - Acceso completo a Clients, Contacts, Orders, Invoices y Payments. + - Acceso de solo lectura al catálogo de productos. + - Gestión de sus propias Tasks. +- `UI Minimal`: acceso mínimo que permite iniciar sesión y navegación básica. diff --git a/README_it.md b/README_it.md new file mode 100644 index 0000000..30dc8ef --- /dev/null +++ b/README_it.md @@ -0,0 +1,157 @@ +# ![CRM](src/main/resources/META-INF/resources/images/logo.svg) B2B CRM + +Lingue: [English](README.md) | [Русский](README_ru.md) | [Deutsch](README_de.md) | [Italiano](README_it.md) | [Español](README_es.md) + +`B2B CRM` è un'applicazione demo sviluppata con Jmix che mostra come creare sistemi aziendali **pronti per la produzione** +per lavorare con `clienti`, `ordini`, `fatture`, `finanza` e `analitica`.
Rappresenta scenari reali **ERP/CRM** e dimostra +le best practice di modellazione del dominio, UI, sicurezza e implementazione della logica del business. + +## 📑 Indice + +- [Panoramica](#-panoramica) +- [Stack tecnico](#-stack-tecnico) +- [Add-on utilizzati](#-add-on-utilizzati) +- [Build ed esecuzione](#-build-ed-esecuzione) +- [Assistente AI](#-assistente-ai) +- [Dati demo](#-dati-demo) +- [Account](#-account-dellapplicazione) +- [Modello di dominio](#-modello-di-dominio) +- [Modello dei ruoli](#-modello-dei-ruoli) + +## 📖 Panoramica + +Questo progetto modella un tipico flusso di vendita B2B: + +- Gestione del catalogo prodotti e categorie +- Gestione di clienti e contatti +- Tracciamento degli ordini e delle loro posizioni +- Emissione di fatture e registrazione dei pagamenti +- Richiesta di business-insight all'assistente AI +- Monitoraggio dei compiti e attività recenti +- Visualizzazione dell'analisi delle vendite + +## 🛠️ Stack tecnico + +- Java 21 +- Jmix 2.7 +- Spring Boot 3 +- HSQLDB + +## 🧩 Add-on utilizzati + +- Audit +- Application settings +- Charts +- Data tools +- Dynamic attributes +- Grid export +- Local file storage +- Reports, incluso un modello di fattura + +## 🚀 Build ed esecuzione + +Prerequisiti: Java 21+ + +### Esecuzione del progetto + +1. Avvia la configurazione Jmix [B2B CRM](.run/crm-app.run.xml) oppure esegui + + ```bash + ./gradlew bootRun + ``` + +2. [Apri l'URL dell'applicazione](http://localhost:8080/b2b-crm) + +### Esecuzione tramite JAR + +```bash +./gradlew bootJar -Pvaadin.productionMode +``` + +```bash +java -jar build/libs/crm.jar +``` + +### Esecuzione tramite Docker + +```bash +docker build -t jmix-crm . +``` + +```bash +docker run --rm -p 8080:8080 jmix-crm +``` + +### Esecuzione tramite Docker Compose + +```bash +docker-compose up +``` + +## 🤖 Assistente AI + +L'applicazione include uno spazio di lavoro integrato `CRM AI` per l'analisi in linguaggio naturale dei dati CRM. + +Funzionalità principali: + +- Porre domande di business su clienti, ordini, fatture, pagamenti e performance delle vendite +- Rispettare le autorizzazioni di accesso ai dati dell'utente corrente e mantenere le conversazioni private per il loro autore +- Usare report aziendali integrati come `Client 360 Report` e `Category Cashflow Risk Allocation Report` +- Conservare la cronologia delle conversazioni con titoli generati automaticamente +- Caricare file nella conversazione e lasciare che l'assistente analizzi documenti e immagini supportati +- Generare link interattivi ai record CRM direttamente nelle risposte + +Configurazione: + +- Imposta `spring.ai.openai.api-key` in [application.properties](src/main/resources/application.properties) oppure fornisci la variabile d'ambiente `SPRING_AI_OPENAI_APIKEY` + +Dopo l'avvio apri la voce `CRM AI` nel menu principale per iniziare una nuova conversazione. + +## 🎲 Dati demo + +Il profilo locale genera dati demo all'avvio dell'applicazione: + +- Puoi disabilitare la generazione dei dati demo con la proprietà `crm.generateDemoData` + in [application.properties](src/main/resources/application.properties) +- Il catalogo viene importato da [catalog.xlsx](src/main/resources/demo-data/catalog.xlsx) + +## 👥 Account dell'applicazione + +| Posizione | Nome utente | Password | Accesso | +|-----------------|---------------|----------|--------------------------------------------------| +| Administrator | ```admin``` | admin | Accesso completo a tutti i dati e impostazioni | +| Supervisor | ```james``` | james | Manager + gestione catalogo + assegnazione account | +| Manager | ```manager``` | manager | Accesso completo a tutti i clienti e ordini | +| Account Manager | ```alice``` | alice | Vede solo i clienti assegnati ad Alice Brown | +| Account Manager | ```robert``` | robert | Vede solo i clienti assegnati a Robert Taylor | + +## ⚙️ Modello di dominio + +```mermaid +classDiagram + Client o-- Contact + Client o-- Order + Client o-- Invoice + Client o-- Payment + Client o-- Address + + Order *-- OrderItem + OrderItem --> CategoryItem + Category o-- CategoryItem + + Invoice o-- Payment +``` + +## 🔐 Modello dei ruoli + +L'applicazione usa un modello di ruoli gerarchico: + +- `Administrator`: accesso completo a tutte le funzionalità, entità e impostazioni dell'applicazione. +- `Supervisor`: estende il ruolo Manager con capacità amministrative aggiuntive: + - Gestione del catalogo prodotti, incluse Categories e Category Items. + - Assegnazione Account Managers ai Clients. +- `Manager`: ruolo principale per le operazioni di vendita. + - Accesso completo a Clients, Contacts, Orders, Invoices e Payments. + - Accesso in sola lettura al catalogo prodotti. + - Gestione dei propri Tasks. +- `UI Minimal`: accesso minimo che consente login e navigazione di base. diff --git a/README_ru.md b/README_ru.md new file mode 100644 index 0000000..670d25f --- /dev/null +++ b/README_ru.md @@ -0,0 +1,157 @@ +# ![CRM](src/main/resources/META-INF/resources/images/logo.svg) B2B CRM + +Языки: [English](README.md) | [Русский](README_ru.md) | [Deutsch](README_de.md) | [Italiano](README_it.md) | [Español](README_es.md) + +`B2B CRM` — корпоративное демонстрационное приложение на Jmix, показывающее, как разрабатывать **готовые к production** бизнес-системы +для работы с `клиентами`, `заказами`, `счетами`, `финансами` и `аналитикой`.
Оно отражает реальные сценарии **ERP/CRM** и демонстрирует +лучшие практики моделирования предметной области, UI, безопасности и реализации бизнес-логики. + +## 📑 Содержание + +- [Обзор](#-обзор) +- [Технический стек](#-технический-стек) +- [Используемые add-ons](#-используемые-add-ons) +- [Сборка и запуск](#-сборка-и-запуск) +- [AI-ассистент](#-ai-ассистент) +- [Демо-данные](#-демо-данные) +- [Учетные записи](#-учетные-записи-приложения) +- [Модель предметной области](#-модель-предметной-области) +- [Ролевая модель](#-ролевая-модель) + +## 📖 Обзор + +Проект моделирует типичный процесс B2B-продаж: + +- Управление каталогом продуктов и категорий +- Ведение клиентов и контактов +- Отслеживание заказов и позиций заказов +- Выставление счетов и регистрация платежей +- Запрос бизнес-инсайтов у AI-ассистента +- Контроль задач и последних активностей +- Просмотр аналитики продаж + +## 🛠️ Технический стек + +- Java 21 +- Jmix 2.7 +- Spring Boot 3 +- HSQLDB + +## 🧩 Используемые Add-ons + +- Audit +- Application settings +- Charts +- Data tools +- Dynamic attributes +- Grid export +- Local file storage +- Reports, включая шаблон счета + +## 🚀 Сборка и запуск + +Требования: Java 21+ + +### Запуск проекта + +1. Запустите Jmix run configuration [B2B CRM](.run/crm-app.run.xml) или выполните команду + + ```bash + ./gradlew bootRun + ``` + +2. [Откройте URL приложения](http://localhost:8080/b2b-crm) + +### Запуск через JAR + +```bash +./gradlew bootJar -Pvaadin.productionMode +``` + +```bash +java -jar build/libs/crm.jar +``` + +### Запуск через Docker + +```bash +docker build -t jmix-crm . +``` + +```bash +docker run --rm -p 8080:8080 jmix-crm +``` + +### Запуск через Docker Compose + +```bash +docker-compose up +``` + +## 🤖 AI-ассистент + +Приложение включает встроенное рабочее пространство `CRM AI` для анализа CRM-данных на естественном языке. + +Основные возможности: + +- Задавать бизнес-вопросы о клиентах, заказах, счетах, платежах и эффективности продаж +- Учитывать права доступа текущего пользователя к данным и хранить диалоги приватно для их автора +- Использовать встроенные бизнес-отчеты, такие как `Client 360 Report` и `Category Cashflow Risk Allocation Report` +- Сохранять историю диалогов с автоматически сгенерированными названиями чатов +- Загружать файлы в диалог и позволять ассистенту анализировать поддерживаемые документы и изображения +- Генерировать интерактивные ссылки на записи CRM прямо в ответах + +Настройка: + +- Укажите `spring.ai.openai.api-key` в [application.properties](src/main/resources/application.properties) или передайте переменную окружения `SPRING_AI_OPENAI_APIKEY` + +После включения откройте пункт `CRM AI` в главном меню, чтобы начать новый диалог. + +## 🎲 Демо-данные + +Локальный профиль генерирует демо-данные при старте приложения: + +- Генерацию демо-данных можно отключить свойством `crm.generateDemoData` + в [application.properties](src/main/resources/application.properties) +- Каталог импортируется из [catalog.xlsx](src/main/resources/demo-data/catalog.xlsx) + +## 👥 Учетные записи приложения + +| Должность | Имя пользователя | Пароль | Доступ | +|-----------------|------------------|---------|----------------------------------------------------| +| Administrator | ```admin``` | admin | Полный доступ ко всем данным и настройкам | +| Supervisor | ```james``` | james | Manager + управление каталогом + назначение аккаунтов | +| Manager | ```manager``` | manager | Полный доступ ко всем клиентам и заказам | +| Account Manager | ```alice``` | alice | Видит только клиентов, назначенных Alice Brown | +| Account Manager | ```robert``` | robert | Видит только клиентов, назначенных Robert Taylor | + +## ⚙️ Модель предметной области + +```mermaid +classDiagram + Client o-- Contact + Client o-- Order + Client o-- Invoice + Client o-- Payment + Client o-- Address + + Order *-- OrderItem + OrderItem --> CategoryItem + Category o-- CategoryItem + + Invoice o-- Payment +``` + +## 🔐 Ролевая модель + +Приложение использует иерархическую ролевую модель: + +- `Administrator`: полный доступ ко всем функциям, сущностям и настройкам приложения. +- `Supervisor`: расширяет роль Manager дополнительными административными возможностями: + - Управление каталогом продуктов, включая Categories и Category Items. + - Назначение Account Managers клиентам. +- `Manager`: основная роль для операций продаж. + - Полный доступ к Clients, Contacts, Orders, Invoices и Payments. + - Доступ только на чтение к каталогу продуктов. + - Управление собственными Tasks. +- `UI Minimal`: минимальный доступ, позволяющий входить в систему и выполнять базовую навигацию.