@atlashub/smartstack-cli 3.31.0 → 3.32.0

package/templates/skills/apex/_shared.md

@@ -55,7 +55,7 @@
 | `scaffold_api_client` | Generate TypeScript API client | Frontend changes |
 | `scaffold_routes` | Generate React Router routes | Frontend changes |
 
-### eXamine (step-04)
+### eXamine (step-04) — 30 POST-CHECKs
 
 | Tool | Purpose | Condition |
 |------|---------|-----------|
@@ -63,6 +63,13 @@
 | `validate_frontend_routes` | Validate route/layout alignment | Frontend changes |
 | `validate_security` | Check security patterns | API changes |
 
+**Key BLOCKING POST-CHECKs (most common failures):**
+- **#8:** Forms must be full pages — ZERO modals/dialogs
+- **#13:** No hardcoded Tailwind colors — use CSS variables only
+- **#6+27:** i18n in separate `locales/{lang}/{module}.json` — NEVER embedded in .ts
+- **#10:** Form pages must have `.test.tsx` companion files
+- **#28:** Pages must use `useTranslation` — no hardcoded strings
+
 ### Analysis (step-01)
 
 | Tool | Purpose |
@@ -70,7 +77,7 @@
 | `api_docs` | Existing API documentation |
 | `analyze_extension_points` | React extension points |
 
-### Tests (step-07, if -t)
+### Tests (step-07)
 
 | Tool | Purpose |
 |------|---------|

package/templates/skills/apex/references/code-generation.md

