phase7: command pattern infrastructure (CommandHandler, UnitOfWork, RequestContext) + example CreateContactCommand
This commit is contained in:
Agent Zero
@@ -0,0 +1,103 @@
|
||||
"""Example command: CreateContact using the Command Pattern.
|
||||
|
||||
This is a reference implementation for new modules.
|
||||
Existing contact_service.py is NOT changed — this is an alternative path.
|
||||
|
||||
Usage:
|
||||
@router.post("/contacts-v2")
|
||||
async def create_contact_v2(
|
||||
body: CreateContactDTO,
|
||||
db: AsyncSession = Depends(get_db),
|
||||
current_user: dict = Depends(require_permission("contacts:write")),
|
||||
):
|
||||
ctx = RequestContext(
|
||||
user_id=uuid.UUID(current_user["user_id"]),
|
||||
tenant_id=uuid.UUID(current_user["tenant_id"]),
|
||||
is_system_admin=current_user.get("is_system_admin", False),
|
||||
permissions=set(current_user.get("permissions", [])),
|
||||
)
|
||||
cmd = CreateContactCommand(
|
||||
firstname=body.firstname,
|
||||
surname=body.surname,
|
||||
email=body.email,
|
||||
)
|
||||
handler = CreateContactHandler()
|
||||
return await handler.execute(cmd, ctx, db)
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import uuid
|
||||
from dataclasses import dataclass
|
||||
from typing import Any
|
||||
|
||||
from app.core.commands import CommandHandler, RequestContext, UnitOfWork
|
||||
from app.models.contact import Contact
|
||||
|
||||
|
||||
@dataclass
|
||||
class CreateContactCommand:
|
||||
"""Command to create a new contact."""
|
||||
firstname: str
|
||||
surname: str
|
||||
email: str | None = None
|
||||
phone: str | None = None
|
||||
company: str | None = None
|
||||
|
||||
|
||||
class CreateContactHandler(CommandHandler[CreateContactCommand, dict[str, Any]]):
|
||||
"""Handler for CreateContactCommand.
|
||||
|
||||
Demonstrates the Command Pattern:
|
||||
1. Authorization check (ctx.require)
|
||||
2. Domain operation (create Contact)
|
||||
3. Outbox event (crm.contact.created.v1)
|
||||
4. Audit log (contact.created)
|
||||
5. Single commit via UoW
|
||||
"""
|
||||
|
||||
async def handle(self, cmd: CreateContactCommand, ctx: RequestContext, uow: UnitOfWork) -> dict[str, Any]:
|
||||
# 1. Authorization
|
||||
ctx.require("contacts:write")
|
||||
|
||||
# 2. Domain operation
|
||||
contact = Contact(
|
||||
tenant_id=ctx.tenant_id,
|
||||
firstname=cmd.firstname,
|
||||
surname=cmd.surname,
|
||||
email_1=cmd.email,
|
||||
phone_1=cmd.phone,
|
||||
company=cmd.company,
|
||||
owner_id=ctx.user_id,
|
||||
created_by=ctx.user_id,
|
||||
updated_by=ctx.user_id,
|
||||
)
|
||||
uow.add(contact)
|
||||
|
||||
# 3. Outbox event (standardized envelope)
|
||||
uow.outbox_add(
|
||||
event_name="crm.contact.created.v1",
|
||||
aggregate_id=contact.id, # Will be set after flush
|
||||
aggregate_type="contact",
|
||||
payload={
|
||||
"firstname": cmd.firstname,
|
||||
"surname": cmd.surname,
|
||||
"email": cmd.email,
|
||||
},
|
||||
)
|
||||
|
||||
# 4. Audit log
|
||||
uow.audit_record(
|
||||
action="create",
|
||||
entity_id=contact.id,
|
||||
entity_type="contact",
|
||||
changes={"firstname": cmd.firstname, "surname": cmd.surname, "email": cmd.email},
|
||||
)
|
||||
|
||||
# 5. Return dict (will be populated after flush in commit)
|
||||
return {
|
||||
"id": str(contact.id),
|
||||
"firstname": contact.firstname,
|
||||
"surname": contact.surname,
|
||||
"email_1": contact.email_1,
|
||||
}
|
||||
@@ -0,0 +1,203 @@
|
||||
"""Command pattern infrastructure for new modules.
|
||||
|
||||
This provides a clean, transactional command handler pattern:
|
||||
|
||||
HTTP Route → Command Handler → Authorization → Domain Operation → Audit + Outbox → one Commit
|
||||
|
||||
Existing services are NOT refactored — they continue to work as-is.
|
||||
New modules (ERP, etc.) should use this pattern.
|
||||
|
||||
Usage:
|
||||
|
||||
@dataclass
|
||||
class CreateInvoiceCommand:
|
||||
customer_id: uuid.UUID
|
||||
amount: Decimal
|
||||
|
||||
class CreateInvoiceHandler(CommandHandler[CreateInvoiceCommand, Invoice]):
|
||||
async def handle(self, cmd: CreateInvoiceCommand, ctx: RequestContext, uow: UnitOfWork) -> Invoice:
|
||||
ctx.require("invoices:create")
|
||||
invoice = Invoice.create(tenant_id=ctx.tenant_id, owner_id=ctx.user_id, ...)
|
||||
uow.add(invoice)
|
||||
uow.outbox.add("crm.invoice.created.v1", invoice.id, "invoice", invoice.to_dict())
|
||||
uow.audit.record("invoice.created", invoice.id)
|
||||
return invoice
|
||||
|
||||
# In route:
|
||||
@router.post("/invoices")
|
||||
async def create_invoice(body: CreateInvoiceDTO, ctx: RequestContext = Depends(get_request_context)):
|
||||
cmd = CreateInvoiceCommand(customer_id=body.customer_id, amount=body.amount)
|
||||
handler = CreateInvoiceHandler()
|
||||
result = await handler.execute(cmd, ctx)
|
||||
return result
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import uuid
|
||||
from abc import ABC, abstractmethod
|
||||
from dataclasses import dataclass, field
|
||||
from datetime import datetime, timezone
|
||||
from typing import Any, Generic, TypeVar
|
||||
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
|
||||
from app.core.audit import log_audit
|
||||
from app.core.outbox import enqueue_outbox_event
|
||||
|
||||
|
||||
TCommand = TypeVar("TCommand")
|
||||
TResult = TypeVar("TResult")
|
||||
|
||||
|
||||
@dataclass
|
||||
class RequestContext:
|
||||
"""Request context with user, tenant, and permission info.
|
||||
|
||||
Passed to every command handler. Provides authorization checks.
|
||||
"""
|
||||
user_id: uuid.UUID
|
||||
tenant_id: uuid.UUID
|
||||
is_system_admin: bool = False
|
||||
permissions: set[str] = field(default_factory=set)
|
||||
correlation_id: uuid.UUID = field(default_factory=uuid.uuid4)
|
||||
|
||||
def require(self, permission: str) -> None:
|
||||
"""Require a permission. Raises PermissionError if not granted."""
|
||||
if self.is_system_admin:
|
||||
return
|
||||
if permission not in self.permissions:
|
||||
raise PermissionError(f"Missing permission: {permission}")
|
||||
|
||||
def has(self, permission: str) -> bool:
|
||||
"""Check if user has a permission."""
|
||||
if self.is_system_admin:
|
||||
return True
|
||||
return permission in self.permissions
|
||||
|
||||
|
||||
class UnitOfWork:
|
||||
"""Unit of Work — collects changes, audit, and outbox events.
|
||||
|
||||
One UoW per business operation. Commit happens once at the end.
|
||||
"""
|
||||
|
||||
def __init__(self, db: AsyncSession, tenant_id: uuid.UUID, user_id: uuid.UUID):
|
||||
self.db = db
|
||||
self.tenant_id = tenant_id
|
||||
self.user_id = user_id
|
||||
self._audit_entries: list[dict[str, Any]] = []
|
||||
self._outbox_events: list[dict[str, Any]] = []
|
||||
|
||||
def add(self, entity: Any) -> None:
|
||||
"""Add an entity to the session."""
|
||||
self.db.add(entity)
|
||||
|
||||
def outbox_add(
|
||||
self,
|
||||
event_name: str,
|
||||
aggregate_id: uuid.UUID,
|
||||
aggregate_type: str,
|
||||
payload: dict[str, Any],
|
||||
schema_version: int = 1,
|
||||
) -> None:
|
||||
"""Queue an outbox event for commit."""
|
||||
self._outbox_events.append({
|
||||
"event_name": event_name,
|
||||
"aggregate_id": aggregate_id,
|
||||
"aggregate_type": aggregate_type,
|
||||
"payload": payload,
|
||||
"schema_version": schema_version,
|
||||
})
|
||||
|
||||
def audit_record(self, action: str, entity_id: uuid.UUID, entity_type: str = "", changes: dict[str, Any] | None = None) -> None:
|
||||
"""Queue an audit log entry for commit."""
|
||||
self._audit_entries.append({
|
||||
"action": action,
|
||||
"entity_id": entity_id,
|
||||
"entity_type": entity_type,
|
||||
"changes": changes or {},
|
||||
})
|
||||
|
||||
async def commit(self) -> None:
|
||||
"""Flush, write audit + outbox, then commit."""
|
||||
# Flush to get entity IDs
|
||||
await self.db.flush()
|
||||
|
||||
# Write outbox events
|
||||
for evt in self._outbox_events:
|
||||
await enqueue_outbox_event(
|
||||
self.db,
|
||||
self.tenant_id,
|
||||
evt["event_name"],
|
||||
evt["payload"],
|
||||
aggregate_type=evt["aggregate_type"],
|
||||
aggregate_id=evt["aggregate_id"],
|
||||
schema_version=evt["schema_version"],
|
||||
)
|
||||
|
||||
# Write audit entries
|
||||
for entry in self._audit_entries:
|
||||
await log_audit(
|
||||
self.db,
|
||||
self.tenant_id,
|
||||
self.user_id,
|
||||
entry["action"],
|
||||
entry["entity_type"],
|
||||
entry["entity_id"],
|
||||
changes=entry["changes"],
|
||||
)
|
||||
|
||||
# Single commit for everything
|
||||
await self.db.commit()
|
||||
|
||||
async def rollback(self) -> None:
|
||||
"""Rollback the transaction."""
|
||||
await self.db.rollback()
|
||||
|
||||
|
||||
class CommandHandler(ABC, Generic[TCommand, TResult]):
|
||||
"""Base class for command handlers.
|
||||
|
||||
Subclasses implement `handle()` with the business logic.
|
||||
The `execute()` method wraps it with UoW creation and error handling.
|
||||
"""
|
||||
|
||||
@abstractmethod
|
||||
async def handle(self, command: TCommand, ctx: RequestContext, uow: UnitOfWork) -> TResult:
|
||||
"""Business logic. Use uow.add(), uow.outbox_add(), uow.audit_record()."""
|
||||
...
|
||||
|
||||
async def execute(self, command: TCommand, ctx: RequestContext, db: AsyncSession) -> TResult:
|
||||
"""Execute the command with a Unit of Work.
|
||||
|
||||
Creates a UoW, calls handle(), commits on success, rolls back on error.
|
||||
"""
|
||||
uow = UnitOfWork(db, ctx.tenant_id, ctx.user_id)
|
||||
try:
|
||||
result = await self.handle(command, ctx, uow)
|
||||
await uow.commit()
|
||||
return result
|
||||
except Exception:
|
||||
await uow.rollback()
|
||||
raise
|
||||
|
||||
|
||||
# ── FastAPI Dependency ───────────────────────────────────────────────────────
|
||||
|
||||
async def get_request_context(
|
||||
current_user: dict = None, # Will be injected by FastAPI with require_permission
|
||||
) -> RequestContext:
|
||||
"""Build a RequestContext from the current user.
|
||||
|
||||
Usage in routes:
|
||||
ctx: RequestContext = Depends(get_request_context)
|
||||
"""
|
||||
if current_user is None:
|
||||
raise PermissionError("Not authenticated")
|
||||
return RequestContext(
|
||||
user_id=uuid.UUID(current_user["user_id"]),
|
||||
tenant_id=uuid.UUID(current_user["tenant_id"]),
|
||||
is_system_admin=current_user.get("is_system_admin", False),
|
||||
permissions=set(current_user.get("permissions", [])),
|
||||
)
|
||||
Reference in New Issue
Block a user