finrep-report/backend/finrep-domain/DOMAIN_LAYER_SUMMARY.md

Finrep-Report Domain Layer Summary

Overview

The Domain layer follows Domain-Driven Design (DDD) principles and contains the core business logic, domain models, and value objects. This layer is independent of infrastructure and application concerns.

Domain Structure

1. Task Aggregate (domain/task/)

The Task aggregate is the root aggregate for managing report generation tasks.

Files:

• Task.java - Aggregate root with business logic for task lifecycle management

  • Status transitions with validation
  • Progress tracking (0-100%)
  • Task lifecycle methods (start, complete, fail, cancel)
  • Version control for optimistic locking

• TaskStatus.java - Enum representing task states

  • States: PENDING_OUTLINE, PENDING_OUTLINE_CONFIRM, PENDING_DATA_PREPARE, PENDING_DATA_CONFIRM, PENDING_REPORT_GENERATE, GENERATING, PENDING_REVIEW, COMPLETED, FAILED, CANCELLED
  • Business rules: isFinal(), canConfirm(), canEdit()

• TaskStage.java - Enum representing task stages

  • Stages: OUTLINE, DATA_PREPARE, REPORT_GENERATE, REVIEW
  • Stage transition validation: canTransitionTo(), nextStage()

• TaskType.java - Enum for report task types

  • Types: PRE_LOAN_INVESTIGATION, CREDIT_APPROVAL, POST_LOAN_INSPECTION, RISK_ASSESSMENT, FINANCIAL_ANALYSIS, INDUSTRY_ANALYSIS, CUSTOM
  • Business rules: isStandardType(), requiresPreLoanInvestigation(), requiresFinancialAnalysis()

2. Outline Aggregate (domain/outline/)

Manages report outline structure and organization.

Files:

• Outline.java - Outline entity with confirmation workflow

  • Factory methods: createLevel1(), createLevel2()
  • Confirmation logic with audit trail
  • Content updates with version control

• OutlineNode.java - Hierarchical outline nodes

  • Tree structure with parent-child relationships
  • Methods: createRoot(), addChild(), getAllNodes()

• OutlineSection.java - Detailed section information

  • Knowledge unit associations
  • Data binding configurations
  • Section type classification

• OutlineType.java - Enum: LEVEL1, LEVEL2

• SectionType.java - Enum: TEXT, CHART, TABLE, APPENDIX

3. Data Preparation Aggregate (domain/dataprep/)

Handles data collection and management for report generation.

Files:

• DataPackage.java - Data package entity

  • Auto and manual data merging
  • Confirmation workflow
  • Status management: markSuccess(), markFailed()

• DataStatus.java - Enum: PENDING, RETRIEVING, SUCCESS, FAILED

• DataSource.java - External data source configuration

  • Connection management: testConnection(), markConnectionSuccess(), markConnectionFailed()
  • DataSourceType: DATABASE, API, FILESYSTEM, MESSAGE_QUEUE, EXTERNAL_SYSTEM
  • DataSourceStatus: ACTIVE, ERROR, DISABLED

4. Report Generation Aggregate (domain/generation/)

Manages report generation and content.

Files:

• Report.java - Report entity with sections

  • Factory method: create()
  • Section management: addSection(), updateSection()
  • Report lifecycle: complete(), fail()
  • Text generation: generateFullText()
  • Inner classes: Section, ReportMetadata

• ReportStatus.java - Enum: DRAFT, GENERATING, COMPLETED, FAILED, CANCELLED

• ReportFormat.java - Enum: PDF, WORD, HTML, MARKDOWN, JSON

  • MIME type mappings
  • File extension support
  • Format categorization: isDownloadable(), isTextFormat(), isDocumentFormat()

5. Knowledge Aggregate (domain/knowledge/)

Domain knowledge for report generation.

Files:

• KnowledgeUnit.java - Knowledge unit entity

  • Template configuration management
  • Enable/disable functionality
  • Hierarchical structure support

• KnowledgeType.java - Enum: BASIC, BUSINESS, RISK, FINANCE, LEGAL, OTHER

• KnowledgeScope.java - Enum: GLOBAL, TENANT, ORGANIZATION, PROJECT, PERSONAL

6. Tenant Aggregate (domain/tenant/)

Multi-tenancy support.

Files:

• Tenant.java - Tenant entity with quota management

  • Activation/deactivation: enable(), disable()
  • Feature flags: isFeatureEnabled(), setFeatureFlag()
  • Quota validation: canAddTask(), canGenerateReport(), canUseStorage()
  • Inner classes: QuotaConfig, TenantStatus

• Organization.java - Hierarchical organization structure

  • Tree structure: createRoot(), createChild(), addChild()
  • Path management for hierarchical queries
  • Inner classes: OrganizationType, OrgStatus

7. Shared Value Objects (domain/shared/)

Base classes and value objects for domain modeling.

Files:

• ValueObject.java - Abstract base class

  • ID generation utilities: generateId(), generateId(prefix)
  • ID validation: isValidId()
  • Value object equality and hashCode

• TaskId.java - Typed ID for tasks

  • Validation on construction
  • Factory methods: generate(), of()

• TenantId.java - Typed ID for tenants

  • Validation on construction
  • Factory methods: generate(), of()

Domain Design Principles Applied

1. Aggregates

• Task: Root aggregate controlling report generation workflow
• Outline: Self-contained with confirmation lifecycle
• DataPackage: Encapsulates data merging logic
• Report: Manages report content and metadata
• KnowledgeUnit: Independent knowledge management
• Tenant: Multi-tenancy boundary with quota management
• Organization: Hierarchical structure with path optimization

2. Value Objects

• Immutable identifiers (TaskId, TenantId)
• Type-safe enums for all domain states and types
• Rich business methods on enums

3. Business Rules

• State transitions: Validated with canTransitionTo() methods
• Invariant enforcement: Progress (0-100%), required fields validation
• Audit trails: Creator tracking, timestamps, version control
• Confirmation workflows: Double-check before proceeding

4. Factory Methods

• Static factory methods for object creation (create, of, generate*)
• Enforce invariants during construction
• Initialize default values and timestamps

5. Lombok Integration

• @Getter/@Setter for property access
• @Builder for flexible construction
• @EqualsAndHashCode for identity equality
• @ToString for debugging

Domain Services

The domain layer currently uses entity methods for business logic. Domain services can be added in domain/services/ for:

• Cross-aggregate business logic
• Complex calculations
• External domain interactions

Persistence Ignorance

All domain entities are independent of:

• Database technology
• ORM frameworks
• Persistence mechanisms
• External service implementations

Testing Strategy

Domain layer should be tested with:

• Unit tests for entity methods
• State transition validation
• Business rule enforcement
• Value object immutability

Next Steps

1. Add domain services if cross-aggregate logic is needed
2. Implement repository interfaces in application layer
3. Create unit tests for all domain entities
4. Document complex business rules

File Count

• Total domain files: 20
• Aggregates: 6 (Task, Outline, DataPackage, Report, KnowledgeUnit, Tenant)
• Entities: 6 + 2 (Organization, DataSource)
• Value objects: 3
• Enums: 13