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>

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.

After reading the workflow, follow it exactly.

<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>

<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>