@coopenomics/desktop 2025.7.3 → 2025.11.8-alpha-2

package/.cursor/rules/widgets.mdc

@@ -0,0 +1,388 @@
+---
+globs: ["**/desktop/widgets/**/*.ts", "**/desktop/widgets/**/*.vue"]
+alwaysApply: false
+---
+## Архитектура виджетов (Widgets Layer)
+
+### Общее устройство
+
+Виджеты - это комплексные UI компоненты, которые комбинируют данные из entities и действия из features для создания полноценных интерфейсных блоков. Виджеты отвечают за композицию и представление сложных частей интерфейса.
+
+**Запрещено**: Виджеты не переиспользуют другие виджеты. Виджеты могут использовать только фичи и shared компоненты.
+
+### Структура папок виджета
+
+```
+widgets/
+  WidgetName/
+    index.ts              # Экспорт виджета
+    WidgetName.vue        # Vue компонент виджета
+    # или
+    ui/
+      WidgetName.vue      # Vue компонент в подпапке
+      index.ts            # Экспорт из ui
+```
+
+### Принципы организации виджетов
+
+#### Использование только разрешенных слоев
+```typescript
+// ✅ Разрешено: entities для данных
+import { useEntityStore, type IEntity } from 'entities/Entity/model';
+
+// ✅ Разрешено: features для действий
+import { useEntityAction } from 'features/Entity/EntityAction';
+import { EntityActionButton } from 'features/Entity/EntityAction';
+
+// ✅ Разрешено: shared компоненты
+import { SharedComponent } from 'src/shared/ui/SharedComponent';
+
+// ❌ Запрещено: импорт других виджетов
+// import { AnotherWidget } from 'widgets/AnotherWidget';
+```
+
+#### Композиция через слоты (опционально)
+Виджеты могут содержать слоты для композиции с другими компонентами на уровне страниц:
+
+```vue
+<template lang="pug">
+.widget-container
+  .widget-header
+    slot(name='header')
+      | Заголовок по умолчанию
+
+  .widget-content
+    slot(name='content')
+      | Контент по умолчанию
+
+  .widget-actions
+    slot(name='actions')
+</template>
+```
+
+### Типы виджетов
+
+#### 1. Презентационные виджеты
+Отображают данные в виде таблиц, списков, карточек:
+
+```vue
+<template lang="pug">
+q-card(flat)
+  q-table(
+    :rows='entities',
+    :columns='columns',
+    :loading='loading'
+  )
+</template>
+
+<script setup>
+import { useEntityStore } from 'entities/Entity/model';
+
+const store = useEntityStore();
+// Логика загрузки и отображения данных
+</script>
+```
+
+#### 2. Интерактивные виджеты
+Комбинируют отображение данных с действиями:
+
+```vue
+<template lang="pug">
+.widget
+  // Отображение данных
+  .data-section
+    EntityItem(v-for='item in items', :item='item')
+
+  // Действия
+  .actions-section
+    CreateEntityButton
+    UpdateEntityButton
+</template>
+```
+
+#### 3. Композитные виджеты со слотами
+Предоставляют гибкую структуру для страниц:
+
+```vue
+<template lang="pug">
+.layout-widget
+  header
+    slot(name='header')
+  main
+    slot(name='main')
+  aside
+    slot(name='sidebar')
+  footer
+    slot(name='footer')
+</template>
+```
+
+### Props и конфигурация
+
+#### Гибкая конфигурация через props
+```typescript
+interface Props {
+  // Данные
+  items?: IEntity[];
+  loading?: boolean;
+
+  // Конфигурация отображения
+  showActions?: boolean;
+  maxItems?: number;
+  emptyMessage?: string;
+
+  // Callbacks для взаимодействия
+  onItemClick?: (item: IEntity) => void;
+  onActionComplete?: () => void;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  showActions: true,
+  maxItems: 50,
+  emptyMessage: 'Нет данных',
+});
+```
+
+#### Управление состоянием
+```typescript
+// Локальное состояние виджета
+const expandedItems = ref<Set<string>>(new Set());
+const selectedItem = ref<IEntity | null>(null);
+
+// Props для внешнего управления
+interface Props {
+  expandedItems?: string[];
+  selectedItemId?: string;
+}
+```
+
+### Использование entities в виджетах
+
+#### Чтение данных из stores
+```typescript
+import { useEntityStore } from 'entities/Entity/model';
+
+const store = useEntityStore();
+
+// Доступ к реактивным данным (уже реактивны через Pinia)
+const entities = computed(() => store.entities);
+const loading = computed(() => store.loading);
+
+// Методы загрузки
+const loadData = () => {
+  store.loadEntities({ filter: props.filter });
+};
+```
+
+#### Важно о реактивности stores
+**Store автоматически реактивен через Pinia** - не нужно использовать `storeToRefs()` или `.value`:
+```typescript
+const store = useEntityStore();
+
+// ✅ Правильно - данные уже реактивны
+const entities = computed(() => store.entities);
+
+// ❌ Неправильно - storeToRefs не нужен
+// const { entities } = storeToRefs(store);
+
+// ❌ Неправильно - данные уже реактивны, .value не нужен
+// const entities = store.entities.value;
+```
+
+### Использование features в виджетах
+
+#### Импорт и использование фич
+```typescript
+import { useEntityAction } from 'features/Entity/EntityAction';
+import { EntityActionButton } from 'features/Entity/EntityAction';
+
+const { entityAction } = useEntityAction();
+
+// Использование в обработчиках
+const handleAction = async () => {
+  try {
+    await entityAction(params);
+    // Обработка успеха
+  } catch (error) {
+    // Обработка ошибки
+  }
+};
+```
+
+#### Интеграция UI компонентов фич
+```vue
+<template>
+  <div class="widget">
+    <!-- Данные -->
+    <EntityList :items="entities" />
+
+    <!-- Действия из фич -->
+    <div class="actions">
+      <CreateEntityButton @created="onEntityCreated" />
+      <UpdateEntityButton :entity="selectedEntity" />
+    </div>
+  </div>
+</template>
+```
+
+### Обработка событий и коммуникация
+
+#### Внутренняя коммуникация
+```typescript
+const emit = defineEmits<{
+  itemSelected: [item: IEntity];
+  actionCompleted: [action: string, result: any];
+}>();
+
+// Генерация событий
+const onItemClick = (item: IEntity) => {
+  emit('itemSelected', item);
+};
+
+const onActionSuccess = (result: any) => {
+  emit('actionCompleted', 'create', result);
+};
+```
+
+#### Внешнее управление через props
+```typescript
+interface Props {
+  selectedItemId?: string;
+  onItemSelect?: (item: IEntity) => void;
+}
+
+const props = defineProps<Props>();
+
+// Синхронизация с внешним состоянием
+watch(() => props.selectedItemId, (newId) => {
+  if (newId) {
+    const item = entities.value.find(e => e.id === newId);
+    if (item) {
+      selectedItem.value = item;
+      props.onItemSelect?.(item);
+    }
+  }
+});
+```
+
+### Экспорты и индексные файлы
+
+#### Виджет (widgets/WidgetName/index.ts)
+```typescript
+export { default as WidgetName } from './WidgetName.vue';
+// или
+export { default as WidgetName } from './ui/WidgetName.vue';
+```
+
+#### Слой виджетов (widgets/index.ts)
+```typescript
+export * from './WidgetName';
+export * from './AnotherWidget';
+```
+
+#### Расширение (extensions/extension-name/index.ts)
+```typescript
+export * from './entities';
+export * from './features';
+export * from './widgets';  // Экспорт всех виджетов расширения
+export * from './pages';
+```
+
+### Примеры использования
+
+#### Простой виджет списка
+```vue
+<template lang="pug">
+q-card(flat)
+  q-card-section
+    .text-h6 Список элементов
+
+  q-card-section
+    q-list
+      q-item(
+        v-for='item in items',
+        :key='item.id',
+        clickable,
+        @click='$emit("itemClick", item)'
+      )
+        q-item-section {{ item.name }}
+
+    .text-center.q-pa-md(v-if='!items.length && !loading')
+      | {{ emptyMessage }}
+
+    .text-center.q-pa-md(v-if='loading')
+      q-spinner(color='primary')
+</template>
+
+<script setup lang="ts">
+import type { IEntity } from 'entities/Entity/model';
+
+interface Props {
+  items: IEntity[];
+  loading?: boolean;
+  emptyMessage?: string;
+}
+
+defineEmits<{
+  itemClick: [item: IEntity];
+}>();
+</script>
+```
+
+#### Виджет с действиями
+```vue
+<template lang="pug">
+.widget
+  .widget-header
+    h3 {{ title }}
+    CreateEntityButton(@created='onEntityCreated')
+
+  .widget-content
+    EntityTable(
+      :entities='entities',
+      :loading='loading',
+      @entity-selected='onEntitySelected'
+    )
+
+  .widget-footer
+    q-pagination(
+      v-model='currentPage',
+      :max='totalPages',
+      @update:model-value='onPageChange'
+    )
+</template>
+
+<script setup lang="ts">
+import { useEntityStore } from 'entities/Entity/model';
+import { CreateEntityButton } from 'features/Entity/CreateEntity';
+import EntityTable from './EntityTable.vue'; // Shared компонент
+
+const store = useEntityStore();
+const { entities, loading } = storeToRefs(store);
+
+// Логика пагинации, фильтрации и т.д.
+</script>
+```
+
+### Важные принципы
+
+#### Разделение ответственности
+- **Entities**: Данные и их хранение
+- **Features**: Бизнес-логика и действия
+- **Widgets**: Композиция UI компонентов
+- **Pages**: Оркестрация виджетов
+
+#### Композиция через слоты
+- Виджеты могут предоставлять слоты для гибкой композиции
+- Страницы используют слоты для вставки виджетов
+- Избегать жесткой связи между виджетами
+
+#### Переиспользование
+- Виджеты могут переиспользоваться в разных страницах
+- Конфигурация через props для адаптации
+- Shared компоненты для общих элементов UI
+
+#### Производительность
+- Ленивая загрузка данных
+- Виртуализация для больших списков
+- Оптимистичные обновления через features

