@coopenomics/desktop 2025.7.3 → 2025.11.8-alpha-2

package/.cursor/rules/features.mdc

@@ -0,0 +1,234 @@
+---
+globs: ["**/desktop/features/**/*.ts", "**/desktop/features/**/*.vue"]
+alwaysApply: false
+---
+## Архитектура фич (Features Layer)
+
+### Общее устройство
+
+Фичи - это бизнес-логика приложения, реализованная в виде Vue composables. Каждая фича отвечает за конкретное действие или набор связанных действий. Фичи взаимодействуют с entities для получения и обновления данных.
+
+**Запрещено**: Размещать методы чтения данных в фичах. Чтение данных - задача entities.
+
+### Структура папок фичи
+
+```
+features/
+  FeatureName/
+    index.ts              # Экспорт composable и UI (если есть)
+    api/
+      index.ts            # Мутации GraphQL через SDK
+    model/
+      index.ts            # Экспорт composable функции
+    ui/                   # Опционально: UI компоненты фичи
+      index.ts            # Экспорт UI компонентов
+      Component.vue       # Компоненты фичи
+```
+
+### Типизация фич
+
+#### Импорты типов напрямую из SDK
+```typescript
+import { Mutations } from '@coopenomics/sdk';
+
+// Типы входных данных мутации
+export type IFeatureInput = Mutations.Extension.FeatureAction.IInput['data'];
+
+// Типы выходных данных мутации
+export type IFeatureOutput = Mutations.Extension.FeatureAction.IOutput[typeof Mutations.Extension.FeatureAction.name];
+```
+
+**Важно**: Ничего не переопределяем вручную! Все типы берутся напрямую из GraphQL Zeus SDK.
+
+### Организация API (api/index.ts)
+
+#### Структура API функций для мутаций
+```typescript
+import { client } from 'src/shared/api/client';
+import { Mutations } from '@coopenomics/sdk';
+import type { IFeatureInput, IFeatureOutput } from '../model';
+
+async function featureAction(
+  data: IFeatureInput,
+): Promise<IFeatureOutput> {
+  const { [Mutations.Extension.FeatureAction.name]: result } =
+    await client.Mutation(Mutations.Extension.FeatureAction.mutation, {
+      variables: {
+        data,
+      },
+    });
+
+  return result;
+}
+
+export const api = {
+  featureAction,
+};
+```
+
+#### Правила для API фич
+- **Только мутации**: API фич содержит только GraphQL мутации
+- **Строгая типизация**: Все параметры и возвраты типизированы через SDK
+- **Использование SDK**: Все мутации через GraphQL Zeus SDK
+- **Единый экспорт**: Все функции экспортируются через объект `api`
+
+### Организация Model (model/index.ts)
+
+#### Структура composable функции
+```typescript
+import { useEntityStore } from 'app/extensions/extension-name/entities/Entity/model';
+import { api } from '../api';
+import type { IFeatureInput, IFeatureOutput } from '../api';
+
+export function useFeatureAction() {
+  const store = useEntityStore();
+
+  const featureAction = async (input: IFeatureInput): Promise<IFeatureOutput> => {
+    const result = await api.featureAction(input);
+
+    if (result) {
+      // Обновляем store сущности для поддержания консистентности
+      store.updateEntityInList(result);
+      // или store.removeEntityFromList(input.entity_id);
+      // или store.addEntityToList(result);
+    }
+
+    return result;
+  };
+
+  return { featureAction };
+}
+```
+
+#### Правила для composables
+- **Использование store**: Фичи обновляют store entities после выполнения мутаций
+- **Поддержание консистентности**: Данные в store всегда актуальны после действий
+- **Возвращение результата**: Composable возвращает результат мутации
+- **Обработка ошибок**: Ошибки обрабатываются в UI компонентах
+
+### UI слой фич (опционально)
+
+#### Когда использовать UI в фичах
+- **Иногда, но не всегда**: UI слой используется только для специфических компонентов фичи
+- **Простые действия**: Для кнопок, форм, специфичных для данной фичи
+- **Не общие компоненты**: Не размещать shared компоненты в фичах
+
+#### Экспорты UI компонентов
+
+##### В ui/index.ts (первый уровень экспорта)
+```typescript
+export { default as FeatureButton } from './FeatureButton.vue';
+export { default as FeatureDialog } from './FeatureDialog.vue';
+```
+
+##### В корне фичи index.ts (второй уровень экспорта)
+```typescript
+export { useFeatureAction } from './model';
+export * from './ui';  // Экспортируем все UI компоненты
+```
+
+### Экспорты и индексные файлы
+
+#### Фича (features/FeatureName/index.ts)
+```typescript
+export { useFeatureAction } from './model';
+export * from './ui';  // Если есть UI слой
+```
+
+#### Слой фич (features/index.ts)
+```typescript
+export { useFeatureAction } from './FeatureName';
+export { useAnotherFeature } from './AnotherFeature';
+```
+
+#### Расширение (extensions/extension-name/index.ts)
+```typescript
+export * from './entities';
+export * from './features';  // Экспорт всех фич расширения
+export * from './widgets';
+export * from './pages';
+```
+
+### Принципы работы с фичами
+
+#### Разделение ответственности
+- **Entities**: Хранение и чтение данных
+- **Features**: Бизнес-логика и действия (мутации)
+- **Widgets**: Сложные UI компоненты
+- **Pages**: Корневые страницы
+
+#### Взаимодействие со stores
+- **Обязательное обновление**: После каждой мутации обновлять соответствующий store
+- **Консистентность данных**: UI всегда показывает актуальные данные из store
+- **Оптимистичные обновления**: Возможны для лучшего UX
+
+#### Типизация
+- **SDK-first**: Все типы из GraphQL Zeus SDK
+- **Не переопределять**: Никаких ручных переопределений типов
+- **Строгая типизация**: Все входы/выходы типизированы
+
+#### Организация кода
+- **Composable pattern**: Каждая фича - отдельный composable
+- **Единая ответственность**: Одна фича = одно действие или группа связанных действий
+- **Переиспользование**: Фичи могут использоваться в разных частях приложения
+
+### Примеры
+
+#### Простая фича (только composable)
+```
+DeleteStory/
+  api/
+    index.ts        # Мутация deleteStory
+  model/
+    index.ts        # useDeleteStory composable
+  index.ts          # Экспорт composable
+```
+
+#### Фича с UI компонентами
+```
+CreateProject/
+  api/
+    index.ts        # Мутация createProject
+  model/
+    index.ts        # useCreateProject composable
+  ui/
+    index.ts        # Экспорт CreateProjectButton
+    CreateProjectButton.vue
+  index.ts          # Экспорт composable + UI
+```
+
+#### Использование фичи в компоненте
+```vue
+<script setup>
+import { useDeleteStory } from 'features/Story/DeleteStory';
+
+const { deleteStory } = useDeleteStory();
+
+// Использование в обработчике
+const handleDelete = async () => {
+  try {
+    await deleteStory({ story_hash: '...' });
+    // Обработка успеха
+  } catch (error) {
+    // Обработка ошибки
+  }
+};
+</script>
+```
+
+### Важные принципы
+
+#### Четкое разделение слоев
+- **Entities** управляют данными
+- **Features** управляют действиями
+- **UI** управляет интерфейсом
+
+#### Консистентность архитектуры
+- Все фичи следуют единому паттерну
+- Типизация через SDK
+- Обновление stores после мутаций
+
+#### Производительность
+- Оптимистичные обновления где возможно
+- Минимальные перерисовки UI
+- Эффективное управление состоянием

