# bls-kox

**Repository Path**: leheya/bls-server

## Basic Information

- **Project Name**: bls-kox
- **Description**: BLS 是一套面向多租户企业管理场景的后台系统，整体由前端管理端、后端服务端、数据库与运维支撑能力组成。系统围绕“平台统一治理、租户独立运营”的设计目标，提供权限控制、基础资料管理、业务管理、日志审计、文件存储、页面配置与实时能力等模块。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-17
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# BLS 系统总览文档

BLS 是一套面向多租户企业管理场景的后台系统，整体由前端管理端、后端服务端、数据库与运维支撑能力组成。系统围绕“平台统一治理、租户独立运营”的设计目标，提供权限控制、基础资料管理、业务管理、日志审计、文件存储、页面配置与实时能力等模块。

## 1. 系统目标

BLS 的核心目标是为企业提供一套可持续扩展的后台管理底座，支持多租户模式下的统一建设与差异化运营。

系统重点解决以下问题：

- 多租户之间的数据隔离与权限隔离
- 平台管理员、租户管理员、普通用户的角色区分
- 常见后台管理能力的标准化复用
- 业务模块快速接入与统一规范维护
- 具备可扩展的实时能力、导出能力和全局搜索能力

### 1.1 截图预览

#### 文件管理页

![文件管理页](img/1.png)

#### 上传弹窗

![上传弹窗](img/2.png)

#### 系统设置页

![系统设置页](img/3.png)

#### 其他界面

![其他界面](img/4.png)


### 1.3 多租户策略

系统没按照传统的 *** 来获取所有权限,根据超管的绝对权限去给自己配置所有权限，以防sql注入的安全性
也就是说，只有你登陆了超管账号才能正常赋予自己权限以及赋予其他子级子租户权限。所以每次的新菜单需要给超管
显示权限，因为接口层已经给超管开绿灯了，前端是权限xxx:xxx:xxx控制显隐

## 2. 系统组成

BLS 当前主要分为两个应用：

### 2.1 `bls-admin`

后台管理前端，基于 Ant Design Pro 构建，提供统一的系统入口和业务管理界面。

主要职责：

- 登录与权限展示
- 系统配置管理
- 用户、角色、部门、菜单管理
- 租户与套餐管理
- 文件、存储、日志管理
- 业务模块管理
- 页面配置与实时看板能力

### 2.2 `bls-server`

后端服务，基于 Koa + TypeScript + MySQL 构建，负责提供业务 API、鉴权、租户隔离、数据访问和系统支撑能力。

主要职责：

- JWT 登录与用户上下文
- 多租户请求处理
- RBAC 权限控制
- CRUD 接口与业务服务
- 全局搜索与实时消息
- 文件/Excel 等通用能力
- 数据库访问与事务处理

## 3. 技术栈

### 前端

- Ant Design Pro
- Ant Design
- TypeScript
- Umi / 相关企业级后台工程体系

### 后端

- Koa
- TypeScript
- MySQL
- Kysely（新业务优先使用）
- JWT
- WebSocket（实时能力）

### 数据与支撑

- MySQL 作为主数据库
- 租户上下文贯穿请求链路
- 统一日志与审计记录
- 文件存储与导入导出能力

## 4. 核心设计原则

### 4.1 多租户优先

系统默认按租户维度进行数据隔离。只要属于业务数据表，通常都需要考虑：

- `tenant_id` 过滤
- 平台管理员与租户用户的访问边界
- 共享数据与租户私有数据的区分

### 4.2 分层清晰

后端保持较明确的分层：

- `Controller`：接收请求、做参数校验、返回响应
- `Service`：负责业务逻辑与流程编排
- `Repository`：负责数据库访问
- `Model`：定义分页、表配置、DTO 等基础类型

### 4.3 新旧代码并行演进

系统历史上存在多种实现方式。当前策略是：

- 既有稳定模块保持原实现
- 新业务优先使用更现代的写法，例如 `Kysely`
- 统一通过约定逐步收敛实现风格

