# ASP.NET Core Web API პროექტის დოკუმენტაცია

## 📋 სარჩევი
- [პროექტის მიმოხილვა](#პროექტის-მიმოხილვა)
- [ფოლდერების სტრუქტურა](#ფოლდერების-სტრუქტურა)
- [პროექტის მუშაობის პრინციპი](#პროექტის-მუშაობის-პრინციპი)
- [ინსტალაცია და კონფიგურაცია](#ინსტალაცია-და-კონფიგურაცია)
- [API მარშრუტები](#api-მარშრუტები)
- [ძირითადი ფუნქციონალი](#ძირითადი-ფუნქციონალი)
- [გამოყენება და გაფართოება](#გამოყენება-და-გაფართოება)
- [კოდის კონვენციები](#კოდის-კონვენციები)

---

## 🎯 პროექტის მიმოხილვა

### ტექნოლოგიები
- **Framework:** ASP.NET Core 8.0
- **ენა:** C# 12
- **არქიტექტურა:** Modular Monolith with Clean Architecture
- **მონაცემთა ბაზა:** Entity Framework Core
- **ავთენტიფიკაცია:** JWT Token Based

### დანიშნულება
ეს არის მოდულარული Web API პროექტი, რომელიც გამიზნულია მასშტაბირებადი და მოქნილი ბექენდ სერვისების ასაგებად. პროექტი იყენებს Clean Architecture პრინციპებს და მოდულარულ მიდგომას.

### ძირითადი მახასიათებლები
- ✅ მოდულარული არქიტექტურა
- ✅ JWT ავთენტიფიკაცია და ავტორიზაცია
- ✅ Entity Framework Core ORM
- ✅ ვალიდაციის სისტემა
- ✅ DTO პატერნი
- ✅ მიდლვეარების სისტემა

---

## 📁 ფოლდერების სტრუქტურა

### 📦 Common/
**დანიშნულება:** საერთო კომპონენტები და სერვისები, რომლებიც გამოიყენება მთელ აპლიკაციაში.

#### Common/DTOs/
**დანიშნულება:** Data Transfer Objects - მონაცემების გადაცემის ობიექტები

##### Common/DTOs/Requests/
- **შეიცავს:** Request მოდელებს API ენდპოინტებისთვის
- **მაგალითი:**

public class LoginRequest
{
    public string Email { get; set; }
    public string Password { get; set; }
}

##### Common/DTOs/Responses/
- **შეიცავს:** Response მოდელებს API პასუხებისთვის
- **მაგალითი:**

public class ApiResponse<T>
{
    public bool Success { get; set; }
    public T Data { get; set; }
    public string Message { get; set; }
}

#### Common/Entities/
**დანიშნულება:** ბაზის Entity-ების საბაზისო კლასები

##### BaseEntity.cs

public abstract class BaseEntity
{
    public int Id { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime? UpdatedAt { get; set; }
    public bool IsDeleted { get; set; }
}

#### Common/Helpers/
**დანიშნულება:** დამხმარე კლასები და utility ფუნქციები

#### Common/Services/Token/
**დანიშნულება:** JWT ტოკენების მართვის სერვისი

public interface ITokenService
{
    string GenerateToken(User user);
    ClaimsPrincipal ValidateToken(string token);
}

#### Common/Validators/
**დანიშნულება:** საერთო ვალიდაციის ლოგიკა

---

### 🔧 Core/
**დანიშნულება:** აპლიკაციის ძირითადი ინფრასტრუქტურა და კონფიგურაცია

#### Core/Constants/
**დანიშნულება:** აპლიკაციის მუდმივები და კონფიგურაციის პარამეტრები

public static class AppConstants
{
    public const string AppName = "MyAPI";
    public const string Version = "1.0.0";
    public const int TokenExpirationDays = 7;
}

#### Core/Extensions/
**დანიშნულება:** Extension მეთოდები სერვისების და Pipeline-ის კონფიგურაციისთვის

##### PipelineExtensions.cs

public static class PipelineExtensions
{
    public static IApplicationBuilder UseCustomMiddlewares(this IApplicationBuilder app)
    {
        app.UseAuthentication();
        app.UseAuthorization();
        // სხვა მიდლვეარები
        return app;
    }
}

##### ServiceExtensions.cs

public static class ServiceExtensions
{
    public static IServiceCollection AddCustomServices(this IServiceCollection services)
    {
        services.AddScoped<ITokenService, TokenService>();
        // სხვა სერვისები
        return services;
    }
}

#### Core/Middlewares/
**დანიშნულება:** Custom მიდლვეარები შეცდომების დამუშავებისთვის, ლოგირებისთვის და სხვა

public class ErrorHandlingMiddleware
{
    public async Task InvokeAsync(HttpContext context, RequestDelegate next)
    {
        try
        {
            await next(context);
        }
        catch (Exception ex)
        {
            await HandleExceptionAsync(context, ex);
        }
    }
}

---

### 💾 Data/
**დანიშნულება:** მონაცემთა ბაზასთან მუშაობის ლოგიკა

#### DataContext.cs

public class DataContext : DbContext
{
    public DataContext(DbContextOptions<DataContext> options) : base(options) { }
    
    public DbSet<User> Users { get; set; }
    public DbSet<EmailVerification> EmailVerifications { get; set; }
    public DbSet<PasswordVerification> PasswordVerifications { get; set; }
    
    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // Entity კონფიგურაციები
        base.OnModelCreating(modelBuilder);
    }
}

**კავშირები:**
- იყენებს Models ფოლდერში განსაზღვრულ Entity კლასებს
- გამოიყენება Modules-ში სერვისების მიერ

---

### 📊 Enums/
**დანიშნულება:** Enumeration ტიპები აპლიკაციის სხვადასხვა სტატუსებისთვის

#### Enums/Auth/

##### ACCOUNT_STATUS.cs

public enum AccountStatus
{
    Pending = 0,
    Active = 1,
    Suspended = 2,
    Deleted = 3
}

##### ROLES.cs

public enum Roles
{
    User = 0,
    Admin = 1,
    SuperAdmin = 2
}

---

### 📝 Models/
**დანიშნულება:** Domain მოდელები და Entity კლასები

#### Models/Auth/

##### User.cs

public class User : BaseEntity
{
    public string Email { get; set; }
    public string PasswordHash { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public AccountStatus Status { get; set; }
    public Roles Role { get; set; }
    
    // Relations
    public virtual ICollection<EmailVerification> EmailVerifications { get; set; }
    public virtual ICollection<PasswordVerification> PasswordVerifications { get; set; }
}

##### EmailVerification.cs

public class EmailVerification : BaseEntity
{
    public int UserId { get; set; }
    public string Token { get; set; }
    public DateTime ExpiresAt { get; set; }
    public string Code { get; set; }
    public int AttemptCount { get; set; } = 0;
    
    public virtual User User { get; set; }
}

##### PasswordVerification.cs

public class PasswordVerification : BaseEntity
{
    public int UserId { get; set; }
    public string Token { get; set; }
    public DateTime ExpiresAt { get; set; }
    public string Code { get; set; }
    public int AttemptCount { get; set; } = 0;
    
    public virtual User User { get; set; }
}

---

### 🧩 Modules/
**დანიშნულება:** ფუნქციონალური მოდულები (Feature Modules)

#### Modules/Auth/
**დანიშნულება:** ავთენტიფიკაციისა და ავტორიზაციის მოდული

##### AuthExtensions.cs

public static class AuthExtensions
{
    public static IServiceCollection AddAuthModule(this IServiceCollection services)
    {
        services.AddScoped<IAuthService, AuthService>();
        services.AddScoped<IUserService, UserService>();
        // სხვა Auth სერვისები
        return services;
    }
}

##### Controllers/
**შეიცავს:** Auth კონტროლერებს

[ApiController]
[Route("api/[controller]")]
public class AuthController : ControllerBase
{
    [HttpPost("login")]
    public async Task<IActionResult> Login([FromBody] LoginRequest request) { }
    
    [HttpPost("register")]
    public async Task<IActionResult> Register([FromBody] RegisterRequest request) { }
    
    [HttpPost("forgot-password")]
    public async Task<IActionResult> ForgotPassword([FromBody] ForgotPasswordRequest request) { }
}

##### DTOs/
**შეიცავს:** Auth მოდულის სპეციფიკურ DTO-ებს

public class RegisterRequest
{
    public string Email { get; set; }
    public string Password { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

##### Helpers/
**შეიცავს:** Auth დამხმარე კლასებს
- პაროლის ჰეშირება
- ტოკენების გენერაცია
- Email შაბლონები

##### Services/
**შეიცავს:** Auth ბიზნეს ლოგიკას

public interface IAuthService
{
    Task<AuthResponse> LoginAsync(LoginRequest request);
    Task<AuthResponse> RegisterAsync(RegisterRequest request);
    Task<bool> VerifyEmailAsync(string token);
    Task<bool> ResetPasswordAsync(ResetPasswordRequest request);
}

##### Validations/
**შეიცავს:** Auth ვალიდაციის წესებს

public class LoginRequestValidator : AbstractValidator<LoginRequest>
{
    public LoginRequestValidator()
    {
        RuleFor(x => x.Email).NotEmpty().EmailAddress();
        RuleFor(x => x.Password).NotEmpty().MinimumLength(6);
    }
}

---

## 🔄 პროექტის მუშაობის პრინციპი

### აპლიკაციის ნაკადი

graph TD
    A[Client Request] --> B[Middleware Pipeline]
    B --> C[Controller]
    C --> D[Service Layer]
    D --> E[Data Layer]
    E --> F[Database]
    F --> E
    E --> D
    D --> C
    C --> G[Response]

### მონაცემების ნაკადი

1. **HTTP Request** → მიდლვეარები (ავთენტიფიკაცია, ვალიდაცია, ლოგირება)
2. **Controller** → მიიღებს და ამუშავებს request-ს
3. **Service Layer** → ბიზნეს ლოგიკის შესრულება
4. **Data Layer** → მონაცემთა ბაზასთან ინტერაქცია
5. **Response** → DTO-ს ფორმირება და დაბრუნება

### არქიტექტურის პატერნი
პროექტი იყენებს **Modular Monolith** არქიტექტურას **Clean Architecture** პრინციპებით:

- **Presentation Layer:** Controllers, DTOs
- **Application Layer:** Services, Validators
- **Domain Layer:** Models, Enums
- **Infrastructure Layer:** Data, Helpers

---

## ⚙️ ინსტალაცია და კონფიგურაცია

### წინაპირობები

# .NET 8 SDK
dotnet --version

# Entity Framework CLI
dotnet tool install --global dotnet-ef

### დამოკიდებულებები

<PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="8.0.0" />
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="8.0.0" />
<PackageReference Include="FluentValidation.AspNetCore" Version="11.3.0" />
<PackageReference Include="AutoMapper.Extensions.Microsoft.DependencyInjection" Version="12.0.1" />
<PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0" />

### Environment Variables

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=MyAppDb;Trusted_Connection=true;"
  },
  "JwtSettings": {
    "Secret": "your-secret-key-here",
    "Issuer": "MyApp",
    "Audience": "MyAppUsers",
    "ExpirationDays": 7
  },
  "EmailSettings": {
    "SmtpHost": "smtp.gmail.com",
    "SmtpPort": 587,
    "SmtpUser": "[e-mail]",
    "SmtpPass": "your-password"
  }
}

### ინსტალაციის ნაბიჯები

# Repository-ს კლონირება
git clone https://github.com/yourusername/project.git
cd project

# დამოკიდებულებების დაინსტალირება
dotnet restore

# მონაცემთა ბაზის მიგრაცია
dotnet ef database update

# პროექტის გაშვება
dotnet run

---

## 🚀 API მარშრუტები

### Authentication Endpoints

| Method | Endpoint | აღწერა | Auth Required |
|--------|----------|--------|---------------|
| POST | `/api/auth/register` | ახალი მომხმარებლის რეგისტრაცია | ❌ |
| POST | `/api/auth/login` | მომხმარებლის ავტორიზაცია | ❌ |
| POST | `/api/auth/refresh-token` | ტოკენის განახლება | ✅ |
| POST | `/api/auth/forgot-password` | პაროლის აღდგენა | ❌ |
| POST | `/api/auth/reset-password` | პაროლის შეცვლა | ❌ |
| GET | `/api/auth/verify-email/{token}` | Email-ის ვერიფიკაცია | ❌ |

### Request/Response მაგალითები

#### Register Request

POST /api/auth/register
{
  "email": "[e-mail]",
  "password": "Password123!",
  "firstName": "გიორგი",
  "lastName": "გიორგაძე"
}

#### Login Response

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "refresh_token_here",
    "expiresIn": 604800,
    "user": {
      "id": 1,
      "email": "[e-mail]",
      "firstName": "გიორგი",
      "lastName": "გიორგაძე",
      "role": "User"
    }
  },
  "message": "წარმატებით შეხვედით სისტემაში"
}

---

## 💡 ძირითადი ფუნქციონალი

### 🔐 Authentication Service

public class AuthService : IAuthService
{
    private readonly DataContext _context;
    private readonly ITokenService _tokenService;
    private readonly IEmailService _emailService;
    
    public async Task<AuthResponse> LoginAsync(LoginRequest request)
    {
        // 1. მომხმარებლის ძებნა
        var user = await _context.Users
            .FirstOrDefaultAsync(u => u.Email == request.Email);
            
        // 2. პაროლის შემოწმება
        if (!VerifyPassword(request.Password, user.PasswordHash))
            throw new UnauthorizedException("არასწორი მონაცემები");
            
        // 3. ტოკენის გენერაცია
        var token = _tokenService.GenerateToken(user);
        
        return new AuthResponse { Token = token, User = user };
    }
}

### 📧 Email Service

public class EmailService : IEmailService
{
    public async Task SendVerificationEmailAsync(string email, string token)
    {
        var verificationUrl = $"https://yourapp.com/verify-email/{token}";
        var subject = "ელ-ფოსტის დადასტურება";
        var body = $"გთხოვთ დააჭიროთ ლინკს: {verificationUrl}";
        
        await SendEmailAsync(email, subject, body);
    }
}

### 🗄️ Database Models

// User Entity Configuration
modelBuilder.Entity<User>(entity =>
{
    entity.HasKey(e => e.Id);
    entity.HasIndex(e => e.Email).IsUnique();
    
    entity.Property(e => e.Email)
        .IsRequired()
        .HasMaxLength(100);
        
    entity.HasMany(e => e.EmailVerifications)
        .WithOne(e => e.User)
        .HasForeignKey(e => e.UserId);
});

---

## 🛠️ გამოყენება და გაფართოება

### ახალი მოდულის დამატება

1. **შექმენით ახალი ფოლდერი Modules-ში:**

Modules/
    YourModule/
        Controllers/
        Services/
        DTOs/
        Validations/

2. **დაამატეთ Extension კლასი:**

public static class YourModuleExtensions
{
    public static IServiceCollection AddYourModule(this IServiceCollection services)
    {
        services.AddScoped<IYourService, YourService>();
        return services;
    }
}

3. **დარეგისტრირეთ Program.cs-ში:**

builder.Services.AddYourModule();

### ტესტირება

# Unit ტესტების გაშვება
dotnet test

# Integration ტესტები
dotnet test --filter Category=Integration

### Deployment

# Production build
dotnet publish -c Release -o ./publish

# Docker image
docker build -t myapp:latest .
docker run -p 5000:80 myapp:latest

---

## 📏 კოდის კონვენციები

### Naming Conventions
- **Classes:** PascalCase (მაგ: `UserService`)
- **Interfaces:** I prefix + PascalCase (მაგ: `IUserService`)
- **Methods:** PascalCase (მაგ: `GetUserById`)
- **Variables:** camelCase (მაგ: `userName`)
- **Constants:** UPPER_CASE (მაგ: `MAX_RETRY_COUNT`)

### ფაილების სტრუქტურა

// 1. Using statements
using System;
using System.Collections.Generic;

// 2. Namespace
namespace MyApp.Modules.Auth.Services
{
    // 3. Class documentation
    /// <summary>
    /// მომხმარებლის სერვისი
    /// </summary>
    public class UserService : IUserService
    {
        // 4. Private fields
        private readonly DataContext _context;
        
        // 5. Constructor
        public UserService(DataContext context)
        {
            _context = context;
        }
        
        // 6. Public methods
        public async Task<User> GetByIdAsync(int id)
        {
            // Implementation
        }
        
        // 7. Private methods
        private bool ValidateUser(User user)
        {
            // Implementation
        }
    }
}

### Best Practices
- ✅ იყენებთ Dependency Injection
- ✅ ასინქრონული მეთოდები async/await პატერნით
- ✅ Exception handling try-catch ბლოკებით
- ✅ ლოგირება ILogger interface-ით
- ✅ ვალიდაცია FluentValidation-ით
- ✅ DTO პატერნი API კონტრაქტებისთვის

---

## 📚 დამატებითი რესურსები

- [ASP.NET Core Documentation](https://docs.microsoft.com/aspnet/core)
- [Entity Framework Core](https://docs.microsoft.com/ef/core)
- [JWT Authentication](https://jwt.io/introduction)
- [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)

---

## 📄 ლიცენზია
MIT License

## 👥 Contributors
- თქვენი სახელი და გუნდის წევრები

---

*დოკუმენტაცია განახლდა: 2024*