# TimerPOS

**Repository Path**: lamfire/timer-pos

## Basic Information

- **Project Name**: TimerPOS
- **Description**: TimerPOS 是一款专为棋牌室、KTV、网吧等计时场所设计的现代化收银管理系统。它完美结合了 Electron、Vue3 和 FastAPI，提供了一个优雅、高效且易用的解决方案。
特色功能
🎯 实时包房监控
⏱️ 智能计时计费
🛒 商品管理：内置零食饮料管理，支持分类和库存跟踪
📊 数据统计：营收报表、使用率分析，助您做出明智决策
💪 离线可用：本地数据库，无需担心网络问题
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 10
- **Forks**: 4
- **Created**: 2025-02-05
- **Last Updated**: 2025-10-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Python

## README

# 包房计时收银系统 (TimerPOS)

## 系统预览
![系统首页](main.png)

## 项目简介
TimerPOS 是一个专门为包房、KTV、棋牌室等按时计费场所设计的现代化收银管理系统。系统采用 Electron + Vue3 + FastAPI 技术栈开发，提供了包房管理、计时收费、零食销售、营业报表等完整的业务功能。

## 功能特性
- 🏠 包房管理
  - 实时状态监控
  - 灵活的计时计费
  - 多种房间状态显示
  - 可视化房态图
- 🛍️ 商品管理
  - 零食饮品管理
  - 库存跟踪
  - 分类管理
  - 快捷添加商品
- 💰 收银功能
  - 智能计时收费
  - 商品消费
  - 灵活的优惠方案
  - 快速结算
- 📊 数据统计
  - 营业额统计
  - 商品销售分析
  - 包房使用率分析
  - 多维度数据报表
- 👥 用户管理
  - 多用户支持
  - 权限控制
  - 操作日志

## 技术栈
- 前端：Vue 3 + Element Plus
- 桌面端：Electron
- 后端：FastAPI
- 数据库：SQLite
- 构建工具：Vite

## 系统要求
- 操作系统：Windows 7 及以上
- 内存：4GB 及以上
- 硬盘空间：200MB 以上

## 安装说明
请先安装python3.12及nodejs22.13.1
### 快速启动
直接运行项目根目录下的 `startup.bat` 文件，该脚本会自动：
1. 安装前端依赖并构建
2. 配置后端 Python 虚拟环境
3. 启动后端服务
4. 打开系统登录页面

### 手动安装

1. 克隆项目
```bash
git clone [项目地址]
cd timerpos
```

2. 安装前端依赖
```bash
cd frontend
npm install
npm run build
```

3. 安装后端依赖
```bash
cd backend
python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Linux/macOS
pip install -r requirements.txt
```

4. 启动服务
```bash
# 启动后端服务
cd backend
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# 访问系统
打开浏览器访问: http://localhost:8000
```

## 使用指南

### 初始登录
- 默认用户名：admin
- 默认密码：admin

### 主要功能
1. 包房管理
   - 查看所有包房状态
   - 开房/结算操作
   - 添加商品消费
   - 优惠调整

2. 零食管理
   - 商品信息维护
   - 库存管理
   - 价格设置

3. 营业统计
   - 营业额报表
   - 商品销售统计
   - 包房使用分析
   - 数据导出

4. 历史记录
   - 消费订单查询
   - 操作日志查看
   - 数据汇总统计

## 开发指南
- 前端开发遵循 Vue3 组合式 API 规范
- 使用 Element Plus UI 组件库
- 后端采用 FastAPI RESTful 接口规范
- 数据持久化使用 SQLite 数据库

## 项目结构
```
timerpos/
├── frontend/               # 前端项目目录
│   ├── src/               # 源代码
│   │   ├── views/         # 页面组件
│   │   ├── components/    # 通用组件
│   │   ├── api/          # API 接口
│   │   └── store/        # 状态管理
│   └── public/           # 静态资源
├── backend/              # 后端项目目录
│   ├── api/             # API 接口
│   ├── models/          # 数据模型
│   └── utils/           # 工具函数
└── startup.bat          # 快速启动脚本
```

## 注意事项
- 首次使用请修改默认管理员密码
- 定期备份数据库文件
- 保持系统时间准确性
- 及时更新系统依赖



## 更新日志
- v1.0.0 (2024-03)
  - 初始版本发布
  - 完整的包房管理功能
  - 商品销售功能
  - 数据统计报表

## 许可说明
本项目采用 MIT 许可证