vitepress-template

Appearance

目录结构说明 ​

**本文档引用的文件** - [[README.md]](../file/readme.md) - [[go.work]](../file/go.work) - [[bi-common/README.md]](../file/bi-common/readme.md) - [[bi-common/go.mod]](../file/bi-common/go.mod) - [[bi-basic/go.mod]](../file/bi-basic/go.mod) - [[bi-analysis/go.mod]](../file/bi-analysis/go.mod) - [[bi-api-leke/go.mod]](../file/bi-api-leke/go.mod) - [[bi-api-jushuitan/go.mod]](../file/bi-api-jushuitan/go.mod) - [[bi-notify/go.mod]](../file/bi-notify/go.mod) - [[bi-sys/go.mod]](../file/bi-sys/go.mod) - [[bi-tenant/go.mod]](../file/bi-tenant/go.mod) - [[bi-cron/go.mod]](../file/bi-cron/go.mod) - [[bi-server/go.mod]](../file/bi-server/go.mod) - [[bi-template/go.mod]](../file/bi-template/go.mod) - [[bi-plan-taoxi/go.mod]](../file/bi-plan-taoxi/go.mod) - [[ui-web/package.json]](../file/ui-web/package.json) - [[ui-web/README.md]](../file/ui-web/readme.md)

更新摘要 ​

所做更改

  • 更新了 Go Workspace 依赖关系图，移除了对 bi-proto 模块的依赖
  • 更新了模块依赖关系分析，反映了最新的模块结构
  • 更新了 bi-basic、bi-analysis 等模块的依赖配置
  • 更新了架构设计原则中的依赖关系说明

目录 ​

  1. 简介
  2. 项目结构概览
  3. 核心模块详解
  4. 架构设计原则
  5. 模块依赖关系
  6. 扩展指南
  7. 开发与部署
  8. 总结

简介 ​

本项目是一个企业级商业智能（BI）分析平台，采用现代化技术栈构建，具备高性能、可扩展性和良好的用户体验。平台由多个相互独立的服务模块组成，包括公共组件库、基础数据服务、核心分析服务、AI对话系统以及多个前端应用。

项目结构概览 ​

项目采用多模块架构，通过 Go Workspace 进行统一管理：

图表来源

核心模块详解 ​

bi-common 公共组件库 ​

bi-common 是整个 BI 平台的基础设施组件库，提供开箱即用的通用能力：

主要功能模块 ​

模块说明关键特性
nacosNacos 配置中心与服务发现零配置集成、智能推断、动态配置
apitypes统一响应格式与错误码管理7位错误码、标准响应结构
logger统一日志组件文件轮转、阿里云 SLS、中间件集成
gormxGORM 数据库封装MySQL/StarRocks 支持、TLS 加密
redisxRedis 客户端封装单机/哨兵/集群模式
kafkaxKafka 客户端封装生产者/消费者/多Topic支持
starrocks/streamloadStarRocks HTTP 批量导入高性能数据导入

设计理念 ​

  • 零配置优先：1-10 行代码完成集成
  • 智能默认：自动推断配置，减少人工配置错误
  • Kratos 原生：深度集成 Kratos 框架生态
  • 类型安全：完整的类型定义和编译时检查

章节来源

bi-basic 基础数据服务 ​

bi-basic 提供 BI 系统的基础数据服务能力，是其他业务模块的重要支撑：

核心能力 ​

  • 订单数据管理：订单、售后订单、重复购买等核心业务数据
  • 商品数据管理：商品、类目、SKU 等商品相关信息
  • 成本数据管理：成本核算、费用统计等功能
  • 店铺数据管理：店铺信息、认证状态等

技术特点 ​

  • 基于 Kratos 框架构建
  • 集成 bi-common 组件库
  • 支持 gRPC + HTTP 双协议
  • 完善的测试体系

章节来源

bi-analysis 核心分析服务 ​

bi-analysis 是 BI 系统的分析引擎，负责复杂的数据分析和指标计算：

主要特性 ​

  • Kratos 框架：微服务架构基础
  • bi-common 集成：统一配置、日志、数据库等基础设施
  • OpenAPI 文档：自动生成并同步到 Apifox
  • 统一响应格式：标准化 API 输出

目录结构 ​

API 文档规范 ​

平台采用统一的 API 文档规范：

  • 响应结构：标准的 code/message/data 格式
  • 分页支持：统一的分页响应结构
  • 标签层级：使用 "/" 分隔符创建层级目录
  • 字段命名：snake_case 命名规范

