vitepress-template

Appearance

Development and Testing ​

**Referenced Files in This Document** - [[bi-analysis/README.md]](file/bi-analysis/readme.md) - [[bi-analysis/Makefile]](file/bi-analysis/makefile) - [[bi-analysis/cmd/bi-analysis/main.go]](file/bi-analysis/cmd/bi-analysis/main.go) - [[bi-common/README.md]](file/bi-common/readme.md) - [[bi-common/go.mod]](file/bi-common/go.mod) - [[bi-common/apitypes/README.md]](file/bi-common/apitypes/readme.md) - [[bi-common/utils/validation/README.md]](file/bi-common/utils/validation/readme.md) - [[ui-web/README.md]](file/ui-web/readme.md) - [[ui-web/package.json]](file/ui-web/package.json) - [[ui-web/tsconfig.json]](file/ui-web/tsconfig.json) - [[bi-chat/docker-compose.yml]](file/bi-chat/docker-compose.yml) - [[bi-chat/requirements.txt]](file/bi-chat/requirements.txt)

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
  10. Appendices

Introduction ​

This document provides comprehensive development and testing guidance for the BI Analysis Platform. It covers local development workflows, service dependencies, debugging approaches, testing strategies (unit, integration, end-to-end), code quality standards, CI/CD and deployment automation, performance and load testing, monitoring, and contribution practices. The platform integrates a Go microservice (bi-analysis) built on Kratos, a shared component library (bi-common), and a React-based frontend (ui-web). Additional services such as the chat assistant (bi-chat) rely on containerized dependencies.

Project Structure ​

The repository is a multi-language, multi-service workspace:

  • Go microservices: bi-analysis, bi-common, bi-proto, and others under bi-*
  • Frontend: ui-web (Next.js)
  • Chat assistant: bi-chat (Python/FastAPI) with Docker Compose for dependencies
  • Shared components and utilities: bi-common modules (Nacos, apitypes, gormx, redisx, kafkax, logger, validation)

Diagram sources

Section sources

Core Components ​

  • bi-analysis: Kratos-based microservice with HTTP/gRPC servers, Nacos configuration, unified response encoding, and OpenAPI generation.
  • bi-common: Shared infrastructure including Nacos integration, apitypes (uniform response/error handling), logging, database (gormx), Redis (redisx), Kafka (kafkax), StarRocks streamload, and validation utilities.
  • ui-web: Next.js frontend configured with TypeScript, ESLint, Tailwind, and environment-specific builds.
  • bi-chat: Python FastAPI service with Milvus vector store, Postgres metadata, Redis session memory, and Docker Compose orchestration.

Key development commands and workflows:

  • bi-analysis Makefile targets for initialization, API generation, OpenAPI docs, synchronization, building, and code generation.
  • ui-web npm scripts for dev/build/test/lint with environment variable control.
  • bi-chat Docker Compose for local dependency provisioning.

Section sources

Architecture Overview ​

The system follows a layered architecture:

  • Presentation: ui-web communicates with bi-analysis via HTTP/gRPC.
  • Business Logic: bi-analysis encapsulates domain logic and coordinates with data access and external systems.
  • Data Access: Uses gormx for MySQL/StarRocks and kafkax for event streaming.
  • Observability: Centralized logging and metrics via bi-common logger and OpenTelemetry integrations.
  • Configuration: Nacos-based dynamic configuration with environment-specific YAML files.

Diagram sources

Detailed Component Analysis ​

bi-analysis: Microservice Bootstrap and Build ​

  • Entry point parses environment flag, loads Nacos configuration, initializes logger, sets up service registry, wires dependencies, and starts Kratos app.
  • Makefile supports init, API generation (proto + OpenAPI), doc sync to Apifox, build, and code generation.

Diagram sources

Section sources

bi-common: Shared Infrastructure ​

  • Provides zero-config integration for Nacos, unified response/error handling (apitypes), logging, database, Redis, Kafka, and validation utilities.
  • Supports environment variable overrides and intelligent defaults.

Diagram sources

Section sources

ui-web: Frontend Development Workflow ​

  • Dev/build scripts support environment-specific builds via NEXT_PUBLIC_APP_ENV.
  • TypeScript strictness and ESLint configuration enable type safety and code quality.

