Клиент Матикон Офис Докспейс

Этот репозиторий содержит клиентскую часть Матикон Офис Докспейс — платформы совместной работы с документами, основанной на комнатах.

Полный обзор продукта приведён в README основного репозитория. Настройка и архитектура серверной части описаны в README сервера.

Содержание

Технологический стек
Структура проекта
Git-подмодули
Начало работы
Поддерживаемые браузеры
Тестирование
Устранение неполадок
Участие в разработке
Лицензирование

Технологический стек

Язык: TypeScript 5.9 в строгом режиме.
Фреймворк: React 19 с React Compiler.
Управление состоянием: MobX 6.
Стили: CSS/SASS, Styled-Components 5.
Интернационализация: i18next.
Сборщик: Vite 6 для клиента, Webpack 5 для приложений Next.js.
Серверный рендеринг: Next.js.
Тестирование: Vitest, Playwright.
Линтинг: Biome.
Менеджер пакетов: pnpm 10.28+ с рабочими пространствами.
Монорепозиторий: Nx.

Структура проекта

Проект организован как pnpm-монорепозиторий под управлением Nx. Он содержит шесть пакетов с чётким разделением ответственности.

packages/
├── client/         # Основное приложение DocSpace
├── login/          # Аутентификация и авторизация
├── doceditor/      # Интерфейс редактора документов
├── management/     # Панель администрирования
├── sdk/            # JavaScript SDK для внешних интеграций
└── shared/         # Общие компоненты, хуки, хранилища и утилиты

Назначение пакетов

`@docspace/client` — основное приложение

Назначение: основное веб-приложение DocSpace.

Возможности:

главная панель и навигация;
управление файлами и папками;
создание и управление комнатами: Public, Collaboration, VDR и Custom;
управление пользователями и группами;
сторонние интеграции;
настройки и предпочтения.

Технологический стек: Vite 6, React 19, MobX 6. Точка входа: packages/client/src/index.tsx.

`@docspace/login` — аутентификация

Назначение: обработка всех сценариев аутентификации.

Возможности:

вход по адресу электронной почты и паролю;
двухфакторная аутентификация (2FA);
единый вход (SSO) через SAML;
сброс и восстановление пароля;
регистрация пользователя, если она включена.

Технологический стек: Next.js, React 19. Точка входа: packages/login/src/index.tsx.

`@docspace/doceditor` — редактор документов

Назначение: интеграция редактора документов Maticon Office.

Возможности:

просмотр и редактирование документов, электронных таблиц и презентаций;
совместная работа в реальном времени;
комментарии и отслеживание изменений;
поддержка плагинов редактора;
интерфейс с поддержкой мобильных устройств.

Технологический стек: Next.js, React 19, Maticon Office Docs API. Точка входа: packages/doceditor/src/index.tsx.

`@docspace/management` — панель администратора

Назначение: интерфейс администрирования.

Возможности:

системное администрирование;
аналитика и отчётность;
расширенные настройки;
управление арендаторами в режиме SaaS;
статистика использования.

Технологический стек: Next.js, React 19. Точка входа: packages/management/src/index.tsx.

`@docspace/sdk` — JavaScript SDK

Назначение: SDK внешней интеграции для сторонних приложений.

Возможности:

встраиваемые компоненты DocSpace;
JavaScript API для внешних приложений;
поддержка интеграции через фреймы;
обёртки публичного API.

Технологический стек: TypeScript, Rollup. Точка входа: packages/sdk/src/index.ts. Документация: документация JavaScript SDK.

`@docspace/shared` — общая библиотека

Назначение: основная общая библиотека, используемая всеми приложениями.

Структура:

packages/shared/
├── components/         # Более 130 переиспользуемых компонентов React
├── hooks/              # Пользовательские хуки React
├── store/              # Управление состоянием MobX
├── api/                # Клиент API и службы
├── utils/              # Вспомогательные функции
├── types/              # Определения типов TypeScript
├── dialogs/            # Компоненты модальных диалогов
├── themes/             # Описания тем
└── enums/              # Перечисления и константы

Поток приложения

Система сборки

Инструмент сборки: Nx с пользовательскими исполнителями.
Сборщик модулей: Vite 6 для клиента, Next.js/Webpack для login, doceditor и management, Rollup для SDK.
Кэш: кэширование вычислений Nx для быстрой повторной сборки.
Параллельная сборка: все пакеты могут собираться независимо.

Основные зависимости

Все приложения зависят от @docspace/shared, который предоставляет:

согласованные компоненты интерфейса;
централизованное управление состоянием;
единый слой API;
общие типы и утилиты;
общую бизнес-логику.

