Skip to content

Instantly share code, notes, and snippets.

@sunmeat

sunmeat/README.md

Created September 29, 2026 14:56
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save sunmeat/149ae059fba88724e97e85d55c2f40f3 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save sunmeat/149ae059fba88724e97e85d55c2f40f3 to your computer and use it in GitHub Desktop.
Download ZIP
приклад рідмі
Raw
README.md

IPAY Backend

⚠️ Розділи з позначкою TODO / <...> потрібно уточнити під ваш проєкт (назва БД, змінні середовища, посилання тощо).

Зміст

Опис проєкту

IPAY Backend — серверна частина застосунку, реалізована на .NET за принципами Clean Architecture. Backend надає REST API для клієнтського застосунку (frontend), відповідає за бізнес-логіку, роботу з базою даних, автентифікацію/авторизацію та валідацію даних.

TODO: 2–3 речення про те, що саме робить ваш застосунок (наприклад: платежі, тестування, облік тощо).

Проблема та мета

Проблема. TODO: опишіть, яку проблему вирішує проєкт (наприклад: ручні процеси, відсутність єдиної системи, повільна обробка даних).

Мета. TODO: опишіть, чого досягає проєкт (наприклад: автоматизація процесу, надійний та безпечний API, зручний інтерфейс для користувачів).

Features

TODO: залишіть лише реалізовані можливості.

  • Реєстрація та автентифікація користувачів (JWT)
  • Рольова авторизація
  • CRUD-операції для основних сутностей домену
  • Валідація вхідних даних
  • Єдина обробка помилок
  • Документація API (Scalar / OpenAPI)
  • Технічна документація (DocFX)
  • Unit/інтеграційні тести
  • Контейнеризація (Docker)

Architecture overview

Проєкт розділений на шари (Clean Architecture). Залежності спрямовані до центру — Domain не залежить ні від чого.

src/
├── ExamTest.Domain           # Сутності, enum-и, доменна логіка, інтерфейси
├── ExamTest.Application      # Use cases, DTO, сервіси, валідація, інтерфейси репозиторіїв
├── ExamTest.Infastructure    # Доступ до БД (EF Core), репозиторії, зовнішні сервіси
├── ExamTest.WebApi           # Точка входу: контролери/endpoint-и, DI, middleware, конфігурація
└── ExamTest.Tests            # Тести
IPAY_BACKEND.slnx             # Solution

WebApi ──► Application ──► Domain
   │            ▲
   └──► Infastructure ──┘
Шар Відповідальність
Domain Ядро: сутності та правила предметної області
Application Бізнес-сценарії, DTO, контракти
Infastructure Реалізація контрактів: БД, ідентифікація, інтеграції
WebApi HTTP-шар, налаштування DI, Swagger/Scalar
Tests Автоматизовані тести

Стек: .NET, ASP.NET Core Web API, Entity Framework Core, TODO: СУБД (SQL Server / PostgreSQL), Scalar, DocFX, Docker.

Prerequisites

  • .NET SDK (версія, вказана у *.csproj, TODO: напр. 9.0 або 10.0)
  • Visual Studio 2022/2026 або VS Code / Rider (.slnx потребує свіжих версій)
  • TODO: СУБД (SQL Server / PostgreSQL) або Docker
  • Git
  • Docker & Docker Compose (опційно)
  • Node.js (для frontend, якщо потрібно)
  • Інструмент EF Core: 
    dotnet tool install --global dotnet-ef
  • DocFX (опційно): 
    dotnet tool install --global docfx

Installation

git clone https://github.com/ThisIsEngineerGaming/IPAY_backend.git
cd IPAY_backend

dotnet restore IPAY_BACKEND.slnx
dotnet build IPAY_BACKEND.slnx

Configuration

Налаштування знаходяться в src/ExamTest.WebApi/appsettings.json та appsettings.Development.json.

Приклад (TODO: підставте свої ключі):

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=ipay;User Id=sa;Password=<password>;TrustServerCertificate=True"
  },
  "Jwt": {
    "Key": "<секретний-ключ-мінімум-32-символи>",
    "Issuer": "IPAY",
    "Audience": "IPAY.Client",
    "ExpiresInMinutes": 60
  }
}

Для локальної розробки секрети краще зберігати через User Secrets:

cd src/ExamTest.WebApi
dotnet user-secrets init
dotnet user-secrets set "ConnectionStrings:DefaultConnection" "<connection-string>"
dotnet user-secrets set "Jwt:Key" "<secret>"

Environment variables

TODO: перевірте назви відповідно до вашого коду. У .NET вкладені ключі задаються через __.

Змінна Опис Приклад
ASPNETCORE_ENVIRONMENT Середовище виконання Development
ASPNETCORE_URLS Адреси, які слухає сервер http://+:8080
ConnectionStrings__DefaultConnection Рядок підключення до БД Server=db;Database=ipay;...
Jwt__Key Секретний ключ JWT <secret>
Jwt__Issuer Видавець токена IPAY
Jwt__Audience Аудиторія токена IPAY.Client
Jwt__ExpiresInMinutes Час життя токена 60

Рекомендується створити файл .env (не коммітити його в git):

ASPNETCORE_ENVIRONMENT=Development
ConnectionStrings__DefaultConnection=Server=localhost;Database=ipay;...
Jwt__Key=change-me

Database setup

  1. Запустіть СУБД (локально або в Docker).
  2. Вкажіть рядок підключення в конфігурації (див. вище).
  3. Застосуйте міграції (див. нижче) — база буде створена автоматично.

