# game-ledger-mp

**Repository Path**: frankch02/game-ledger-mp

## Basic Information

- **Project Name**: game-ledger-mp
- **Description**: 打牌计分小程序
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-06-01
- **Last Updated**: 2026-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 聚牌小程序

聚牌小程序 - 多人实时协作记账 + 自动结算 + 零门槛使用

## 项目结构

```
card-game-ledger/
├── cloudfunctions/          # 云函数目录
│   ├── login/              # 用户登录与自动注册
│   ├── updateUserInfo/     # 更新用户信息
│   ├── createRoom/         # 创建房间
│   ├── joinRoom/           # 加入房间
│   ├── getRoomDetail/      # 获取房间详情
│   ├── addPlayer/          # 添加玩家
│   ├── removePlayer/       # 移除玩家
│   ├── recordRound/        # 记录局
│   ├── deleteRecord/       # 删除记录
│   ├── settleRoom/         # 结算房间
│   ├── getMyRooms/         # 获取我的房间列表
│   └── getRoomHistory/     # 获取历史记录
├── miniprogram/             # 小程序前端
│   ├── pages/
│   │   ├── index/          # 首页
│   │   ├── room/           # 房间内页
│   │   ├── room/create/    # 创建房间
│   │   ├── record/         # 记录本局
│   │   ├── settle/         # 结算页
│   │   ├── mine/           # 我的页面
│   │   └── history/detail/ # 牌局详情
│   ├── components/          # 自定义组件
│   ├── utils/               # 工具函数
│   ├── app.js              # 应用入口
│   ├── app.json            # 应用配置
│   └── app.wxss            # 全局样式
└── project.config.json      # 项目配置
```

## 开发环境

- 微信开发者工具：最新版本
- 基础库版本：2.19.0+
- Node.js：14.x+

## 快速开始

### 1. 配置环境变量

在 `miniprogram/app.js` 中配置云开发环境 ID：

```javascript
wx.cloud.init({
  env: 'your-env-id', // 替换为你的云开发环境 ID
  traceUser: true
})
```

### 2. 上传云函数

在微信开发者工具中：

1. 右键点击 `cloudfunctions` 目录
2. 选择"云函数入口文件"确认每个云函数的入口
3. 右键点击每个云函数文件夹，选择"上传并部署：云端安装依赖"

或在终端中批量上传：

```bash
cd cloudfunctions
for dir in */; do
  cd "$dir"
  npm install
  cd ..
done
```

### 3. 配置数据库

在微信开发者工具中：

1. 打开"云开发"控制台
2. 创建以下集合：
   - `users` - 用户表
   - `rooms` - 房间表

3. 设置数据库权限：

**users 集合权限：**
```json
{
  "read": "auth.openid == doc.openId",
  "write": "auth.openid == doc.openId"
}
```

**rooms 集合权限：**
```json
{
  "read": true,
  "write": "auth.openid == doc.createBy || auth.openid in doc.players[*].openId"
}
```

4. 创建索引：
   - `users.openId` - 唯一索引
   - `rooms.roomId` - 唯一索引
   - `rooms.createBy` - 普通索引
   - `rooms.status` - 普通索引

### 4. 配置 AppID

在 `project.config.json` 中填入你的小程序 AppID：

```json
{
  "appid": "wx1234567890abcdef",
  "projectname": "card-game-ledger"
}
```

### 5. 编译运行

在微信开发者工具中点击"编译"按钮即可运行。

## 功能模块

### 用户系统
- 微信静默登录（自动生成昵称）
- 修改昵称
- 查看历史牌局

### 房间管理
- 创建房间（生成 6 位数字房间号）
- 加入房间（输入房间号或扫码）
- 添加/移除玩家
- 正在进行的牌局列表

### 记账功能
- 记录每局输赢
- 实时计算总分
- 总分校验（必须为 0）
- 编辑/删除记录

### 结算功能
- 自动结算
- 最小转账次数算法
- 生成结算单

## 核心功能说明

### 登录流程

1. 小程序启动时自动调用 `login` 云函数
2. 云函数获取用户 openId
3. 如果是新用户，自动生成昵称（"牌友 XXXX"格式）并创建用户记录
4. 用户信息缓存在本地 Storage

### 最小转账算法

```javascript
输入：A 赢 120，B 输 50，C 输 30，D 输 40
输出：
  B → A: 50
  C → A: 30
  D → A: 40
总计：3 笔
```

算法原理：
1. 分为两组：赢家（正分），输家（负分）
2. 贪心匹配：每次从赢家和输家各取一人
3. 转账金额 = min(赢家余额，|输家欠款|)
4. 更新余额，归零则换下一人
5. 重复直到所有人归零

## 部署上线

### 1. 开通微信云开发

1. 在微信开发者工具中点击"云开发"按钮
2. 开通云开发服务（免费版即可）
3. 记录环境 ID

### 2. 上传代码

1. 在微信开发者工具中点击"上传"
2. 填写版本号和备注
3. 等待上传完成

### 3. 提交审核

1. 登录 [微信公众平台](https://mp.weixin.qq.com)
2. 在"版本管理"中选择刚上传的版本
3. 提交审核

### 4. 广告接入（UV 达标后）

当 UV ≥ 1000 时：

1. 在微信公众平台开通"流量主"
2. 创建广告位（Banner、激励视频、插屏）
3. 在 `app.js` 中配置广告 ID
4. 将 `adConfig.isEnabled` 设为 `true`

## 技术栈

- **前端**：微信小程序原生开发（WXML/WXSS/JavaScript）
- **后端**：微信云开发（云函数 + 云数据库 + 云存储）
- **算法**：贪心算法（最小转账次数）

## 注意事项

1. **隐私保护**：
   - 不收集用户手机号、地理位置等敏感信息
   - 仅使用 openId 标识用户身份

2. **性能优化**：
   - 使用云数据库 watch 实现实时同步
   - 分页加载历史记录
   - 事务处理保证数据一致性

3. **安全规则**：
   - 数据库权限严格控制
   - 云函数自动校验用户身份
   - 输入数据严格验证

## 版本规划

- **v1.0**：MVP 版本（当前版本）
- **v1.1**：广告接入
- **v2.0**：云端同步 + 多设备协作
- **v2.1**：数据统计
- **v3.0**：社交功能

## 许可证

MIT License