spiderly 19.8.3 → 19.8.5

package/agent/docs/authorization/SKILL.md

@@ -0,0 +1,385 @@
+---
+name: authorization
+description: Set up permission-based authorization in Spiderly. Use when implementing user/role/permission entities, seeding permissions, using DoNotAuthorize or AuthGuard attributes, checking permissions in custom code, configuring frontend auth guards, or setting up Google OAuth.
+---
+
+# Authorization
+
+## Entity Interfaces
+
+Implement these on your User, Role, and Permission entities:
+
+### ISecurityPrincipal
+
+The authorization root — anything that can hold roles and be permission-checked (a human `User`, a
+machine/service account, an AI agent). Authorization resolves permissions against this contract, not a
+concrete user type, so an app may have **one** principal kind (just `User`) or **many**.
+
+```csharp
+public interface ISecurityPrincipal : IBusinessObject<long>
+{
+    bool? IsDisabled { get; set; }
+    IReadOnlyCollection<IRole> Roles { get; }
+}
+```
+
+### IUser
+
+A human principal that authenticates by email. Inherits identity, disabled-state, and roles from
+`ISecurityPrincipal`; adds only `Email`.
+
+```csharp
+public interface IUser : ISecurityPrincipal
+{
+    string Email { get; set; }
+}
+```
+
+### IRole
+
+```csharp
+public interface IRole : IBusinessObject<int>
+{
+    string Name { get; set; }
+    IReadOnlyCollection<IUser> Users { get; }
+    IReadOnlyCollection<IPermission> Permissions { get; }
+}
+```
+
+### IPermission
+
+```csharp
+public interface IPermission : IReadonlyObject<int>
+{
+    string Name { get; set; }
+    string Code { get; set; }
+    IReadOnlyCollection<IRole> Roles { get; }
+}
+```
+
+### Real-World Entity Example
+
+```csharp
+[Index(nameof(Email), IsUnique = true)]
+public class User : BusinessObject<long>, IUser
+{
+    [Required]
+    [StringLength(70, MinimumLength = 5)]
+    [Email]
+    public string Email { get; set; }
+
+    public string FirstName { get; set; }
+    public string LastName { get; set; }
+
+    public bool? HasLoggedInWithGoogleAsExternalProvider { get; set; }
+    public bool? IsDisabled { get; set; }
+
+    public virtual List<Role> Roles { get; } = new();
+    IReadOnlyCollection<IRole> ISecurityPrincipal.Roles => Roles; // Roles moved to the principal base
+}
+
+public class Role : BusinessObject<int>, IRole
+{
+    [Required]
+    [StringLength(255, MinimumLength = 1)]
+    public string Name { get; set; }
+
+    [UIControlType(nameof(UIControlTypeCodes.MultiAutocomplete))]
+    public virtual List<User> Users { get; } = new();
+    IReadOnlyCollection<IUser> IRole.Users => Users;
+
+    [UIControlType(nameof(UIControlTypeCodes.MultiSelect))]
+    public virtual List<Permission> Permissions { get; } = new();
+    IReadOnlyCollection<IPermission> IRole.Permissions => Permissions;
+}
+
+[UIDoNotGenerate]
+[Index(nameof(Code), IsUnique = true)]
+public class Permission : ReadonlyObject<int>, IPermission
+{
+    [Required]
+    [StringLength(100, MinimumLength = 1)]
+    public string Name { get; set; }
+
+    [Required]
+    [StringLength(100, MinimumLength = 1)]
+    public string Code { get; set; }
+
+    public virtual List<Role> Roles { get; } = new();
+    IReadOnlyCollection<IRole> IPermission.Roles => Roles;
+}
+```
+
+## Permission Code Convention
+
+Auto-generated per entity (via `PermissionCodesGenerator`):
+
+| Code             | Purpose           |
+| ---------------- | ----------------- |
+| `Read{Entity}`   | View list/details |
+| `Update{Entity}` | Modify existing   |
+| `Insert{Entity}` | Create new        |
+| `Delete{Entity}` | Remove            |
+
+Generated as a partial class:
+
+```csharp
+public static partial class PermissionCodes
+{
+    public static string ReadProduct { get; } = "ReadProduct";
+    public static string UpdateProduct { get; } = "UpdateProduct";
+    public static string InsertProduct { get; } = "InsertProduct";
+    public static string DeleteProduct { get; } = "DeleteProduct";
+    // ... one set per entity
+}
+```
+
+Extend with custom codes:
+
+```csharp
+public static partial class PermissionCodes
+{
+    public static string ExportReports { get; } = "ExportReports";
+}
+```
+
+## Seeding Permissions
+
+In `ApplicationDbContext.SeedData()`:
+
+```csharp
+private static void SeedData(ModelBuilder modelBuilder)
+{
+    DateTime seedDate = new DateTime(2025, 1, 1, 0, 0, 0, DateTimeKind.Utc);
+
+    Permission[] permissions =
+    [
+        new Permission { Id = 1, Name = "View users", Code = "ReadUser" },
+        new Permission { Id = 2, Name = "Edit users", Code = "UpdateUser" },
+        new Permission { Id = 3, Name = "Add users", Code = "InsertUser" },
+        new Permission { Id = 4, Name = "Delete users", Code = "DeleteUser" },
+        new Permission { Id = 5, Name = "View products", Code = "ReadProduct" },
+        // ... more permissions with sequential IDs
+    ];
+
+    modelBuilder.Entity<Permission>().HasData(permissions);
+
+    modelBuilder.Entity<Role>().HasData(new Role
+    {
+        Id = 1,
+        Name = "Admin",
+        CreatedAt = seedDate,
+        ModifiedAt = seedDate,
+    });
+
+    modelBuilder.Entity<Role>()
+        .HasMany(r => r.Permissions)
+        .WithMany(p => p.Roles)
+        .UsingEntity(j => j.HasData(
+            permissions.Select((p, i) => new { RoleId = 1, PermissionId = p.Id }).ToArray()
+        ));
+}
+```
+
+After adding new permissions: `spiderly add-migration AddNewPermissions` → `spiderly update-database`.
+
+## First-User Bootstrap
+
+Permissions and an "Admin" role are seeded via `HasData()` in the generated `ApplicationDbContext` (applied through EF migrations). On first login, `SecurityService.OnAfterLogin` auto-grants Admin to the user — no manual bootstrap needed on a fresh deploy.
+
+## Attributes
+
+### `[DoNotAuthorize]`
+
+Skip all permission checks for an entity:
+
+```csharp
+[DoNotAuthorize]
+public class PaymentMethod : ReadonlyObject<byte> { ... }
+```
+
+Use for public lookup tables. Generated CRUD endpoints won't require login.
+
+### `[AuthGuard]`
+
+Require valid JWT on a controller action:
+
+```csharp
+[HttpGet]
+[AuthGuard]
+public async Task<UserBaseDTO> GetProfile() { ... }
+```
+
+Validates JWT from `Authorization: Bearer {token}` header. Returns 401 if invalid. Applied automatically on all generated CRUD endpoints (unless entity has `[DoNotAuthorize]`).
+
+## Generated Authorization Service
+
+`AuthorizationServicesGenerator` creates per-entity authorization methods:
+
+```csharp
+// Generated — override in your AuthorizationService to customize.
+// The call is principal-kind-agnostic: it authorizes the current principal (whatever kind) by
+// resolving it through the principal registry — no compile-time user type.
+public virtual async Task AuthorizeProductReadAndThrow(long? productIdToRead)
+{
+    await AuthorizeAndThrowAsync(PermissionCodes.ReadProduct);
+}
+
+public virtual async Task AuthorizeProductUpdateAndThrow(ProductDTO dto)
+{
+    await AuthorizeAndThrowAsync(PermissionCodes.UpdateProduct);
+}
+
+public virtual async Task AuthorizeProductInsertAndThrow(ProductDTO dto)
+{
+    await AuthorizeAndThrowAsync(PermissionCodes.InsertProduct);
+}
+
+public virtual async Task AuthorizeProductDeleteAndThrow(long id)
+{
+    await AuthorizeAndThrowAsync(PermissionCodes.DeleteProduct);
+}
+```
+
+## Registering Principal Kinds
+
+Register each principal kind in `AddAppServices` so authorization can resolve the current principal.
+A single-principal app registers just `User`; the kind-dispatched authorization then resolves it
+without a `principal_kind` claim (it is the sole, default kind):
+
+```csharp
+services.AddSpiderlyPrincipal<User>("User");
+// Add a line per additional principal kind, e.g.:
+// services.AddSpiderlyPrincipal<ServiceAccount>("ServiceAccount");
+```
+
+Each kind is any entity implementing `ISecurityPrincipal` with its own `Roles` into the shared
+Role/Permission catalog. (`spiderly init` scaffolds the `User` registration for you.)
+
+## Checking Permissions in Custom Code
+
+```csharp
+// Preferred — authorizes the current principal whatever its kind:
+await _authorizationService.AuthorizeAndThrowAsync(PermissionCodes.ExportReports);
+
+// Check without throwing:
+bool canExport = await _authorizationService.IsAuthorizedAsync(PermissionCodes.ExportReports);
+
+// The generic overload still exists for an explicit single-type check (e.g. a User-only admin path):
+await _authorizationService.AuthorizeAndThrowAsync<User>(PermissionCodes.ExportReports);
+```
+
+## Authentication Flow
+
+Spiderly uses **email-based login** (no passwords):
+
+```
+1. Client sends email → SendLoginVerificationEmail
+2. Server sends 6-digit code via email (or shows in dev mode)
+3. Client sends code → Login
+4. Server returns access token (JWT, 20 min) + refresh token (24h)
+5. Auto-refresh 5 seconds before expiration
+```
+
+### SecurityServiceBase Hooks
+
+```csharp
+public class SecurityService : SecurityServiceBase<User>
+{
+    public override async Task OnAfterLogin(AuthResultDTO authResultDTO)
+    {
+        // Custom post-login logic (analytics, logging, etc.)
+    }
+}
+```
+
+### SecurityBaseController Endpoints
+
+The full auth API surface — every endpoint, its HTTP method, whether it needs a valid access token, and what it does — is generated from `SecurityBaseController`: see [references/security-endpoints.generated.md](references/security-endpoints.generated.md).
+
+## API error codes
+
+Failed requests return an `ApiErrorDTO` whose machine-readable `errorCode` clients switch on (the Angular interceptor, storefront middleware, external API consumers). The full list — names, wire values, and when each is returned — is generated from the `ApiErrorCodes` contract: see [references/api-error-codes.generated.md](references/api-error-codes.generated.md).
+
+## Google OAuth Setup
+
+1. Get a Google Client ID from Google Developer Console
+2. Set in `Backend/appsettings.json`:
+   ```json
+   { "AppSettings": { "Spiderly.Shared": { "GoogleClientId": "..." } } }
+   ```
+3. Set in `Frontend/src/environments/environment.ts`:
+   ```typescript
+   GoogleClientId: "...";
+   ```
+4. Enable in config service:
+   ```typescript
+   override showGoogleAuth = true;
+   ```
+
+Flow: Google returns JWT → `LoginExternal` validates → auto-creates user if new → returns tokens.
+
+## Frontend Auth
+
+### AuthServiceBase
+
+Key observables:
+
+```typescript
+user$: Observable<UserBase | null>; // Current user
+currentUserPermissionCodes$: Observable<string[]>; // Permission codes
+```
+
+Key methods:
+
+```typescript
+login(body: VerificationTokenRequest): Observable<Promise<AuthResult>>
+loginExternal(body: ExternalProvider): Observable<Promise<AuthResult>>
+logout()
+refreshToken(): Observable<AuthResult>
+```
+
+Overridable hooks:
+
+```typescript
+onAfterLoginExternal = () => { ... }
+onAfterLogout = () => { ... }
+onAfterRefreshToken = () => { ... }
+```
+
+### Route Guards
+
+```typescript
+// Protect authenticated routes
+{ path: 'dashboard', component: DashboardComponent, canActivate: [AuthGuard] }
+
+// Protect login page from logged-in users
+{ path: 'login', component: LoginComponent, canActivate: [NotAuthGuard] }
+```
+
+### Permission-Based Menu Visibility
+
+```typescript
+menu: SpiderlyMenuItem[] = [
+  {
+    label: 'Users',
+    routerLink: ['/user-list'],
+    hasPermission: (codes) => codes.includes('ReadUser'),
+  },
+];
+```
+
+### Multi-Tab Sync
+
+Login/logout events sync across browser tabs via `localStorage` events. `getBrowserId()` generates a UUID per browser — server limits to 5 concurrent sessions per user.
+
+## Settings Reference
+
+```csharp
+AccessTokenExpiration = 20          // minutes
+RefreshTokenExpiration = 1440       // minutes (24h)
+VerificationTokenExpiration = 5     // minutes
+AllowedBrowsersForTheSingleUser = 5
+OnlyAdminCanAddUsers = false        // true = block self-registration
+AllowTheUseOfAppWithDifferentIpAddresses = true
+```