package/.eslintignore

@@ -1,8 +1,14 @@
-/dist
-/src-capacitor
-/src-cordova
-/.quasar
-/node_modules
-.eslintrc.cjs
-/quasar.config.*.temporary.compiled*
-Env-example.ts
+# Exclude ESLint config files
+**/.eslintrc.js
+src-pwa/.eslintrc.js
+
+# Exclude build outputs
+dist/
+build/
+*.tsbuildinfo
+
+# Exclude node_modules
+node_modules/
+
+# Exclude generated files
+*.generated.*

package/.vscode/settings.json

@@ -1,14 +1,13 @@
 {
   "editor.bracketPairColorization.enabled": true,
   "editor.guides.bracketPairs": true,
-  "editor.formatOnSave": true,
+  "editor.formatOnSave": false,
   "editor.tabCompletion": "onlySnippets",
   "editor.defaultFormatter": "esbenp.prettier-vscode",
-  "editor.codeActionsOnSave": ["source.fixAll.eslint"],
   "eslint.validate": ["javascript", "typescript", "vue"],
   "typescript.tsdk": "node_modules/typescript/lib",
   "i18n-ally.localesPaths": ["src/i18n"],
   "typescript.format.enable": true,
   "typescript.format.indentSwitchCase": false,
-  "typescript.validate.enable": true,
+  "typescript.validate.enable": true
 }

