Общая информация - Документация HRoom

1.1. Описание проекта

HRoom - это комплексная платформа для HR-менеджеров и руководителей, предназначенная для анализа вовлеченности сотрудников и улучшения показателей эффективности команд. Платформа предлагает инструменты для проведения опросов, анализа данных и получения AI-рекомендаций для улучшения рабочей среды.

Основные возможности HRoom:

Дашборд - интерактивный обзор ключевых метрик и показателей эффективности команд
Аналитика - детальный анализ ответов на опросы и метрик по различным параметрам
Управление идеями - AI-генерируемые инсайты и рекомендации для улучшения командной работы
Комментарии - работа с текстовыми отзывами сотрудников и их анализ
Опросы - создание, настройка и проведение различных видов опросов
Управление командами - организация и управление структурой команд и отделов
Административные инструменты - управление пользователями, компаниями и настройками системы

HRoom использует современные технологии искусственного интеллекта для анализа ответов сотрудников и генерации практических рекомендаций. Платформа помогает HR-специалистам и руководителям команд принимать обоснованные решения на основе данных, выявлять проблемные области и разрабатывать стратегии для улучшения показателей вовлеченности и эффективности.

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

HRoom построен на основе современных технологий, обеспечивающих высокую производительность, масштабируемость и удобство разработки.

Frontend

React - библиотека для создания пользовательских интерфейсов
TypeScript - типизированный JavaScript для улучшения качества кода
Vite - быстрый инструмент сборки для современных веб-приложений
Tailwind CSS - утилитарный CSS-фреймворк для стилизации компонентов
Recharts - библиотека для создания графиков и диаграмм
React Router - маршрутизация в React-приложении

API-интеграция

Fetch API - для выполнения HTTP-запросов
RESTful API - взаимодействие с серверной частью через API (api.hroom.ai)
JWT - токены для аутентификации запросов

Инструменты разработки

ESLint - статический анализ кода для выявления проблем
PostCSS - инструмент для трансформации CSS
npm - менеджер пакетов для управления зависимостями
Git - система контроля версий

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


{
  "name": "hroom",
  "private": true,
  "version": "0.2.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-router-dom": "^6.18.0",
    "recharts": "^2.10.1"
  },
  "devDependencies": {
    "@types/react": "^18.2.15",
    "@types/react-dom": "^18.2.7",
    "@typescript-eslint/eslint-plugin": "^6.0.0",
    "@typescript-eslint/parser": "^6.0.0",
    "@vitejs/plugin-react": "^4.0.3",
    "autoprefixer": "^10.4.16",
    "eslint": "^8.45.0",
    "eslint-plugin-react-hooks": "^4.6.0",
    "eslint-plugin-react-refresh": "^0.4.3",
    "postcss": "^8.4.31",
    "tailwindcss": "^3.3.5",
    "typescript": "^5.0.2",
    "vite": "^4.4.5"
  }
}

1.3. Требования к окружению

Для разработки и запуска проекта HRoom необходимо следующее окружение:

Минимальные требования

Node.js - версия 16.0.0 или выше
npm - версия 7.0.0 или выше (поставляется с Node.js)
Современный браузер - Chrome, Firefox, Safari или Edge последних версий
Доступ к интернету - для подключения к API-сервисам

Установка и запуск

Клонирование репозитория:

git clone https://github.com/your-org/hroom.git
cd hroom

Установка зависимостей:
```
npm install
```
Запуск проекта в режиме разработки:
```
npm run dev
```
После запуска приложение будет доступно по адресу http://localhost:5173.
Сборка проекта для продакшн:
```
npm run build
```
Результат сборки будет находиться в директории dist.

Конфигурация

Для корректной работы проекта необходимо настроить доступ к API-сервисам. По умолчанию проект настроен на работу с API по адресу https://api.hroom.ai.

Проект использует Vite для сборки и разработки. Подробная информация о конфигурации находится в файле vite.config.ts:


import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': '/src',
    },
  },
})

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

Проект HRoom организован по функциональному принципу, обеспечивающему четкую структуру, масштабируемость и удобство поддержки кода.

Корневая директория


hroom/
├── dist/               # Скомпилированная версия приложения
├── public/             # Статические файлы
├── src/                # Исходный код приложения
├── .bolt/              # Конфигурации для AI-генерации
├── .eslintrc.js        # Конфигурация ESLint
├── .gitattributes      # Настройки Git
├── .gitignore          # Игнорируемые файлы Git
├── index.html          # Точка входа HTML
├── package.json        # Зависимости и скрипты npm
├── postcss.config.js   # Конфигурация PostCSS
├── tailwind.config.js  # Конфигурация Tailwind CSS
├── tsconfig.json       # Конфигурация TypeScript
└── vite.config.ts      # Конфигурация Vite

Директория src

Основная директория с исходным кодом приложения имеет следующую структуру:


src/
├── components/         # Многоразовые компоненты UI
│   ├── Layout.tsx      # Компонент основного макета
│   ├── Modal.tsx       # Компонент модального окна
│   ├── Sidebar.tsx     # Компонент боковой навигации
│   ├── ui/             # Базовые UI-компоненты
│   ├── surveys/        # Компоненты для работы с опросами
│   └── teams/          # Компоненты для работы с командами
├── pages/              # Страницы приложения
│   ├── Admin/          # Административные страницы
│   ├── Analytics/      # Страницы аналитики
│   ├── Auth/           # Страницы аутентификации
│   ├── Comments/       # Страница комментариев
│   ├── Dashboard/      # Компоненты дашборда
│   ├── Ideas/          # Страница идей и рекомендаций
│   ├── Profile/        # Страницы профиля пользователя
│   └── Teams/          # Страницы управления командами
├── services/           # Сервисы для работы с API
│   ├── api/            # API-клиенты
│   └── teams/          # Сервисы для работы с командами
├── types/              # TypeScript типы и интерфейсы
│   ├── ai-data.ts      # Типы для AI-данных
│   ├── company.ts      # Типы для компаний
│   ├── hrmanager.ts    # Типы для HR-менеджеров
│   ├── insights.ts     # Типы для инсайтов
│   ├── metrics.ts      # Типы для метрик
│   ├── question.ts     # Типы для вопросов
│   ├── questionGroup.ts # Типы для групп вопросов
│   └── survey.ts       # Типы для опросов
├── App.tsx             # Корневой компонент приложения
├── index.css           # Глобальные стили
├── main.tsx            # Точка входа JavaScript
└── vite-env.d.ts       # Типы окружения Vite

Организация компонентов

Компоненты в проекте организованы по следующему принципу:

Компоненты страниц - находятся в директории pages и представляют собой полноценные страницы приложения
UI-компоненты - находятся в директориях components и components/ui, это переиспользуемые элементы интерфейса
Специализированные компоненты - сгруппированы по функциональности (surveys, teams и т.д.)

Для каждого модуля (Dashboard, Analytics, Ideas и т.д.) соблюдается следующая структура:


pages/ModuleName/
├── components/         # Компоненты для данного модуля
├── hooks/              # Хуки для работы с данными
├── services/           # Сервисы для API-запросов
├── utils/              # Вспомогательные функции
├── types/              # Специфичные типы
├── constants/          # Константы
└── index.tsx           # Основная страница

Соглашения по именованию

Компоненты React - используется PascalCase (например, TeamList.tsx)
Хуки - используется camelCase с префиксом 'use' (например, useTeamsData.ts)
Утилиты и сервисы - используется camelCase (например, teamsService.ts)
Типы и интерфейсы - используется PascalCase (например, Survey, MetricType)

Стилизация компонентов

В проекте HRoom используется Tailwind CSS для стилизации компонентов. Tailwind CSS позволяет применять стили непосредственно в HTML с помощью предопределенных классов:


<div className="bg-white rounded-lg shadow p-4 hover:shadow-lg transition-shadow">
  <h2 className="text-xl font-semibold text-gray-800 mb-2">Заголовок</h2>
  <p className="text-gray-600">Содержимое</p>
</div>

Конфигурация Tailwind CSS находится в файле tailwind.config.js, где определены кастомные цвета, шрифты и другие параметры:


/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {
      colors: {
        primary: "#7d4cf1",
        "primary-light": "#9369f5",
        secondary: "#10b981",
        // Другие кастомные цвета
      },
      // Другие расширения темы
    },
  },
  plugins: [],
}

Инфраструктура типов

Проект использует TypeScript для обеспечения типобезопасности. Основные типы определены в директории src/types. Пример типа для опроса:


// src/types/survey.ts
import { Question } from './question';

export type SurveyStatus = 'DRAFT' | 'ACTIVE' | 'COMPLETED' | 'ARCHIVED';

export type SurveyType = 'REGULAR' | 'PULSE' | 'ONBOARDING' | 'EXIT';

export interface Survey {
  id: string;
  title: string;
  description?: string;
  type: SurveyType;
  status: SurveyStatus;
  questions: Question[];
  startDate: string;
  endDate?: string;
  createdAt: string;
  updatedAt: string;
  respondents?: number;
  responses?: number;
}

export interface SurveyResponse {
  id: string;
  surveyId: string;
  userId: string;
  answers: {
    questionId: string;
    value: number | string;
    comment?: string;
  }[];
  submittedAt: string;
}

API-интеграция

Проект интегрируется с API через сервисы, расположенные в директории src/services. Пример сервиса для работы с опросами:


// src/services/surveyService.ts
import { Survey, SurveyResponse } from '../types/survey';

const API_URL = 'https://api.hroom.ai';

export const surveyService = {
  async getSurveys(): Promise<Survey[]> {
    const response = await fetch(`${API_URL}/surveys`, {
      headers: {
        'Authorization': `Bearer ${localStorage.getItem('authToken')}`,
      },
    });
    
    if (!response.ok) {
      throw new Error('Failed to fetch surveys');
    }
    
    return response.json();
  },
  
  async getSurveyById(id: string): Promise<Survey> {
    const response = await fetch(`${API_URL}/surveys/${id}`, {
      headers: {
        'Authorization': `Bearer ${localStorage.getItem('authToken')}`,
      },
    });
    
    if (!response.ok) {
      throw new Error(`Failed to fetch survey with id ${id}`);
    }
    
    return response.json();
  },
  
  // Другие методы для работы с опросами
};

Выводы

Структура проекта HRoom хорошо организована и следует современным практикам разработки React-приложений:

Четкое разделение по функциональности
Использование TypeScript для типобезопасности
Компонентный подход с переиспользуемыми элементами
Модульная организация сервисов
Централизованное определение типов
Современный инструментарий сборки (Vite)
Утилитарный подход к стилизации с Tailwind CSS

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

Документация HRoom

1. Общая информация

1.1. Описание проекта

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

Frontend

API-интеграция

Инструменты разработки

1.3. Требования к окружению

Минимальные требования

Рекомендуемое окружение разработки

Установка и запуск

Конфигурация

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

Корневая директория

Директория src

Организация компонентов

Соглашения по именованию

Стилизация компонентов

Инфраструктура типов

API-интеграция

Выводы