# 零售AI 租户端
**Repository Path**: neomor/Retail-AI
## Basic Information
- **Project Name**: 零售AI 租户端
- **Description**: RetailAI-Lite 是在 RuoYi-Vue v3.8.9 基础上深度改造的多租户 SaaS 零售 AI 智慧门店系统后端，专为中小零售门店提供 AI 驱动的经营决策支持。本模块也可以独立于saas端运行，支持数据独立
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-05
- **Last Updated**: 2026-08-05
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
RetailAI-Lite Backend
基于 RuoYi-Vue v3.8.9 改造的多租户 SaaS 零售 AI 智慧门店系统后端
## 项目简介
RetailAI-Lite 是在 RuoYi-Vue v3.8.9 基础上深度改造的多租户 SaaS 零售 AI 智慧门店系统后端，专为中小零售门店提供 AI 驱动的经营决策支持。
### 核心特性
- **多租户 SaaS 架构**：动态数据源管理，每个租户独立数据库，数据完全隔离
- **三层权限安全**：门店级数据权限 + 角色级功能权限 + 套餐级付费权限
- **AI 服务集成**：DeepSeek API 驱动的日报/周报生成、订货预测、营销文案生成
- **数据导入引擎**：支持银豹/六讯/中仑等主流收银系统模板解析
- **库存风险智能评估**：多维度风险识别与 AI 建议
- **Flyway 数据库迁移**：版本化管理数据库变更，支持回滚
- **容器化部署**：Docker + Docker Compose 一键部署
## 技术栈
### 后端
- **核心框架**：Spring Boot 2.5.x + Spring Security + Spring Validation
- **多租户数据源**：baomidou dynamic-datasource-spring-boot-starter（动态创建/销毁租户连接池）
- **数据库**：MySQL 8.0 + Flyway 8.x（版本化迁移）
- **缓存**：Redis（JWT Token + 租户数据源缓存 + 限流计数）
- **安全**：JWT + AES-256-GCM（敏感字段加密）+ HMAC-SHA256（签名）
- **AI 服务**：DeepSeek API（日报/周报/文案）+ Prophet（订货预测）
- **工具库**：Hutool 5.x + Lombok + MapStruct
### 前端
- **框架**：Vue 2.6 + Element UI 2.15
- **构建**：Webpack 5
- **状态管理**：Vuex 3
### 容器化
- **Docker**：多阶段构建，生产镜像不含源码
- **Docker Compose**：编排 MySQL + Redis + Backend + Frontend + Prophet Service
## 架构改造亮点
### 1. 多租户数据源管理
```
TenantDataSourceManager
├── 运行时动态创建租户数据库连接池（Druid）
├── 租户登录时注入 tenantId 到 SecurityContext
├── TenantContextFilter 拦截请求注入租户上下文
└── StoreDataInterceptor 强制所有业务 SQL 携带 store_id
```
**关键改造**：
- 移除原 RuoYi 自研 `DynamicDataSource`，改用 baomidou 方案
- 新增 `sys_auth_user` 主库统一认证表（替代原 `sys_user` 承载跨租户登录）
- 新增 `sys_global_username` 全局用户名占用表（注册防重）
- 租户注册流程 7 步：建库 → 建表 → 初始化数据 → 分配角色 → 分配菜单 → 创建用户 → 回调通知
### 2. 三层权限安全
| 层级 | 实现方式 | 说明 |
|------|---------|------|
| 数据权限 | `StoreDataInterceptor` | 所有业务 SQL 强制 `WHERE store_id = ?`，无跨店查询 |
| 角色权限 | Spring Security + 自定义 `DesensitizedUtil` | 店员账号自动脱敏营收敏感数据 |
| 套餐权限 | `PackageAuthAspect` 切面 | 基础版功能前端隐藏 + 后端 403 双拦截 |
### 3. AI 服务层
```
AI Services
├── DeepSeekServiceImpl（DeepSeek API 集成）
│ ├── 日报生成：销售分析 + 异常识别 + AI 建议
│ ├── 周报生成：趋势分析 + 品类洞察 + 经营建议
│ └── 营销文案生成：场景化文案 + 风格定制
├── OrderPredictServiceImpl（订货预测）
│ ├── Prophet 时序预测（调用独立 Prophet 服务）
│ └── 规则引擎混合（库存阈值 + 历史销量 + 风险标签）
└── InventoryRiskServiceImpl（库存风险评估）
├── 多维度风险识别（缺货/滞销/临期/异常）
└── AI 建议生成（补货量/促销策略/调价建议）
```
### 4. 数据导入引擎
```
DataImportServiceImpl
├── TemplateParserFactory（模板识别工厂）
│ ├── YinbaoTemplateParser（银豹销售/库存/会员/收银）
│ ├── SixunTemplateParser（六讯模板）
│ └── ZhonglunTemplateParser（中仑模板）
├── DataCleanEngine（数据清洗）
│ ├── SKU 标准化（去重/合并/分类推断）
│ └── 异常检测（负库存/异常价格/重复订单）
└── ImportLockAspect（防重入锁）
```
## 内置功能
### 系统管理（继承自 RuoYi）
1. 用户管理：系统用户配置，支持多租户隔离
2. 部门管理：组织机构树结构，支持数据权限
3. 岗位管理：用户担任职务配置
4. 菜单管理：动态菜单 + 操作权限 + 按钮权限
5. 角色管理：角色菜单权限 + 数据范围权限
6. 字典管理：系统字典数据维护
7. 参数管理：系统动态参数配置
8. 通知公告：系统公告发布维护
9. 操作日志：系统操作日志记录查询
10. 登录日志：系统登录日志记录查询
11. 在线用户：活跃用户状态监控
12. 定时任务：在线任务调度 + 执行日志
13. 代码生成：前后端代码生成（java/html/xml/sql）
14. 系统接口：Swagger API 文档
15. 服务监控：系统 CPU/内存/磁盘监控
16. 缓存监控：Redis 缓存信息查询
17. 连接池监视：Druid 连接池状态监控
### 多租户管理（新增）
18. 租户管理：租户 CRUD + 数据源生命周期管理
19. 租户注册：6 步注册流程（建库/建表/初始化/角色/菜单/用户）
20. 租户菜单管理：菜单模板 + 租户级覆盖
21. 租户到期扫描：定时任务自动禁用过期租户
22. 开户意愿确认：企业认证 + 法人认证
### 业务功能（新增）
23. 门店管理：门店信息 CRUD + 套餐绑定
24. 数据导入：银豹/六讯/中仑模板导入 + 清洗 + 校验
25. 销售明细：销售数据查询 + 导出 + 统计
26. 库存管理：库存查询 + 预警 + 盘点
27. 库存风险：多维度风险评估 + AI 建议
28. 订货预测：Prophet 时序预测 + 规则引擎
29. AI 日报：每日经营分析 + AI 建议
30. AI 周报：每周趋势分析 + 经营建议
31. 营销文案：场景化文案生成 + 风格定制
32. 收银记录：收银数据查询 + 对账
33. 仪表盘：销售/库存/趋势聚合展示
34. 子账号管理：多账号权限管理
35. 套餐订购：套餐购买 + 到期管理
### AI 服务（新增）
36. DeepSeek 集成：日报/周报/文案生成
37. Prophet 集成：时序预测服务客户端
38. AI 用量追踪：API 调用统计 + 限流
## 数据库架构
### 主库（ry_saas）
- `sys_tenant`：租户注册信息（db_url/db_username/db_password AES 加密）
- `sys_auth_user`：跨租户统一认证用户表
- `sys_global_username`：全局用户名占用表
- `saas_*`：SaaS 主控表（角色模板/菜单模板/套餐定义）
- `ops_*`：运营中台表（迁移至独立服务 saas-ops-service）
### 租户库（tenant_xxx）
- `sys_user`：租户内用户表（登录时同步 sys_auth_user）
- `sys_store`：门店信息表
- `biz_sales_detail`：销售明细
- `biz_inventory`：库存台账
- `biz_inventory_risk`：库存风险
- `biz_order_prediction`：订货预测
- `biz_ai_daily_report`：AI 日报
- `biz_ai_weekly_report`：AI 周报
- `biz_marketing_copy`：营销文案
- `biz_cashier`：收银记录
- `biz_import_log`：导入日志
- `biz_api_usage_log`：AI 用量日志
### 数据库迁移
所有数据库变更通过 Flyway 管理，位于 `ruoyi-admin/src/main/resources/db/migration/`：
```
V20240629.1__init_ry_base.sql # RuoYi 基础表
V20240629.2__init_quartz.sql # Quartz 定时任务表
V20240629.3__init_retail_ai.sql # 零售业务表
V20240629.4__init_saas_master.sql # SaaS 主控表
V20240629.5__init_master.sql # 主库初始化
V20240629.6__init_tenant.sql # 租户库模板
V20240629.7__init_ops.sql # 运营中台表
V20240701~V20240711 # 增量补丁
V20260728~V20260805 # 近期迁移
```
## 安全加固
### P0 阻断项修复
- ✅ 敏感配置外部化（AES_KEY / JWT_SECRET 等通过环境变量注入）
- ✅ 异常信息脱敏（生产环境不返回堆栈信息）
- ✅ 事务 rollbackFor 配置（所有 @Transactional 指定 rollbackFor = Exception.class）
- ✅ 分布式锁防重入（导入/预测等操作加 ImportLock）
- ✅ XSS 校验增强（HTML 上传白名单 + 内容过滤）
- ✅ CORS 配置严格化（生产环境仅允许指定域名）
### 敏感数据加密
- `sys_tenant.db_password`：AES-256-GCM 加密，支持多版本密钥轮换
- `sys_user.password`：BCrypt 加密（继承自 RuoYi）
- API 签名：HMAC-SHA256（内部接口调用）
### 数据脱敏
- 店员账号自动脱敏营收敏感字段（通过 `DesensitizedUtil`）
- 日志脱敏（不记录密码/Token 等敏感信息）
## 快速开始
### 环境要求
- JDK 11+
- Maven 3.6+
- MySQL 8.0+
- Redis 6.0+
- Node.js 14+（前端构建）
- Docker & Docker Compose（推荐）
### Docker Compose 部署（推荐）
```bash
# 克隆项目
git clone https://gitee.com/neomor/retail-ai-lite.git
cd retail-ai-lite
# 配置环境变量
cp .env.example .env
# 编辑 .env 填入必要的配置（AES_KEY / JWT_SECRET / DB_PASSWORD 等）
# 启动所有服务
docker compose up -d
# 查看日志
docker compose logs -f ruoyi-backend
# 访问系统
# 前端：http://localhost:80
# 后端：http://localhost:8080
# 默认账号：tenant_demo / admin / admin123
```
### 本地开发
```bash
# 后端
cd ruoyi
mvn clean install
cd ruoyi-admin
mvn spring-boot:run
# 前端
cd ruoyi-ui
npm install
npm run dev
```
## 项目结构
```
ruoyi/
├── ruoyi-admin/ # 后端主模块
│ ├── src/main/java/
│ │ └── com/ruoyi/web/controller/ # 控制器
│ └── src/main/resources/
│ ├── application.yml # 主配置
│ ├── db/migration/ # Flyway 迁移脚本
│ └── sql/ # SQL 脚本
├── ruoyi-common/ # 公共模块
│ └── src/main/java/
│ ├── constant/ # 常量定义
│ ├── core/domain/ # 领域模型
│ ├── enums/ # 枚举定义
│ └── utils/ # 工具类（AES/HMAC/脱敏等）
├── ruoyi-framework/ # 框架模块
│ └── src/main/java/
│ ├── config/ # 配置类（多租户数据源/安全等）
│ ├── interceptor/ # 拦截器（门店数据权限/租户上下文）
│ └── web/service/ # 登录/注册服务
├── ruoyi-system/ # 系统模块
│ └── src/main/java/
│ ├── service/ # 业务服务
│ │ ├── TenantRegisterService # 租户注册（688 行）
│ │ ├── TenantService # 租户管理（480 行）
│ │ ├── ai/ # AI 服务
│ │ ├── aipredict/ # 订货预测
│ │ ├── aireport/ # AI 日报/周报
│ │ ├── imports/ # 数据导入
│ │ ├── inventory/ # 库存风险
│ │ └── dashboard/ # 仪表盘
│ └── mapper/ # MyBatis Mapper
├── ruoyi-ui/ # 前端
│ ├── src/
│ │ ├── api/ # API 接口
│ │ ├── views/ # 页面组件
│ │ └── utils/ # 工具函数
│ └── dist/ # 构建产物
├── sql/ # SQL 脚本
│ └── tenant_demo_init.sql # 演示租户初始化
├── Dockerfile # 后端容器化
└── pom.xml # Maven 父 POM
```
## 测试覆盖
核心业务测试覆盖率达 60%+，关键模块测试用例：
- `TenantRegisterServiceTest`（698 行）：租户注册流程单元测试
- `TenantRegistrationConcurrencyTest`：并发注册测试
- `TenantRegistrationIntegrationTest`：集成测试
- `DataImportServiceTest`：数据导入测试
- `DataCleanEngineTest`：数据清洗测试
- `OrderPredictServiceTest`：订货预测测试
- `InventoryRiskServiceTest`：库存风险测试
- `AiReportServiceTest`：AI 日报/周报测试
- `AesUtilTest` / `HmacUtilTest`：加密工具测试
- `PackageAuthServiceTest`：套餐权限测试
## 性能优化
- 租户数据源缓存：首次访问创建连接池，缓存 30 分钟
- SQL 优化：所有业务查询强制走索引（store_id + create_time）
- Redis 缓存：菜单/角色/字典等热点数据缓存
- 异步处理：AI 报告生成异步执行，不阻塞主线程
- 分页查询：所有列表查询强制分页，默认 20 条/页
## 监控与运维
- 健康检查：`GET /actuator/health`
- 指标监控：Spring Boot Actuator + Prometheus（可选）
- 日志聚合：logback 配置 JSON 格式日志（可选 ELK）
- 连接池监控：Druid 内置监控页面
## 与 RuoYi-Vue 原版的主要差异
| 项目 | RuoYi-Vue v3.8.9 | RetailAI-Lite |
|------|------------------|---------------|
| 架构 | 单体应用 | 多租户 SaaS |
| 数据源 | 单数据源 + 自研动态数据源 | baomidou dynamic-datasource（动态创建连接池） |
| 用户体系 | sys_user 单表 | sys_auth_user（主） + tenant_xxx.sys_user（租户）双表 |
| 权限 | 角色权限 + 数据权限 | 角色权限 + 数据权限 + 套餐权限（三层） |
| 数据库迁移 | 手动执行 SQL | Flyway 版本化管理 |
| 业务功能 | 通用后台管理 | 零售 AI 专用（导入/预测/日报/周报/文案） |
| AI 服务 | 无 | DeepSeek + Prophet 集成 |
| 安全 | 基础安全 | 增强安全（AES 加密/HMAC 签名/脱敏/限流） |
| 部署 | 手动部署 | Docker Compose 一键部署 |
## 开源协议
本项目基于 RuoYi-Vue 改造，遵循 MIT 协议开源。
- RuoYi-Vue 原版：https://gitee.com/y_project/RuoYi-Vue
- RetailAI-Lite：https://gitee.com/neomor/retail-ai-lite
## 致谢
感谢 RuoYi 团队提供优秀的基础框架，本项目在其基础上进行了深度改造和扩展。