Git-подмодули

Репозиторий использует Git-подмодуль с библиотекой компонентов интерфейса.

`libs/ui-kit` — библиотека компонентов интерфейса

Назначение: общая библиотека компонентов интерфейса приложений DocSpace.

Репозиторий: docspace-ui-kit-react. Расположение: libs/ui-kit/.

Возможности:

более 90 компонентов React: Button, Input, Modal, Table и другие;
пользовательские хуки и контексты;
система светлой Base- и тёмной Dark-тем;
поддержка интернационализации;
типы и утилиты TypeScript.

Работа с подмодулем:

# Клонировать репозиторий с подмодулями
git clone --recurse-submodules https://github.com/MaticonOffice/DocSpace.git

# Инициализировать подмодули, если репозиторий был клонирован без них
git submodule update --init --recursive

# Обновить подмодуль до последнего коммита
cd libs/ui-kit
git pull origin develop
cd ../..
git add libs/ui-kit
git commit -m "Update ui-kit submodule"

# Проверить состояние подмодулей
git submodule status

Документация: примеры компонентов и их использования приведены в README libs/ui-kit.

Начало работы

Примечание: для клиентской части требуется работающий сервер. Инструкции по настройке серверной части приведены в README сервера.

Предварительные требования

Инструмент	Версия	Команда проверки
Node.js	>= 24	`node --version`
pnpm	>= 10.28.0	`pnpm --version`
.NET SDK	10.0	`dotnet --version`
Docker	>= 28.5.0	`docker --version`

Быстрый старт

Примечание: репозиторий использует Git-подмодули. Если при клонировании не был указан параметр --recurse-submodules, сначала выполните git submodule update --init --recursive. Подробнее см. раздел «Git-подмодули».

Терминал 1 — запуск серверной части:

# Из корня DocSpace
cd server/common/ASC.AppHost
dotnet run --launch-profile frontend-dev

Терминал 2 — запуск клиентской части:

# Из корня DocSpace
cd client
pnpm install && pnpm start

Доступ к приложению:

DocSpace: http://localhost:8092
панель Aspire: http://localhost:15208

Редакции серверной части

По умолчанию сервер запускается в режиме Community Edition (CE). Другую редакцию можно выбрать с помощью переменной окружения APP_EDITION.

Выберите и выполните одну из следующих команд:

# Из корня DocSpace
cd server/common/ASC.AppHost

# Community Edition (CE): редакция по умолчанию, лицензия не требуется
dotnet run --launch-profile frontend-dev

# Enterprise Edition (EE): требуется файл лицензии
APP_EDITION=enterprise dotnet run --launch-profile frontend-dev

# Developer Edition (DE): требуется файл лицензии
APP_EDITION=developer dotnet run --launch-profile frontend-dev

# Режим SaaS с несколькими арендаторами
dotnet run --launch-profile frontend-dev --APP_HOSTING_STANDALONE false

Примечание: для Enterprise Edition (EE) и Developer Edition (DE) требуется действительный файл лицензии. Профили запуска и конфигурация серверной части описаны в README сервера.

Запуск отдельных приложений

Выберите и выполните одну из следующих команд.

Режим разработки:

# Запустить только client
cd packages/client && pnpm start

# Запустить только login
cd packages/login && pnpm start

# Запустить только doceditor
cd packages/doceditor && pnpm start

# Запустить только management
cd packages/management && pnpm start

# Запустить все приложения из корня
pnpm start

# Запустить только основные приложения: client, login и doceditor
pnpm start:lite

Промышленный режим:

pnpm start-prod       # Все приложения
pnpm start-prod:lite  # Только основные приложения

Режим предварительного просмотра

В режиме предварительного просмотра все четыре приложения Next.js — login, doceditor, management и SDK — запускаются как предварительно собранные промышленные пакеты, а не в режиме разработки. Это значительно сокращает время запуска и потребление памяти.

Шаг 1 — сборка и развёртывание:

cd client
pnpm deploy:preview

Шаг 2 — запуск статического сервера клиента:

cd publish/web/client
npx serve -s -p 5001

Шаг 3 — запуск сервера приложений:

cd publish/web/apps
node server.js --app.port=5055 --app.hostname=127.0.0.1

Портал будет доступен по адресу http://localhost:8092; серверная часть должна быть запущена с профилем frontend-dev.

Основные отличия от pnpm start:

SSR-приложения работают в промышленном режиме, поэтому запускаются быстрее и потребляют меньше памяти;
горячая перезагрузка отсутствует: после изменений необходимо повторно выполнить pnpm deploy:preview;
клиентское приложение обслуживается как статические файлы через Nginx в Docker или локально через npx serve.

Подробности об архитектуре и конфигурации приведены в README режима предварительного просмотра.

Разработка в VSCode

Для разработки клиентской части рекомендуется использовать рабочее пространство VSCode, которое предоставляет кнопки задач для запуска серверной и клиентской частей одним нажатием.

1. Откройте рабочее пространство:

code client/frontend.code-workspace

2. Установите расширение Task Buttons (spencerwmiles.vscode-task-buttons), чтобы добавить удобные кнопки на панель инструментов.

3. Запускайте службы кнопками задач:

Серверную и клиентскую части можно запускать прямо с панели инструментов VSCode.

Задачи серверной части:

Задачи клиентской части:

Задачи также доступны через стандартное меню VSCode Terminal → Run Task.

Разработка серверной части C# в VSCode описана в README сервера.

Очистка артефактов Docker Aspire

Linux/macOS (bash):

docker ps -a --format '{{.Names}}' | grep -E 'mysql|redis|cache-|rabbitmq|messaging-|opensearch|mailpit|dbgate|redisinsight|maticonoffice-editors|openresty' | xargs -r docker stop && \
docker ps -a --format '{{.Names}}' | grep -E 'mysql|redis|cache-|rabbitmq|messaging-|opensearch|mailpit|dbgate|redisinsight|maticonoffice-editors|openresty' | xargs -r docker rm && \
docker volume prune -f && docker network prune -f

Windows (PowerShell):

$c = docker ps -a --format '{{.Names}}' | Where-Object { $_ -match 'mysql|redis|cache-|rabbitmq|messaging-|opensearch|mailpit|dbgate|redisinsight|maticonoffice-editors|openresty' }; if ($c) { $c | ForEach-Object { docker stop $_ }; $c | ForEach-Object { docker rm $_ } }; docker volume prune -f; docker network prune -f

Поддерживаемые браузеры

Браузер	Минимальная версия
Chrome	Две последние версии
Firefox	Две последние версии
Safari	Две последние версии
Edge	Две последние версии

Поддерживаются мобильные браузеры в iOS 14+ и Android 8+.

Тестирование

Статический анализ

# Линтинг Biome для всех пакетов
pnpm lint

# Автоматически исправить проблемы линтинга
pnpm lint:fix

# Проверить типы TypeScript во всех пакетах
pnpm tsc

Модульные тесты

Модульные тесты используют Vitest и покрывают общие компоненты, хуки и утилиты в @docspace/shared.

# Запустить все модульные тесты
pnpm test

# Запустить интерактивный интерфейс
cd packages/shared && pnpm test:ui

# Запустить с отчётом о покрытии
cd packages/shared && pnpm test:coverage

Общие тесты

Проверки ресурсов и качества находятся в common/tests/:

cd common/tests

# Запустить все общие тесты
npm test

# Отдельные наборы тестов
npm run test:locales        # Проверка полноты переводов
npm run test:images         # Проверка графических ресурсов
npm run test:colors         # Проверка цветовой палитры
npm run test:ascii          # Проверка символов ASCII
npm run test:dependencies   # Аудит зависимостей и безопасности

Дополнительные проверки качества из корня репозитория:

# Аудит соответствия лицензиям
pnpm licenses-audit

# Аудит безопасности зависимостей
pnpm audit --audit-level=moderate

E2E-тестирование с Playwright

Для сквозного тестирования проект использует Playwright. Тесты выполняются в Docker-контейнерах, чтобы среда была одинаковой у всех разработчиков.

Зачем использовать Docker для E2E-тестов?

Согласованность: одинаковая среда для всех разработчиков — шрифты, браузеры и ОС.
Воспроизводимость: тесты дают одинаковый результат на любой машине.
Изоляция: тесты не влияют на локальную систему.
Точность снимков: тестам визуальной регрессии требуется попиксельная согласованность.
Готовность к CI/CD: локальные конвейеры и CI используют одну среду.

Запуск E2E-тестов

Первоначальная настройка — сборка Docker-образа:

cd packages/client
pnpm test:e2e:docker:build

Запуск всех E2E-тестов:

cd packages/client
pnpm test:e2e:docker:start

Запуск тестов отдельного пакета:

# Тесты клиента
cd packages/client && pnpm test:e2e:docker:start

# Тесты login
cd packages/login && pnpm test:e2e:docker:start

# Тесты doceditor
cd packages/doceditor && pnpm test:e2e:docker:start

