kratos-biz-layer

<essential_principles>

How Kratos Business Layer Works

Clean Architecture Dependency Rule

The business layer (biz) is the core of Clean Architecture in Kratos microservices:

Dependency Flow: Service → Biz → Data

• Biz defines interfaces that data layer implements
• Biz contains business logic independent of frameworks
• Biz uses domain models not ORM entities

Domain-Driven Structure (Current Pattern)

The biz layer follows domain-driven design with these subdirectories:

1. Domain Layer (internal/biz/domain/)

• models.go - Domain entities with validation tags
• interfaces.go - Repository, use case, and event publisher interfaces
• errors.go - Domain errors (ErrSymbolNotFound) and data layer errors (ErrDataNotFound)

2. Use Case Layer (internal/biz/{entity}/)

• usecase.go - Use case implementation
• usecase_test.go - Use case tests with event assertions
• validator.go - Validation logic factory

3. Event Layer (internal/biz/event/) - Optional

• mapper.go - Event payload transformations
• topics.go - Event topic constants

4. Provider (internal/biz/provider.go)

• Wire ProviderSet for dependency injection

Error Separation Pattern

Data Layer Errors (returned by repositories):

• domain.ErrDataNotFound - Record not found
• domain.ErrDataDuplicateEntry - Unique constraint violation
• domain.ErrDataDatabase - Generic database error

Domain Errors (returned by use cases):

• domain.ErrSymbolNotFound - Symbol not found (business error)
• domain.ErrDuplicateSymbol - Duplicate symbol (business error)
• domain.ErrDatabaseOperation - Database operation failed

Pattern: Repositories return data errors, use cases map to domain errors via toDomainError() helper.

Event Publishing Pattern

Use cases integrate event publishing for domain events:

• Accept domain.{Entity}EventPublisher interface
• Publish events within transactions
• Transaction rolls back if publishing fails

Example:

err := uc.tm.InTx(ctx, func(ctx context.Context) error {
    symbol, err = uc.repo.Create(ctx, s)
    if err != nil {
        return err
    }
    return uc.pub.PublishSymbolCreated(ctx, symbol)
})

Wire Dependency Injection

All constructors must be added to ProviderSet in internal/biz/provider.go:

var ProviderSet = wire.NewSet(symbol.NewValidator, symbol.NewUseCase)

After changes, run make generate to regenerate Wire code. </essential_principles>

<intake> What would you like to do?

1. Create a new entity (use case + interface + model + validator)
2. Add methods to existing use case
3. Create standalone validator
4. View examples and patterns

Wait for response before proceeding. </intake>

<routing> | Response | Workflow | |----------|----------| | 1, "create", "new entity", "new" | `workflows/create-entity.md` | | 2, "add method", "add", "extend" | `workflows/add-methods.md` | | 3, "validator", "validation" | `workflows/create-validator.md` | | 4, "examples", "patterns", "help" | `workflows/view-examples.md` |

After reading the workflow, follow it exactly. </routing>

<reference_index> All domain knowledge in references/:

Core Patterns: use-case-pattern.md, interface-pattern.md, model-pattern.md Code Style: naming-conventions.md

Additional patterns (error handling, logging, transactions, testing) are covered within use-case-pattern.md. </reference_index>

<workflows_index> | Workflow | Purpose | |----------|---------| | create-entity.md | Generate complete biz layer for new entity | | add-methods.md | Add CRUD methods to existing use case | | create-validator.md | Create standalone validator | | view-examples.md | Show patterns and examples | </workflows_index>

<success_criteria> Business layer code is correct when:

Structure:

• Domain models in internal/biz/domain/models.go
• Interfaces in internal/biz/domain/interfaces.go
• Errors in internal/biz/domain/errors.go
• Use case in internal/biz/{entity}/usecase.go
• Validator in internal/biz/{entity}/validator.go
• Tests in internal/biz/{entity}/usecase_test.go

Use Case Implementation:

• Struct has repo, pub, log, validator, tm fields
• Constructor returns interface type (domain.{Entity}UseCase)
• Methods accept context.Context as first parameter
• Validation happens before repository calls
• Data errors mapped to domain errors via toDomainError()
• Events published within transactions
• All errors logged with context

Domain Layer:

• Repository interface in domain/interfaces.go
• Event publisher interface in domain/interfaces.go (if events)
• Business model in domain/models.go with validation tags
• Domain errors (ErrSymbolNotFound) separated from data errors (ErrDataNotFound)

Wire Integration:

• Constructor added to ProviderSet in internal/biz/provider.go
• User reminded to run make generate </success_criteria>