vitepress-template

Appearance

Business Logic Implementation ​

**Referenced Files in This Document** - [[README.md]](file/bi-basic/readme.md) - [[go.mod]](file/bi-basic/go.mod) - [[biz.go]](file/bi-basic/internal/biz/biz.go) - [[data.go]](file/bi-basic/internal/data/data.go) - [[service.go]](file/bi-basic/internal/service/service.go) - [[goods.go]](file/bi-basic/internal/service/goods.go) - [[order.go]](file/bi-basic/internal/service/order.go) - [[base.sql]](file/bi-basic/docs/base.sql)

Table of Contents ​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction ​

This document explains the business logic implementation patterns in bi-basic, focusing on foundational services for goods management, order processing, shop administration, and category handling. It covers service layer abstractions, repository patterns, transaction management, validation logic, workflow implementations, state management, error handling, business constraint enforcement, audit trails, and data consistency mechanisms. The goal is to make the system understandable for both technical and non-technical readers.

Project Structure ​

The bi-basic module provides a layered architecture:

  • API layer: Protocol buffers define request/response contracts for goods, orders, shops, categories, and related services.
  • Service layer: Implements business operations and orchestrates repositories and external integrations.
  • Biz layer: Encapsulates business logic via Wire provider sets for DI.
  • Data layer: Provides repositories, transactions, and persistence clients (GORM, Redis).
  • Docs: Database design and SQL templates for dynamic StarRocks tables.

Diagram sources

Section sources

Core Components ​

  • Service layer providers: Centralized registration of services for DI.
  • Biz layer providers: Centralized registration of business logic implementations for DI.
  • Data layer: Database and Redis initialization, transaction helpers, and repository constructors.
  • API contracts: Protobuf-defined requests/responses for goods, orders, categories, and shops.

Key responsibilities:

  • GoodsService: CRUD, filtering, batch updates, import, link template management.
  • OrderService: CRUD, filtering, display lists, sync placeholders.
  • Data: Transactional DB access, Redis access, repository wiring.

Section sources

Architecture Overview ​

The system follows a clean architecture with explicit separation of concerns:

  • API layer defines contracts and marshaling/unmarshaling.
  • Service layer validates inputs, enforces business rules, and coordinates workflows.
  • Biz layer encapsulates domain logic and orchestrates repositories.
  • Data layer abstracts persistence and caching with transaction support.

Diagram sources

Detailed Component Analysis ​

Goods Management ​

GoodsService exposes operations for listing, creating, updating, deleting, and querying goods, with filtering and display formatting. It also manages link templates for custom analytics.

Implementation highlights:

  • Filtering and validation: Combines multiple filter criteria with mutual exclusivity checks (standard vs custom category).
  • Batch operations: Bulk updates for manager/head/helper roles and virtual flag.
  • Import: Parses JSON payload and delegates to business logic.
  • Link templates: Tenant-scoped CRUD with uniqueness enforcement.

Diagram sources

Section sources

Order Processing ​

OrderService supports retrieving, creating, updating, listing, and filtered display of orders. It includes placeholder handlers for synchronization tasks.

Implementation highlights:

  • Validation: Enforces page size limits and required fields.
  • Mapping: Converts between protobuf and business objects, including time conversions.
  • Filters: Supports shop, platform, product/SKU identifiers, flags, and date ranges.
  • Display: Formats fields for frontend consumption.

Diagram sources

Section sources

Shop Administration ​

Shop-related APIs and services are defined under the shop API namespace. The service layer handles shop metadata, authorization, and dictionary operations. Transaction management and repository wiring are handled by the data layer.

Notes:

  • ShopService and related logic are registered via the service provider set.
  • Shop authorization and dictionaries are supported by dedicated services.

Section sources

Category Handling ​

Category APIs and services manage standard and custom categories. The data layer initializes category tables and provides repository implementations for category queries and updates.

Notes:

  • Category services are registered via the service provider set.
  • Category repository implementations are wired in the data layer.

Section sources

Data Access and Transactions ​

The data layer centralizes:

  • Database and Redis initialization with environment-aware configuration.
  • Transaction helpers: Execute arbitrary work inside a transaction and fetch the current DB handle with transaction context propagation.
  • Repository wiring: Aggregates multiple repositories (goods, shop, category, orders, etc.) for DI.

Diagram sources

Section sources

Business Rules, Validation, and Constraints ​

  • Goods filtering: Mutual exclusivity between standard and custom category filters; robust time-range parsing; sorting and pagination normalization.
  • Orders: Page size capped at 100; required fields validated before sync operations; platform enums mapped to human-readable names.
  • Templates: Unique name per tenant enforced at the business logic level.

Section sources

Audit Trails and Data Consistency ​

  • Operation logs: Dedicated tables for shop logs and cost logs enable audit trails for changes.
  • Consistency: Transactions ensure atomicity for multi-step operations; repository methods operate against the same transactional context.
  • Indexing: StarRocks tables use primary keys, bloom/bitmap indexes, and persistent indexes to maintain consistency and performance.

Section sources

Dependency Analysis ​

The module relies on shared libraries for common concerns:

  • bi-common: Auth, gRPC gateway, logging, database (GORM), Kafka, Redis, Nacos registry, OpenAPI generation.
  • bi-proto: Shared protocol buffer definitions.

Diagram sources

Section sources

Performance Considerations ​

  • StarRocks indexing: Bloom/bitmap and persistent indexes improve query performance for high-cardinality fields and frequent filters.
  • Pagination limits: Frontend-facing endpoints cap page sizes to prevent heavy loads.
  • Transaction batching: Use Data.InTx to group related writes for consistency and reduced round trips.
  • Caching: Redis client is initialized for hot reads and caches; cluster mode supports local port-forwarding for development.

Section sources

Troubleshooting Guide ​

Common issues and resolutions:

  • Filter conflicts: Standard and custom category filters cannot be combined; adjust the request accordingly.
  • Invalid inputs: Ensure required fields (e.g., shop_id, order number) are present before invoking sync operations.
  • Page size limits: Reduce page size if encountering timeouts or large payloads.
  • Transaction failures: Wrap multi-step updates in Data.InTx to ensure rollback on errors.
  • Redis connectivity: For cluster mode, confirm address mapping for local port-forwarding.

Section sources

Conclusion ​

Bi-basic implements a clean, modular business logic layer with strong separation between API, service, biz, and data concerns. It enforces business rules at the service boundary, manages transactions for consistency, and leverages StarRocks indexing and Redis caching for performance. The design supports extensibility via Wire DI and provides clear audit trails through dedicated logging tables.