vitepress-template

Appearance

Data Models and Entities ​

**Referenced Files in This Document** - [[base.sql]](file/bi-basic/docs/base.sql) - [[base_good_category.sql]](file/bi-basic/docs/base-good-category.sql) - [[shop.go]](file/bi-basic/internal/data/do/shop.go) - [[goods.go]](file/bi-basic/internal/data/do/goods.go) - [[order.go]](file/bi-basic/internal/data/do/order.go) - [[good_category.go]](file/bi-basic/internal/data/do/good-category.go) - [[shop.go]](file/bi-basic/internal/biz/bo/shop.go) - [[goods.go]](file/bi-basic/internal/biz/bo/goods.go) - [[repoimpl.go]](file/bi-basic/internal/data/repo/repoimpl/repoimpl.go) - [[shop.go]](file/bi-basic/internal/data/repo/shop.go) - [[goods.go]](file/bi-basic/internal/data/repo/goods.go) - [[shop.go]](file/bi-basic/internal/biz/logic/shop.go) - [[goods.go]](file/bi-basic/internal/biz/logic/goods.go)

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 describes the core data models and entity relationships in the bi-basic module. It covers the foundational entities (goods, orders, shops, categories), their DO (Data Object), BO (Business Object), and Repo (Repository) implementations, along with database design principles, indexing strategies, and performance optimizations. It also documents entity lifecycle management, validation rules, and business constraints enforced across the system.

Project Structure ​

The bi-basic module organizes data models under internal/data/do, business logic under internal/biz/bo and internal/biz/logic, and repositories under internal/data/repo. The database schema is defined in bi-basic/docs/base.sql and bi-basic/docs/base_good_category.sql.

Diagram sources

Section sources

Core Components ​

This section documents the core entities and their roles in the system.

  • Shop (Store)

    • Purpose: Represents a seller storefront across platforms.
    • DO: internal/data/do/shop.go defines the Shop struct mapped to base_shop.
    • BO: internal/biz/bo/shop.go defines ShopBO and request/response structs for CRUD operations.
    • Logic: internal/biz/logic/shop.go implements shop lifecycle operations and dynamic table resolution.
    • Repo: internal/data/repo/shop.go defines ShopRepo interface; implemented via RepoImpl.

  • Goods (Product)

    • Purpose: Product catalog entity with SKU linkage and inventory metadata.
    • DO: internal/data/do/goods.go defines Goods struct mapped to base_goods and related SKU tables.
    • BO: internal/biz/bo/goods.go defines GoodsBO and request/response structs.
    • Logic: internal/biz/logic/goods.go implements listing, filtering, creation, updates, and import operations.
    • Repo: internal/data/repo/goods.go defines GoodsRepo interface; implemented via RepoImpl.

  • Order

    • Purpose: Transaction records for sales, including refund and billing period tracking.
    • DO: internal/data/do/order.go defines Order struct mapped to base_order and related tables.
    • BO: internal/biz/bo/goods.go includes order-related BOs and enums for status mapping.
    • Logic: internal/biz/logic/goods.go integrates order queries and metrics via dynamic table naming.

  • Category

    • Purpose: Platform and custom category taxonomy.
    • DO: internal/data/do/good_category.go defines GoodCategory mapped to base_good_category.
    • BO: internal/biz/bo/goods.go includes category-related BOs and filters.
    • Logic: internal/biz/logic/goods.go includes category mapping and filtering helpers.

  • Repositories

    • RepoImpl: internal/data/repo/repoimpl/repoimpl.go aggregates repository implementations for goods, shop, and categories.
    • Interfaces: internal/data/repo/shop.go and internal/data/repo/goods.go define repository contracts.

Section sources

Architecture Overview ​