package/agent/docs/authorization/references/api-error-codes.generated.md

@@ -0,0 +1,17 @@
+<!-- GENERATED FROM framework-metadata.json — DO NOT EDIT.
+     Regenerate: `dotnet run --project Spiderly.MetadataExporter -- --out framework-metadata.json && node tools/extract-ts-metadata.mjs && node tools/gen-skill-docs.mjs` -->
+
+# API error codes
+
+Machine-readable error codes returned in ErrorCode. Treat as a public contract — clients (Angular interceptor, storefront middleware, external API consumers) switch on these values.
+
+| Name | Value | Description |
+| --- | --- | --- |
+| `ConcurrencyConflict` | `concurrency_conflict` | An optimistic-concurrency check failed — the row was modified by someone else after it was loaded. The client should reload the latest data and retry. |
+| `EmailNotVerified` | `email_not_verified` | Login or auto-provisioning was blocked because the account's email address is not verified (e.g. an external provider returned an unverified email). |
+| `ExternalEmailMissing` | `external_email_missing` | An external (OAuth/OIDC) login was validated but the provider returned no email address (e.g. the user declined the email permission, or a phone-only Facebook account). Auto-provisioning needs an email to key the account on, so login is rejected with this code and the client should route the user to another sign-in method. Distinct from EmailNotVerified, which means an email was returned but not verified. |
+| `ExternalProviderNotConfigured` | `external_provider_not_configured` | An external (OAuth) login was attempted for a provider that is not configured on the server, or that provider's token exchange failed. |
+| `ForeignKeyViolation` | `foreign_key_violation` | A database foreign-key constraint was violated — e.g. referencing a row that does not exist, or deleting a row that is still referenced by dependent rows. |
+| `InvalidToken` | `invalid_token` | The JWT bearer token is missing, malformed, or expired. Returned with HTTP 401 (also surfaced in the WWW-Authenticate header); the client should refresh the token or re-authenticate. |
+| `UniqueViolation` | `unique_violation` | A database unique constraint (or unique index) was violated — e.g. saving a duplicate value for a column that must be unique. |
+| `ValidationFailed` | `validation_failed` | One or more request fields failed server-side validation. Returned with HTTP 400; the per-field messages are carried in ApiErrorDTO.FieldErrors. |

