dflow-sdd-ddd 0.7.0 → 0.8.0

package/templates/greenfield/references/ddd-modeling-guide.md

@@ -0,0 +1,351 @@
+# DDD Modeling Guide
+
+When a developer asks "How should I model X?" or is designing domain structures,
+use this guide to walk them through DDD tactical patterns.
+
+## The Modeling Conversation
+
+Start with the business, not the code:
+
+```
+"Let's forget about databases and classes for a moment.
+Tell me: what are the rules? What must always be true?
+What can never happen?"
+```
+
+These invariants drive the entire model design.
+
+## Pattern Selection Flowchart
+
+```
+Is it identified by an ID that persists over time?
+    │
+    ├─ Yes → Is it the "boss" that protects a consistency boundary?
+    │   ├─ Yes → AGGREGATE ROOT
+    │   └─ No  → ENTITY (belongs inside an Aggregate)
+    │
+    └─ No → Is it defined entirely by its properties?
+        ├─ Yes → VALUE OBJECT
+        └─ No  → Does it represent an operation spanning multiple Aggregates?
+            ├─ Yes → DOMAIN SERVICE
+            └─ No  → Re-examine — it's probably one of the above
+```
+
+## Aggregate Design
+
+Aggregates are the most important and most commonly misunderstood DDD concept.
+
+### What is an Aggregate?
+
+A cluster of objects treated as a single unit for data changes. The Aggregate Root
+is the only entry point — outside code cannot reach inside and modify child entities
+or value objects directly.
+
+### Aggregate Design Rules
+
+1. **Protect invariants** — The Aggregate exists to enforce business rules that span
+   multiple objects within it.
+
+2. **One Aggregate per transaction** — A single operation should modify only ONE
+   Aggregate. If you need to modify two Aggregates, use Domain Events for eventual
+   consistency.
+
+3. **Reference other Aggregates by ID only** — Never hold a direct object reference
+   to another Aggregate. Store its ID instead.
+
+4. **Keep them small** — Large Aggregates cause concurrency issues. If two users can
+   independently modify different parts, those parts should probably be separate Aggregates.
+
+### Example: Expense Report Aggregate
+
+```csharp
+// ExpenseReport is the Aggregate Root
+public class ExpenseReport : AggregateRoot
+{
+    private readonly List<ExpenseLineItem> _lineItems = new();
+
+    public EmployeeId SubmittedBy { get; private set; }   // Reference by ID
+    public ReportPeriod Period { get; private set; }       // Value Object
+    public Money TotalAmount => CalculateTotal();          // Derived
+    public ReportStatus Status { get; private set; }       // Value Object (enum-like)
+
+    // State change through explicit methods — not property setters
+    public void AddLineItem(string description, Money amount, ExpenseCategory category)
+    {
+        // Enforce invariants
+        if (Status != ReportStatus.Draft)
+            throw new DomainException("Cannot add items to a submitted report.");
+
+        if (_lineItems.Count >= 50)
+            throw new DomainException("Maximum 50 line items per report.");
+
+        var lineItem = new ExpenseLineItem(description, amount, category);
+        _lineItems.Add(lineItem);
+
+        // Raise domain event
+        AddDomainEvent(new LineItemAddedEvent(Id, lineItem.Id, amount));
+    }
+
+    public void Submit()
+    {
+        if (Status != ReportStatus.Draft)
+            throw new DomainException("Only draft reports can be submitted.");
+
+        if (!_lineItems.Any())
+            throw new DomainException("Cannot submit an empty report.");
+
+        Status = ReportStatus.Submitted;
+        AddDomainEvent(new ExpenseReportSubmittedEvent(Id, SubmittedBy, TotalAmount));
+    }
+}
+```
+
+### Design Questions to Ask
+
+When designing a new Aggregate:
+
+1. **What are the invariants?** What business rules must ALWAYS be true?
+2. **What's the consistency boundary?** What must be updated atomically?
+3. **What can change independently?** Separate Aggregates for separate concerns.
+4. **Who modifies this?** How many concurrent users? (Affects Aggregate size)
+5. **What events does this produce?** What other parts of the system need to know?
+
+### Set-Based / Uniqueness Invariants
+
+Some invariants are not about one Aggregate but about a **set selected by a
+business key or status**: "email (normalized) is unique across all Users", "each
+seat holds at most one active booking", "each connector has at most one
+in-progress charging session". A single Aggregate instance cannot see the rest of
+that set, so it cannot enforce the rule on its own.
+
+Handle them the same way **regardless of which Aggregate boundary you choose**:
+
+1. **As separate Aggregates** (e.g. `User` and `Booking` are distinct): the
+   Application layer *orchestrates* the check — via a repository query, a
+   Specification, or a domain service (the rule stays domain-named; it is not an
+   inline `if-else` in the command handler) — and the **database enforces it with
+   a unique / partial (filtered) unique index**. The DB constraint is the real
+   guarantee under concurrency; the orchestrated check just returns a friendlier
+   error first.
+
+2. **Folded into one Aggregate** (e.g. the active session lives *inside* a
+   `Connector` as a child entity): the in-memory check (`if (Status == InUse)
+   throw …`) is logically correct, **but is still not concurrency-safe by
+   itself**. Two concurrent commands can each load the Aggregate, both pass the
+   check, and both save. Close the race with **optimistic concurrency** (a
+   `rowversion` / version token on the Aggregate root) or a DB constraint — but
+   the version check only protects you if every save actually touches the root's
+   token: inserting a child row without bumping the root's version leaves the
+   race open. Translate the resulting concurrency exception / unique violation
+   into a meaningful business conflict (e.g. HTTP 409), not a generic 500.
+
+**Key point:** an in-memory check — at *any* layer — is never the final guarantee
+for a uniqueness / "only one active X" rule under concurrent requests. The durable
+enforcement is a DB unique / filtered index, an optimistic-concurrency token, or
+an equivalent conditional write / compare-and-swap. Pick the Aggregate boundary on
+modeling grounds (does the inner thing have an independent lifecycle / history
+worth querying?), then add the store-level guard either way. (Heavier
+serialization tactics — distributed locks, per-key actors, aggregate-per-key
+sharding — exist but are advanced; reach for a store-level constraint or version
+check first.)
+
+## Value Objects
+
+### When to Use Value Objects
+
+If the answer to ALL of these is "yes", it's a Value Object:
+- Is it defined by its properties, not by an ID?
+- Is it immutable once created?
+- Can two instances with the same properties be considered equal?
+
+### Common Value Objects
+
+```csharp
+// Money — the classic example
+public record Money(decimal Amount, Currency Currency)
+{
+    public static Money Zero(Currency currency) => new(0, currency);
+
+    public Money Add(Money other)
+    {
+        if (Currency != other.Currency)
+            throw new CurrencyMismatchException(Currency, other.Currency);
+        return new Money(Amount + other.Amount, Currency);
+    }
+
+    public Money ConvertTo(Currency target, ExchangeRate rate)
+    {
+        return new Money(rate.Convert(Amount), target);
+    }
+}
+
+// DateRange
+public record DateRange(DateOnly Start, DateOnly End)
+{
+    public DateRange
+    {
+        if (Start > End) throw new DomainException("Start must be before End.");
+    }
+
+    public bool Contains(DateOnly date) => date >= Start && date <= End;
+    public int Days => End.DayNumber - Start.DayNumber + 1;
+}
+
+// Currency (constrained string)
+public record Currency
+{
+    public string Code { get; }
+    public int DecimalPlaces { get; }
+
+    public static readonly Currency TWD = new("TWD", 0);
+    public static readonly Currency USD = new("USD", 2);
+    public static readonly Currency JPY = new("JPY", 0);
+
+    private Currency(string code, int decimalPlaces)
+    {
+        Code = code;
+        DecimalPlaces = decimalPlaces;
+    }
+
+    public decimal Round(decimal amount) =>
+        Math.Round(amount, DecimalPlaces, MidpointRounding.AwayFromZero);
+}
+```
+
+### Value Object Design Questions
+
+1. **Does it have behavior?** Good VOs have methods, not just properties.
+2. **Does it enforce constraints?** Constructor should reject invalid states.
+3. **Is it reusable?** `Money` can be used across many Aggregates.
+
+## Domain Events
+
+### What Are Domain Events?
+
+Something that happened in the domain that other parts of the system care about.
+Past tense naming: `ExpenseReportSubmitted`, `LineItemAdded`, `ReportApproved`.
+
+### When to Use Domain Events
+
+- When one Aggregate needs to trigger changes in another Aggregate
+- When side effects (email, notification, audit log) should happen after a domain action
+- When different Bounded Contexts need to communicate
+
+### Event Design
+
+```csharp
+public record ExpenseReportSubmittedEvent(
+    ExpenseReportId ReportId,
+    EmployeeId SubmittedBy,
+    Money TotalAmount
+) : IDomainEvent;
+```
+
+### Event Flow
+
+```
+1. Aggregate method called → state changes → event added to DomainEvents list
+2. Repository saves Aggregate
+3. After save (in same transaction or via outbox):
+   - In-process handlers: update read models, trigger other commands
+   - Cross-context: publish to message queue
+```
+
+### Event Handling Guidelines
+
+- **Same Bounded Context**: Handle synchronously (same transaction OK for read models)
+- **Cross Bounded Context**: Handle asynchronously (eventual consistency)
+- Event handlers should be idempotent (safe to process multiple times)
+- **Dispatch / clear lifecycle**: clear `DomainEvents` at the Repository / Unit
+  of Work **save boundary** — the UoW clears them *after* the save succeeds and
+  the events have been dispatched (or the outbox row persisted, or dispatch
+  explicitly decided to be dropped/deferred). Never clear inside an Aggregate
+  method, and never before the save succeeds. A simple in-process dispatcher
+  (e.g. `IPublisher` / MediatR) is enough for Phase 1; an **outbox /
+  integration-event bridge is the Phase 2+ upgrade** for reliable cross-service
+  delivery. If no dispatcher is wired yet, record it as deferred tech debt — but
+  still clear on a successful save so events cannot accumulate unbounded.
+
+## Specifications
+
+For complex query logic that belongs to the domain:
+
+```csharp
+public class PendingApprovalSpec : Specification<ExpenseReport>
+{
+    private readonly EmployeeId _approverId;
+
+    public PendingApprovalSpec(EmployeeId approverId)
+    {
+        _approverId = approverId;
+    }
+
+    public override Expression<Func<ExpenseReport, bool>> ToExpression()
+    {
+        return report =>
+            report.Status == ReportStatus.Submitted &&
+            report.ApproverId == _approverId;
+    }
+}
+```
+
+## Domain Services
+
+Use Domain Services for operations that:
+- Involve multiple Aggregates (read-only access to the second Aggregate)
+- Require external information (through interfaces) to make domain decisions
+- Don't naturally belong to any single Entity
+
+```csharp
+// Domain Service — in Domain layer
+public class ExpenseApprovalService
+{
+    private readonly IApprovalPolicyRepository _policyRepo;
+
+    public ApprovalResult Evaluate(ExpenseReport report, ApprovalPolicy policy)
+    {
+        if (report.TotalAmount.Amount > policy.AutoApprovalLimit)
+            return ApprovalResult.RequiresManagerApproval;
+
+        if (policy.RestrictedCategories.Overlaps(report.Categories))
+            return ApprovalResult.RequiresComplianceReview;
+
+        return ApprovalResult.AutoApproved;
+    }
+}
+```
+
+## Bounded Context Relationships
+
+If `dflow/specs/domain/context-map.md` does not exist yet, create it from `templates/context-map.md` before documenting relationships.
+
+Document in `dflow/specs/domain/context-map.md`:
+
+| Relationship | Pattern | Example |
+|---|---|---|
+| Context A calls Context B | Customer-Supplier | Expense → HR (get employee info) |
+| Contexts share data | Shared Kernel | Currency, Money in SharedKernel/ |
+| Context A translates B's language | Anti-Corruption Layer | Expense → External Accounting System |
+| Fire and forget | Domain Events | Expense → Notification (report submitted) |
+
+## Common Mistakes to Catch
+
+1. **Anemic Domain Model** — Entities with only getters/setters, all logic in services
+   → Move behavior INTO the Entity/Aggregate
+
+2. **Too-large Aggregates** — Aggregate that loads entire object graph
+   → Split into smaller Aggregates, reference by ID
+
+3. **Business logic in Application layer** — If-else rules in command handlers
+   → Move to Domain (Entity methods or Domain Services)
+
+4. **Business logic in Infrastructure** — Rules in SQL queries or EF configurations
+   → Domain defines WHAT, Infrastructure defines HOW
+
+5. **Direct cross-Aggregate modification** — One command modifying two Aggregates
+   → Use Domain Events for the second Aggregate
+
+6. **Set-based invariant guarded only in memory** — A "unique" / "only one active"
+   rule enforced solely by an in-app check, with no DB unique constraint or
+   optimistic-concurrency token → two concurrent requests can both pass and break it
+   → Back it with a DB constraint / `rowversion`; see "Set-Based / Uniqueness Invariants"