Приклад запуску БД у Docker (SQL Server, TODO: змініть на вашу СУБД):

docker run -d --name ipay-db \
  -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=Your_password123" \
  -p 1433:1433 mcr.microsoft.com/mssql/server:2022-latest

Migrations

Міграції створюються в проєкті Infastructure, а стартовим є WebApi.

Створити нову міграцію:

dotnet ef migrations add <MigrationName> \
  --project src/ExamTest.Infastructure \
  --startup-project src/ExamTest.WebApi

Застосувати міграції до БД:

dotnet ef database update \
  --project src/ExamTest.Infastructure \
  --startup-project src/ExamTest.WebApi

Відкотити останню міграцію:

dotnet ef migrations remove \
  --project src/ExamTest.Infastructure \
  --startup-project src/ExamTest.WebApi

Seed

TODO: уточніть, як реалізовано початкові дані.

  • Якщо seed виконується автоматично при старті (наприклад, через DbInitializer або HasData) — початкові дані (ролі, адміністратор, довідники) додадуться при першому запуску API.
  • Дані адміністратора за замовчуванням: TODO: email / пароль (змініть у production!).

Запуск backend

Через CLI:

dotnet run --project src/ExamTest.WebApi

З hot reload:

dotnet watch --project src/ExamTest.WebApi

Або відкрийте IPAY_BACKEND.slnx у Visual Studio, оберіть стартовий проєкт ExamTest.WebApi і натисніть F5.

API буде доступне за адресою, вказаною у Properties/launchSettings.json (TODO: напр. https://localhost:7000).

Запуск frontend

Цей репозиторій містить лише backend. Frontend знаходиться в окремому репозиторії:

TODO: посилання на репозиторій frontend

Типові кроки:

git clone <frontend-repo-url>
cd <frontend-folder>
npm install
# вкажіть URL backend у .env фронтенду, напр. VITE_API_URL=https://localhost:7000
npm run dev

Запуск тестів

dotnet test IPAY_BACKEND.slnx

Лише проєкт тестів, із детальним виводом:

dotnet test src/ExamTest.Tests --logger "console;verbosity=detailed"

Покриття коду (за наявності coverlet.collector):

dotnet test src/ExamTest.Tests --collect:"XPlat Code Coverage"

Docker

TODO: перевірте наявність Dockerfile / docker-compose.yml у репозиторії. Нижче — приклад-шаблон.

Dockerfile (у корені репозиторію):

FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
WORKDIR /app
COPY . .
RUN dotnet restore src/ExamTest.WebApi/ExamTest.WebApi.csproj
RUN dotnet publish src/ExamTest.WebApi/ExamTest.WebApi.csproj -c Release -o /out

FROM mcr.microsoft.com/dotnet/aspnet:9.0
WORKDIR /app
COPY --from=build /out .
EXPOSE 8080
ENV ASPNETCORE_URLS=http://+:8080
ENTRYPOINT ["dotnet", "ExamTest.WebApi.dll"]

docker-compose.yml:

services:
  db:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      ACCEPT_EULA: "Y"
      MSSQL_SA_PASSWORD: "Your_password123"
    ports:
      - "1433:1433"

  api:
    build: .
    depends_on:
      - db
    environment:
      ASPNETCORE_ENVIRONMENT: Production
      ConnectionStrings__DefaultConnection: "Server=db;Database=ipay;User Id=sa;Password=Your_password123;TrustServerCertificate=True"
      Jwt__Key: "change-me-to-a-long-secret-key-32chars+"
    ports:
      - "8080:8080"

Запуск:

docker compose up --build -d
docker compose logs -f api
docker compose down

Deployed application

  • 🌐 Frontend: TODO: https://...
  • 🔌 Backend API: TODO: https://...

Документація (DocFX)

Технічна документація згенерована за допомогою DocFX.

  • 📚 Онлайн: TODO: https://...

Локальна збірка:

docfx docfx.json --serve

Після запуску документація доступна за адресою http://localhost:8080.

API (Scalar)

Інтерактивна документація API побудована на Scalar (на основі OpenAPI).

  • 🔗 Онлайн: TODO: https://.../scalar/v1
  • 🖥️ Локально (у Development): https://localhost:<port>/scalar/v1
  • 📄 OpenAPI JSON: https://localhost:<port>/openapi/v1.json

Додаткові кроки

Повна послідовність для відтворення проєкту з нуля:

  1. Встановити .NET SDK, Git, dotnet-ef (і за потреби Docker).
  2. Клонувати репозиторій і виконати dotnet restore.
  3. Підняти СУБД та налаштувати ConnectionStrings.
  4. Налаштувати JWT та інші секрети (User Secrets або змінні середовища).
  5. Застосувати міграції: dotnet ef database update ....
  6. Переконатися, що seed-дані створені.
  7. Запустити backend: dotnet run --project src/ExamTest.WebApi.
  8. Відкрити Scalar та перевірити роботу API.
  9. Запустити frontend та вказати йому URL backend.
  10. Запустити тести: dotnet test.

Важливо для production:

  • Ніколи не коммітьте секрети (appsettings.*.json з паролями, .env).
  • Додайте .gitignore (зокрема .vs/, bin/, obj/) — у репозиторії зараз є папка .vs.
  • Налаштуйте CORS для домену вашого frontend.
  • Використовуйте HTTPS та змініть паролі/ключі за замовчуванням.

Ліцензія

TODO: вкажіть ліцензію (наприклад, MIT).

Автор

ThisIsEngineerGaming

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment