@atlashub/smartstack-cli 4.32.0 → 4.34.0

package/templates/skills/controller/references/controller-code-templates.md

@@ -6,124 +6,127 @@
 
 ## Controller Template
 
-**Target path:** `src/SmartStack.Api/Controllers/{ApplicationPascal}/{entity}Controller.cs`
+**Target path:** `src/SmartStack.Api/Controllers/{ApplicationPascal}/{ModulePascal}/{entity}Controller.cs`
 
 > Application mapping: `administration` → `Administration`, `support` → `Support`, `myspace` → `MySpace`
+> Deep hierarchy: navRoute segments map to folder levels.
 
 ```csharp
+using MediatR;
 using Microsoft.AspNetCore.Mvc;
-using Microsoft.AspNetCore.Http;
+using SmartStack.Api.Authorization;
+using SmartStack.Api.Routing;
 using SmartStack.Application.Common.Authorization;
-using SmartStack.Application.Common.Interfaces;
-using SmartStack.Domain.Entities;
 
 namespace SmartStack.Api.Controllers.{area};
 
 [ApiController]
-[Route("api/{area_lowercase}/[controller]")]
-[Authorize]
-public class {module}Controller : ControllerBase
+[NavRoute("{app}.{module}")]
+[Microsoft.AspNetCore.Authorization.Authorize]
+[Produces("application/json")]
+[Tags("{namePlural}")]
+public class {entity}Controller : ControllerBase
 {
-    private readonly IApplicationDbContext _context;
-    private readonly ICurrentUserService _currentUser;
-    private readonly ILogger<{module}Controller> _logger;
-
-    public {module}Controller(
-        IApplicationDbContext context,
-        ICurrentUserService currentUser,
-        ILogger<{module}Controller> logger)
-    {
-        _context = context;
-        _currentUser = currentUser;
-        _logger = logger;
-    }
+    private readonly ISender _mediator;
+
+    public {entity}Controller(ISender mediator) => _mediator = mediator;
 
     // Endpoints generated based on plan...
 }
 ```
 
+**Key conventions:**
+- `ISender _mediator` (MediatR) — NOT `IApplicationDbContext` or `I{Name}Service`
+- `[Microsoft.AspNetCore.Authorization.Authorize]` — fully qualified
+- `[NavRoute]` is the ONLY route attribute — do NOT combine with `[Route("api/...")]`
+- `[Tags]` and `[Produces("application/json")]` always present
+- `[RequirePermission]` on every endpoint — `[Authorize]` alone has no RBAC
+
 ---
 
 ## GET Endpoint Example
 
 ```csharp
 [HttpGet]
-[RequirePermission(Permissions.{module}.View)]
-[ProducesResponseType(typeof(PaginatedResult<{entity}ResponseDto>), StatusCodes.Status200OK)]
+[RequirePermission(Permissions.{Module}.{Resource}.View)]
+[ProducesResponseType(typeof(List<{entity}ListDto>), StatusCodes.Status200OK)]
 [ProducesResponseType(StatusCodes.Status401Unauthorized)]
 [ProducesResponseType(StatusCodes.Status403Forbidden)]
-public async Task<IActionResult> GetAll(
-    [FromQuery] int page = 1,
-    [FromQuery] int pageSize = 20,
-    CancellationToken ct = default)
+public async Task<ActionResult<List<{entity}ListDto>>> GetAll(CancellationToken ct)
 {
-    var query = _context.{module}
-        .AsNoTracking()
-        .OrderByDescending(x => x.CreatedAt);
-
-    var total = await query.CountAsync(ct);
-    var items = await query
-        .Skip((page - 1) * pageSize)
-        .Take(pageSize)
-        .Select(x => new {entity}ResponseDto(x))
-        .ToListAsync(ct);
-
-    return Ok(new PaginatedResult<{entity}ResponseDto>(items, total, page, pageSize));
+    var result = await _mediator.Send(new Get{entityPlural}Query(), ct);
+    return Ok(result);
 }
 ```
 
 **Endpoint attributes to include:**
 1. `[HttpGet]`, `[HttpPost]`, etc.
