@atlashub/smartstack-cli 4.18.0 → 4.20.0

package/templates/skills/apex/references/smartstack-api.md

@@ -231,9 +231,9 @@ public class {Name} : BaseEntity, IScopedTenantEntity, IAuditableEntity
 
 ### Entity Pattern — Person Extension (User-linked roles)
 
-For entities representing a "person role" of a User (Employee, Customer, Contact). Avoids duplicating User personal data.
+For entities representing a "person role" of a User (Employee, Customer, Contact). Links entity to User instead of duplicating personal data.
 
-> **Full reference:** See `references/person-extension-pattern.md` for complete entity, config, service, DTO, and frontend patterns.
+> **Full reference:** See `references/person-extension-pattern.md` for complete entity, config, service, DTO, and frontend patterns with C# templates, decision guide, and examples.
 
 **Two variants:**
 
@@ -242,9 +242,18 @@ For entities representing a "person role" of a User (Employee, Customer, Contact
 | **Mandatory** | `Guid UserId` | Employee, Manager — always a User |
 | **Optional** | `Guid? UserId` | Customer, Contact — may or may not have account |
 
+**IPersonExtension interface:**
+```csharp
+public interface IPersonExtension
+{
+    Guid? UserId { get; }
+    User? User { get; }
+}
+```
+
 **Mandatory variant (entity):**
 ```csharp
-public class Employee : BaseEntity, ITenantEntity, IAuditableEntity
+public class Employee : BaseEntity, ITenantEntity, IAuditableEntity, IPersonExtension
 {
     public Guid TenantId { get; private set; }
     public string? CreatedBy { get; set; }
@@ -254,7 +263,7 @@ public class Employee : BaseEntity, ITenantEntity, IAuditableEntity
     public Guid UserId { get; private set; }
     public User? User { get; private set; }
 
-    // Business properties ONLY — ZERO person fields (FirstName, LastName, Email come from User)
+    // Business properties ONLY — no duplicate person fields
     public string Code { get; private set; } = null!;
     public DateOnly HireDate { get; private set; }
 }
@@ -262,7 +271,7 @@ public class Employee : BaseEntity, ITenantEntity, IAuditableEntity
 
 **Optional variant (entity):**
 ```csharp
-public class Customer : BaseEntity, ITenantEntity, IAuditableEntity
+public class Customer : BaseEntity, ITenantEntity, IAuditableEntity, IPersonExtension
 {
     public Guid TenantId { get; private set; }
     public string? CreatedBy { get; set; }
@@ -272,7 +281,7 @@ public class Customer : BaseEntity, ITenantEntity, IAuditableEntity
     public Guid? UserId { get; private set; }
     public User? User { get; private set; }
 
-    // Person fields (standalone when no User linked)
+    // Person fields (used only when UserId is null)
     public string FirstName { get; private set; } = null!;
     public string LastName { get; private set; } = null!;
     public string? Email { get; private set; }
@@ -284,14 +293,11 @@ public class Customer : BaseEntity, ITenantEntity, IAuditableEntity
 }
 ```
 
-**EF Config (mandatory):** `builder.HasIndex(e => new { e.TenantId, e.UserId }).IsUnique();`
-**EF Config (optional):** `builder.HasIndex(e => new { e.TenantId, e.UserId }).IsUnique().HasFilter("[UserId] IS NOT NULL");`
-
-**Service rules (both):** `Include(x => x.User)` on all queries. Inject `ICoreDbContext` for User reads. CreateAsync verifies User exists + no duplicate `(TenantId, UserId)`.
-
-**DTO rules:** Mandatory CreateDto has `Guid UserId` + business fields only. Optional CreateDto has `Guid? UserId` + person fields. ResponseDto (both) includes `Display*` fields.
-
-**FORBIDDEN (mandatory variant):** `FirstName`, `LastName`, `Email`, `PhoneNumber` properties in entity — these come from User.
+**Key rules:**
+- **EF Config (mandatory):** Unique index on `(TenantId, UserId)` without filter
+- **EF Config (optional):** Unique index on `(TenantId, UserId)` with `.HasFilter("[UserId] IS NOT NULL")`
+- **Service:** Include User on all queries. Verify User exists and no duplicate on CreateAsync.
+- **DTO:** Mandatory CreateDto requires `UserId`. Optional CreateDto requires person fields when `UserId` is null.
 
 ---
 
@@ -354,9 +360,9 @@ public class {Name}Configuration : IEntityTypeConfiguration<{Name}>
 
 ---
 
-## Service Pattern (tenant-scoped, MANDATORY)
+## Service Pattern (tenant-scoped, required)
 
-> **CRITICAL:** ALL services MUST inject `ICurrentUserService` + `ICurrentTenantService` and filter by `TenantId`. Missing TenantId = OWASP A01 vulnerability.
+> All services must inject `ICurrentUserService` + `ICurrentTenantService` and filter by `TenantId`. Missing TenantId is an OWASP A01 vulnerability.
 
 ```csharp
 using Microsoft.EntityFrameworkCore;
@@ -392,12 +398,12 @@ public class {Name}Service : I{Name}Service
         int pageSize = 20,
         CancellationToken ct = default)
     {
-        // MANDATORY guard — throws 400 if no tenant context (e.g., missing X-Tenant-Slug header)
+        // Guard clause — throws 400 if no tenant context (e.g., missing X-Tenant-Slug header)
         var tenantId = _currentTenant.TenantId
             ?? throw new TenantContextRequiredException();
 
         var query = _db.{Name}s
-            .Where(x => x.TenantId == tenantId)  // MANDATORY tenant filter
+            .Where(x => x.TenantId == tenantId)  // Required tenant filter
             .AsNoTracking();
 
         // Search filter — enables EntityLookup on frontend
@@ -425,7 +431,7 @@ public class {Name}Service : I{Name}Service
             ?? throw new TenantContextRequiredException();
 
         return await _db.{Name}s
-            .Where(x => x.Id == id && x.TenantId == tenantId)  // MANDATORY
+            .Where(x => x.Id == id && x.TenantId == tenantId)  // Required
             .AsNoTracking()
             .Select(x => new {Name}ResponseDto(x.Id, x.Code, x.Name, x.CreatedAt))
             .FirstOrDefaultAsync(ct);
@@ -437,7 +443,7 @@ public class {Name}Service : I{Name}Service
             ?? throw new TenantContextRequiredException();
 
         var entity = {Name}.Create(
-            tenantId: tenantId,  // MANDATORY — never Guid.Empty
+            tenantId: tenantId,  // Required — never Guid.Empty
             code: dto.Code,
             name: dto.Name);
 
@@ -472,7 +478,7 @@ public class {Name}Service : I{Name}Service
 - `ICurrentTenantService` (from `SmartStack.Application.Common.Interfaces.Tenants`): provides `TenantId` (Guid?), `HasTenant` (bool), `TenantSlug` (string?)
 - `IExtensionsDbContext` (for client extensions) or `ICoreDbContext` (for platform)
 
-**MANDATORY guard clause (first line of every method):**
+**Guard clause (first line of every method):**
 ```csharp
 var tenantId = _currentTenant.TenantId
     ?? throw new TenantContextRequiredException();
@@ -480,7 +486,7 @@ var tenantId = _currentTenant.TenantId
 This converts a null TenantId into a clean 400 Bad Request response via `GlobalExceptionHandlerMiddleware`.
 **IMPORTANT:** Uses `TenantContextRequiredException` (400), NOT `UnauthorizedAccessException` (401). A missing tenant is a bad request, not an auth failure — the JWT is valid, `[Authorize]` passed.
 
-**FORBIDDEN in services:**
+Do not use in services:
 - `_currentTenant.TenantId!.Value` — throws `InvalidOperationException` (500) instead of clean 400
 - `UnauthorizedAccessException("Tenant context is required")` — throws 401, triggers frontend token clearing
 - `tenantId: Guid.Empty` — always use validated tenantId from guard clause
@@ -557,18 +563,18 @@ public class {Name}Controller : ControllerBase
 }
 ```
 
-**CRITICAL — Route attribute rules:**
+Route attribute rules:
 - `[NavRoute]` is the ONLY route attribute needed — it resolves routes dynamically from Navigation entities at startup
-- **FORBIDDEN:** `[Route("api/...")]` alongside `[NavRoute]` — causes route conflicts and 404s at runtime
-- **FORBIDDEN:** `[Route("api/[controller]")]` — this is standard ASP.NET Core, NOT SmartStack
+- Do not use `[Route("api/...")]` alongside `[NavRoute]` — causes route conflicts and 404s at runtime
+- Do not use `[Route("api/[controller]")]` — this is standard ASP.NET Core, NOT SmartStack
 - If a controller has `[NavRoute]`, there must be NO `[Route]` attribute on the class
 
-**CRITICAL:** Use `[RequirePermission(Permissions.{Module}.{Action})]` on EVERY endpoint — NEVER `[Authorize]` alone (no RBAC enforcement).
+Use `[RequirePermission(Permissions.{Module}.{Action})]` on every endpoint — do not use `[Authorize]` alone (no RBAC enforcement).
 
-**CRITICAL — Permission paths use IDENTICAL segments to NavRoute codes (kebab-case):**
+Permission paths must use identical segments to NavRoute codes (kebab-case):
 - NavRoute: `human-resources.employees` → Permission: `human-resources.employees.read`
 - NavRoute: `human-resources.employees.leaves` → Permission: `human-resources.employees.leaves.read`
-- FORBIDDEN: `humanresources.employees.read` (no kebab-case — mismatches NavRoute)
+- Do not use: `humanresources.employees.read` (no kebab-case — mismatches NavRoute)
 - SmartStack.app convention: `support-client.my-tickets.read` (always kebab-case)
 
 ### Section-Level Controller (NavRoute with 3 segments)
@@ -636,16 +642,16 @@ public class AiPromptsController : ControllerBase
 public async Task<ActionResult<PaginatedResult<LeaveTypeResponseDto>>> GetAllLeaveTypes(...)
 ```
 
-> **CRITICAL — Sub-resource frontend completeness:**
+> Sub-resource frontend completeness:
 > If a parent page has a button (e.g., "Manage Leave Types") that `navigate()`s to a sub-resource route,
-> the frontend MUST include a page component for that route. Otherwise → dead link → white screen.
+> the frontend must include a page component for that route. Otherwise → dead link → white screen.
 > - Either create a dedicated sub-resource ListPage (e.g., `LeaveTypesPage.tsx`)
-> - Or DON'T include the navigate() button if pages won't be created
-> - **Prefer separate controllers** (with Suffix) over sub-endpoints in parent controller — easier to route
+> - Or do not include the navigate() button if pages won't be created
+> - Prefer separate controllers (with Suffix) over sub-endpoints in parent controller — easier to route
 
 ---
 
-## Navigation Seed Data Pattern (CRITICAL — routes must be full paths)
+## Navigation Seed Data Pattern (routes must be full paths)
 
 > **The navigation seed data defines menu routes stored in DB. These routes MUST be full paths starting with `/`.**
 > Short routes (e.g., `humanresources`) cause 400 Bad Request on application-tracking.
@@ -659,12 +665,12 @@ public async Task<ActionResult<PaginatedResult<LeaveTypeResponseDto>>> GetAllLea
 | Section | `/{app-kebab}/{module-kebab}/{section-kebab}` | `/human-resources/employees/departments` |
 | Resource | `/{app-kebab}/{module-kebab}/{section-kebab}/{resource-kebab}` | `/human-resources/employees/departments/export` |
 
-**ROUTE SPECIAL CASES (list and detail sections):**
+**Route special cases (list and detail sections):**
 > The `list` and `detail` sections are NOT functional sub-areas — they are view modes of the module itself.
-> Their navigation routes MUST NOT add extra segments:
+> Their navigation routes must NOT add extra segments:
 > - `list` section route = module route (e.g., `/human-resources/employees`)
 > - `detail` section route = module route + `/:id` (e.g., `/human-resources/employees/:id`)
-> - FORBIDDEN: `/employees/list`, `/employees/detail/:id`
+> - Do not use: `/employees/list`, `/employees/detail/:id`
 > - Other sections (dashboard, approve, import, etc.) = module route + `/{section-kebab}` (normal behavior)
 
 **Rules:**
@@ -716,13 +722,13 @@ var section = NavigationSection.Create(
     10);
 ```
 
-### FORBIDDEN in Seed Data
+### Avoid in Seed Data
 
 | Mistake | Reality |
 |---------|---------|
 | `"humanresources"` as route | Must be `"/human-resources"` (full path, kebab-case) |
 | `"employees"` as route | Must be `"/human-resources/employees"` (includes parent) |
-| Deterministic/sequential/fixed GUIDs in seed data | ALWAYS use `Guid.NewGuid()` |
+| Deterministic/sequential/fixed GUIDs in seed data | Use `Guid.NewGuid()` instead |
 | Missing translations | Must have 4 languages: fr, en, it, de |
 | Missing NavigationApplicationSeedData | Menu invisible without Application level |
 
@@ -750,7 +756,7 @@ services.AddValidatorsFromAssemblyContaining<Create{Name}DtoValidator>();
 
 ---
 
-## DTO Type Mapping (CRITICAL)
+## DTO Type Mapping
 
 > **Use the correct .NET type for each property.** Incorrect types cause runtime parsing errors.
 
@@ -762,7 +768,7 @@ services.AddValidatorsFromAssemblyContaining<Create{Name}DtoValidator>();
 | Duration, hours | `decimal` | `8.5` | `public decimal HoursWorked { get; set; }` |
 | FK reference | `Guid` | `"uuid-string"` | `public Guid EmployeeId { get; set; }` |
 
-**FORBIDDEN in DTOs:**
+Do not use in DTOs:
 - `string Date` / `string StartDate` — use `DateOnly`
 - `string Time` — use `TimeOnly`
 - `DateTime BirthDate` — use `DateOnly` (no time component needed)
@@ -780,7 +786,7 @@ services.AddValidatorsFromAssemblyContaining<Create{Name}DtoValidator>();
 | `e.IsDeleted` filter | Does NOT exist — no soft delete |
 | `SmartStack.Api.Core.Routing` | Wrong — use `SmartStack.Api.Routing` |
 | `SystemEntity` base class | Does NOT exist — use `BaseEntity` for all |
-| `[Route("api/...")] + [NavRoute]` | **FORBIDDEN** — causes 404s. Only `[NavRoute]` needed (resolves route from DB at startup). Remove ALL `[Route]` attributes when `[NavRoute]` is present. |
+| `[Route("api/...")] + [NavRoute]` | Do not combine — causes 404s. Only `[NavRoute]` needed (resolves route from DB at startup). Remove `[Route]` when `[NavRoute]` is present. |
 | `SmartStack.Domain.Common.Interfaces` | Wrong — interfaces are in `SmartStack.Domain.Common` directly |
 | `[Authorize]` without `[RequirePermission]` | No RBAC enforcement — always use `[RequirePermission]` |
 | `tenantId: Guid.Empty` in services | OWASP A01 — always use validated `_currentTenant.TenantId` |
@@ -793,11 +799,11 @@ services.AddValidatorsFromAssemblyContaining<Create{Name}DtoValidator>();
 | `humanresources.employees.read` in permissions | Permission segments MUST match NavRoute kebab-case: `human-resources.employees.read` |
 | `Permission.Create()` | Does NOT exist — use `CreateForModule()`, `CreateForSection()`, etc. |
 | `GetAllAsync()` without search param | ALL GetAll endpoints MUST support `?search=` for EntityLookup |
-| `string Date` in DTO | Date-only fields MUST use `DateOnly`, NEVER `string` |
+| `string Date` in DTO | Date-only fields must use `DateOnly`, not `string` |
 | `DateTime` for date-only | Use `DateOnly` when no time component needed |
 | FK field as plain text input | Frontend MUST use `EntityLookup` component for Guid FK fields |
-| `PagedResult<T>` / `PaginatedResultDto<T>` | FORBIDDEN — use `PaginatedResult<T>` only |
-| Controller injects `DbContext` | **Clean Architecture violation** — create an Application service and inject it instead |
+| `PagedResult<T>` / `PaginatedResultDto<T>` | Use `PaginatedResult<T>` instead |
+| Controller injects `DbContext` | Create an Application service and inject it instead (Clean Architecture) |
 | Domain entity has `[Table]` attribute | Infrastructure concern in Domain — move to `IEntityTypeConfiguration<T>` in Infrastructure |
 | `using Microsoft.EntityFrameworkCore` in Domain | EF Core belongs in Infrastructure, not Domain — Domain must be persistence-ignorant |
 | Controller returns `Employee` entity | Domain leak in API response — return `EmployeeResponseDto` instead |
@@ -949,10 +955,10 @@ export interface PaginationParams {
 }
 ```
 
-### FORBIDDEN Type Names
+### Type Names to Avoid
 
-| Forbidden | Canonical Replacement |
-|-----------|----------------------|
+| Avoid | Use Instead |
+|-------|------------|
 | `PagedResult<T>` | `PaginatedResult<T>` |
 | `PaginatedResultDto<T>` | `PaginatedResult<T>` |
 | `PaginatedResponse<T>` | `PaginatedResult<T>` |
@@ -968,8 +974,8 @@ export interface PaginationParams {
 - **Max pageSize = 100** — enforced via `Math.Clamp(pageSize, 1, 100)` or extension method
 - **Default page = 1, pageSize = 20** — all GetAll endpoints
 - **Search param mandatory** — enables `EntityLookup` on frontend
-- **POST-CHECK 11** blocks `List<T>` returns on GetAll
-- **POST-CHECK 26** blocks non-canonical pagination type names
+- **POST-CHECK C12** blocks `List<T>` returns on GetAll
+- **POST-CHECK C28** blocks non-canonical pagination type names
 
 ---
 
@@ -977,7 +983,7 @@ export interface PaginationParams {
 
 > **These are the most common and dangerous mistakes.** Each one has been observed in production code generation.
 
-### Anti-Pattern 1: HasQueryFilter with `!= Guid.Empty` (SECURITY — OWASP A01)
+### Anti-Pattern 1: HasQueryFilter with `!= Guid.Empty` (Security vulnerability)
 
 The `HasQueryFilter` in EF Core should use **runtime tenant resolution**, NOT a static comparison against `Guid.Empty`.
 
@@ -992,11 +998,11 @@ public void Configure(EntityTypeBuilder<MyEntity> builder)
 
 **CORRECT — Tenant isolation via service:**
 ```csharp
-// CORRECT: In SmartStack, tenant filtering is done in the SERVICE layer, not via HasQueryFilter.
+// Correct: In SmartStack, tenant filtering is done in the SERVICE layer, not via HasQueryFilter.
 public async Task<PaginatedResult<MyEntityDto>> GetAllAsync(...)
 {
     var query = _db.MyEntities
-        .Where(x => x.TenantId == _currentUser.TenantId)  // MANDATORY runtime filter
+        .Where(x => x.TenantId == _currentUser.TenantId)  // Required runtime filter
         .AsNoTracking();
     // ...
 }
@@ -1022,7 +1028,7 @@ public async Task<List<MyEntityDto>> GetAllAsync(CancellationToken ct)
 
 **CORRECT — Paginated with search:**
 ```csharp
-// CORRECT: Returns PaginatedResult<T> with search, page, pageSize
+// Correct: Returns PaginatedResult<T> with search, page, pageSize
 public async Task<PaginatedResult<MyEntityDto>> GetAllAsync(
     string? search = null, int page = 1, int pageSize = 20, CancellationToken ct = default)
 {
@@ -1128,16 +1134,16 @@ public class UpdateMyEntityDtoValidator : AbstractValidator<UpdateMyEntityDto>
 
 ---
 
-### Anti-Pattern 6: `TenantId!.Value` null-forgiving operator (RUNTIME CRASH)
+### Anti-Pattern 6: `TenantId!.Value` null-forgiving operator
 
 The `!` (null-forgiving) operator followed by `.Value` on a `Guid?` suppresses compiler warnings but **throws `InvalidOperationException` at runtime** when TenantId is null.
 
 **INCORRECT — Crashes with 500 Internal Server Error:**
 ```csharp
-// WRONG: Throws InvalidOperationException("Nullable object must have a value") → 500 error
+// Wrong: Throws InvalidOperationException("Nullable object must have a value") → 500 error
 public async Task<PaginatedResult<MyEntityDto>> GetAllAsync(...)
 {
-    var tenantId = _currentTenant.TenantId!.Value;  // CRASH if no tenant context
+    var tenantId = _currentTenant.TenantId!.Value;  // Crashes if no tenant context
     var query = _db.MyEntities.Where(x => x.TenantId == tenantId);
     // ...
 }
@@ -1145,7 +1151,7 @@ public async Task<PaginatedResult<MyEntityDto>> GetAllAsync(...)
 
 **CORRECT — Clean 400 via GlobalExceptionHandlerMiddleware:**
 ```csharp
-// CORRECT: Throws TenantContextRequiredException → middleware converts to 400 Bad Request
+// Correct: Throws TenantContextRequiredException → middleware converts to 400 Bad Request
 public async Task<PaginatedResult<MyEntityDto>> GetAllAsync(...)
 {
     var tenantId = _currentTenant.TenantId