Initial commit: base slice (auth, roles, users, admin) scaffold
Backend: .NET 10 Clean Architecture + LiteCqrs.Net + EF Core/PostgreSQL + Identity/JWT. Frontend: React 19 + Vite + TanStack Query/Router + Tailwind v4 with a retro CRT theme. Docker/compose deployment mirroring PnvPanel's conventions, scoped down to the current base feature set.
This commit is contained in:
Leonid Pershin
@@ -0,0 +1,136 @@
|
||||
# CLAUDE.md
|
||||
|
||||
Инструкции для Claude Code при работе в этом репозитории.
|
||||
|
||||
## Что это
|
||||
|
||||
**TeleWave** — сервис онлайн-каналов: пользователи смотрят сетку каналов, видео отдаётся из
|
||||
хранилища на сервере. Админ управляет каналами и пользователями.
|
||||
|
||||
> Текущее состояние — **база**: вход/регистрация, роли, пользователи, минимальная админка,
|
||||
> приветственная главная страница. Каталог каналов и сама раздача видео **не реализованы** —
|
||||
> это следующий шаг. Telegram-бот сознательно не делаем.
|
||||
|
||||
Архитектура и код-конвенции — прямое зеркало [`D:\Github\PnvPanel`](../PnvPanel) (тот же автор,
|
||||
тот же стек), но домен урезан под текущий объём фичи.
|
||||
|
||||
## Стек
|
||||
|
||||
- **Backend**: C# / .NET 10, ASP.NET Core Web API (Minimal API), Clean Architecture, CQRS через
|
||||
[`LiteCqrs.Net`](https://github.com/mrleo1nid/LiteCqrs.Net) (NuGet-пакет, лёгкая
|
||||
CQRS-библиотека, альтернатива MediatR с явным разделением Command/Query — см. её README).
|
||||
EF Core 10 + Npgsql, ASP.NET Core Identity + JWT (access + refresh), FluentValidation, Serilog.
|
||||
Маппинг DTO вручную. OpenAPI — нативный `Microsoft.AspNetCore.OpenApi` + Scalar UI.
|
||||
- **Frontend**: React 19 + Vite + TS, TanStack Query/Router, shadcn-стиль поверх Radix + Tailwind
|
||||
v4, Zustand (только auth+тема), react-hook-form + zod. pnpm, oxlint.
|
||||
- **Инфра**: единый Docker-образ (API + статика SPA) + PostgreSQL в docker-compose.
|
||||
|
||||
## Архитектура — жёсткие правила
|
||||
|
||||
Слои и направление зависимостей: **Api → Infrastructure → Application → Domain** (внутрь).
|
||||
|
||||
- **Domain** — без внешних зависимостей. Сейчас единственная сущность — `Auth/RefreshToken`
|
||||
(rich model: приватные сеттеры, фабричный `Issue(...)`, поведенческий `Revoke(...)`).
|
||||
- **Application** — CQRS-хендлеры, DTO, валидаторы, **порты** (интерфейсы:
|
||||
`IAppDbContext`, `ICurrentUser`, `IIdentityService`, `IJwtTokenService`, `IRefreshTokenService`,
|
||||
`IRoleService`). Зависит только от Domain — никаких `Npgsql`/`AspNetCore.Identity`, только их
|
||||
абстракции.
|
||||
- **Infrastructure** — реализации портов: EF Core (`AppDbContext : IdentityDbContext<AppUser,
|
||||
AppRole, Guid>`), `IdentityService`/`RoleService`/`JwtTokenService`/`RefreshTokenService`,
|
||||
идемпотентный `DbInitializer` (сидинг ролей + админа).
|
||||
- **Api** — Minimal API эндпоинты (`Endpoints/*Endpoints.cs`), middleware, DI composition root
|
||||
(`Program.cs`).
|
||||
|
||||
Обязательно:
|
||||
- Команды меняют состояние в транзакции (`UnitOfWorkBehavior`); запросы только читают. Диспетчер —
|
||||
из `LiteCqrs.Net` (`ISender`/`ICommandHandler`/`IQueryHandler`), регистрация через
|
||||
`AddLiteCqrs(...)` в `TeleWave.Application/DependencyInjection.cs`.
|
||||
- Управляемые ошибки — через `Result<T>` (`Common/Models/Result.cs`), не исключениями.
|
||||
- Валидация — FluentValidation через `ValidationBehavior`; хендлер не перепроверяет формат ввода.
|
||||
- Всё I/O асинхронно, `CancellationToken` пробрасывается до EF/HTTP. Никаких `.Result`/`.Wait()`.
|
||||
- Nullable reference types включены; `Directory.Build.props` включает
|
||||
`TreatWarningsAsErrors=true` — предупреждения анализаторов не игнорировать.
|
||||
|
||||
## Домен: роли, пользователи, аутентификация
|
||||
|
||||
Полноценной доменной модели (каналы/видео) пока нет — см. заметку в начале файла. Текущие
|
||||
инварианты:
|
||||
|
||||
- **Роли** (`AppRole : IdentityRole<Guid>`, `Infrastructure/Identity/`) — динамические,
|
||||
без квот (в отличие от PnvPanel: тут нет `MaxIpLimit`/`BillingEnabled` — при появлении
|
||||
доменных фич квоты/лимиты добавляются на `AppRole`/`AppUser` по мере необходимости, не заранее).
|
||||
У пользователя ровно одна роль. Системные роли `admin`/`user` (`IsSystem=true`) нельзя
|
||||
переименовать/удалить — проверяется в `RoleService`. Смену роли (`ChangeUserRoleCommand`)
|
||||
запрещено делать так, чтобы не осталось ни одного `admin` (`RoleErrors.CannotRemoveLastAdmin`).
|
||||
- **Регистрация** — открытая, без гейта активации (в отличие от PnvPanel): `RegisterCommandHandler`
|
||||
создаёт пользователя с ролью `user` и сразу выдаёт токены (auto-login). Если в будущем
|
||||
понадобится модерация новых пользователей — добавлять отдельным полем/флагом по аналогии с
|
||||
`IsActivated` в PnvPanel, не переиспользовать `IsBlocked`.
|
||||
- **Блокировка** (`AppUser.IsBlocked`) — админ блокирует/разблокирует пользователя; вход
|
||||
запрещён (`LoginCommandHandler`/`RefreshCommandHandler` проверяют флаг). Админ не может
|
||||
заблокировать/удалить самого себя (`UserErrors.CannotBlockSelf`/`CannotDeleteSelf`).
|
||||
- **Вход по `UserName`** (email не используется, SMTP не нужен). JWT — access (короткий TTL) +
|
||||
refresh (httpOnly cookie `tw_refresh_token`, `SameSite=Strict`, ротация с обнаружением повторного
|
||||
использования отозванного токена — см. `RefreshTokenService.RotateAsync`).
|
||||
- **Сидинг**: идемпотентный `DbInitializer` создаёт системные роли + админа из env
|
||||
(`AdminSeed__Username`/`Password`) при старте. Источник примера env — `.env.example`.
|
||||
|
||||
## Единый контейнер
|
||||
|
||||
- Один образ: Api раздаёт REST (`/api`) и статику SPA из `wwwroot` (fallback на `index.html`).
|
||||
Один origin, база API — относительный `/api`.
|
||||
- Multi-stage Dockerfile: node (фронт) → dotnet sdk (publish + копирование в `wwwroot`) → aspnet
|
||||
runtime. Никакого gosu/root-drop и Data Protection key-ring — секретов на диске пока нет
|
||||
(JWT-ключ — обычная конфигурация, не шифруемый секрет at-rest); если появятся зашифрованные
|
||||
данные (например API-ключи внешних сервисов) — добавлять Data Protection по образцу PnvPanel.
|
||||
- docker-compose: `app` + `db` (PostgreSQL). Миграции применяются авто на старте
|
||||
(`ApplyMigrationsAsync` в `Program.cs`).
|
||||
- Не вводи отдельный nginx-контейнер для статики — ломает требование единого контейнера.
|
||||
- **TLS — внешний**; `app` отдаёт HTTP + доверяет `X-Forwarded-*` (`ForwardedHeaders`).
|
||||
|
||||
## Соглашения по коду
|
||||
|
||||
- `<Verb><Noun>Command`/`<Get|List><Noun>Query` + `Handler`/`Validator` (валидатор — где есть что
|
||||
проверить). Папки — по фичам (`Auth/Login/`, `Admin/Roles/CreateRole/`, ...).
|
||||
- DTO — суффикс `Dto`; тела запросов Api-эндпоинтов, не совпадающие с командой 1:1, — `Body`
|
||||
(`sealed record` внизу файла эндпоинта).
|
||||
- Один публичный тип на файл = имя файла (кроме `Body` в файле эндпоинтов).
|
||||
- Ошибки — статические каталоги `XErrors` (`AuthErrors`, `RoleErrors`, `UserErrors`) с
|
||||
`Error.Validation/NotFound/Conflict/Unauthorized/Forbidden(...)`.
|
||||
- Секреты не логировать; логи — Serilog.
|
||||
- Ошибки API — единый `application/problem+json` (см. `Api/Common/ResultExtensions.cs`).
|
||||
|
||||
## Команды
|
||||
|
||||
Backend (из `backend/`):
|
||||
```bash
|
||||
dotnet build
|
||||
dotnet test tests/TeleWave.Domain.Tests tests/TeleWave.Application.Tests
|
||||
dotnet run --project src/TeleWave.Api
|
||||
dotnet ef migrations add <Name> --project src/TeleWave.Infrastructure --startup-project src/TeleWave.Api
|
||||
dotnet ef database update --project src/TeleWave.Infrastructure --startup-project src/TeleWave.Api
|
||||
```
|
||||
|
||||
Frontend (из `frontend/`):
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm dev
|
||||
pnpm build
|
||||
pnpm lint && pnpm typecheck
|
||||
```
|
||||
|
||||
Инфраструктура:
|
||||
```bash
|
||||
docker compose up -d --build # api + postgres
|
||||
```
|
||||
|
||||
> Окружение: Windows, основная оболочка — **PowerShell**. Для POSIX-скриптов есть Bash-инструмент.
|
||||
|
||||
## Рабочие принципы
|
||||
|
||||
- Не начинай крупную реализацию (каталог каналов, раздача видео, транскодинг и т.п.) без сверки
|
||||
с пользователем — это следующий большой этап после базы, архитектурные решения там ещё не приняты.
|
||||
При неоднозначности — вопрос пользователю, не предположение.
|
||||
- Соблюдай границы слоёв — главный инвариант проекта, как и в PnvPanel.
|
||||
- Не коммить и не пуши без явной просьбы.
|
||||
- Отвечай пользователю на русском.
|
||||
Reference in New Issue
Block a user