# Тесты SDK
cd packages/sdk && pnpm test:e2e:docker:start

# Тесты management
cd packages/management && pnpm test:e2e:docker:start

Запуск тестов всех пакетов единым способом:

# Из корня репозитория
cd client

# Собрать единый Docker-образ E2E
docker compose -f docker/e2e/compose.yaml build e2e-tests

# Запустить все тесты
docker compose -f docker/e2e/compose.yaml run --rm \
  -e RUN_CLIENT=true \
  -e RUN_LOGIN=true \
  -e RUN_DOCEDITOR=true \
  -e RUN_SDK=true \
  -e RUN_MANAGEMENT=true \
  e2e-tests

Запуск одного файла тестов:

cd packages/client
pnpm exec playwright test path/to/test.spec.ts

Обновление эталонных снимков

ВАЖНО: для согласованности снимки всегда следует обновлять в Docker.

cd packages/client
pnpm test:e2e:docker:update-screenshots

Эта команда:

запускает тесты в Docker;
создаёт новые снимки в той же среде;
обновляет эталонные снимки с порогом 0,16 для визуального сравнения.

Зачем использовать Docker для снимков?

отрисовка шрифтов отличается в macOS, Linux и Windows;
поведение браузеров немного различается между платформами;
Docker гарантирует, что снимки создаются точно в той же среде, что и в CI/CD.

Просмотр отчётов о тестах

После выполнения тестов откройте HTML-отчёт:

# Отчёт клиента, порт 9325
cd packages/client
pnpm exec playwright show-report --port 9325

# Отчёт login, порт 9326
cd packages/login
pnpm exec playwright show-report --port 9326

# Отчёт doceditor, порт 9327
cd packages/doceditor
pnpm exec playwright show-report --port 9327

# Отчёт SDK, порт 9328
cd packages/sdk
pnpm exec playwright show-report --port 9328

# Отчёт management, порт 9329
cd packages/management
pnpm exec playwright show-report --port 9329

Очистка среды E2E

Удаление Docker-образа отдельного пакета:

cd packages/client
pnpm test:e2e:docker:clear

Удаление единого Docker-образа E2E:

cd client
docker compose -f docker/e2e/compose.yaml down --volumes --remove-orphans --rmi all

Конфигурация тестов

Тестовый фреймворк: Playwright.
Браузеры: Chromium, Firefox, WebKit.
Порог снимка: 0,16; допускается различие 16 % пикселей.
Тайм-аут: 30 секунд на тест.
Повторные попытки: две попытки после сбоя, только в CI.

Написание новых тестов