章节来源

前端应用模块 ​

平台提供多个前端应用，满足不同用户场景的需求：

ui-web 租户控制台 ​

基于 Next.js 16 构建的企业级前端应用：

  • 技术栈：TypeScript + React 19 + Next.js 16
  • UI 框架：Arco Design
  • 图表库：ECharts 6.x
  • 状态管理：Zustand
  • 样式系统：Tailwind CSS

ui-web-admin 运营后台 ​

系统运营管理后台，提供平台级管理功能。

ui-web-top 顶部导航 ​

门户级组件，提供统一的导航体验。

ui-crx 浏览器扩展 ​

增强用户在目标网站上的数据分析体验。

章节来源

架构设计原则 ​

1. 分层架构原则 ​

2. 模块化设计 ​

  • 单一职责：每个模块专注于特定业务领域
  • 低耦合：模块间通过明确定义的接口交互
  • 可替换性：核心组件支持配置化替换

3. 可扩展性设计 ​

  • 插件机制：支持功能模块的动态加载
  • 配置驱动：通过配置文件控制行为
  • 版本管理：清晰的版本升级策略

模块依赖关系 ​

Go Workspace 依赖 ​

图表来源

依赖关系分析 ​

bi-basic 依赖关系 ​

  • 依赖 bi-common 提供基础设施组件
  • 已移除 依赖 bi-proto 定义数据接口
  • 使用 Kratos 框架进行服务治理

bi-analysis 依赖关系 ​

  • 依赖 bi-common 统一基础设施
  • 已移除 依赖 bi-proto 定义分析接口
  • 集成 OpenAPI 文档生成

前端应用依赖 ​

  • ui-web 依赖后端 API 服务
  • 使用 Next.js 生态系统
  • 集成各种 UI 组件库

更新 移除了对 bi-proto 模块的所有依赖关系，所有模块现在直接使用本地生成的 proto 文件

章节来源

扩展指南 ​

新模块开发流程 ​

开发规范 ​

代码规范 ​

  • Go 语言：使用 Go 1.25+ 版本
  • TypeScript：前端使用 TypeScript 严格模式
  • ESLint：代码风格统一检查
  • Prettier：代码格式化工具

Git 提交规范 ​

类型用途示例
feat新功能feat: 添加用户管理功能
fix修复 bugfix: 修复登录验证问题
docs文档更新docs: 更新API文档
style代码格式调整style: 修复代码格式问题
refactor重构代码refactor: 优化数据库查询
test测试相关test: 添加单元测试

配置管理 ​

环境配置 ​

环境配置文件用途
devapplication-dev.yaml开发环境
testapplication-test.yaml测试环境
prodapplication-prod.yaml生产环境

Nacos 配置优先级 ​

  1. 环境变量 - 最高优先级
  2. 用户配置 - 通过 WithXXX() 函数
  3. 配置文件 - 通过 WithConfigFile() 加载
  4. 智能推断 - 组件自动推断
  5. 默认配置 - 内嵌默认值

开发与部署 ​

前端开发 ​

开发环境启动 ​

bash
# 进入 ui-web 目录
cd ui-web

# 安装依赖
npm install

# 启动开发服务器
npm run dev

构建与部署 ​

bash
# 构建生产版本
npm run build

# 启动生产服务器
npm run start

后端开发 ​

开发环境启动 ​

bash
# 进入 bi-analysis 目录
cd bi-analysis

# 初始化开发环境
make init

# 启动服务
./bin/bi-analysis -env dev

构建与部署 ​

bash
# 构建二进制文件
make build

# 容器化部署
docker build -t bi-analysis .
docker run -p 8080:8080 bi-analysis

总结 ​

本 BI 分析平台采用模块化、分层化的架构设计，通过 bi-common 提供统一的基础设施，bi-basic 和 bi-analysis 分别承担基础数据服务和核心分析功能，多个前端应用满足不同用户场景需求。

核心优势 ​

  1. 统一基础设施：bi-common 提供标准化的组件库
  2. 清晰的模块边界：各模块职责明确，便于维护和扩展
  3. 现代化技术栈：前后端分离，微服务架构
  4. 完善的开发规范：从代码到部署的全流程规范
  5. 强大的扩展能力：支持新模块的快速开发和集成

发展方向 ​

  • 性能优化：针对大数据量场景进行性能调优
  • 监控完善：加强全链路监控和日志分析能力
  • 自动化运维：完善 CI/CD 流水线和自动化部署
  • 模块化演进：继续推进服务模块的解耦和独立部署