studio/docs/ONBOARDING.md

# Onboarding нового разработчика — путь от нуля до первого PR

Этот документ — пошаговый сценарий **первого дня** нового контрибьютора Рублокса. От «никогда не видел проект» до «мой PR смержили».

Время — **~2-3 часа** при хорошей сети.

---

## Что мы делаем

Тебе предстоит:

1. **Создать аккаунт** в Майнкрафтии (если ещё нет).
2. **Получить роль `developer`** от Лида.
3. **Зайти в /developer** на team.rublox.pro — это твой dashboard контрибьютора.
4. **Подписать CLA** (Contributor License Agreement, одна кнопка).
5. **Добавить SSH-ключ** в Gitea.
6. **Склонировать репо** (player или studio).
7. **Поднять локальное окружение** (npm install + dev-сервер).
8. **Открыть staging** для тестов с реальными данными.
9. **Сделать ветку, изменения, коммит, push, открыть PR.**
10. **Получить ревью** и (после правок если нужно) — merge.

---

## Шаг 1. Аккаунт в Майнкрафтии

Если ещё нет:

1. Зайди на https://minecraftia-school.ru/
2. Жми «Регистрация», заполняй (email, пароль, имя).
3. Подтверди email через ссылку в письме (или через Яндекс OAuth).

Запиши свой **email** и **числовой user_id** — он будет нужен дальше. Найти его можно так: открой свой профиль (`/profile`), там в URL будет id.

---

## Шаг 2. Получить роль `developer`

Только Лид (МИН) может выдать эту роль. Напиши ему в команде, дай свой `user_id`. Он выполнит:

```bash
POST https://team.rublox.pro/api-team/developer/grant/<твой_uid>
```

После этого в team-flask твой `team_roles_extra` будет содержать `developer`, и у тебя появится доступ к `/developer`.

**Как проверить:** зайди на https://team.rublox.pro/ — в сайдбаре должен появиться пункт **«Разработка»**. Если нет — роль не выдана.

---

## Шаг 3. Зайти в /developer (твой dashboard)

URL: https://team.rublox.pro/developer

Что увидишь — 7 вкладок:

| Вкладка | Что в ней |
|---|---|
| **Обзор** | Твоя статистика (PR, merged, score) + открытые PR команды + последние коммиты |
| **Pull Requests** | Все открытые PR в org `rublox`, можно фильтровать |
| **Коммиты** | Последние 50 коммитов по всем репо |
| **Репозитории** | Карточки `rublox/player` + `rublox/studio` с командой `git clone` |
| **Топ** | Лидерборд разработчиков по score |
| **SSH-ключи** | Управление твоими SSH-ключами в Gitea |
| **CLA** | Статус подписи Contributor License Agreement |

---

## Шаг 4. Подписать CLA

CLA — это юридическое соглашение что ты передаёшь Рублоксу права на свой код (стандартная opensource-практика, как у Google CLA).

1. Открой вкладку **«CLA»**.
2. Прочитай текст соглашения.
3. Жми **«Подписать»**.

В БД создастся запись `team_cla_signatures (user_id, version, signed_at, ip, ua)` — это и есть твоя подпись.

**Без CLA твои PR смержить нельзя.** Это технически возможно (Gitea пропустит), но юридически — нет.

---

## Шаг 5. Добавить SSH-ключ в Gitea

Чтобы делать `git push` без ввода пароля.

### 5.1. Сгенерируй ключ (если нет)

В терминале:

```bash
ssh-keygen -t ed25519 -C "твой_email@example.com"
```

Жми Enter на все вопросы (без passphrase для простоты). Получится пара файлов:
- `~/.ssh/id_ed25519` — приватный (НИКОМУ не показывай)
- `~/.ssh/id_ed25519.pub` — публичный (его и загружаем)

### 5.2. Скопируй публичный ключ

```bash
cat ~/.ssh/id_ed25519.pub
```

Скопируй вывод целиком (начинается с `ssh-ed25519 AAAA...`).

### 5.3. Добавь в Gitea

