docs: update CLAUDE.md and README.md for v0.0.1

- CLAUDE.md: add dev:https command, UI Architecture section (design
  system, room layout, screen share, sidebar), new Known Issues (HTTPS,
  chat duplication, self-ban), https:// in trustedOrigins note
- README.md: add dev:https command, features list for v0.0.1, screen
  share mention, HTTPS note for LAN, self-ban protection in API table
This commit is contained in:
2026-03-24 12:39:52 +03:00
parent 287d2295b3
commit f9f8d22f8d
2 changed files with 36 additions and 6 deletions

View File

@@ -43,8 +43,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
│ │ ├── login/ & register/ # Auth pages │ │ ├── login/ & register/ # Auth pages
│ │ └── page.tsx # Landing │ │ └── page.tsx # Landing
│ ├── components/ │ ├── components/
│ │ ├── room/ # ChatPanel, ModerationPanel │ │ ├── room/ # ChatPanel, ModerationPanel (with self-ban protection)
│ │ └── lobby/ # WaitingRoom, LobbyManager │ │ └── lobby/ # WaitingRoom, LobbyManager (scrollable)
│ ├── lib/ # prisma, auth, auth-helpers, livekit, redis, rate-limit, lobby-pubsub, chat-pubsub │ ├── lib/ # prisma, auth, auth-helpers, livekit, redis, rate-limit, lobby-pubsub, chat-pubsub
│ ├── middleware.ts # Dev protection (DEV_ACCESS_KEY, ALLOWED_IPS) │ ├── middleware.ts # Dev protection (DEV_ACCESS_KEY, ALLOWED_IPS)
│ └── types/ │ └── types/
@@ -106,6 +106,7 @@ Clients → Traefik (LB) → Next.js (x2 replicas) → PgBouncer (pool 25, max 5
```bash ```bash
# Dev # Dev
npm run dev # Next.js dev server (localhost:3000) npm run dev # Next.js dev server (localhost:3000)
npm run dev:https # Dev server with self-signed HTTPS (media devices on LAN)
docker compose up -d postgres minio redis pgbouncer # DB + Storage + Redis + PgBouncer docker compose up -d postgres minio redis pgbouncer # DB + Storage + Redis + PgBouncer
npm run lint # TypeScript type-check (tsc --noEmit) npm run lint # TypeScript type-check (tsc --noEmit)
@@ -182,7 +183,7 @@ DEV_ACCESS_KEY=mySecretKey123
- `better-auth` handles registration/login via `/api/auth/[...all]` catch-all route - `better-auth` handles registration/login via `/api/auth/[...all]` catch-all route
- **Client:** `auth-client.ts` uses `createAuthClient()` without `baseURL` — auto-detects current origin (works from any IP/domain) - **Client:** `auth-client.ts` uses `createAuthClient()` without `baseURL` — auto-detects current origin (works from any IP/domain)
- **Server:** `auth.ts` uses `BETTER_AUTH_URL` for `baseURL` and `BETTER_AUTH_TRUSTED_ORIGINS` (comma-separated) for CSRF origin validation. Without `BETTER_AUTH_TRUSTED_ORIGINS`, auto-detects all machine IPs via `os.networkInterfaces()` + localhost on ports 30003010 - **Server:** `auth.ts` uses `BETTER_AUTH_URL` for `baseURL` and `BETTER_AUTH_TRUSTED_ORIGINS` (comma-separated) for CSRF origin validation. Without `BETTER_AUTH_TRUSTED_ORIGINS`, auto-detects all machine IPs via `os.networkInterfaces()` + localhost on ports 30003010, both `http://` and `https://` protocols
- First admin: first registered user automatically becomes ADMIN (via `databaseHooks.user.create.before` in `auth.ts`) - First admin: first registered user automatically becomes ADMIN (via `databaseHooks.user.create.before` in `auth.ts`)
- **No `"type"` field in `package.json`** — removed to fix Turbopack ESM/CJS conflict in dev mode. Next.js handles ESM in `.ts/.tsx` automatically - **No `"type"` field in `package.json`** — removed to fix Turbopack ESM/CJS conflict in dev mode. Next.js handles ESM in `.ts/.tsx` automatically
@@ -222,6 +223,20 @@ DEV_ACCESS_KEY=mySecretKey123
| `setup.sh doctor` crashes on .env check | Comments in `.env.example` parsed as variable names by `set -euo pipefail` | Fixed parsing logic | | `setup.sh doctor` crashes on .env check | Comments in `.env.example` parsed as variable names by `set -euo pipefail` | Fixed parsing logic |
| `setup.sh update` runs git pull after stash declined | Missing `else` branch after stash prompt | Fixed control flow | | `setup.sh update` runs git pull after stash declined | Missing `else` branch after stash prompt | Fixed control flow |
| Auth form resets on non-localhost (no error shown) | `trustedOrigins` fallback only had `localhost:3000`, CSRF rejected other origins silently | `auth.ts` auto-allows ports 30003010 + `LAN_HOST`; `setup.sh dev` auto-detects LAN IP | | Auth form resets on non-localhost (no error shown) | `trustedOrigins` fallback only had `localhost:3000`, CSRF rejected other origins silently | `auth.ts` auto-allows ports 30003010 + `LAN_HOST`; `setup.sh dev` auto-detects LAN IP |
| Media devices blocked on LAN (not HTTPS) | Browsers require secure context for getUserMedia | `npm run dev:https` (Next.js `--experimental-https`), `setup.sh dev` auto-uses HTTPS |
| Chat messages duplicated | Race: SSE delivers msg before POST response, seenIds doesn't have real id yet | Check if SSE already delivered the message before replacing optimistic |
| Ban self crashes room | No server-side check for self-ban/kick | API rejects `targetSessionId === session.user.id`, UI hides buttons for self |
## UI Architecture
- **Design system:** CSS custom properties in `globals.css` via Tailwind v4 `@theme` — surface levels (03), accent (indigo), status colors, border tokens
- **Room layout (Google Meet style):**
- Minimal top bar (room name + code)
- Video area: `GridLayout` (cameras) or `FocusLayout` (screen share active — carousel + focused view)
- Bottom control bar: mic, camera, screen share | chat, lobby, moderation, hand raise | leave/end
- **Screen share:** auto-detected via `useTracks(Track.Source.ScreenShare)`, switches to focus layout with `CarouselLayout` for camera feeds
- **Sidebar:** 320px right panel for chat, lobby manager, moderation — stacked, each with own scroll
- **Components use LiveKit hooks:** `useLocalParticipant`, `useParticipants`, `useRoomContext`, `useTracks`
## Conventions ## Conventions

View File

@@ -1,6 +1,6 @@
# LiveServer-M1 # LiveServer-M1
Образовательная видеоконференц-платформа на базе LiveKit. AI-транскрипция, модерация, пост-лекционные артефакты. Образовательная видеоконференц-платформа на базе LiveKit. Демонстрация экрана, AI-транскрипция, модерация, пост-лекционные артефакты.
## Стек ## Стек
@@ -85,7 +85,7 @@ npx prisma db push
npm run dev npm run dev
``` ```
Приложение: `http://localhost:3000` Приложение: `http://localhost:3000` (или `https://localhost:3000` с `npm run dev:https` для доступа к камере/микрофону по LAN)
**Первый администратор:** первый зарегистрированный пользователь автоматически получает роль ADMIN. **Первый администратор:** первый зарегистрированный пользователь автоматически получает роль ADMIN.
@@ -163,6 +163,7 @@ Traefik автоматически получит SSL-сертификат че
# Разработка (ручной запуск) # Разработка (ручной запуск)
npm run dev # Next.js dev server npm run dev # Next.js dev server
npm run dev:https # Dev server с HTTPS (для камеры/микрофона по LAN)
npm run lint # TypeScript type-check (tsc --noEmit) npm run lint # TypeScript type-check (tsc --noEmit)
npm run build -- --webpack # Production build (Webpack, не Turbopack — WASM на Windows) npm run build -- --webpack # Production build (Webpack, не Turbopack — WASM на Windows)
@@ -232,7 +233,7 @@ docker compose logs -f app #
| `POST` | `/api/rooms/:id/start` | Старт лекции | | `POST` | `/api/rooms/:id/start` | Старт лекции |
| `POST` | `/api/rooms/:id/end` | Завершение лекции | | `POST` | `/api/rooms/:id/end` | Завершение лекции |
| `GET/POST` | `/api/rooms/:id/lobby` | Управление лобби | | `GET/POST` | `/api/rooms/:id/lobby` | Управление лобби |
| `POST` | `/api/rooms/:id/moderate` | Kick, ban, mute all | | `POST` | `/api/rooms/:id/moderate` | Kick, ban, mute all (self-ban protected) |
| `POST` | `/api/livekit/token` | Генерация токена LiveKit | | `POST` | `/api/livekit/token` | Генерация токена LiveKit |
### Требуют участия в комнате (sessionId) ### Требуют участия в комнате (sessionId)
@@ -248,3 +249,17 @@ docker compose logs -f app #
| **ADMIN** | Всё + глобальная панель, мониторинг всех комнат | | **ADMIN** | Всё + глобальная панель, мониторинг всех комнат |
| **HOST** | Создание комнат, модерация, настройки безопасности | | **HOST** | Создание комнат, модерация, настройки безопасности |
| **GUEST** | Вход по ссылке, участие в лекции (без регистрации) | | **GUEST** | Вход по ссылке, участие в лекции (без регистрации) |
## Возможности v0.0.1
- Видеоконференции (камера, микрофон, демонстрация экрана)
- Google Meet-style UI: нижняя панель управления, тёмная тема
- Автофокус при демонстрации экрана (карусель камер + фокус на экране)
- Зал ожидания (lobby) с SSE через Redis pub/sub
- PIN-коды для комнат (bcrypt + rate limiting)
- Real-time чат (SSE + optimistic UI, дедупликация)
- Модерация: kick, ban по fingerprint, mute all
- Поднятие руки (вебинар-режим)
- Первый пользователь автоматически → ADMIN
- HTTPS для локальной разработки (`--experimental-https`)
- Универсальный setup.sh (install/dev/doctor/status/update)