package/templates/greenfield/references/dflow-feedback-flow.md

@@ -0,0 +1,179 @@
+# Dflow Feedback Draft Flow
+
+`/dflow:report-dflow-feedback` helps the developer turn a Dflow problem or
+improvement observed during real project work into a high-quality upstream
+feedback draft.
+
+This flow is **not** a project feature workflow and does not change the
+application being built. It is a standalone governance/support flow for Dflow
+itself.
+
+## Hard Boundaries
+
+- Do not submit anything to GitHub automatically.
+- Do not run `gh issue create`, `gh pr create`, `git push`, or any networked
+  submission command from this flow.
+- Do not expose private project details, business rules, customer data,
+  secrets, tokens, internal URLs, or proprietary source snippets.
+- Always show the draft to the developer before anything leaves the local
+  machine.
+- If the developer later asks to submit through GitHub CLI, stop and treat that
+  as a separate explicit task with fresh permission and environment checks.
+
+## Trigger Conditions
+
+Enter this flow when:
+
+- The developer explicitly runs `/dflow:report-dflow-feedback`.
+- The developer says the Dflow process, template, generated file, or docs seem
+  wrong or improvable.
+- The AI notices a clear contradiction or gap in Dflow guidance and asks:
+  "This looks like a possible Dflow upstream issue. Should I draft feedback for
+  you to review?"
+
+Do not interrupt normal development for minor preference differences. If the
+observation is speculative, ask before drafting.
+
+## Output Location
+
+Write the draft to:
+
+```text
+dflow/feedback/dflow-feedback-YYYY-MM-DD-{slug}.md
+```
+
+Create `dflow/feedback/` if it does not exist. The file is local project
+working material; the developer decides whether to copy it into a GitHub issue,
+turn it into a PR, or discard it.
+
+## Step 1: Classify the Feedback
+
+Classify the feedback as one of:
+
+- Bug report
+- Workflow change request
+- Documentation feedback
+- Question / unclear usage
+- Maintainer release/process feedback
+
+Capture:
+
+- Observed during which flow or command
+- Affected Dflow track: Greenfield, Brownfield, both, or unknown
+- Affected area: CLI, generated template, scaffolding, skill reference,
+  tutorial, README/docs, release/governance
+- Whether the issue blocks current project work
+
+## Step 2: Capture Evidence Safely
+
+Collect only the evidence needed to explain the Dflow issue.
+
+Allowed evidence:
+
+- Dflow command name
+- Dflow version if known
+- Template or reference file name
+- Generic project type, such as "existing legacy presentation-framework app"
+- Minimal paraphrased symptom
+- Short sanitized snippets from Dflow-owned files
+
+Avoid:
+
+- Internal business rules
+- Customer or tenant names
+- Private repository names or URLs
+- Secrets, tokens, credentials, or auth headers
+- Long proprietary code snippets
+- Full logs containing private paths or environment data
+
+## Step 3: Redaction Pass
+
+Before writing the issue body section, perform a redaction check and include it
+in the draft:
+
+```markdown
+## Redaction Checklist
+
+- [ ] No secrets, tokens, credentials, or auth headers
+- [ ] No customer, tenant, or private organization names
+- [ ] No proprietary business rules beyond sanitized paraphrase
+- [ ] No private repository URLs or internal hostnames
+- [ ] No long proprietary source snippets
+- [ ] Developer reviewed before submission
+```
+
+Leave the final "Developer reviewed before submission" unchecked unless the
+developer explicitly confirms it.
+
+## Step 4: Write the Feedback Draft
+
+Use this structure:
+
+```markdown
+# Dflow Feedback Draft: {short-title}
+
+## Summary
+
+{One or two sentences.}
+
+## Type
+
+{Bug report | Workflow change request | Documentation feedback | Question | Maintainer process feedback}
+
+## Observed While Using
+
+- Dflow version: {version-or-unknown}
+- Command / flow: {command-or-flow}
+- Track: {Greenfield | Brownfield | both | unknown}
+- Project context: {sanitized generic context}
+
+## Affected Dflow Area
+
+- {CLI | template | scaffolding | skill reference | tutorial | docs | governance}
+- Files or concepts: {sanitized list}
+
+## Problem
+
+{What happened, why it is confusing or harmful, and who is affected.}
+
+## Expected Behavior or Improvement
+
+{What Dflow should do or explain instead.}
+
+## Evidence
+
+{Minimal sanitized observations.}
+
+## Compatibility / Breaking-Change Risk
+
+{None | low | medium | high}, with reasoning.
+
+## Suggested GitHub Issue Body
+
+{Copy-ready issue body matching the closest issue template.}
+
+## Optional PR Plan
+
+{Only include if the change is small and concrete. Otherwise write "Not recommended yet; start with an issue."}
+
+## Redaction Checklist
+
+- [ ] No secrets, tokens, credentials, or auth headers
+- [ ] No customer, tenant, or private organization names
+- [ ] No proprietary business rules beyond sanitized paraphrase
+- [ ] No private repository URLs or internal hostnames
+- [ ] No long proprietary source snippets
+- [ ] Developer reviewed before submission
+```
+
+## Step 5: Present Submission Options
+
+After writing the draft, summarize the options:
+
+- Copy the suggested issue body manually into GitHub.
+- Use the optional PR plan as implementation guidance in a Dflow source
+  checkout.
+- Discard the draft if it was only a local observation.
+
+Do not submit anything automatically. End by naming the draft file path and
+whether any redaction checklist items remain unchecked.