### 4.4 统一治理

系统尽量把通用能力收敛到公共模块中，包括：

- 鉴权
- 租户处理
- 错误处理
- 请求响应封装
- 审计日志
- 文件上传与导出
- 实时能力

## 5. 主要功能模块

### 5.1 基础系统模块

这部分是后台系统的核心管理能力，主要包括：

- 用户管理
- 角色管理
- 菜单管理
- 部门管理
- 字典管理
- 系统配置
- 主题配置
- 文件管理
- 存储配置
- 日志中心

### 5.2 租户与套餐模块

用于支撑多租户运营体系：

- 租户管理
- 租户套餐管理
- 租户状态控制
- 租户数据范围控制

### 5.3 业务模块

系统已扩展出业务场景相关模块，例如：

- 生产线
- 产品
- 订单
- 财务记录
- 销售记录
- 库存

这些模块通常遵循统一 CRUD 模式，并结合导入导出、页面配置、实时刷新等能力。

### 5.4 页面配置模块

页面配置用于统一管理前端页面的字段、展示方式和列表/表单配置，便于不同业务页面复用同一套配置逻辑。

### 5.5 全局搜索模块

提供跨模块检索能力，便于管理员快速定位系统中的关键数据或配置项。

### 5.6 实时能力

系统支持实时连接与状态同步，适合用于：

- 实时看板
- 状态更新
- 后台通知
- 运行态监控

### 5.7 通用工具能力

后端还提供了若干通用支撑能力，例如：

- Excel 导入导出
- 请求元数据记录
- IP 与访问上下文处理
- 统一缓存/会话支撑

## 6. 前后端协作方式

### 6.1 前端职责

前端负责：

- 路由与页面布局
- 表单、表格、弹窗等交互
- 权限菜单展示
- 接口调用与结果展示
- 页面配置和实时看板渲染

### 6.2 后端职责

后端负责：

- 提供 REST API
- 执行权限校验与租户隔离
- 维护数据一致性
- 处理导入导出、日志、实时消息
- 统一错误和响应格式

### 6.3 接口风格

接口通常遵循后台管理常见风格：

- 列表查询
- 详情查询
- 新增
- 编辑
- 删除
- 状态更新
- 导入/导出

## 7. 数据访问与开发规范

### 7.1 数据库访问

- 现有连接池和事务封装保持稳定
- 新业务优先使用 `Kysely`
- 旧模块可以逐步迁移，不要求一次性重构

### 7.2 查询规范

业务查询需要考虑：

- 软删除条件
- 租户条件
- 分页与排序
- 模糊搜索
- 条件过滤

### 7.3 代码组织规范

建议新功能按以下结构扩展：

- `controller`：接口入口
- `service`：业务逻辑
- `repository`：数据库访问
- `model`：类型定义
- `routes`：路由注册

## 8. 部署与运行概览

系统通常包含以下运行步骤：

1. 安装依赖
2. 配置环境变量
3. 初始化数据库
4. 启动后端服务
5. 启动前端管理端
6. 通过浏览器登录并验证权限与模块

## 9. 适用角色

BLS 主要面向以下角色：

- 平台管理员
- 租户管理员
- 业务管理员
- 系统维护人员
- 开发与测试人员

## 10. 文档使用建议

如果你是系统维护人员，建议优先阅读：

1. 本文档：了解系统整体结构
2. `bls-server/README.md`：了解后端开发与接入规范
3. `bls-admin/README.md`：了解前端页面组织与能力范围

如果你是开发人员，建议按模块继续补充更细的专题文档，例如：

- 接口文档
- 部署文档
- 权限模型文档
- 多租户设计文档
- 业务模块接入文档

## 其他文档参见

- [CurdTable 及其 hook 封装文档](./CurdTable及其hook封装文档.md)
- [存储桶通用文档](./存储桶通用文档.md)
- [系统多开策略及单开策略文档](./系统多开策略及单开策略文档.md)
- [全局搜索策略文档](./全局搜索技术文档.md)