# JCSoft.StoreHelper

**Repository Path**: jamesying/JCSoft.StoreHelper

## Basic Information

- **Project Name**: JCSoft.StoreHelper
- **Description**: 🔥🔥🔥 Admin.NET 基于 .NET 6/8 (Furion/SqlSugar) 实现的通用权限开发框架，前端采用 Vue3/Element-plus，代码简洁、易扩展。整合最新技术，模块插件式开发，前后端分离，开箱即用。集成多租户、缓存、数据校验、鉴权、事件总线、动态API、通讯、远程请求、任务调度、打印等众多黑科技。让开发更简单、更通用、更流行！
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: v2
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 3593
- **Created**: 2025-10-22
- **Last Updated**: 2025-11-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# JCSoft.StoreHelper - 门店客流管理系统（客流通）

<div align="center">

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![.NET](https://img.shields.io/badge/.NET-8.0-purple.svg)
![Vue](https://img.shields.io/badge/Vue-3.x-green.svg)
![Element Plus](https://img.shields.io/badge/Element%20Plus-2.x-blue.svg)

一款面向零售企业的智能门店客流管理系统，通过精准的客流数据采集和多维度分析，帮助门店优化运营策略、提升客户转化率与整体业绩。

</div>

## 📋 目录

- [项目概述](#-项目概述)
- [核心特性](#-核心特性)
- [技术栈](#-技术栈)
- [快速开始](#-快速开始)
- [功能模块](#-功能模块)
- [系统架构](#-系统架构)
- [部署指南](#-部署指南)
- [贡献指南](#-贡献指南)
- [许可证](#-许可证)

## 🎯 项目概述

**客流通** 是一款面向零售企业的智能门店客流管理系统，核心价值是通过精准的客流数据采集、多维度分析，帮助门店优化运营策略、提升客户转化率与整体业绩。系统支持单门店到多连锁门店的规模化管理，兼顾 Web 端数据可视化与移动端轻量化操作。

### 核心目标

- 🎯 **实时统计**：实时、精准统计门店进出客流数据，解决"客流看不见、分析难"的痛点
- 📊 **智能分析**：提供可视化报表与智能分析，辅助门店决策（如人员排班、促销活动效果评估）
- 🏪 **多店管理**：支持多门店集中管理，满足连锁企业规模化运营需求
- 🔒 **数据安全**：保障数据安全，提供稳定、高效的系统服务（可用性≥99.9%）

### 目标用户

- **零售门店经营者**（店长、区域经理）：查看门店客流数据、优化运营
- **企业总部管理人员**：监控多门店数据、制定整体策略
- **系统管理员**：维护账号权限、设备配置、数据备份

## ✨ 核心特性

- 🔄 **实时数据采集**：支持多种设备接入（摄像头、红外传感器）
- 📈 **多维度分析**：日/周/月/季度趋势分析，客流来源分布
- 🎨 **可视化报表**：丰富的图表展示，支持自定义报表生成
- 🏢 **多门店管理**：层级化门店管理，设备状态实时监控
- 👥 **权限管理**：基于RBAC模型的角色权限控制
- 📱 **响应式设计**：支持PC端和移动端访问
- 🔐 **安全保障**：JWT认证，数据加密传输
- 📋 **操作日志**：完整的系统操作日志记录

## 🛠 技术栈

### 后端技术
- **.NET 8.0** - 主框架
- **Admin.NET** - 基础框架
- **SqlSugar** - ORM框架
- **SignalR** - 实时通信
- **JWT** - 身份认证
- **Redis** - 缓存服务
- **MySQL/SQL Server** - 数据库

### 前端技术
- **Vue 3** - 前端框架
- **TypeScript** - 类型支持
- **Element Plus** - UI组件库
- **ECharts** - 图表库
- **Vite** - 构建工具
- **Pinia** - 状态管理

## 🚀 快速开始

### 环境要求

- .NET 8.0 SDK
- Node.js 18+
- MySQL 8.0+ 或 SQL Server 2019+
- Redis 6.0+

### 安装步骤

1. **克隆项目**
```bash
git clone https://github.com/your-username/JCSoft.StoreHelper.git
cd JCSoft.StoreHelper
```

2. **后端配置**
```bash
cd Admin.NET
# 修改数据库连接字符串
# 编辑 Admin.NET.Web.Entry/appsettings.json

# 运行数据库迁移
dotnet ef database update

# 启动后端服务
dotnet run --project Admin.NET.Web.Entry
```

3. **前端配置**
```bash
cd Web
# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

4. **访问系统**
- 前端地址：http://localhost:5173
- 后端API：http://localhost:5000
- 默认账号：admin / 123456

## 📦 功能模块

### 核心功能模块

| 模块名称 | 核心功能点 | 业务价值 |
|---------|-----------|----------|
| **客流数据采集** | • 实时统计进出店人数<br>• 记录客户停留时长<br>• 识别新老客户比例<br>• 多设备数据接入 | 为后续分析提供精准、实时的原始数据，避免人工统计误差 |
| **数据分析与报表** | • 多维度趋势分析<br>• 客流来源分布<br>• 客户转化率计算<br>• 自定义报表生成与导出 | 从数据中挖掘经营规律，辅助决策 |
| **门店管理** | • 门店基础信息维护<br>• 多门店层级管理<br>• 门店设备状态监控 | 满足连锁企业规模化管理需求，实时掌握各门店运营状态 |
| **系统管理** | • 用户账号管理<br>• 角色与权限配置<br>• 系统日志记录<br>• 数据备份与恢复 | 保障系统安全、可追溯，避免权限滥用或数据丢失 |

### 前端界面模块

#### 🔐 登录与权限校验
- **核心元素**：用户名输入框、密码输入框（加密传输）、验证码、"记住密码"选项、"忘记密码"链接、登录按钮
- **逻辑规则**：密码错误3次锁定账号15分钟，登录成功后生成JWT令牌（有效期2小时），无权限访问页面自动跳转登录页

#### 📊 仪表盘（首页）
**布局结构：**
- **顶部**：系统标题、用户信息（头像/姓名）、通知中心（设备告警、数据异常提醒）、退出登录按钮
- **左侧**：导航菜单（可折叠）
- **主区域**：
  - 数据卡片：今日客流总数、同比增长率、平均停留时长、新客户占比
  - 折线图：今日每小时客流趋势（支持hover查看具体数值）
  - 排行榜：各门店今日客流TOP5（柱状图）
  - 告警提示：离线设备数量、异常数据记录（点击跳转详情页）

#### 📈 数据报表中心
**功能交互：**
- **筛选区**：时间范围（今日/昨日/近7天/自定义）、门店选择（单门店/多门店对比）、数据维度（客流总数/来源/转化率）
- **图表区**：支持切换图表类型（折线图/柱状图/饼图/热力图），支持拖拽调整大小
- **操作区**：导出（Excel/PDF）、打印、分享（生成临时链接）、保存为"常用报表"
- **数据表格**：展示详细数据列表（支持分页、排序、搜索）

#### 🏪 门店管理页
- **门店列表页**：展示所有门店（名称、地址、负责人、状态、设备数量），支持搜索、筛选（按区域/状态）、新增/编辑/删除门店
- **门店详情页**：
  - 基础信息：门店基本配置（可编辑）
  - 设备列表：展示该门店所有采集设备（型号、IP地址、状态、安装时间），支持设备重启、配置修改、解绑
  - 客流概览：该门店近30天客流趋势图

#### ⚙️ 系统设置页
- **个人设置**：修改密码、更新头像、配置通知偏好（邮件/短信告警）
- **权限管理**：角色创建/编辑（分配权限）、用户关联角色
- **日志查询**：按时间/用户/操作类型筛选日志，支持导出
- **数据备份**：手动触发备份、设置自动备份周期（每日凌晨2点）

## 🏗 系统架构

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   前端展示层     │    │   API网关层     │    │   业务逻辑层     │
│                │    │                │    │                │
│  Vue 3 + TS    │◄──►│  Admin.NET     │◄──►│  .NET 8.0      │
│  Element Plus  │    │  JWT认证       │    │  SqlSugar ORM  │
│  ECharts       │    │  权限控制       │    │  SignalR       │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                       │
                       ┌─────────────────┐    ┌─────────────────┐
                       │   缓存层        │    │   数据存储层     │
                       │                │    │                │
                       │  Redis         │◄──►│  MySQL/SQL     │
                       │  分布式缓存     │    │  Server        │
                       └─────────────────┘    └─────────────────┘
```

## 📚 部署指南

### Docker 部署

1. **使用 Docker Compose**
```bash
# 进入docker目录
cd docker

# 启动所有服务
docker-compose up -d
```

2. **单独部署**
```bash
# 构建后端镜像
docker build -t storehelper-api ./Admin.NET

# 构建前端镜像
docker build -t storehelper-web ./Web

# 运行容器
docker run -d -p 5000:80 storehelper-api
docker run -d -p 3000:80 storehelper-web
```

### 生产环境部署

1. **服务器要求**
   - CPU: 2核心以上
   - 内存: 4GB以上
   - 存储: 50GB以上
   - 操作系统: Linux/Windows Server

2. **数据库配置**
   - 建议使用MySQL 8.0+或SQL Server 2019+
   - 配置主从复制确保数据安全
   - 定期备份数据库

3. **负载均衡**
   - 使用Nginx进行反向代理
   - 配置SSL证书确保HTTPS访问
   - 设置健康检查

## 🤝 贡献指南

我们欢迎所有形式的贡献！请遵循以下步骤：

### 开发流程

1. **Fork 项目**
```bash
git clone https://github.com/your-username/JCSoft.StoreHelper.git
cd JCSoft.StoreHelper
```

2. **创建功能分支**
```bash
git checkout -b feature/your-feature-name
```

3. **提交更改**
```bash
git add .
git commit -m "feat: 添加新功能描述"
```

4. **推送分支**
```bash
git push origin feature/your-feature-name
```

5. **创建 Pull Request**

### 代码规范

- **后端**：遵循 .NET 编码规范，使用 EditorConfig
- **前端**：遵循 Vue 3 + TypeScript 最佳实践
- **提交信息**：使用 [Conventional Commits](https://conventionalcommits.org/) 规范

### 问题反馈

- 🐛 **Bug报告**：使用 [Bug模板](https://github.com/your-username/JCSoft.StoreHelper/issues/new?template=bug.yml)
- 💡 **功能建议**：使用 [功能模板](https://github.com/your-username/JCSoft.StoreHelper/issues/new?template=feature.yml)

## 📄 许可证

本项目基于 [MIT License](LICENSE) 开源协议。

```
MIT License

Copyright (c) 2024 JCSoft

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

## 🙏 致谢

- [Admin.NET](https://gitee.com/zuohuaijun/Admin.NET) - 提供了优秀的基础框架
- [Vue.js](https://vuejs.org/) - 强大的前端框架
- [Element Plus](https://element-plus.org/) - 优秀的UI组件库
- [ECharts](https://echarts.apache.org/) - 专业的数据可视化库

## 📞 联系我们

- 📧 邮箱：support@jcsoft.com
- 🌐 官网：https://www.jcsoft.com
- 📱 QQ群：123456789

---

<div align="center">

**如果这个项目对您有帮助，请给我们一个 ⭐️**

Made with ❤️ by JCSoft Team

</div>