Тесты находятся в каталогах packages/*/src/__tests__/. Пример:

import { test, expect } from '@playwright/test';

test('should display dashboard', async ({ page }) => {
  await page.goto('http://localhost:8092');
  await expect(page).toHaveTitle(/DocSpace/);

  // Тест визуальной регрессии
  await expect(page).toHaveScreenshot('dashboard.png', {
    threshold: 0.16,
  });
});

Отладка тестов

Запуск тестов в видимом режиме с интерфейсом браузера:

cd packages/client
pnpm exec playwright test --headed

Запуск тестов в режиме отладки:

cd packages/client
pnpm exec playwright test --debug

Просмотр трассировки упавшего теста:

cd packages/client
pnpm exec playwright show-trace trace.zip

Конвейер CI/CD

Процесс GitHub Actions trigger-action автоматически запускается при отправке изменений в ветки develop, release/v* и hotfix/v* и вызывает последующую автоматизацию buildtools. В последующем конвейере тестирования клиентской части используются следующие этапы.

Этапы конвейера:

Определение изменений — определяет необходимые тесты по изменённым файлам.
Статический анализ и тесты — параллельно выполняются:
- линтинг Biome;
- компиляция TypeScript;
- модульные тесты Vitest;
- общие тесты изображений, цветов, ASCII и локалей;
- аудит зависимостей и соответствия лицензиям.
E2E-тесты — тесты Playwright для каждого пакета: client, login, doceditor, SDK и management; каждый набор выполняется в Docker-контейнере.

Запускаются только затронутые тесты. Например, изменения в packages/login/ запускают только E2E-тесты Login, а изменения в packages/shared/ — все наборы E2E.

Устранение неполадок

Сбой pnpm install

Очистите кэш pnpm: pnpm store prune.
Удалите node_modules: rm -rf node_modules.
Удалите pnpm-lock.yaml: rm pnpm-lock.yaml.
Повторите установку: pnpm install.

Порт 8092 уже используется

Завершите процесс, использующий порт:

# macOS/Linux
lsof -ti:8092 | xargs kill -9

# Windows
netstat -ano | findstr :8092
taskkill /PID <PID> /F

Проблемы серверной части

См. раздел об устранении неполадок в README сервера.

Другие проблемы можно найти в трекере задач или обсудить на форуме.

Участие в разработке

Процесс разработки

Создайте форк репозитория.
Клонируйте свой форк: git clone https://github.com/YOUR_USERNAME/DocSpace.git.
Создайте ветку функции: git checkout -b feature/amazing-feature.
Внесите изменения.
Запустите тесты: pnpm test.
Проверьте код линтером: pnpm lint:fix.
Создайте коммит: git commit -m 'Add amazing feature'.
Отправьте ветку в свой форк: git push origin feature/amazing-feature.
Откройте запрос на включение изменений.

Стандарты кода

Следуйте лучшим практикам TypeScript и React.
Выполняйте pnpm lint перед созданием коммита.
Добавляйте тесты для новых функций.
Делайте коммиты атомарными и снабжайте их ясным описанием.

Хуки перед отправкой с Lefthook

Для автоматических проверок качества перед отправкой кода проект использует Lefthook.

Перед отправкой автоматически выполняются:

проверка типов TypeScript (pnpm tsc);
линтинг Biome (pnpm lint);
тесты полноты переводов;
модульные тесты (pnpm test).

Lefthook автоматически устанавливается командой pnpm install. Конфигурация хранится в lefthook.yml в корне репозитория.

Пропуск хуков, использовать с осторожностью:

# Пропустить все хуки
LEFTHOOK=0 git push

# Пропустить отдельный хук
LEFTHOOK_EXCLUDE=tests git push

Соглашение о сообщениях коммитов

Следуйте соглашению Conventional Commits:

feat: новая функция;
fix: исправление ошибки;
docs: изменения документации;
style: изменения стиля кода;
refactor: рефакторинг кода;
test: изменения тестов;
chore: изменения сборки или инструментов.

Лицензирование

Матикон Офис Докспейс распространяется по лицензии AGPLv3. Дополнительная информация приведена в файле LICENSE.

Нужна помощь разработчику?

Ознакомьтесь с нашей официальной документацией API.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.agents/skills/fallow		.agents/skills/fallow
.claude		.claude
.gitea/workflows		.gitea/workflows
.github/workflows		.github/workflows
.vscode		.vscode
assets		assets
common		common
docker		docker
i18next		i18next
libs		libs
packages		packages
public		public
scripts		scripts
.dockerignore		.dockerignore
.fallowrc.json		.fallowrc.json
.gitignore		.gitignore
.gitmodules		.gitmodules
.npmrc		.npmrc
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
MATICON-NOTICE.md		MATICON-NOTICE.md
README.en.md		README.en.md
README.md		README.md
frontend.code-workspace		frontend.code-workspace
lefthook.yml		lefthook.yml
nx.json		nx.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
skills-lock.json		skills-lock.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Клиент Матикон Офис Докспейс

Содержание

Технологический стек

Структура проекта

Назначение пакетов

@docspace/client — основное приложение

@docspace/login — аутентификация

@docspace/doceditor — редактор документов

@docspace/management — панель администратора

@docspace/sdk — JavaScript SDK

@docspace/shared — общая библиотека

Поток приложения

Система сборки

Основные зависимости

Git-подмодули

libs/ui-kit — библиотека компонентов интерфейса

Начало работы

Предварительные требования

Быстрый старт

Редакции серверной части

Запуск отдельных приложений

Режим предварительного просмотра

Разработка в VSCode

Очистка артефактов Docker Aspire

Поддерживаемые браузеры

Тестирование

Статический анализ

Модульные тесты

Общие тесты

E2E-тестирование с Playwright

Зачем использовать Docker для E2E-тестов?

Запуск E2E-тестов

Обновление эталонных снимков

Просмотр отчётов о тестах

Очистка среды E2E

Конфигурация тестов

Написание новых тестов

Отладка тестов

Конвейер CI/CD

Устранение неполадок

Участие в разработке

Процесс разработки

Стандарты кода

Хуки перед отправкой с Lefthook

Соглашение о сообщениях коммитов

Лицензирование

Нужна помощь разработчику?

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`@docspace/client` — основное приложение

`@docspace/login` — аутентификация

`@docspace/doceditor` — редактор документов

`@docspace/management` — панель администратора

`@docspace/sdk` — JavaScript SDK

`@docspace/shared` — общая библиотека

`libs/ui-kit` — библиотека компонентов интерфейса

Packages