# Repository Guidelines

## Hard Rules — Always Enforced

1. **Never call `uow.SaveChangesAsync()` in any repository or service.** Only `uow.CommitAsync()` (or `BeginAsync`/`CommitAsync`/`RollbackAsync` for transactions) may be called, and only from the service layer.
2. **Never use `DateTime.UtcNow`.** Use `DateTime.Now` (server time) everywhere.
3. **Never build a feature that was not explicitly requested.** Confirm with the user before creating any new entity, endpoint, service, or infrastructure component.

---

## Project Structure & Module Organization
The repository contains one solution file, `Distribution.slnx`, and one ASP.NET Core 10 Web API project in `Distribution/`. The intended folder layout is:

```
Distribution/
├── Controllers/          # Thin HTTP endpoints — no business logic, no UoW calls
├── Data/
│   └── AppDBContext.cs   # EF Core DbContext — add DbSets here
├── Domain/
│   └── Entities/         # Plain POCO entities; one file per entity
├── Infra/
│   ├── UoW/              # IUnitOfWork + EFUnitOfWork (already implemented)
│   └── Repositories/     # IRepository<T>, EFRepository<T>, and per-aggregate repos
├── Application/
│   └── Services/         # Business logic; owns the uow.CommitAsync() call
└── DTOs/                 # Request/Response DTOs per module
```

Core entrypoint: `Distribution/Program.cs`. Configuration: `appsettings.json` / `appsettings.Development.json`. Launch profiles: `Distribution/Properties/launchSettings.json`. Do not commit build output from `Distribution/bin/` or `Distribution/obj/`.

## UoW Call-Chain Rule

```
Controller → Service → Repository (EF change tracking only)
                ↓
          uow.CommitAsync()   ← only the service calls this
```

- Repositories call `AddAsync`, `Update`, `Remove` on the DbSet — nothing more.
- Services call `_uow.CommitAsync(ct)` to flush and commit.
- For multi-step operations, services call `BeginAsync` → work → `CommitAsync` (or `RollbackAsync` in catch).
- `uow.SaveChangesAsync()` exists on the interface but must never appear in repo or service code.

---

## Build, Test, and Development Commands
Run commands from the repository root unless noted otherwise.

- `dotnet restore Distribution.slnx`: restore NuGet packages.
- `dotnet build Distribution.slnx`: compile the solution.
- `dotnet run --project Distribution/Distribution.csproj`: start the API locally.
- `dotnet watch run --project Distribution/Distribution.csproj`: run with hot reload during development.
- `dotnet test`: run automated tests once a test project is added.

The default development URLs are defined in `launchSettings.json`, currently `http://localhost:5089` and `https://localhost:7025`.

## Coding Style & Naming Conventions
Use standard C# conventions: 4-space indentation, PascalCase for public types and members, camelCase for local variables and parameters, and one class per file. Name controllers with the `*Controller.cs` pattern and keep route names explicit. Nullable reference types are enabled, so handle nullability deliberately rather than suppressing warnings.

## Testing Guidelines
There is no test project in the repository yet. Add new tests in a sibling project such as `Distribution.Tests/` and include it in the solution. Prefer xUnit for .NET API coverage. Name test files after the subject under test, for example `OrdersControllerTests.cs`, and use method names like `Get_ReturnsNotFound_WhenIdIsMissing`.

## Commit & Pull Request Guidelines
The current branch has no commit history yet, so use a clean convention from the start: short imperative subjects such as `Add orders controller` or `Configure OpenAPI in development`. Keep commits focused on one change. Pull requests should include a brief summary, impacted endpoints or config files, test evidence (`dotnet build`, `dotnet test`), and sample request or response details when API behavior changes.

## Configuration Notes
Keep secrets out of `appsettings.json`; use environment variables or user secrets for local development. Restrict `appsettings.Development.json` to non-sensitive machine-local defaults.