✅ .NET Web API Architecture & Quality Checklist

This checklist defines the architectural requirements, code quality rules, and engineering standards for the InventoryAlert codebase.

---

🏛️ 1. Architecture & Layer Discipline

• Layer Boundaries: InventoryAlert.Domain has zero imports from Application, Infrastructure, or Web layers.
• Primary Constructors: C# 12 primary constructors are used for dependency injection across services and repositories.
• No Async Without Await: Methods returning Task without async operations return Task.FromResult(...) directly (no CS1998 warnings).
• Cancellation Tokens: CancellationToken ct is the last parameter in every service and repository method.

---

🗄️ 2. Entity Framework Core & Transactions

• Transaction Capture Pattern: Every multi-write operation uses _unitOfWork.ExecuteTransactionAsync with result assignment inside the lambda:

  AlertRuleResponse result = null!;
  await _unitOfWork.ExecuteTransactionAsync(async () => {
      var updated = await _repo.UpdateAsync(entity);
      result = MapToResponse(updated);
  }, ct);
  return result;

• Read-Only Queries: All read-only EF Core LINQ queries specify .AsNoTracking().
• No Direct DbContext Injections: Services inject IUnitOfWork or specific repositories, never AppDbContext directly.

---

🧪 3. Unit & Integration Testing Standards

• Test Coverage: Happy path, not found, and transaction execution counts are verified for all service methods.
• Mock Delegate Invocation: ExecuteTransactionAsync mocks invoke the delegate parameter:

  _uowMock.Setup(u => u.ExecuteTransactionAsync(It.IsAny<Func<Task>>(), It.IsAny<CancellationToken>()))
      .Returns<Func<Task>, CancellationToken>((action, _) => action());

• Zero Thread.Sleep: No Thread.Sleep calls allowed in test suites.

---

📝 4. API Response Standards & Error Handling

• Global Error Middleware: GlobalExceptionMiddleware catches UserFriendlyException and returns standardized problem details JSON:

  {
    "status": 404,
    "title": "NotFound",
    "detail": "Stock listing for 'INVALID' was not found."
  }

• Thin Controllers: Controllers contain no business logic; they delegate directly to Application-layer services.