package/EXTENSIONS-ARCHITECTURE.md

@@ -0,0 +1,178 @@
+# Архитектура системы расширений
+
+## Обзор
+
+Система расширений построена на принципах модульной архитектуры и позволяет динамически добавлять новые возможности в приложение без изменения основного кода. Расширения могут быть как полноценными рабочими столами (desktops), так и дополнительными функциями (extensions).
+
+## Основные компоненты
+
+### 1. Backend (Controller)
+
+#### Реестр расширений
+- **Файл**: `controller/src/extensions/extensions.registry.ts`
+- **Назначение**: Централизованный реестр всех доступных расширений
+- **Структура**: Объект с конфигурациями расширений (название, описание, классы, схемы)
+
+#### Модуль расширений
+- **Файл**: `controller/src/extensions/extensions.module.ts`
+- **Назначение**: Регистрация всех расширений в NestJS DI контейнере
+- **Принцип**: Динамический модуль с автоматическим импортом всех классов расширений
+
+### 2. Frontend (Desktop)
+
+#### Магазин расширений
+- **Компоненты**: ExtensionsShowcase, ExtensionPage
+- **Функции**: Просмотр, установка, настройка и управление расширениями
+- **API**: GraphQL мутации для установки/отключения расширений
+
+#### Рабочие столы (Workspaces)
+- **Store**: DesktopStore (Pinia)
+- **Функции**: Управление списком рабочих столов, маршрутами, активным состоянием
+- **Принцип**: Каждый workspace соответствует установленному расширению
+
+#### Меню системы
+- **Первый уровень**: WorkspaceMenu - кнопки рабочих столов
+- **Второй уровень**: SecondLevelMenuList - навигация внутри рабочего стола
+- **Фильтрация**: По ролям пользователя и условиям
+
+## Принципы работы
+
+### Инициализация
+1. **Загрузка системной информации** - базовые настройки кооператива
+2. **Инициализация Desktop Store** - получение списка доступных рабочих столов
+3. **Регистрация маршрутов** - базовые маршруты рабочих столов в Vue Router
+4. **Загрузка всех расширений** - автоматическая загрузка всех install.ts модулей
+5. **Выбор активного workspace** - по ролям пользователя или сохраненным настройкам
+
+### Установка расширения
+1. **GraphQL мутация** - установка расширения на backend
+2. **Обновление списка расширений** - перезагрузка данных из API
+3. **Загрузка desktop** - получение обновленного списка рабочих столов
+4. **Динамическая загрузка маршрутов** - загрузка routes из install.ts модуля
+5. **Регистрация в router** - добавление маршрутов в Vue Router
+
+### Структура расширения
+```
+extensions/{extension-name}/
+├── install.ts          # Конфигурация workspace и маршрутов
+├── entities/           # Бизнес-логика (Domain)
+├── features/           # Действия пользователя (Use Cases)
+├── pages/              # Страницы (UI)
+├── shared/             # Общие компоненты
+└── widgets/            # Виджеты (UI)
+```
+
+## Архитектурные принципы
+
+### Feature-Sliced Design (FSD)
+- **Entities**: Бизнес-сущности и их логика
+- **Features**: Действия пользователя и сценарии использования
+- **Pages**: Страницы приложения
+- **Shared**: Переиспользуемые компоненты
+- **Widgets**: Составные UI компоненты
+
+### Принципы SOLID
+- **Single Responsibility**: Каждый модуль отвечает за одну задачу
+- **Open/Closed**: Расширения открыты для расширения, закрыты для модификации
+- **Liskov Substitution**: Интерфейсы позволяют замену реализаций
+- **Interface Segregation**: Минимальные интерфейсы для каждого модуля
+- **Dependency Inversion**: Зависимости от абстракций, не от реализаций
+
+### Domain-Driven Design (DDD)
+- **Bounded Contexts**: Каждое расширение - изолированный контекст
+- **Entities**: Доменные объекты с бизнес-логикой
+- **Value Objects**: Неизменяемые объекты-значения
+- **Services**: Бизнес-сервисы для сложной логики
+
+## Типы расширений
+
+### Desktop расширения
+- Полноценные рабочие столы с собственным меню
+- Примеры: soviet, chairman, participant, capital
+- Имеют собственные маршруты и навигацию
+
+### Functional расширения
+- Дополнительные функции без собственного UI
+- Примеры: powerup, yookassa, qrpay
+- Расширяют возможности существующих рабочих столов
+
+## Ролевая модель
+
+### Роли пользователей
+- **chairman**: Председатель совета
+- **member**: Член совета
+- **user**: Обычный пользователь
+
+### Фильтрация доступа
+- Маршруты фильтруются по ролям в meta.roles
+- Условная логика через meta.conditions
+- Динамическое скрытие недоступных элементов
+
+## Состояние и хранение
+
+### Pinia Stores
+- **ExtensionStore**: Управление списком расширений
+- **DesktopStore**: Управление рабочими столами и маршрутами
+
+### Локальное хранилище
+- **localStorage**: Сохранение выбранного рабочего стола
+- **Session**: Управление аутентификацией пользователя
+
+## Маршрутизация
+
+### Vue Router
+- **Base route**: Корневой маршрут приложения
+- **Workspace routes**: Маршруты рабочих столов
+- **Extension routes**: Вложенные маршруты расширений
+
+### Динамическая регистрация
+- Автоматическая загрузка маршрутов при инициализации
+- Горячая регистрация маршрутов при установке расширений
+- Проверка дубликатов для предотвращения конфликтов
+
+## Производительность
+
+### Ленивая загрузка
+- **Dynamic imports**: Загрузка компонентов по требованию
+- **markRaw()**: Предотвращение реактивности для компонентов Vue
+- **Code splitting**: Разделение кода по расширениям
+
+### Кэширование
+- **Route caching**: Сохранение маршрутов в DesktopStore
+- **Module caching**: Кэширование загруженных модулей
+- **State persistence**: Сохранение состояния между сессиями
+
+## Безопасность
+
+### Аутентификация
+- Проверка прав доступа к маршрутам
+- Фильтрация по ролям пользователя
+- Защита от несанкционированного доступа
+
+### Валидация
+- **Zod schemas**: Строгая типизация конфигураций
+- **Input validation**: Проверка данных на frontend и backend
+- **Error boundaries**: Обработка ошибок в расширениях
+
+## Разработка и поддержка
+
+### Добавление нового расширения
+1. Создать папку в `extensions/`
+2. Реализовать `install.ts` с конфигурацией
+3. Добавить в `extensions.registry.ts`
+4. Зарегистрировать модуль в `extensions.module.ts`
+5. Протестировать установку и работу
+
+### Тестирование
+- **Unit tests**: Тестирование отдельных модулей
+- **Integration tests**: Тестирование взаимодействия компонентов
+- **E2E tests**: Полное тестирование сценариев использования
+
+### Мониторинг
+- **Логирование**: Отслеживание загрузки расширений
+- **Метрики**: Мониторинг производительности
+- **Обработка ошибок**: Graceful degradation при сбоях
+
+## Заключение
+
+Архитектура системы расширений обеспечивает гибкость, масштабируемость и поддерживаемость приложения. Модульный подход позволяет независимо развивать отдельные расширения, а строгие архитектурные принципы гарантируют качество и надежность кода.