# eom-sample-project-instructure

**Repository Path**: java-and-net/eom-sample-project-instructure

## Basic Information

- **Project Name**: eom-sample-project-instructure
- **Description**: EOM 基础项目脚手架
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-04
- **Last Updated**: 2026-04-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EOM.SampleProject.Instructure

A modern Web API project template based on .NET 10, featuring a layered architecture design with support for database agnosticism (SqlSugar ORM), JWT authentication, two-factor authentication, role-based permissions, and other enterprise-grade features.

## Project Overview

EOM.SampleProject.Instructure is an ASP.NET Core Web API template designed for enterprise applications, built upon a classic three-tier/multi-tier architecture comprising the API layer, service layer, contract layer, domain layer, data layer, infrastructure layer, and common layer. The project integrates numerous enterprise-grade features, including claim-based authorization, two-factor authentication (2FA), idempotency handling, request logging, CSRF protection, and more.

## Technology Stack

The backend technology stack is built primarily on mainstream open-source frameworks and components from the .NET ecosystem. The core framework is ASP.NET Core 10; the ORM layer uses SqlSugar to support multiple databases, including MySQL, PostgreSQL, SQL Server, Oracle, MariaDB, and SQLite. Authentication and authorization leverage JWT (JSON Web Token) combined with custom authorization policies, supporting two-factor authentication via TOTP and recovery codes. Redis is utilized for distributed caching, token revocation, and idempotency enforcement, while Quartz.NET handles scheduled tasks. API documentation is generated using Swashbuckle (Swagger), and the dependency injection container is Autofac.

## Project Structure

The project follows a layered architecture with clearly defined responsibilities:

- **EOM.SampleProject.API**: The entry layer, handling controllers, middleware, authorization filters, and extension methods.
- **EOM.SampleProject.Service**: The business logic layer, encapsulating core services such as admin management, role management, menu management, permission management, scheduled tasks, user favorites, profile management, and two-factor authentication.
- **EOM.SampleProject.Contract**: Defines data transfer objects (DTOs), request inputs, and response outputs as contractual interfaces.
- **EOM.SampleProject.Domain**: Contains domain entities such as admins, roles, permissions, menus, and operation logs.
- **EOM.SampleProject.Data**: Manages data access, implementing the repository pattern and database initialization logic.
- **EOM.SampleProject.Infrastructure**: Provides infrastructure support, including factory classes for various configurations.
- **EOM.SampleProject.Common**: Includes common utilities such as encryption/decryption tools, filter builders, and JSON serialization extensions.
- **EOM.SampleProject.Migration**: Handles database migrations and entity modeling.

## Core Features

The project delivers comprehensive enterprise-grade modules:

- **System Management**: Supports CRUD operations for admin accounts and admin type maintenance.
- **Permission Management**: Implements claim-based authorization policies; fine-grained API-level permissions can be enforced using the `RequirePermission` attribute.
- **Role Management**: Enables creation, modification, deletion of roles, and assignment of permissions to roles.
- **Menu Management**: Dynamically builds menu trees and automatically filters accessible menu items based on user permissions.
- **Two-Factor Authentication**: Supports TOTP (Time-based One-Time Password) and recovery codes for enhanced account security.
- **User Favorites**: Allows users to save preferred route snapshots with cross-device synchronization.
- **Profile Management**: Enables users to view their profile, upload avatars, and change passwords.
- **Logging**: Records operation logs and request logs with filtering capabilities by time range and criteria.

## Security Features

The project implements multi-layered security mechanisms:

- **Authentication & Authorization**: Uses JWT Bearer authentication with custom policy-based authorization for fine-grained, attribute-driven API access control.
- **Authentication Failure Handling**: Custom middleware uniformly handles scenarios such as token expiration and revocation.
- **CSRF Protection**: Employs Antiforgery Tokens, requiring the token to be included in POST/PUT/DELETE requests.
- **Idempotency**: Ensures request uniqueness via the `Idempotency-Key` header, with duplicate request detection powered by Redis or in-memory storage.
- **Two-Factor Authentication**: Supports TOTP codes and one-time recovery codes.
- **Sensitive Data Protection**: Uses ASP.NET Core Data Protection to encrypt sensitive fields at the attribute level.
- **Request Logging**: Captures detailed information for every API call, facilitating auditing and troubleshooting.

## Configuration

Configuration is managed via `appsettings.json` and environment-specific configuration files. Key configurations include:

- Database connections (`ConnectionStrings`)
- Redis connections (`Redis`)
- JWT settings (`Jwt`)
- Email service (`Mail`)
- Image storage (`Lsky`)
- Two-factor authentication (`TwoFactor`)

The database type is specified via `Database:DefaultDatabase` or `Database:Type`, with support for MariaDB, MySQL, PgSql, SqlServer, Oracle, and SQLite. The default admin account is `admin`, and its initial password is automatically set during database initialization based on configuration or environment variables.

## Quick Start

### System Requirements

To run this project, ensure the following environment requirements are met: .NET 10 SDK, Docker and Docker Compose (optional), a supported database instance (MySQL 8.0+, PostgreSQL 14+, SQL Server 2019+, etc.), and Redis 6.0+ (optional, for distributed caching and idempotency).

### Local Execution

After cloning the repository, navigate to the project root directory and execute:

```bash
dotnet restore
```

Edit `appsettings.json` to configure your target database connection string, then start the application:

```bash
dotnet run --project EOM.SampleProject.API
```

On first launch, the project automatically initializes the default admin account (`admin/admin666`).

### Docker Execution

The project includes a `docker-compose.yml` file to launch the complete runtime environment. Execute:

```bash
docker-compose up -d
```

Then access the Swagger API documentation at `http://localhost:8080` in your browser.

## API Overview

- **System Management**: Admin login, list/query admins, create/update/delete admins, admin type management, role assignment, permission assignment, two-factor authentication management.
- **Role Management**: List roles, create/update/delete roles, assign permissions to roles, assign users to roles.
- **Menu Management**: Query menus, build menu trees, create/update/delete menus.
- **Permission Management**: Query permission lists.
- **Utility APIs**: Query TOTP secrets, query/delete operation logs, query/delete request logs.
- **User APIs**: Retrieve current user profile, upload avatar, change password, manage favorites.

## License

This project is open-sourced under the MIT License.

## Contribution Guidelines

Pull requests are welcome! Before submitting, please ensure your code adheres to the project's existing coding style and includes appropriate unit tests to describe your changes.