# 打牌记账小程序 - 使用说明

## 🚀 快速开始

### 1. 环境准备
- 微信开发者工具
- 后端服务已启动（http://localhost:3000）

### 2. 导入项目
1. 打开微信开发者工具
2. 导入项目，选择 `miniapp` 目录
3. AppID 使用测试号或实际AppID

### 3. 安装依赖
```bash
cd miniapp
npm install
```

在微信开发者工具中：
- 工具 > 构建 npm

### 4. 修改配置
如果后端不在localhost:3000，修改：
- `app.js` 中的 `apiBase`
- `utils/request.js` 中的 `API_BASE`

## 📱 功能说明

### 已实现功能
1. **用户登录** - 首页点击登录按钮
2. **首页展示**
   - 用户信息卡片
   - 快速操作入口
   - 进行中的牌局列表

### 核心页面
| 页面 | 路径 | 功能 |
|------|------|------|
| 首页 | pages/index/index | 登录、快速操作、牌局列表 |
| 创建牌局 | pages/game/create/create | 创建新牌局 |
| 加入牌局 | pages/game/join/join | 输入邀请码加入 |
| 牌局详情 | pages/game/detail/detail | 查看牌局信息 |
| 游戏进行 | pages/game/play/play | 记账功能 |
| 个人统计 | pages/stats/personal/personal | 战绩统计 |
| 个人中心 | pages/profile/index/index | 个人信息 |

## 🎮 使用流程

### 1. 登录流程
```
打开小程序 → 首页 → 点击登录 → 授权用户信息 → 登录成功
```

### 2. 创建牌局
```
首页 → 创建牌局 → 填写信息 → 生成邀请码 → 分享给朋友
```

### 3. 加入牌局
```
首页 → 加入牌局 → 输入邀请码 → 加入成功 → 进入牌局
```

### 4. 记账流程
```
牌局详情 → 开始游戏 → 记一笔 → 输入输赢金额 → 保存
```

## 🔧 API调用示例

### 登录
```javascript
const app = getApp()
await app.login()
```

### 创建牌局
```javascript
import request from '../../utils/request'

const data = await request.post('/sessions/create', {
  session_name: '周五麻将',
  game_type: 'mahjong',
  base_score: 100,
  player_count: 4
})
```

### 记录游戏
```javascript
const data = await request.post('/records/add', {
  session_id: 1,
  dealer_id: 1,
  player_records: [
    { player_id: 1, score_change: 300 },
    { player_id: 2, score_change: -100 },
    { player_id: 3, score_change: -100 },
    { player_id: 4, score_change: -100 }
  ],
  notes: '张三自摸'
})
```

## 📝 注意事项

1. **登录状态** - Token保存在Storage，24小时有效
2. **数据刷新** - onShow时自动刷新数据
3. **错误处理** - 网络错误自动提示
4. **金额单位** - 后端使用分，前端显示元

## 🐛 常见问题

### 1. 无法登录
- 检查后端服务是否启动
- 检查网络连接
- 清除缓存重试

### 2. 请求失败
- 检查API地址配置
- 查看控制台错误信息
- 验证Token是否过期

### 3. 页面空白
- 重新构建npm
- 检查页面路径配置
- 查看编译错误

## 📂 项目结构
```
miniapp/
├── pages/                # 页面文件
│   ├── index/           # 首页
│   ├── game/            # 游戏相关
│   │   ├── create/      # 创建牌局
│   │   ├── join/        # 加入牌局
│   │   ├── detail/      # 牌局详情
│   │   └── play/        # 游戏进行
│   ├── stats/           # 统计相关
│   └── profile/         # 个人中心
├── utils/               # 工具函数
│   ├── request.js       # 请求封装
│   └── format.js        # 格式化工具
├── images/              # 图片资源
├── app.js              # 应用入口
├── app.json            # 应用配置
└── app.wxss            # 全局样式
```

## 🎯 下一步开发

### 待实现功能
1. 实时同步（WebSocket）
2. 结算功能
3. 数据图表展示
4. 语音记账
5. 拍照记录
6. 导出报表

### 优化建议
1. 添加骨架屏
2. 优化加载动画
3. 添加下拉刷新
4. 缓存优化
5. 错误重试机制

## 📞 技术支持

如需帮助，请参考：
- [后端README](../BACKEND_README.md)
- [系统架构文档](../SYSTEM_ARCHITECTURE.md)
- [API设计文档](../API_DESIGN.md)