package/agent/docs/authorization/references/security-endpoints.generated.md

@@ -0,0 +1,24 @@
+<!-- GENERATED FROM framework-metadata.json — DO NOT EDIT.
+     Regenerate: `dotnet run --project Spiderly.MetadataExporter -- --out framework-metadata.json && node tools/extract-ts-metadata.mjs && node tools/gen-skill-docs.mjs` -->
+
+# SecurityBaseController endpoints
+
+A base controller providing core security functionalities such as authentication, user management, and role-based access control. It leverages various services for handling user authentication (login, registration, logout, token refresh). This controller is designed to be extended for specific user types.
+
+| Endpoint | Method | Auth | Description |
+| --- | --- | --- | --- |
+| `ExternalLoginCallback` | GET | No | Server-side external-login step 2: the provider redirects here with the code. Exchanges it for the id token (server-side), validates + links the user, issues the session as HttpOnly cookies, and redirects back to the originating app (returnUrl). This is a top-level browser navigation, so failures must redirect back to the app (never render a JSON error onto the API origin). The app surfaces a friendly message via the externalAuthError hint: expired (the state cookie lapsed — the user lingered on the provider's picker) or failed (invalid state/nonce, failed code exchange, or denied consent). |
+| `ExternalLoginChallenge` | GET | No | Server-side external-login step 1: redirects the browser to the provider's authorize endpoint. The state/nonce/PKCE-verifier are stored in a short-lived, Data-Protection-signed HttpOnly cookie. |
+| `GetCurrentUserBase` | GET | Yes | Returns the authenticated user's base profile (id, email, core fields). Requires a valid access token. |
+| `GetCurrentUserPermissionCodes` | GET | Yes | Returns the permission codes granted to the authenticated user via their roles. Requires a valid access token. |
+| `GetExternalLoginNonce` | GET | No | Issues a one-time nonce for the client-side (GIS / id-token) external-login flow: returns the raw nonce for the SPA to pass to the provider's sign-in call (so it is echoed into the id token), and stores a signed copy in a short-lived HttpOnly cookie that LoginExternal / LoginExternalWithCookies verify the returned id token against. Anonymous. SameSite=None so the cookie rides the cross-site login POST. |
+| `GetExternalProviders` | GET | No | Public list of enabled external providers (code + OIDC authority + client id + button display), so the frontend can render sign-in buttons and run the client OIDC flow. Anonymous — the values are public by OIDC design. |
+| `Login` | POST | No | Passwordless login step 2: verifies the emailed code and, on success, returns the access + refresh tokens in the response body. Anonymous. |
+| `LoginExternal` | POST | No | Client-side external (OIDC) login: validates the provider id token against the single-use nonce cookie and returns the access + refresh tokens in the response body. Anonymous. |
+| `LoginExternalWithCookies` | POST | No | Like LoginExternal, but issues the session as HttpOnly cookies instead of returning the tokens in the response body. Anonymous. |
+| `LoginWithCookies` | POST | No | Like Login, but issues the session as HttpOnly cookies instead of returning the tokens in the response body. Anonymous. |
+| `Logout` | GET | Yes | Invalidates the current user's refresh token for the given browser session. Requires a valid access token. |
+| `LogoutWithCookies` | GET | Yes | Like Logout, and additionally clears the auth HttpOnly cookies. Requires a valid access token. |
+| `RefreshTokenWithCookies` | POST | No | Refreshes the access token using the refresh token stored in an HttpOnly cookie. POST (not GET) because it mutates server state — it rotates the single-use refresh token. A safe/idempotent GET was cacheable, so browsers replayed a stale "logged-in" body on back/forward navigations (phantom dashboard after logout); POST is never cached, and the controller-level no-store is belt-and-braces. |
+| `RefreshTokenWithHeaders` | POST | No | Refreshes the access token using the refresh token supplied in the request body, returning a new access + refresh token pair. Anonymous — the refresh token is itself the credential. |
+| `SendLoginVerificationEmail` | POST | No | Passwordless login step 1: sends a short-lived numeric verification code to the user's email. Anonymous. |

package/agent/docs/backend-hooks/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: backend-hooks
+description: Override Spiderly lifecycle hooks to customize generated CRUD behavior. Use when overriding lifecycle hooks, customizing generated CRUD logic, adding business logic to save/delete/get operations, handling MARS exceptions or transaction issues, or throwing business/security-violation exceptions.
+---
+
+# Backend Hooks
+
+## Inheritance Chain
+
+```
+ServiceBase (Spiderly.Shared — concrete base class)
+        ↓
+{Entity}ServiceGenerated (generated — per-entity virtual hooks)
+        ↓
+{Entity}Service (your code — override hooks here)
+```
+
+Each entity gets its own generated service class. All generated methods are `public virtual` or `protected virtual`. Override them by creating an `{Entity}Service` class that inherits from `{Entity}ServiceGenerated`. DI registration is fully auto-generated — the source generator detects your override class and registers it automatically.
+
+The generated service receives `EntityServiceDependencies` (bundles `IApplicationDbContext`, `ExcelService`, `AuthorizationService`, `IFileManager`, `IStringLocalizer`, `IServiceProvider`). Access them via `_deps`.
+
+## Hook Signatures by Phase
+
+### Save Flow (execution order)
+
+```
+1. SaveBody validation (SaveBodyDTOValidationRules — usually empty)
+2. OnBeforeSave{Entity}AndReturnMainUIFormDTO(SaveBodyDTO)
+3. DTO validation ({Entity}DTOValidationRules — NotEmpty, Length, etc.)
+4. OnBefore{Entity}IsMapped(DTO)
+5. OnBefore{Entity}Insert(entity, DTO)  — or —  OnBefore{Entity}Update(entity, DTO)
+6. SaveChangesAsync
+7. Update M2M + ordered O2M collections
+8. OnAfterSave{Entity}AndReturnMainUIFormDTO(SaveBodyDTO, MainUIFormDTO)
+```
+
+Step 2 runs **before** step 3 — this means `OnBeforeSave` can set server-generated fields (e.g., `[UIDoNotGenerate]` + `[Required]` properties like hashes or computed values) before DTO validation runs.
+
+On the **update path**, the entity load before step 5b goes through `GetInstanceAsync(id, dto.Version)` — it throws a localized `ConcurrencyException` (HTTP 409) when the client's `Version` is stale, and the whole flow runs in a transaction. Generated saves are therefore protected by optimistic concurrency out of the box; don't add manual race-condition guards to hooks for plain concurrent edits. Mechanism and limits: `entity-design` skill, *Base Classes* (`BusinessObject` `Version`).
+
+**Signatures:**
+
+```csharp
+// Step 2 — modify DTO before DTO validation
+protected virtual async Task OnBeforeSave{Entity}AndReturnMainUIFormDTO(
+    {Entity}SaveBodyDTO saveBodyDTO) { }
+
+// Step 4 — just before DTO→Entity mapping
+protected virtual async Task OnBefore{Entity}IsMapped(
+    {Entity}DTO dto) { }
+
+// Step 5a — after mapping, before insert
+protected virtual async Task OnBefore{Entity}Insert(
+    {Entity} entity, {Entity}DTO dto) { }
+
+// Step 5b — after loading from DB, before update
+protected virtual async Task OnBefore{Entity}Update(
+    {Entity} entity, {Entity}DTO dto) { }
+
+// Step 8 — after everything is saved
+protected virtual async Task OnAfterSave{Entity}AndReturnMainUIFormDTO(
+    {Entity}SaveBodyDTO saveBodyDTO,
+    {Entity}MainUIFormDTO mainUIFormDTO) { }
+```
+
+### Delete Hooks
+
+```csharp
+// Default forwards to OnBefore{Entity}ListDelete with a single-element list.
+public virtual Task OnBefore{Entity}Delete({IdType} id) =>
+    OnBefore{Entity}ListDelete(id.StructToList());
+
+public virtual async Task OnBefore{Entity}ListDelete(List<{IdType}> ids) { }
+```
+
+**When single and batch deletes need the same logic, override only the list hook** — the single-id path forwards to it automatically. Override the single hook only when the per-id behaviour genuinely diverges from the batch case.
+
+### Get Hooks
+
+```csharp
+// After MainUIFormDTO is constructed (enrich with computed fields)
+protected virtual async Task OnAfterGet{Entity}MainUIFormDTO(
+    {Entity}MainUIFormDTO mainUIFormDTO) { }
+```
+
+### Paginated List (override the whole method)
+
+Override in your `{Entity}Service`:
+
+```csharp
+public override async Task<PaginatedResultDTO<{Entity}DTO>> GetPaginated{Entity}List(
+    FilterDTO filterDTO, IQueryable<{Entity}> query, bool authorize)
+{
+    query = query.Where(x => x.IsActive);
+    return await base.GetPaginated{Entity}List(filterDTO, query, authorize);
+}
+```
+
+### Blob/File Upload Hooks
+
+```csharp
+// Before upload authorization
+public virtual async Task OnBefore{Property}BlobFor{Entity}UploadIsAuthorized(
+    IFormFile file, {IdType} id) { }
+
+// Before upload to storage (transform bytes, validate)
+public virtual async Task<byte[]> OnBefore{Property}BlobFor{Entity}IsUploaded(
+    Stream stream, IFormFile file, {IdType} id) { }
+
+// Image-specific hooks (called by OnBefore*IsUploaded for image/* content types)
+public virtual async Task ValidateImageFor{Property}Of{Entity}(
+    Stream stream, IFormFile file, {IdType} id) { }
+public virtual async Task<byte[]> OptimizeImageFor{Property}Of{Entity}(
+    Stream stream, IFormFile file, {IdType} id) { }
+```
+
+### Relationship Hooks
+
+```csharp
+// Customize the base query for M2M autocomplete/dropdown
+protected virtual async Task<IQueryable<{Related}>> GetAll{Property}QueryFor{Entity}(
+    IQueryable<{Related}> query) { return query; }
+```
+
+## All Hooks Run Inside Transactions
+
+Every generated method wraps its logic in `_context.WithTransactionAsync(...)`. Nested calls reuse the existing transaction. You do **not** need to start your own transaction in hooks.
+
+**Generated CRUD operations flush the change tracker before commit**, so you can stage tracked writes — an entity `Add`/`Update`, or `IOutbox.Enqueue` — inside any `OnBefore...` hook (including `OnBefore{Entity}Delete`) and they persist atomically with the operation; no manual `SaveChangesAsync`. This holds even though the delete path deletes via untracked bulk `ExecuteDeleteAsync` — the operation still flushes whatever the hook staged. The catch: `WithTransactionAsync`'s clean-tracker-at-commit guard is a backstop, so if you stage a tracked write in a **custom** (non-hook) `WithTransactionAsync` block, you must `SaveChangesAsync` it yourself or the guard throws.
+
+If you need a transaction in **custom** (non-hook) methods:
+
+```csharp
+await _context.WithTransactionAsync(async () =>
+{
+    // all DB operations here are transactional
+});
+```
+
+## Exception Types
+
+| Type | HTTP Status | When to Use |
+|---|---|---|
+| `BusinessException(message)` | 400 | Validation the user can trigger through normal UI usage |
+| `SecurityViolationException()` | 403 | Impossible conditions, tampering, unauthorized access |
+
+```csharp
+throw new BusinessException("Sale price must be less than regular price.");
+throw new SecurityViolationException(); // logs detailed message server-side, returns generic error
+```
+
+Both surface in the admin UI automatically — the global HTTP-error interceptor toasts the `BusinessException` message (and a safe generic message for everything else). Throw and return; don't build a parallel error channel or per-call frontend handling.
+
+## PostgreSQL MARS Pitfall
+
+EF Core on PostgreSQL does **not** support Multiple Active Result Sets. You'll get a `NpgsqlOperationInProgressException` if you enumerate two queries concurrently.
+
+**Fix 1 — Materialize with `.Select()` before starting another query:**
+
+```csharp
+// BAD — lazy enumeration holds the connection open
+var dict = await _context.DbSet<Product>().ToDictionaryAsync(x => x.Id, x => x.Name);
+
+// GOOD — materialize first
+var dict = await _context.DbSet<Product>()
+    .Select(x => new { x.Id, x.Name })
+    .ToDictionaryAsync(x => x.Id, x => x.Name);
+```
+
+**Fix 2 — Use `.Include()` instead of lazy loading navigation properties:**
+
+```csharp
+// BAD — accessing Product.Category triggers lazy load while connection is busy
+var products = await _context.DbSet<Product>().ToListAsync();
+var names = products.Select(p => p.Category.Name); // MARS error
+
+// GOOD — eager load
+var products = await _context.DbSet<Product>()
+    .Include(p => p.Category)
+    .ToListAsync();
+```
+
+## Real-World Example
+
+```csharp
+public class ProductService : ProductServiceGenerated
+{
+    private readonly MeilisearchService _meilisearchService;
+    private readonly StorefrontRevalidationService _storefrontRevalidationService;
+
+    public ProductService(
+        EntityServiceDependencies deps,
+        MeilisearchService meilisearchService,
+        StorefrontRevalidationService storefrontRevalidationService
+    ) : base(deps)
+    {
+        _meilisearchService = meilisearchService;
+        _storefrontRevalidationService = storefrontRevalidationService;
+    }
+
+    protected override async Task OnBeforeSaveProductAndReturnMainUIFormDTO(
+        ProductSaveBodyDTO saveBodyDTO)
+    {
+        // Validate variant prices
+        foreach (ProductVariantSaveBodyDTO v in saveBodyDTO.OrderedProductVariantsSaveBodyDTO)
+        {
+            if (v.ProductVariantDTO.SalePrice >= v.ProductVariantDTO.Price)
+                throw new BusinessException("Sale price must be less than regular price.");
+        }
+
+        // Compute aggregate fields
+        saveBodyDTO.ProductDTO.Price = saveBodyDTO.OrderedProductVariantsSaveBodyDTO[0]
+            .ProductVariantDTO.Price;
+        saveBodyDTO.ProductDTO.Stock = saveBodyDTO.OrderedProductVariantsSaveBodyDTO
+            .Sum(v => v.ProductVariantDTO.Stock ?? 0);
+    }
+
+    protected override async Task OnAfterSaveProductAndReturnMainUIFormDTO(
+        ProductSaveBodyDTO saveBodyDTO,
+        ProductMainUIFormDTO mainUIFormDTO)
+    {
+        // Cross-entity service call
+        ProductVariantServiceGenerated variantService =
+            _deps.ServiceProvider.GetRequiredService<ProductVariantServiceGenerated>();
+
+        // Side effects: indexing, cache invalidation
+        await _meilisearchService.IndexProduct(mainUIFormDTO.ProductDTO.Id);
+        _storefrontRevalidationService.RevalidateProducts(mainUIFormDTO.ProductDTO.Slug);
+    }
+}
+```