172 lines
4.1 KiB
Markdown
172 lines
4.1 KiB
Markdown
# 打牌记账小程序 - 使用说明
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 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) |