Diagram sources

Section sources

bi-chat: Local Dependencies and Testing ​

  • Docker Compose provisions Postgres, Milvus, etcd, MinIO, and Redis for chat assistant services.
  • Python requirements include FastAPI, Pydantic, Milvus, Redis, and testing libraries.

Diagram sources

Section sources

Dependency Analysis ​

  • bi-analysis depends on bi-common and bi-proto; replace directives ensure local development alignment.
  • bi-common aggregates Kratos, Nacos, GORM, Redis, Kafka, and OpenTelemetry dependencies.
  • ui-web relies on Next.js, React, ECharts, Tailwind, and TypeScript toolchain.
  • bi-chat depends on FastAPI, Pydantic, Milvus, Redis, and testing stack.

Diagram sources

Section sources

Performance Considerations ​

  • Logging and metrics: Use bi-common logger for structured logs and integrate OpenTelemetry for distributed tracing and metrics collection.
  • Database and caching: Configure gormx and redisx with appropriate connection pools and timeouts; leverage validation utilities for safe configuration.
  • API consistency: apitypes ensures uniform response shapes, simplifying client-side caching and error handling.
  • Frontend performance: Enable strict TypeScript checks and linting; optimize bundle sizes with Next.js static exports and code splitting.

[No sources needed since this section provides general guidance]

Troubleshooting Guide ​

  • Configuration loading: Verify Nacos YAML files and environment-specific config paths; ensure precedence order and environment variables override as expected.
  • Unified responses: Confirm apitypes middleware is installed on HTTP servers; inspect error codes and messages for failures.
  • Validation errors: Use bi-common validation helpers to catch misconfigurations early; ensure non-empty fields, valid ports, URLs, and timeouts.
  • Frontend builds: Check NEXT_PUBLIC_APP_ENV usage and script targets; validate tsconfig strictness and ESLint rules.
  • Chat assistant dependencies: Confirm Docker Compose services are reachable and credentials are set; verify Milvus and Postgres schemas.

Section sources

Conclusion ​

The BI Analysis Platform leverages a robust, modular architecture with shared infrastructure (bi-common), standardized API responses (apitypes), and consistent development tooling across Go and JavaScript ecosystems. By following the documented workflows, quality standards, and troubleshooting steps, contributors can efficiently develop, test, and operate services while maintaining high reliability and maintainability.

[No sources needed since this section summarizes without analyzing specific files]

Appendices ​

Development Environment Setup ​

  • Install dependencies and tools via bi-analysis Makefile init target.
  • Configure Nacos with environment-specific YAML files and verify precedence.
  • Run bi-analysis with -env flag for dev/test/prod.
  • Use ui-web npm scripts for development and production builds.
  • Provision bi-chat dependencies locally with Docker Compose.

Section sources

Testing Strategy ​

  • Unit testing: Use Go test for Go packages; leverage apitypes testing patterns and validation utilities.
  • Integration testing: Validate Nacos configuration loading, database connectivity, and Kafka producers/consumers.
  • End-to-end testing: Use ui-web integration tests and bi-chat API tests; coordinate with Docker Compose services.

Section sources

Code Quality Standards ​

  • Go: Use bi-common validation utilities and apitypes for consistent responses; keep configuration safe and validated.
  • JavaScript/TypeScript: Enforce strict tsconfig and ESLint; maintain clean separation of concerns in Next.js app.

Section sources

CI/CD and Deployment Automation ​

  • API documentation generation and synchronization to Apifox are automated via Makefile targets.
  • Build artifacts are produced with version flags; containerization is supported by Dockerfiles in relevant services.

Section sources

Release Management ​

  • Versioning is embedded via ldflags in Makefile build target; ensure semantic version tags for releases.
  • Synchronize OpenAPI documentation to Apifox for API governance and team alignment.

Section sources

Contribution Guidelines and Best Practices ​

  • Follow module naming and configuration precedence as outlined in bi-common and bi-analysis documentation.
  • Maintain consistent error codes and response formats using apitypes.
  • Keep configuration safe with validation utilities and environment variable overrides.
  • Use Docker Compose for local dependency management in Python services.

Section sources