@drunkcoding/dknet-implementation-skills 0.1.0

package/skills/dknet-docs/templates/architecture-template.md

@@ -0,0 +1,166 @@
+# {FeatureName} — Architecture
+
+## Vertical Slice Overview
+
+This feature follows the DKNet vertical slice architecture.
+Each layer has a single, focused responsibility for this feature.
+
+```mermaid
+graph TD
+    Client["Client / Browser"]
+
+    subgraph API["Minimal.Api"]
+        EP["{EntityName}V1Endpoint\n(IEndpointConfig)"]
+    end
+
+    subgraph AppServices["Minimal.AppServices"]
+        REQ["Request Types\n(Create / Update / Delete\n+ custom actions)"]
+        VAL["Validators\n(FluentValidation)"]
+        HDL["Command Handlers\n(IHandler)"]
+        SPEC["Query Specs\n(Ardalis.Specification)"]
+        EVT["Domain Events\n({EntityName}CreatedEvent etc.)"]
+    end
+
+    subgraph Domains["Minimal.Domains"]
+        ENT["{EntityName}\n(AggregateRoot)"]
+    end
+
+    subgraph Infra["Minimal.Infra"]
+        MAP["{EntityName}Mapper.cs\n(EF Core Config)"]
+        REPO["IRepositorySpec\n(EF Core + Spec)"]
+        EVH["Event Handlers\n(Azure Bus / In-Memory)"]
+    end
+
+    DB[("SQL Server")]
+
+    Client -->|HTTP| EP
+    EP -->|Message Bus| REQ
+    REQ --> VAL
+    VAL --> HDL
+    HDL -->|Query via Spec| SPEC
+    SPEC -->|Reads| REPO
+    HDL -->|Mutations| REPO
+    HDL -->|Publish| EVT
+    REPO --> MAP
+    MAP --> DB
+    EVT --> EVH
+```
+
+## Create {EntityName} — Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant C as Client
+    participant EP as {EntityName}Endpoints
+    participant BUS as MessageBus
+    participant VAL as Validator
+    participant HDL as Create{EntityName}Handler
+    participant SPEC as Spec{EntityName}GetByEmail
+    participant REPO as IRepositorySpec
+    participant EVT as EventPublisher
+
+    C->>EP: POST /api/v1/{feature-route}
+    EP->>BUS: bus.Send(Create{EntityName}Request)
+    BUS->>VAL: Validate request
+    VAL-->>BUS: Valid ✓
+
+    BUS->>HDL: Handle(request)
+    HDL->>SPEC: new Spec{EntityName}GetByEmail(email)
+    HDL->>REPO: FirstOrDefaultAsync(spec)
+    REPO-->>HDL: null (no duplicate)
+
+    HDL->>HDL: new {EntityName}(...)
+    HDL->>REPO: AddAsync(entity)
+    HDL->>REPO: SaveChangesAsync()
+    REPO-->>HDL: OK
+
+    HDL->>EVT: PublishAsync({EntityName}CreatedEvent)
+    EVT-->>HDL: OK
+
+    HDL-->>BUS: Result<{EntityName}Dto>.Success(dto)
+    BUS-->>EP: {EntityName}Dto
+    EP-->>C: 201 Created + {EntityName}Dto
+```
+
+## Component Diagram
+
+```mermaid
+classDiagram
+    class {EntityName}V1Endpoint {
+        +int Version = 1
+        +string GroupEndpoint = "/{feature-route}"
+        +Map(RouteGroupBuilder group)
+    }
+
+    class Create{EntityName}Request {
+        +string Field1
+        +string Field2
+    }
+
+    class Create{EntityName}CommandHandler {
+        -IMapper _mapper
+        -IRepositorySpec _repo
+        -IEventPublisher _eventPublisher
+        +Handle(request) Result~{EntityName}Dto~
+    }
+
+    class {EntityName} {
+        +Guid Id
+        +string Field1
+        +string Field2
+        +string Status
+        +Approve(reason)
+        +Reject(reason)
+        +Update(...)
+    }
+
+    class {EntityName}Mapper {
+        +Configure(EntityTypeBuilder)
+    }
+
+    {EntityName}V1Endpoint ..> Create{EntityName}Request : maps request
+    Create{EntityName}CommandHandler --> {EntityName} : creates
+    Create{EntityName}CommandHandler --> IRepositorySpec : uses
+    {EntityName}Mapper --> {EntityName} : configures
+```
+
+## Status State Machine
+
+> Remove this section if the entity has no status/approval workflow.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Pending : {EntityName} Created
+
+    Pending --> Approved : approve() action
+    Pending --> Rejected : reject() action
+
+    Approved --> [*] : (soft-deleted)
+    Rejected --> [*] : (soft-deleted)
+
+    note right of Pending : Default status on creation
+    note right of Approved : Entity available for downstream use
+    note right of Rejected : Reason stored for audit trail
+```
+
+## Event Flow
+
+```mermaid
+graph LR
+    HDL["Create{EntityName}Handler"] -->|Publish| EVT["{EntityName}CreatedEvent"]
+
+    EVT --> MEM["In-Memory Bus Handler"]
+    EVT --> AZ["Azure Service Bus Handler\n(if AzureBus configured)"]
+
+    MEM -->|Side effects| LOG["Audit Log / Internal"]
+    AZ -->|Message to subscribers| EXT["External Systems\n(Notifications, Billing, etc.)"]
+```
+
+## Layer Responsibilities
+
+| Layer | Responsibility in this feature |
+|-------|-------------------------------|
+| `Minimal.Api` | Route mapping only; zero business logic |
+| `Minimal.AppServices` | Command handling, validation, event publishing |
+| `Minimal.Domains` | Entity state, domain rules, invariants |
+| `Minimal.Infra` | Persistence, EF Core config, message bus setup |

