# CardRoomPro

**Repository Path**: qfmx/CardRoomPro

## Basic Information

- **Project Name**: CardRoomPro
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-25
- **Last Updated**: 2026-08-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 棋牌室押金管理系统

简单、方便的棋牌室押金 / 台费管理。

技术栈：Spring Boot 2.7 + MyBatis + Druid + MySQL / Vue 3 + Element Plus

## 功能

- **台位总览**：一个界面看所有台。每台显示所有玩家：姓名、开始时间、押金状态（如 `张三 13:20，押金200` / `李四 14:20，无支付押金，手动填写`）。
- **台数可页面增减**：顶部「添加台」新增；卡片右上角 × 或抽屉内「删除该台」删除（仅空台可删）。初始 13 台，之后增删不会被重启复原。
- **维修暂停**：抽屉内「设为维修暂停 / 恢复使用」。维修台橙色标记，禁止添加玩家。
- **单人计时**：不需要 4 人同时付押金，有人付钱（或手动登记）即开始计时。点开任意一台可看该台所有玩家信息（开始时间、是否付押金）。
- **全桌无人扫码 / 手动填写**：空闲台点击进入，添加玩家（可勾选「手动填写」表示未扫码支付）。
- **押金扣除退款**：点「结算退款」自动算台费（时长 × 费率，不足 1 小时按 1 小时）、扣多少、退多少。金额可手动修改，确认后记录台费收入并退还押金。
- **个人 / 财务**：总台费收入、已退押金、已提现、可提现余额、提现操作、完整流水。

## 目录结构

```
CardRoomPro/
  backend/                       Spring Boot 后端（端口 8080）
    src/main/java/com/cardroom/
      entity/                    实体（POJO）
      mapper/                    MyBatis Mapper（注解式 SQL，无 XML）
      service/                   业务逻辑
      controller/                REST 接口
      config/                    初始化 / 跨域 / 全局异常
    src/main/resources/
      application.yml            MySQL + Druid 主配置
      application-h2.yml         H2 备用配置（本机无 MySQL 时）
      schema-mysql.sql           MySQL 建表脚本（启动自动执行）
      schema-h2.sql              H2 建表脚本
  frontend/                      Vue 3 前端（端口 5173）
```

## 启动方式

### 0. 准备 MySQL

需要 MySQL 5.7+ / 8.x。默认连接配置在 `backend/src/main/resources/application.yml`：

```yaml
url: jdbc:mysql://localhost:3306/cardroom?...&createDatabaseIfNotExist=true
username: root
password: 123456
```

**请把 `username` / `password` 改成你自己的 MySQL 账号密码。**
库自动创建（`createDatabaseIfNotExist=true`），表由 `schema-mysql.sql` 启动时自动建（`CREATE TABLE IF NOT EXISTS`，不会覆盖已有数据）。

### 1. 后端（需要 JDK 8 + Maven）

```bash
cd backend
mvn spring-boot:run
```

启动后自动创建 13 个台。台数之后完全由页面增删控制，重启不会复原。

**Druid 监控页**：http://localhost:8080/druid — 账号 `admin` / 密码 `admin123`（可在 `application.yml` 修改）。能看 SQL 执行次数、慢 SQL、连接池状态。

> 本机没装 MySQL 想先试跑？用 H2 profile 启动：
> `mvn spring-boot:run -Dspring-boot.run.profiles=h2`
> （数据存 `backend/data/cardroom.mv.db`，H2 控制台 http://localhost:8080/h2-console ）
>
> 内存不足启动失败时，可先打包再跑：
> `mvn package -DskipTests && java -jar target/cardroom-backend-1.0.0.jar`

### 2. 前端（需要 Node 18+）

```bash
cd frontend
npm install
npm run dev
```

打开 http://localhost:5173 即可使用（前端已配置 `/api` 代理到 8080）。

## 默认配置（`backend/src/main/resources/application.yml`）

- 台数：13
- 默认费率：5 元/小时（每台可单独在「费率设置」修改）
- 默认押金：200 元

## 主要接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/tables` | 台位总览 |
| POST | `/api/tables` | 新增一个台 |
| DELETE | `/api/tables/{id}` | 删除一个台（需空台） |
| PUT | `/api/tables/{id}` | 修改费率 / 默认押金 |
| PUT | `/api/tables/{id}/status` | 设维修暂停 / 恢复使用 |
| DELETE | `/api/tables/{id}/clear` | 一键清台 |
| POST | `/api/players/table/{tableId}` | 添加玩家（扫码/手动） |
| PUT | `/api/players/{id}` | 修改玩家 |
| DELETE | `/api/players/{id}` | 删除玩家 |
| GET | `/api/players/{id}/checkout/preview` | 结算预览（自动算台费/退款） |
| POST | `/api/players/{id}/checkout` | 确认结算（金额可改） |
| GET | `/api/finance` | 财务汇总 |
| POST | `/api/finance/withdraw` | 提现 |