# card-account

**Repository Path**: AaronGitee/card-account

## Basic Information

- **Project Name**: card-account
- **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-17
- **Last Updated**: 2026-09-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 牌局记账（极简版）

面向线下熟人牌局（麻将、斗地主、德州扑克等）的轻量计分微信小程序。
无需注册、微信一键登录、3 秒创建 / 加入房间、实时计分、零和规则自动校验、历史牌局永久留存。

## 技术栈

- 后端：Spring Boot 2.7 + MyBatis-Plus 3.5 + MySQL 8.0 + JWT + Redis（令牌缓存 / 防重复提交 / 分布式锁）
- 前端：UniApp + Vue3（Composition API）+ SCSS（rpx 自适应），编译为微信小程序
- 构建：Maven 3.9+ / Node 18+

## 目录结构

```
card-account/
├── backend/            # Spring Boot 后端
│   └── src/main/java/com/card/account/
│       ├── controller/ # Auth / User / Room 三组 REST 接口
│       ├── service/    # 用户登录、房间与计分核心逻辑（零和校验在此）
│       ├── entity/     # user / room / room_member / game_round / round_score
│       ├── security/   # JWT 工具、拦截器、令牌缓存（Redis / 内存双实现）
│       └── common/     # 统一响应、业务异常、全局异常处理
├── frontend/           # UniApp Vue3 前端（src 为源码目录）
│   └── src/pages/      # index / room(create,join,detail,invite,score,ranking,result,rounds) / history / profile / settings
└── sql/schema.sql      # MySQL 建库建表脚本
```

## 快速启动

### 1. 初始化数据库

```bash
mysql -uroot -p < sql/schema.sql
```

### 2. 启动后端

修改 `backend/src/main/resources/application.yml`：

- `spring.datasource`：数据库地址、账号、密码
- `spring.redis`：Redis 地址（无 Redis 时将 `app.cache.type` 改为 `simple` 使用内存缓存）
- `app.wechat.appid / secret`：微信小程序凭证；**留空时自动启用开发模拟登录**（任意 code 可登录，方便本地联调）
- `app.jwt.secret`：生产环境务必替换为复杂随机串

```bash
cd backend
mvn spring-boot:run
# 或打包：mvn clean package -DskipTests && java -jar target/card-account.jar
```

接口根路径：`http://localhost:8080/api`

### 3. 启动前端

```bash
cd frontend
npm install
npm run dev:mp-weixin     # 开发模式，产物在 dist/dev/mp-weixin
npm run build:mp-weixin   # 生产构建，产物在 dist/build/mp-weixin
```

微信开发者工具导入 `dist/dev/mp-weixin` 目录，填入小程序 AppID（测试号亦可），勾选「不校验合法域名」。
联调地址在 `frontend/src/utils/config.js` 中修改（默认 `http://localhost:8080/api`）。

## 核心接口

| 方法 | 路径 | 说明 |
| ---- | ---- | ---- |
| POST | /api/auth/wx-login | 微信一键登录，返回 JWT |
| GET/PUT | /api/user/info / /api/user/profile | 用户信息查询 / 修改 |
| POST | /api/room/create | 创建房间（房主自动入座，生成 6 位房间号） |
| POST | /api/room/join | 房间号加入（校验状态与人数上限） |
| GET | /api/room/{id} | 房间详情（成员 + 累计积分） |
| POST | /api/room/{id}/round | 提交一局记分（**零和模式强制总分=0**，防重复提交） |
| GET | /api/room/{id}/rounds | 全部对局明细 |
| GET | /api/room/{id}/ranking | 当前排行榜 |
| POST | /api/room/{id}/finish | 结束牌局（仅房主） |
| GET | /api/room/{id}/result | 结算页数据（总局数 / 人数 / 时长 / 排名） |
| GET | /api/room/my?status= | 我的牌局；status=1 为历史已结束牌局 |

## 项目文档

- [docs/REQUIREMENTS.md](docs/REQUIREMENTS.md)：需求与功能对照表、裁剪执行记录、视觉规范、已知偏差
- [docs/API.md](docs/API.md)：完整接口文档（请求/响应示例、错误码）
- [docs/TEST-REPORT.md](docs/TEST-REPORT.md)：42 项功能测试报告与漏洞修复记录
- [docs/DEPLOY.md](docs/DEPLOY.md)：本地启动、回归测试、生产上线清单、优化建议

## 回归测试

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\api-test.ps1
```

42 项接口级用例（认证/校验/零和/并发/越权/结算/注入），当前全部通过。

## MVP 功能裁剪说明

- 个人中心仅保留：基础用户信息、我的牌局、设置（已删除 VIP / 常用好友 / 账单统计）
- 历史牌局页仅保留：历史牌局列表（已删除终身总积分等统计项）
- 全局无好友系统、会员充值、钱包、商城、社区、账单分析等非 MVP 功能