-2. `[RequirePermission(Permissions.{module}.View)]`
-3. `[ProducesResponseType(typeof(...), StatusCodes.Status200OK)]`
+2. `[RequirePermission(Permissions.{Module}.{Resource}.View)]` — permission constants
+3. `[ProducesResponseType(typeof(...), StatusCodes.Status200OK)]` — StatusCodes constants
 4. `[ProducesResponseType(StatusCodes.Status401Unauthorized)]`
 5. `[ProducesResponseType(StatusCodes.Status403Forbidden)]`
 
 ---
 
+## Return Types by Endpoint
+
+| Endpoint | Return Type | Notes |
+|----------|-------------|-------|
+| GetAll | `Task<ActionResult<List<{entity}ListDto>>>` | List DTO for summary |
+| GetById | `Task<ActionResult<{entity}DetailDto>>` | Detail DTO with full data |
+| Create | `Task<ActionResult<{entity}DetailDto>>` | Returns 201 with CreatedAtAction |
+| Update | `Task<ActionResult<{entity}DetailDto>>` | Check `result.IsNotFound` |
+| Delete | `Task<IActionResult>` | Returns 204 NoContent or 404 |
+
+---
+
 ## DTO Templates
 
 **Target paths:**
 ```
-src/SmartStack.Application/DTOs/{module}/{entity}CreateDto.cs
-src/SmartStack.Application/DTOs/{module}/{entity}UpdateDto.cs
-src/SmartStack.Application/DTOs/{module}/{entity}ResponseDto.cs
+src/SmartStack.Application/{Application}/{Module}/DTOs/{entity}ListDto.cs
+src/SmartStack.Application/{Application}/{Module}/DTOs/{entity}DetailDto.cs
+src/SmartStack.Application/{Application}/{Module}/DTOs/Create{entity}Request.cs
+src/SmartStack.Application/{Application}/{Module}/DTOs/Update{entity}Request.cs
 ```
 
-**CreateDto:**
-```csharp
-public record {entity}CreateDto(
-    string Name,
-    // ... required properties
-);
-```
+> DTOs are in `Application/{Domain}/.../DTOs/` — NOT in `Application/DTOs/{module}/`.
 
-**UpdateDto:**
+**ListDto (for GetAll):**
 ```csharp
-public record {entity}UpdateDto(
-    string? Name,
-    // ... optional properties
+public record {entity}ListDto(
+    Guid Id,
+    string Name,
+    // ... summary properties
+    DateTime CreatedAt
 );
 ```
 
-**ResponseDto:**
+**DetailDto (for GetById, Create, Update):**
 ```csharp
-public record {entity}ResponseDto(
+public record {entity}DetailDto(
     Guid Id,
     string Name,
-    // ... all public properties
+    // ... all properties
     DateTime CreatedAt,
     DateTime? UpdatedAt
-)
-{
-    public {entity}ResponseDto({entity} entity) : this(
-        entity.Id,
-        entity.Name,
-        // ... mapping
-        entity.CreatedAt,
-        entity.UpdatedAt
-    ) { }
-}
+);
+```
+
+**CreateRequest:**
+```csharp
+public record Create{entity}Request(
+    string Name
+    // ... required properties
+);
+```
+
+**UpdateRequest:**
+```csharp
+public record Update{entity}Request(
+    string? Name
+    // ... optional properties
+);
 ```
 
 ---

package/templates/skills/controller/references/mcp-scaffold-workflow.md

@@ -68,12 +68,16 @@ const controllerCall = await mcp__smartstack__scaffold_extension({
   options: {
     navRoute: "{permission_path}",  // MANDATORY for NavRoute attribute
     navRouteSuffix: null,             // Optional: e.g., "details" → [NavRoute("path", Suffix = "details")]
+    customSegment: null,              // Optional: e.g., "user/dashboard" → [NavRoute("path", CustomSegment = "user/dashboard")]
     dryRun: false
   }
 });
 
 // Expected output:
-// Api/Controllers/{area}/{entityName}Controller.cs with [NavRoute] attribute
+// Api/Controllers/{Application}/{Module}/{entityName}Controller.cs with [NavRoute] attribute
+// Uses MediatR (ISender _mediator), [Microsoft.AspNetCore.Authorization.Authorize] (fully qualified),
+// [Tags], [Produces("application/json")], [RequirePermission] with Permissions constants,
+// [ProducesResponseType] with StatusCodes.* constants including 401/403
 ```
 
 **From response, extract:**