The bi-basic module follows a layered architecture:

  • Data Objects (DO): ORM-mapped structs representing database tables.
  • Business Objects (BO): Request/response DTOs and business entities for APIs.
  • Logic: Orchestrates business rules, validations, and cross-entity operations.
  • Repository: Abstracts persistence and supports dynamic table naming for tenant/platform scoping.
  • Database: StarRocks OLAP tables with bitmap and bloom filter indexes for analytical workloads.

Diagram sources

Detailed Component Analysis ​

Shop Entity ​

  • DO: Shop struct maps to base_shop with fields for platform, shop identity, operational flags, and pricing parameters.
  • Dynamic table naming: GetShopTableName resolves tenant-scoped tables (base_shop_{tenant}).
  • BO: ShopBO encapsulates request/response DTOs and platform name mapping.
  • Logic: CRUD operations, logging, and dynamic table existence checks; uses native SQL for StarRocks compatibility.
  • Validation: Requests implement Verify() and Params() for safe updates.

Diagram sources

Section sources

Goods Entity ​

  • DO: Goods struct maps to base_goods with product identifiers, pricing, sales metrics, and categorization.
  • Dynamic table naming: GetGoodsTableName supports tenant, platform, and shop scoping.
  • BO: GoodsBO mirrors DO fields and provides display-friendly structures.
  • Logic: Listing with filters, pagination, batch updates, and import workflows; uses INSERT OVERWRITE for StarRocks primary-key model.
  • Validation: Requests implement Verify() and Params() for safe updates.

Diagram sources

Section sources

Order Entity ​

  • DO: Order struct maps to base_order with payment, quantity, logistics, and flags for refunds and promotions.
  • Status Enum: OrderStatus constants and description map enable consistent status handling.
  • Metrics: base_goods_metrics stores per-day metrics keyed by shop/product/sku/date.

Diagram sources

Section sources

Category Entity ​

  • DO: GoodCategory maps to base_good_category with hierarchical path and parent-child relations.
  • BO: Category filters and mappings support product categorization and reporting.

Diagram sources

Section sources

Repository Pattern Implementation ​

  • RepoImpl aggregates repository instances for goods, shop, and categories.
  • Interfaces define minimal contracts for listing and querying by dynamic table names.
  • Logic components depend on RepoImpl to resolve tenant/platform-specific tables.

Diagram sources

Section sources

Dependency Analysis ​

  • DO depends on GORM tags for column mapping and primary keys.
  • BO depends on DO and protobuf-generated request/response types.
  • Logic depends on BO, DO, and RepoImpl; performs dynamic table resolution and native SQL for StarRocks.
  • RepoImpl composes repository interfaces and delegates persistence to underlying clients.

Diagram sources

Section sources

Performance Considerations ​

  • StarRocks OLAP engine: Tables configured with primary keys, distributed hashing, and persistent indexes for efficient analytical scans.
  • Bitmap indexes: Used on high-cardinality attributes (e.g., SKU IDs, platform IDs, tenant IDs) to accelerate filtering.
  • Bloom filters: Enabled on selective columns to reduce I/O during lookups.
  • Native SQL: Logic uses raw SQL for pagination and updates to align with StarRocks limitations and performance characteristics.
  • Dynamic table naming: Tenant and platform scoping reduces contention and improves isolation.

[No sources needed since this section provides general guidance]

Troubleshooting Guide ​

  • Dynamic table resolution failures: Ensure tenant context is correctly resolved and table naming functions return valid names.
  • StarRocks compatibility: Use native SQL for LIMIT/OFFSET and avoid prepared statements; handle string escaping carefully.
  • Repository contract mismatches: Confirm RepoImpl instantiates all required repository implementations.
  • Logging and audit: Shop operations log changes; verify log table creation and insertion logic.

Section sources

Conclusion ​

The bi-basic module establishes a robust foundation for e-commerce analytics with clear separation of concerns across DO, BO, and Logic layers. Its StarRocks-centric design leverages bitmap and bloom filters for performance, while dynamic table naming ensures tenant and platform isolation. The repository abstraction simplifies persistence, and the logic layer enforces business rules and validations consistently across entities.