package/skills/dknet-docs/templates/data-model-template.md

@@ -0,0 +1,99 @@
+# {FeatureName} — Data Model
+
+## Entity Relationship Diagram
+
+```mermaid
+erDiagram
+    {ENTITY_TABLE_NAME} {
+        uniqueidentifier Id PK "Auto-generated GUID"
+        nvarchar(150)   Field1 "Not null"
+        nvarchar(256)   Field2 UK "Unique, not null"
+        nvarchar(50)    Field3 "Nullable"
+        nvarchar(50)    Status "Enum: Pending / Approved / Rejected"
+        bit             IsDeleted "Soft delete flag; default false"
+        nvarchar(450)   CreatedBy FK "Linked to user"
+        datetime2       CreatedAt "UTC, auto-set on insert"
+        nvarchar(450)   UpdatedBy "Nullable"
+        datetime2       UpdatedAt "UTC, auto-updated"
+    }
+
+    RELATED_TABLE {
+        uniqueidentifier Id PK
+        uniqueidentifier {EntityName}Id FK
+        nvarchar(100)   SomeField
+    }
+
+    {ENTITY_TABLE_NAME} ||--o{ RELATED_TABLE : "has many"
+```
+
+> Remove the `RELATED_TABLE` block if there are no related entities.  
+> Add `UK` (unique key) annotation to columns with unique indexes.
+
+---
+
+## Properties
+
+| Property | C# Type | DB Column | Constraints |
+|----------|---------|-----------|-------------|
+| `Id` | `Guid` | `Id` (PK) | Not null, auto-generated |
+| `Field1` | `string` | `Field1` | Not null, max {N} chars |
+| `Field2` | `string` | `Field2` | Not null, max {N} chars, unique index |
+| `Field3` | `string?` | `Field3` | Nullable, max {N} chars |
+| `Status` | `string` | `Status` | Not null, max 50 chars |
+| `IsDeleted` | `bool` | `IsDeleted` | Default: `false` |
+| `CreatedBy` | `string` | `CreatedBy` | Not null (from the request's `[FromClaim(ClaimTypes.Name)]` `ByUser`) |
+| `CreatedAt` | `DateTime` | `CreatedAt` | UTC, auto-set on insert |
+| `UpdatedBy` | `string?` | `UpdatedBy` | Nullable |
+| `UpdatedAt` | `DateTime?` | `UpdatedAt` | UTC, auto-updated |
+
+---
+
+## EF Core Mapping Configuration
+
+Source: `ApiEndpoints/Minimal.Infra/Features/{EntityFolder}/Mappers/{EntityName}Mapper.cs`
+
+Key mapping decisions:
+
+| Configuration | Value | Reason |
+|--------------|-------|--------|
+| Table name | `{EntityTableName}` (schema: `dbo`) | Convention |
+| Unique index | `{Field2}` | Business uniqueness constraint |
+| Unique index | `{Field1}` (if applicable) | {Reason} |
+| Global query filter | `IsDeleted == false` | Automatically excludes soft-deleted records from all queries |
+| Column type | `datetime2(7)` for `UpdatedAt` | Sub-second precision for audit trail |
+| Column precision | `nvarchar({N})` for `Field1` | Max length constraint from business rules |
+
+---
+
+## Validation Rules
+
+| Field | Rule | Enforcement |
+|-------|------|-------------|
+| `Field2` (e.g., Email) | Must be unique per entity | DB unique index + FluentValidation Spec check before insert |
+| `Field1` (e.g., Name) | 2–{N} characters | FluentValidation in `Create{EntityName}RequestValidator` |
+| `Field3` (e.g., Phone) | Valid phone format if provided | FluentValidation with `.When()` conditional |
+| `Status` | Valid transition only (`Pending → Approved/Rejected`) | Domain entity method enforces valid transitions |
+| Soft delete | `IsDeleted` flag | EF Core Global Query Filter excludes deleted from all queries |
+
+---
+
+## Status Values
+
+> Remove this section if the entity has no status field.
+
+| Value | Meaning | Transitions to |
+|-------|---------|----------------|
+| `Pending` | Default on create; awaiting review | `Approved`, `Rejected` |
+| `Approved` | Passed review; active | N/A (terminal for workflow) |
+| `Rejected` | Failed review; inactive | N/A (terminal for workflow) |
+
+---
+
+## Migration History
+
+| Migration Name | Description |
+|----------------|-------------|
+| `Initial_{EntityName}` | Create initial `{EntityTableName}` table |
+| `Add_{Field}_To_{EntityName}` | {Reason for the change} |
+
+> Keep this table updated when running `dotnet ef migrations add <Name> -c CoreDbContext -p Minimal.Infra/Minimal.Infra.csproj`.

package/skills/dknet-docs/templates/events-template.md

@@ -0,0 +1,155 @@
+# {FeatureName} — Domain Events
+
+## Events Published
+
+### {EntityName}CreatedEvent
+
+Raised immediately after a new {entityName} is successfully created and persisted.
+
+**Published by**: `Create{EntityName}CommandHandler`
+
+**Payload**
+
+```csharp
+public sealed record {EntityName}CreatedEvent(Guid Id, string {KeyField});
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Id` | `Guid` | The newly created {entityName}'s ID |
+| `{KeyField}` | `string` | {Key identifying property, e.g., Name or Email} |
+
+**Current Subscribers**
+
+| Handler Class | Bus Type | Action |
+|--------------|----------|--------|
+| `{EntityName}CreatedFromMemoryHandler` | In-Memory | Internal audit / testing |
+| _{Add external handlers as they are added}_ | Azure Service Bus | External notifications |
+
+**Code Example** — How to subscribe:
+
+```csharp
+internal sealed class SendWelcomeNotificationHandler :
+    Fluents.EventsConsumers.IHandler<{EntityName}CreatedEvent>
+{
+    public Task OnHandle(
+        {EntityName}CreatedEvent notification,
+        CancellationToken cancellationToken)
+    {
+        // TODO: implement side-effect logic
+        return Task.CompletedTask;
+    }
+}
+```
+
+---
+
+### {EntityName}StatusChangedEvent
+
+> Add this section if status changes (approve/reject) publish events.
+
+Raised when a {entityName}'s status changes (e.g., Approved or Rejected).
+
+**Published by**: `Approve{EntityName}CommandHandler`, `Reject{EntityName}CommandHandler`
+
+**Payload**
+
+```csharp
+public sealed record {EntityName}StatusChangedEvent(
+    Guid Id,
+    string OldStatus,
+    string NewStatus,
+    string? Reason);
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Id` | `Guid` | The {entityName}'s ID |
+| `OldStatus` | `string` | Status before change |
+| `NewStatus` | `string` | Status after change |
+| `Reason` | `string?` | Reason provided (e.g., rejection reason) |
+
+**Current Subscribers**
+
+| Handler Class | Bus Type | Action |
+|--------------|----------|--------|
+| _{None yet — add as needed}_ | — | — |
+
+---
+
+### {EntityName}DeletedEvent
+
+> Add this section only if deletion publishes an event.
+
+Raised when a {entityName} is soft-deleted.
+
+**Published by**: `Delete{EntityName}CommandHandler`
+
+**Payload**
+
+```csharp
+public sealed record {EntityName}DeletedEvent(Guid Id, string DeletedBy);
+```
+
+---
+
+## Events Consumed
+
+> List any events from OTHER features that this feature subscribes to.
+> If none, keep the statement below.
+
+This feature does not currently consume events from other features.
+
+---
+
+## Event Bus Configuration
+
+Events are dispatched via the Minimal message bus with two bus types:
+
+| Bus Type | When Active | Purpose |
+|----------|-------------|---------|
+| **In-Memory** | Always (all environments) | Same-process handlers; local side effects |
+| **Azure Service Bus** | When `ConnectionStrings:AzureBus` is non-empty | Cross-service/process messaging |
+
+See `ApiEndpoints/Minimal.Infra/Extensions/ServiceBusSetup.cs` for wiring configuration.
+
+```mermaid
+graph LR
+    HDL["Create{EntityName}Handler"]
+    EVT["{EntityName}CreatedEvent"]
+    MEM["In-Memory Bus"]
+    AZ["Azure Service Bus\n(if configured)"]
+    INTL["Internal Handlers\n(same process)"]
+    EXT["External Systems\n(notifications, billing...)"]
+
+    HDL -->|PublishAsync| EVT
+    EVT --> MEM
+    EVT --> AZ
+    MEM --> INTL
+    AZ --> EXT
+```
+
+---
+
+## Adding a New Event Subscriber
+
+To subscribe to an event from this feature:
+
+1. Create a handler class in the consuming feature's AppServices project
+2. Implement `Fluents.EventsConsumers.IHandler<TEvent>`
+3. The message bus auto-discovers handlers via assembly scan — no manual registration needed
+
+```csharp
+// In the consuming feature's AppServices project:
+internal sealed class On{EntityName}CreatedHandler :
+    Fluents.EventsConsumers.IHandler<{EntityName}CreatedEvent>
+{
+    public Task OnHandle(
+        {EntityName}CreatedEvent notification,
+        CancellationToken cancellationToken)
+    {
+        // React to the event
+        return Task.CompletedTask;
+    }
+}
+```