package/.cursor/rules/pages.mdc

@@ -0,0 +1,291 @@
+---
+globs: ["**/desktop/pages/**/*.ts", "**/desktop/pages/**/*.vue"]
+alwaysApply: false
+---
+## Архитектура страниц (Pages Layer)
+
+### Общее устройство
+
+Страницы - это корневые компоненты приложения, которые используются в маршрутах. Страницы отвечают за оркестрацию виджетов, управление состоянием UI и навигацию. Они могут быть как простыми контейнерами, так и сложными композитными компонентами.
+
+### Структура папок страницы
+
+```
+pages/
+  PageName/
+    index.ts              # Экспорт страницы
+    ui/                   # Vue компонент страницы
+      PageName.vue        # Основной компонент
+      index.ts            # Экспорт из ui
+```
+
+### Типы страниц
+
+#### 1. Контейнерные страницы
+Простые страницы, которые делегируют отображение дочерним маршрутам:
+
+```vue
+<template lang="pug">
+div
+  // Лоадер пока идет предзагрузка данных
+  WindowLoader(v-if="isLoading", text="Загрузка данных...")
+
+  // Основной контент после загрузки
+  router-view(v-else)
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue';
+import { WindowLoader } from 'src/shared/ui/Loader';
+import { useContributorStore } from 'entities/Contributor/model';
+
+const contributorStore = useContributorStore();
+const isLoading = ref(true);
+
+onMounted(async () => {
+  // Предзагрузка необходимых данных
+  await contributorStore.loadSelf({ username: session.username });
+  isLoading.value = false;
+});
+</script>
+```
+
+#### 2. Композитные страницы
+Страницы с сложной композицией виджетов и собственной логикой:
+
+```vue
+<template lang="pug">
+div
+  q-card(flat)
+    // Композиция виджетов
+    StoriesWidget(
+      :stories='storyStore.stories?.items || []',
+      :loading='loading'
+    )
+
+    // Собственная логика пагинации
+    q-card-actions(align='center')
+      q-pagination(
+        v-model='pagination.page',
+        :max='Math.ceil((storyStore.stories?.totalCount || 0) / pagination.rowsPerPage)',
+        @update:model-value='onPageChange'
+      )
+</template>
+
+<script setup>
+import { ref, onMounted } from 'vue';
+import { StoriesWidget } from 'widgets/StoriesWidget';
+import { useStoryStore } from 'entities/Story/model';
+
+const storyStore = useStoryStore();
+const loading = ref(false);
+
+// Собственная логика пагинации
+const pagination = ref({
+  page: 1,
+  rowsPerPage: 25,
+});
+
+const loadData = async () => {
+  loading.value = true;
+  try {
+    await storyStore.loadStories({
+      filter: { /* фильтры */ },
+      pagination: pagination.value,
+    });
+  } catch (error) {
+    FailAlert(`Ошибка загрузки: ${error.message}`);
+  } finally {
+    loading.value = false;
+  }
+};
+</script>
+```
+
+### Принципы организации страниц
+
+#### Использование слоев
+```typescript
+// ✅ Правильно: страницы используют все нижележащие слои
+import { useEntityStore } from 'entities/Entity/model';      // Данные
+import { useEntityAction } from 'features/Entity/EntityAction'; // Действия
+import { EntityWidget } from 'widgets/EntityWidget';         // Композиция UI
+
+// ❌ Неправильно: страницы не используют другие страницы
+// import { OtherPage } from 'pages/OtherPage';
+```
+
+#### Управление состоянием
+Страницы управляют:
+- **Загрузкой данных**: инициализация, фильтры, пагинация
+- **UI состоянием**: загрузка, ошибки, навигация
+- **Взаимодействием**: обработка событий от виджетов
+
+#### Композиция виджетов
+```vue
+<template lang="pug">
+// Простая композиция
+EntityWidget(:items='store.items')
+
+// Сложная композиция со слотами
+LayoutWidget
+  template(#header)
+    PageHeader(title='Заголовок страницы')
+
+  template(#content)
+    EntityWidget(:items='store.items')
+
+  template(#sidebar)
+    FiltersWidget(@filter-changed='onFilterChange')
+</template>
+```
+
+### Экспорты и индексные файлы
+
+#### Страница (pages/PageName/index.ts)
+```typescript
+export { default as PageName } from './ui/PageName.vue';
+```
+
+#### Слой страниц (pages/index.ts)
+```typescript
+export * from './PageName';
+export * from './AnotherPage';
+```
+
+#### Использование в маршрутах
+Страницы используются в `install.ts` расширения:
+
+```typescript
+routes: [{
+  path: '/:coopname/extension/page',
+  name: 'page',
+  component: markRaw(PageName), // Импорт из pages
+  meta: { /* ... */ }
+}]
+```
+
+### Принципы работы со страницами
+
+#### Разделение ответственности
+- **Entities**: Данные и их хранение
+- **Features**: Бизнес-логика и действия
+- **Widgets**: Композиция UI компонентов
+- **Pages**: Оркестрация всего вышеперечисленного
+
+#### Загрузка данных
+Страницы отвечают за:
+- Инициализацию данных при монтировании
+- Управление пагинацией и фильтрами
+- Обработку ошибок загрузки
+- Кеширование и оптимизацию запросов
+
+#### Навигация и взаимодействие
+```typescript
+const router = useRouter();
+
+const onItemClick = (item) => {
+  router.push({
+    name: 'item-details',
+    params: { id: item.id }
+  });
+};
+
+const onActionComplete = () => {
+  // Обновление данных после действия
+  loadData();
+};
+```
+
+### Примеры использования
+
+#### Простая страница списка
+```vue
+<template lang="pug">
+div
+  q-card(flat)
+    // Виджет таблицы
+    ItemsListWidget(
+      :items='store.items',
+      :loading='loading',
+      @item-click='onItemClick'
+    )
+
+    // Пагинация
+    q-pagination(
+      v-model='currentPage',
+      :max='totalPages',
+      @update:model-value='loadPage'
+    )
+</template>
+
+<script setup>
+import { ref, computed } from 'vue';
+import { ItemsListWidget } from 'widgets/ItemsListWidget';
+import { useItemStore } from 'entities/Item/model';
+
+const store = useItemStore();
+const currentPage = ref(1);
+
+const totalPages = computed(() =>
+  Math.ceil((store.items?.totalCount || 0) / 25)
+);
+
+const loadPage = async (page) => {
+  await store.loadItems({ page });
+};
+</script>
+```
+
+#### Страница с несколькими виджетами
+```vue
+<template lang="pug">
+.q-pa-md
+  // Заголовок страницы
+  PageHeader(title='Дашборд')
+
+  .row.q-gutter-md
+    .col-12.col-md-6
+      // Статистика
+      StatsWidget(:stats='stats')
+
+    .col-12.col-md-6
+      // Недавние действия
+      RecentActionsWidget(:actions='recentActions')
+
+  // Основной контент
+  MainContentWidget(
+    :data='mainData',
+    @refresh='loadData'
+  )
+</template>
+
+<script setup>
+import { onMounted } from 'vue';
+import PageHeader from 'src/shared/ui/PageHeader';
+import StatsWidget from 'widgets/StatsWidget';
+import RecentActionsWidget from 'widgets/RecentActionsWidget';
+import MainContentWidget from 'widgets/MainContentWidget';
+
+onMounted(() => {
+  loadData();
+});
+</script>
+```
+
+### Важные принципы
+
+#### Производительность
+- Ленивая загрузка данных
+- Оптимизация перерисовок
+- Эффективное управление памятью
+
+#### Доступность
+- Правильная структура заголовков
+- Клавиатурная навигация
+- Screen reader поддержка
+
+#### SEO и метаданные
+- Управление title страницы
+- Meta теги для социальных сетей
+- Структурированные данные