В /developer открой вкладку **«SSH-ключи»** → жми «Добавить ключ» → вставь публичный ключ → название («Мой ноут»).

Это под капотом дёрнет Gitea admin API и привяжет ключ к твоему аккаунту в `git.rublox.pro`.

### 5.4. Проверь

```bash
ssh -T git@git.rublox.pro -p 2222
```

Должен ответить `Hi <твой_логин>!`. Если ругается на permission denied — ключ не привязался, проверь шаг 5.3.

---

## Шаг 6. Склонировать репо

В /developer вкладка **«Репозитории»** — выбери что хочешь:

### Player (веб-плеер, что юзеры открывают для игры)

```bash
git clone ssh://git@git.rublox.pro:2222/rublox/player.git
cd player
```

### Studio (редактор где создаются игры)

```bash
git clone ssh://git@git.rublox.pro:2222/rublox/studio.git
cd studio
```

**Что выбрать первым:** если ты frontend-разработчик React, и хочешь начать с чего-то проще — бери **player** (он меньше, ~50К строк). Studio тяжелее (~80К + Babylon-движок).

---

## Шаг 7. Поднять локальное окружение

### 7.1. Требования

- **Node.js 20+** ([nodejs.org](https://nodejs.org/))
- **npm 10+** (идёт с Node)
- **Git** ([git-scm.com](https://git-scm.com/))
- IDE — рекомендую VS Code

Проверка:

```bash
node --version   # должно быть v20.x.x или выше
npm --version    # должно быть 10.x.x или выше
```

### 7.2. Установить зависимости

```bash
npm install
```

Это займёт 2-5 минут. Скачает Babylon.js, React, Vite и ~200 других пакетов в `node_modules/`.

### 7.3. Запустить dev-сервер

```bash
npm run dev
```

Vite запустит локальный сервер:
- **player** — http://localhost:5173
- **studio** — http://localhost:5174

Открой URL в браузере — увидишь свою локальную копию.

**Как работает API в dev-режиме:** Vite автоматически проксирует все `/api-*` запросы на **staging-окружение** `https://dev-api.rublox.pro/` (это копия прод-БД с анонимизированными юзерами). То есть твоя локальная копия будет ходить на staging — никаких проблем с CORS, никаких опасностей задеть прод.

---

## Шаг 8. Аутентификация в dev-режиме

Локально у тебя нет JWT — окно регистрации/логина откроется.

**Два варианта:**

### Вариант A — сделать тестовый аккаунт прямо на staging

Зарегистрируйся на dev-api.rublox.pro как новый юзер (или используй один из 2487 анонимизированных, чьи пароли все сброшены на `test123`). У этих юзеров уже есть тестовые проекты в БД.

### Вариант B — STANDALONE-режим (без бэка)

Создай файл `.env.local` в корне репо:

```
VITE_STANDALONE=true
```

И перезапусти `npm run dev`. Студия/плеер запустятся в режиме «гость» — все API-запросы замокированы, можно тестировать UI без реальных данных.

---

## Шаг 9. Сделать первое изменение

Для тренировки — измени какой-нибудь видимый текст или цвет.

### 9.1. Создай ветку

```bash
git checkout -b fix/typo-on-homepage
```

Соглашение по именам:
- `feature/<short-name>` — новая фича
- `fix/<short-name>` — багфикс
- `chore/<short-name>` — рефакторинг, документация

### 9.2. Сделай изменение

Открой файл в IDE, измени что-нибудь.

Пример (для studio): открой `src/community/KubikonStudio.jsx`, найди строку `'Создавай большие игры'`, замени на что-нибудь. Сохрани — Vite сделает HMR и ты увидишь изменение в браузере мгновенно.

### 9.3. Проверь свой код

```bash
npm run lint          # ESLint — проверка стиля
npm run format:check  # Prettier — проверка форматирования
npm run build         # Сборка должна пройти
```

Если что-то ругается — поправь.

### 9.4. Закоммить

```bash
git add .
git commit -m "fix: typo on homepage"
```

Формат commit message — **Conventional Commits**:
- `feat: добавил кнопку X`
- `fix: исправил Y`
- `chore: рефакторинг Z`
- `docs: обновил README`

### 9.5. Запушь

```bash
git push -u origin fix/typo-on-homepage
```

Gitea ответит:

```
remote: Create a new pull request for 'fix/typo-on-homepage':
remote:   https://git.rublox.pro/rublox/studio/compare/main...fix/typo-on-homepage
```

---

## Шаг 10. Открыть Pull Request

### 10.1. Перейти по ссылке

Открой URL из вывода `git push`, ИЛИ зайди на https://git.rublox.pro/rublox/studio → жми «Pull Requests» → «New Pull Request».

### 10.2. Заполнить PR

**Title:** одна строка, на русском, описывает что сделано
- ✅ «fix: опечатка на главной странице студии»
- ❌ «исправление»

**Description:** что и зачем, можно добавить скриншот «до/после». Шаблон:

```markdown
## Что сделано
Исправил опечатку «Создавай большие иры» → «Создавай большие игры».

## Зачем
Юзеры жаловались, выглядит непрофессионально.

## Как проверить
1. Открой главную студии
2. В hero-баннере смотри заголовок
3. Должно быть «игры», не «иры»
```

### 10.3. Жми «Create Pull Request»

Сразу после создания запустится **CI** в Gitea Actions:
- `lint` — ESLint без warnings
- `format-check` — Prettier
- `build` — vite build проходит
- `secret-scan` — trufflehog не нашёл утечек секретов
- `size-check` — PR не больше 1000 строк (warning)

Жди ~3-5 минут пока зелёные галочки появятся. Если красная — открой лог, поправь, `git commit --amend && git push -f` или новым коммитом.

### 10.4. Жди ревью

В **/developer → Pull Requests** твой PR появится в списке. Кто-то из core-команды его посмотрит, оставит комментарии или сразу одобрит.

Если будут замечания — внеси правки, закоммить, запушь. PR автоматически обновится.

### 10.5. Merge

Когда CI зелёный и ревьюер одобрил — Лид нажмёт **«Merge»**.

После merge:
- Твои метрики обновятся: `prs_merged += 1`, `score += 5`.
- Ты появишься в **«Топе»** лидерборда (если ещё нет).
- На staging автоматически уйдёт твой код (через ~5 минут — CD не настроен, ручной редеплой).

---

## Что почитать дальше

После первого merged PR — погружайся глубже:

- [ARCHITECTURE.md](../ARCHITECTURE.md) — как устроена студия архитектурно
- [src/editor/engine/README.md](../src/editor/engine/README.md) — движок Babylon
- [TUTORIAL_ADD_BLOCK.md](./TUTORIAL_ADD_BLOCK.md) — добавить новый тип блока
- [TUTORIAL_DEBUG_BABYLON.md](./TUTORIAL_DEBUG_BABYLON.md) — отладка 3D-сцены
- [API_USAGE.md](../API_USAGE.md) — какие эндпоинты бэкенда мы дёргаем

## Куда обращаться за помощью

- **Канал #разработка** в https://team.rublox.pro — главное место для вопросов
- **Issues в Gitea** — https://git.rublox.pro/rublox/studio/issues — для багов/предложений
- **Лид (МИН)** — последняя инстанция, пингуй если ничего не работает

---

## Чек-лист готовности

Перед тем как считать что освоился:

- [ ] Аккаунт в Майнкрафтии
- [ ] Роль `developer` от Лида
- [ ] CLA подписан
- [ ] SSH-ключ в Gitea, `ssh -T git@git.rublox.pro -p 2222` работает
- [ ] Репо склонирован, `npm install` прошёл
- [ ] `npm run dev` запустил, открыл http://localhost:5173 (или 5174)
- [ ] Залогинился в локальную копию
- [ ] Сделал тестовое изменение, увидел через HMR
- [ ] Запушил, открыл PR, CI зелёный, merge получил

Прошёл всё — поздравляю, ты в команде. Дальше — выбирай задачу из issues и поехали.