@@ -0,0 +1,412 @@
+# Code Generation — Pattern Reference
+
+> **Source of truth:** feature.json `analysis.entities[].codePattern`
+> **Loaded by:** step-01 (analyze), step-03 (execute)
+> **Shared by:** /business-analyse + /apex
+
+---
+
+## Code Strategies
+
+| Strategy | Pattern | Example | Use Case |
+|----------|---------|---------|----------|
+| `sequential` | `{tenant}-{prefix}-{N:digits}` | `acme-emp-00001` | Employees, customers, projects |
+| `timestamp-daily` | `{tenant}-{prefix}-{yyyyMMdd}-{N:3}` | `acme-inv-20260215-001` | Invoices, orders, receipts |
+| `timestamp-minute` | `{tenant}-{prefix}-{yyyyMMddHHmm}-{N:3}` | `acme-ticket-202602151430-001` | Tickets, incidents, requests |
+| `year-sequential` | `{tenant}-{prefix}-{yyyy}-{N:digits}` | `acme-ctr-2026-00001` | Contracts, policies, agreements |
+| `uuid-short` | `{tenant}-{prefix}-{8hex}` | `acme-ref-a1b2c3d4` | Reference tables, categories, tags |
+| `manual` | User-provided | `custom-code` | No auto-generation |
+
+---
+
+## Volume-to-Digits (x10 Rule)
+
+Anticipate volume growth by multiplying estimated records by 10:
+
+```
+digits = max(4, ceil(log10(estimatedVolume * 10)))
+```
+
+| Estimated Volume | x10 | Digits | Max Capacity |
+|-----------------|-----|--------|-------------|
+| 100 | 1,000 | 4 | 9,999 |
+| 1,000 | 10,000 | 5 | 99,999 |
+| 10,000 | 100,000 | 6 | 999,999 |
+| 100,000 | 1,000,000 | 7 | 9,999,999 |
+
+**Default:** If no volume estimate is provided, use 5 digits (capacity: 99,999).
+
+---
+
+## Strategy Selection Heuristic
+
+When the user does not specify a strategy, apply these defaults based on entity name:
+
+| Entity name pattern | Default strategy | Rationale |
+|--------------------|-----------------|-----------|
+| Invoice, Order, Receipt, Bill, Delivery | `timestamp-daily` | Date context aids lookup and sorting |
+| Ticket, Request, Incident, Support, Alert | `timestamp-minute` | High-frequency, time-sensitive items |
+| Contract, Agreement, Policy, License, Subscription | `year-sequential` | Yearly lifecycle, annual numbering |
+| Reference, Category, Tag, Type, Status, Config | `uuid-short` | Lookup tables, no sequential need |
+| Employee, Customer, Client, Partner, Project, Product, Department | `sequential` | Standard business entities |
+| Any other entity | `sequential` | Safe default |
+
+---
+
+## Code Regex
+
+**Updated pattern** (supports hyphens for generated codes):
+
+```
+^[a-z0-9_-]+$
+```
+
+The previous pattern `^[a-z0-9_]+$` did NOT support hyphens, which are the default separator in all auto-generated codes. All validators MUST use the updated regex.
+
+---
+
+## Feature.json — codePattern Structure
+
+Stored in `analysis.entities[].codePattern`:
+
+```json
+{
+  "name": "Employee",
+  "description": "Company employee",
+  "attributes": [...],
+  "relationships": [...],
+  "codePattern": {
+    "strategy": "sequential",
+    "prefix": "emp",
+    "includeTenantSlug": true,
+    "separator": "-",
+    "estimatedVolume": 1000,
+    "digits": 5,
+    "example": "acme-emp-00001"
+  }
+}
+```
+
+---
+
+## Backend Architecture
+
+### CodeStrategy Enum
+
+```csharp
+namespace SmartStack.Application.Common.Models.CodeGeneration;
+
+public enum CodeStrategy
+{
+    Sequential,
+    TimestampDaily,
+    TimestampMinute,
+    YearSequential,
+    UuidShort,
+    Manual
+}
+```
+
+### CodePatternConfig Record
+
+```csharp
+namespace SmartStack.Application.Common.Models.CodeGeneration;
+
+public record CodePatternConfig(
+    CodeStrategy Strategy = CodeStrategy.Sequential,
+    string Prefix = "item",
+    bool IncludeTenantSlug = true,
+    string Separator = "-",
+    int EstimatedVolume = 1000,
+    int Digits = 5);
+```
+
+### ICodeGenerator<TEntity> Interface
+
+```csharp
+namespace SmartStack.Application.Common.Interfaces.CodeGeneration;
+
+/// <summary>
+/// Generates unique codes for entities following configurable patterns.
+/// </summary>
+public interface ICodeGenerator<TEntity> where TEntity : class
+{
+    /// <summary>
+    /// Generate the next unique code for the current tenant.
+    /// Handles concurrency via retry on unique constraint violation (3 attempts).
+    /// </summary>
+    Task<string> NextCodeAsync(CancellationToken ct = default);
+}
+```
+
+### CodeGenerator<TEntity> Implementation
+
+```csharp
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Logging;
+using SmartStack.Application.Common.Interfaces.Tenants;
+using SmartStack.Application.Common.Interfaces.Persistence;
+using SmartStack.Application.Common.Models.CodeGeneration;
+
+namespace SmartStack.Infrastructure.Services.CodeGeneration;
+
+public class CodeGenerator<TEntity> : ICodeGenerator<TEntity>
+    where TEntity : class
+{
+    private readonly IExtensionsDbContext _db;
+    private readonly ICurrentTenantService _currentTenant;
+    private readonly CodePatternConfig _config;
+    private readonly ILogger<CodeGenerator<TEntity>> _logger;
+    private const int MaxRetries = 3;
+
+    public CodeGenerator(
+        IExtensionsDbContext db,
+        ICurrentTenantService currentTenant,
+        CodePatternConfig config,
+        ILogger<CodeGenerator<TEntity>> logger)
+    {
+        _db = db;
+        _currentTenant = currentTenant;
+        _config = config;
+        _logger = logger;
+    }
+
+    public async Task<string> NextCodeAsync(CancellationToken ct = default)
+    {
+        var tenantId = _currentTenant.TenantId
+            ?? throw new UnauthorizedAccessException("Tenant context is required");
+        var tenantSlug = _currentTenant.TenantSlug ?? "default";
+
+        for (var attempt = 0; attempt < MaxRetries; attempt++)
+        {
+            try
+            {
+                var code = await GenerateCodeAsync(tenantId, tenantSlug, ct);
+                return code;
+            }
+            catch (DbUpdateException ex) when (IsUniqueConstraintViolation(ex))
+            {
+                _logger.LogWarning(
+                    "Code generation retry {Attempt}/{Max} for {Entity} tenant {TenantId}",
+                    attempt + 1, MaxRetries, typeof(TEntity).Name, tenantId);
+
+                if (attempt == MaxRetries - 1)
+                    throw new InvalidOperationException(
+                        $"Failed to generate unique code for {typeof(TEntity).Name} after {MaxRetries} attempts", ex);
+            }
+        }
+
+        throw new InvalidOperationException("Code generation exhausted all retries");
+    }
+
+    private async Task<string> GenerateCodeAsync(
+        Guid tenantId, string tenantSlug, CancellationToken ct)
+    {
+        var sep = _config.Separator;
+        var parts = new List<string>();
+
+        // 1. Tenant prefix (dynamic slug)
+        if (_config.IncludeTenantSlug)
+            parts.Add(tenantSlug.ToLowerInvariant());
+
+        // 2. Entity prefix
+        parts.Add(_config.Prefix);
+
+        // 3. Date segment (for timestamp strategies)
+        var now = DateTime.UtcNow;
+        switch (_config.Strategy)
+        {
+            case CodeStrategy.TimestampDaily:
+                parts.Add(now.ToString("yyyyMMdd"));
+                break;
+            case CodeStrategy.TimestampMinute:
+                parts.Add(now.ToString("yyyyMMddHHmm"));
+                break;
+            case CodeStrategy.YearSequential:
+                parts.Add(now.ToString("yyyy"));
+                break;
+        }
+
+        // 4. Sequential number or UUID segment
+        if (_config.Strategy == CodeStrategy.UuidShort)
+        {
+            parts.Add(Guid.NewGuid().ToString("N")[..8]);
+        }
+        else if (_config.Strategy != CodeStrategy.Manual)
+        {
+            var codePrefix = string.Join(sep, parts) + sep;
+            var nextSeq = await GetNextSequenceAsync(tenantId, codePrefix, ct);
+            parts.Add(nextSeq.ToString().PadLeft(_config.Digits, '0'));
+        }
+
+        return string.Join(sep, parts);
+    }
+
+    private async Task<int> GetNextSequenceAsync(
+        Guid tenantId, string codePrefix, CancellationToken ct)
+    {
+        // Find the highest existing sequence matching the prefix
+        var maxCode = await _db.Set<TEntity>()
+            .Where(e => EF.Property<Guid>(e, "TenantId") == tenantId)
+            .Where(e => !EF.Property<bool>(e, "IsDeleted"))
+            .Where(e => EF.Property<string>(e, "Code").StartsWith(codePrefix))
+            .Select(e => EF.Property<string>(e, "Code"))
+            .OrderByDescending(c => c)
+            .FirstOrDefaultAsync(ct);
+
+        if (maxCode == null) return 1;
+
+        // Extract the last segment (sequential number)
+        var lastSegment = maxCode.Split(_config.Separator[0]).Last();
+        return int.TryParse(lastSegment, out var seq) ? seq + 1 : 1;
+    }
+
+    private static bool IsUniqueConstraintViolation(DbUpdateException ex)
+    {
+        var message = ex.InnerException?.Message ?? "";
+        return message.Contains("UNIQUE", StringComparison.OrdinalIgnoreCase)
+            || message.Contains("duplicate", StringComparison.OrdinalIgnoreCase)
+            || message.Contains("IX_", StringComparison.OrdinalIgnoreCase)
+            || message.Contains("Cannot insert duplicate key", StringComparison.OrdinalIgnoreCase);
+    }
+}
+```
+
+---
+
+## DI Registration Pattern
+
+In `DependencyInjection.cs` (Infrastructure layer):
+
+```csharp
+// One registration per entity with auto-generated code
+services.AddScoped<ICodeGenerator<Employee>>(sp =>
+    new CodeGenerator<Employee>(
+        sp.GetRequiredService<IExtensionsDbContext>(),
+        sp.GetRequiredService<ICurrentTenantService>(),
+        new CodePatternConfig(
+            Strategy: CodeStrategy.Sequential,
+            Prefix: "emp",
+            IncludeTenantSlug: true,
+            Separator: "-",
+            EstimatedVolume: 1000,
+            Digits: 5),
+        sp.GetRequiredService<ILogger<CodeGenerator<Employee>>>()));
+```
+
+---
+
+## Service Integration Pattern
+
+When `codePattern.strategy != "manual"`, the service's `CreateAsync` method uses `ICodeGenerator<T>`:
+
+```csharp
+public class EmployeeService : IEmployeeService
+{
+    private readonly IExtensionsDbContext _db;
+    private readonly ICurrentTenantService _currentTenant;
+    private readonly ICodeGenerator<Employee> _codeGenerator;
+
+    public EmployeeService(
+        IExtensionsDbContext db,
+        ICurrentTenantService currentTenant,
+        ICodeGenerator<Employee> codeGenerator)
+    {
+        _db = db;
+        _currentTenant = currentTenant;
+        _codeGenerator = codeGenerator;
+    }
+
+    public async Task<EmployeeResponseDto> CreateAsync(
+        CreateEmployeeDto dto, CancellationToken ct = default)
+    {
+        var tenantId = _currentTenant.TenantId
+            ?? throw new UnauthorizedAccessException("Tenant context is required");
+
+        // Auto-generate code (NOT from DTO)
+        var code = await _codeGenerator.NextCodeAsync(ct);
+
+        var entity = Employee.Create(
+            tenantId: tenantId,
+            code: code,
+            name: dto.Name,
+            createdBy: null);
+
+        _db.Employees.Add(entity);
+        await _db.SaveChangesAsync(ct);
+
+        return MapToDto(entity);
+    }
+}
+```
+
+---
+
+## CreateDto Changes (when auto-generated)
+
+When `codePattern.strategy != "manual"`:
+- **REMOVE** `Code` from `CreateDto` (auto-generated, not user-provided)
+- **KEEP** `Code` in `ResponseDto` (returned to user after creation)
+- **KEEP** `Code` in `UpdateDto` ONLY if code is mutable (rare)
+
+```csharp
+// CreateDto when strategy != manual — NO Code property
+public record CreateEmployeeDto
+{
+    [Required]
+    public string Name { get; init; } = string.Empty;
+    // Code is auto-generated by ICodeGenerator — not in CreateDto
+}
+
+// ResponseDto — ALWAYS includes Code
+public record EmployeeResponseDto
+{
+    public Guid Id { get; init; }
+    public string Code { get; init; } = string.Empty;
+    public string Name { get; init; } = string.Empty;
+}
+```
+
+---
+
+## Anti-Pattern: Count() + 1 (Race Condition)
+
+```csharp
+// WRONG — concurrent requests generate duplicate codes
+var count = await _db.Employees
+    .Where(e => e.TenantId == tenantId)
+    .CountAsync(ct);
+return $"emp-{(count + 1):D5}";
+
+// CORRECT — use ICodeGenerator with retry on unique constraint violation
+var code = await _codeGenerator.NextCodeAsync(ct);
+```
+
+**Why it's wrong:** `Count() + 1` causes **race conditions** — two concurrent requests get the same count and generate duplicate codes. The `ICodeGenerator` approach uses `OrderByDescending` on existing codes + retry on unique constraint violation for safe concurrency.
+
+---
+
+## Validator Regex Update
+
+All entity validators MUST use the updated regex:
+
+```csharp
+// OLD (FORBIDDEN): ^[a-z0-9_]+$
+// NEW (REQUIRED): ^[a-z0-9_-]+$
+RuleFor(x => x.Code)
+    .NotEmpty()
+    .MaximumLength(100)
+    .Matches("^[a-z0-9_-]+$")
+    .WithMessage("Code must be lowercase alphanumeric with underscores and hyphens");
+```
+
+> **Note:** When `codePattern.strategy != "manual"`, the Code field is NOT in CreateDto, so the CreateValidator does NOT have a Code rule. The UpdateValidator still has it if Code is mutable.
+
+---
+
+## Edge Cases
+
+1. **Concurrency:** The retry mechanism (3 attempts) handles typical SmartStack workloads (< 10 concurrent creates/second/tenant). For extreme volumes, consider DB sequences.
+2. **Tenant slug null:** Falls back to `"default"` — should only happen in test/seed scenarios.
+3. **Midnight/minute boundary:** For `timestamp-daily` and `timestamp-minute`, the sequence resets naturally within each time period. Two requests straddling midnight get different date prefixes.
+4. **Backward compatibility:** Existing entities without `codePattern` are treated as `strategy: "manual"` (current behavior preserved).