# billiards_wx_app

**Repository Path**: oftenlin/billiards_wx_app

## Basic Information

- **Project Name**: billiards_wx_app
- **Description**: 球准猩台球微信小程序
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-11
- **Last Updated**: 2025-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 台球厅智能管理小程序

## 目录结构

```
├── pages/                # 页面目录，按功能模块分子目录
├── components/           # 公共组件，每个组件独立目录
├── api/                  # API请求相关
├── util/                 # 通用工具函数
├── enum/                 # 枚举值
├── common/               # 通用业务逻辑
├── images/               # 图片资源
├── custom-tab-bar/       # 自定义底部TabBar
├── mock/                 # Mock数据
├── miniprogram_npm/      # 小程序NPM构建产物
├── unocss.config.js      # UnoCSS配置
├── unocss.wxss           # UnoCSS生成样式
├── package.json          # NPM依赖声明
├── jsconfig.json         # JS开发体验增强
├── app.json              # 小程序全局配置
├── project.config.json   # 小程序项目配置
└── README.md             # 项目说明文档
```

---

# 台球厅AI管理系统 - 微信小程序子系统需求文档

## 项目背景
本项目是台球厅智能管理系统的一部分，通过安装在台球厅上方的摄像头结合AI算法进行台球状态判定。微信小程序作为用户端子系统，主要功能是通过扫描二维码与球局关联，为用户提供历史成绩查看和精彩集锦回放服务。

## 系统架构
- **硬件系统**: 台球厅上方摄像头设备
- **AI算法**: 台球状态识别和判定
- **后端系统**: 数据处理和存储
- **小程序**: 用户端应用（本文档范围）

## 核心功能需求

### 1. 对局管理系统
- **历史对局**
  - 对局记录列表展示
  - 球厅和球桌信息
  - VS界面显示比分
  - 对局时间和用时统计
  - 对手信息展示

- **历史对手**
  - 与不同对手的对战记录
  - 对手胜负统计

- **当前对局**
  - 实时对局状态
  - 当前比分显示

- **筛选功能**
  - 按日期筛选对局
  - 按门店查找记录

### 2. AI精彩集锦系统
- **智能视频生成**
  - AI自动识别精彩进球片段
  - 智能剪辑生成短视频
  - 按局数分类整理

- **视频管理**
  - 视频缩略图展示
  - 时长显示
  - 90天保存期限制
  - 过期自动清理提醒

- **球号标记系统**
  - 1-15号球的圆点选择器
  - 标记精彩球的具体球号
  - 按球号筛选精彩片段

- **视频下载**
  - "精剪下载"功能
  - 本地保存精彩片段

### 3. AI战绩榜系统
- **排行榜功能**
  - 每日6:00自动更新
  - 前三名特殊展示（皇冠标识）
  - 全国范围排名

- **多维度统计**
  - 总战绩排行
  - 清台专项排行
  - 3连杆技巧排行
  - 进球数据排行

- **时间维度**
  - 上周数据统计
  - 本周数据统计
  - 总榜历史统计

- **地区筛选**
  - 全国数据
  - 地区下拉选择

### 4. 个人数据统计系统
- **核心数据**
  - 个人胜率计算
  - 总局数统计
  - 胜负场次记录
  - 战绩周榜排名

- **出杆数据分析**
  - 进球率统计（圆形进度条展示）
  - 总杆数统计
  - 进球数统计
  - 出杆平均用时

- **清台技术统计**
  - 一杆清台次数
  - 炸清次数和成功率
  - 接清次数和成功率

- **技巧球统计**
  - 连杆技巧次数
  - 牙轮技巧次数
  - 饼图可视化展示

### 5. 用户系统
- **用户管理**
  - 微信授权登录
  - 用户头像和昵称
  - 个人资料编辑
  - 账号退出功能

### 6. 二维码扫描功能
- **扫码关联**
  - 台球桌二维码识别
  - 球局身份关联
  - 实时数据同步

## 技术架构需求

### 1. 小程序端技术栈
- **框架**: 微信小程序原生开发
- **UI库**: WeUI
- **网络请求**: wx.request
- **扫码功能**: wx.scanCode
- **视频播放**: video组件

### 2. 接口对接
- **后端API**: RESTful接口
- **数据格式**: JSON
- **认证方式**: 微信登录授权
- **实时通信**: WebSocket（可选）

### 3. 数据存储
- **本地存储**: wx.setStorage
- **用户数据**: 云端同步
- **视频缓存**: 临时文件管理

## 界面设计需求

### 1. 对局页面（历史对局）
- **顶部切换栏**
  - 历史对局
  - 历史对手  
  - 当前对局
- **筛选功能**
  - 选择日期
  - 门店查找
- **对局记录展示**
  - 球厅名称和球桌信息
  - 对局时间
  - 比分结果（VS界面）
  - 对局用时
  - 对手信息（头像、昵称）

### 2. AI精彩秀页面
- **页面头部**
  - 标题："AI精彩秀"
  - 副标题："智能生成精彩进球剪辑视频"
  - 提醒信息："视频可保存90天，过期无法查看/下载"
- **时间筛选**
  - 月份选择器
- **视频列表**
  - 视频缩略图
  - 视频时长显示
  - 场地和球桌信息
  - 局数信息（第X局）
  - 时间戳
  - 球号选择器（1-15号球的圆点）
  - "精剪下载"按钮

### 3. AI战绩榜页面
- **页面标题**
  - "AI战绩榜" + "每日6:00更新"
- **筛选选项**
  - 数据类型：总战绩、清台、3连杆、进球
  - 时间范围：上周、本周、总榜
  - 地区选择：全国（下拉选择）
- **排行榜展示**
  - 前三名特殊显示（1st、2nd、3rd + 皇冠图标）
  - 用户头像、昵称
  - 获胜次数、胜率百分比
  - 个人排名状态（未上榜显示）

### 4. 个人信息页面
- **用户基本信息**
  - 用户头像
  - 用户昵称 + "编辑"按钮
  - 退出按钮
- **核心数据展示**
  - 胜率百分比（大字显示）
  - 总局数、胜负统计
  - 战绩周榜排名
- **出杆统计**
  - 进球率（圆形进度条）
  - 总杆数、进球数
  - 出杆均速
- **清台统计**
  - 一杆清台次数
  - 炸清次数和百分比
  - 接清次数和百分比
- **技巧球统计**
  - 饼图显示连杆/牙轮比例
  - 具体次数统计

### 5. 底部导航栏
- 对局（历史对局入口）
- AI剪辑（精彩集锦入口）
- 扫码（二维码扫描）
- 战绩榜（排行榜）
- 我的（个人中心）

## 性能要求

### 1. 响应性能
- 页面加载时间 < 2秒
- 扫码识别响应 < 1秒
- 视频加载缓冲 < 3秒
- 数据查询响应 < 2秒

### 2. 兼容性
- 支持iOS 10+
- 支持Android 6.0+
- 适配不同屏幕尺寸
- 微信版本兼容性

### 3. 稳定性
- 扫码成功率 > 95%
- 视频播放流畅度
- 数据同步准确性
- 网络异常处理

## 数据接口需求

### 1. 用户相关接口
- **用户登录**: `POST /api/user/login` - 微信授权登录
- **用户信息**: `GET /api/user/profile` - 获取用户基本信息
- **更新资料**: `PUT /api/user/profile` - 更新用户昵称等信息
- **用户退出**: `POST /api/user/logout` - 账号退出

### 2. 对局相关接口
- **历史对局**: `GET /api/match/history` - 获取历史对局列表
- **历史对手**: `GET /api/match/opponents` - 获取历史对手记录
- **当前对局**: `GET /api/match/current` - 获取当前对局状态
- **对局详情**: `GET /api/match/detail/{id}` - 获取具体对局详情
- **门店列表**: `GET /api/store/list` - 获取门店信息用于筛选

### 3. 扫码关联接口
- **二维码验证**: `POST /api/qr/verify` - 验证扫描的二维码
- **球局关联**: `POST /api/match/bind` - 绑定用户到指定球局
- **关联状态**: `GET /api/match/bind/status` - 查询关联状态

### 4. AI精彩集锦接口
- **视频列表**: `GET /api/highlight/list` - 获取精彩集锦列表
- **视频详情**: `GET /api/highlight/detail/{id}` - 获取视频详情
- **球号筛选**: `GET /api/highlight/filter` - 按球号筛选视频
- **视频下载**: `GET /api/highlight/download/{id}` - 视频文件下载
- **视频清理**: `DELETE /api/highlight/expired` - 清理过期视频

### 5. 战绩榜接口
- **排行榜数据**: `GET /api/ranking/list` - 获取排行榜数据
- **个人排名**: `GET /api/ranking/personal` - 获取个人排名信息
- **筛选条件**: `GET /api/ranking/filters` - 获取可用的筛选条件

### 6. 个人统计接口
- **核心数据**: `GET /api/stats/overview` - 胜率、局数等核心数据
- **出杆统计**: `GET /api/stats/shot` - 进球率、总杆数等
- **清台统计**: `GET /api/stats/clearance` - 一杆清台、炸清等
- **技巧统计**: `GET /api/stats/skills` - 连杆、牙轮等技巧数据
- **周榜排名**: `GET /api/stats/weekly` - 战绩周榜排名

## 开发计划

### 第一阶段 (基础功能)
- 用户登录系统
- 二维码扫描功能
- 基础界面搭建

### 第二阶段 (核心功能)
- 球局关联功能
- 历史成绩展示
- 数据统计图表

### 第三阶段 (完善功能)
- 精彩集锦播放
- 视频分享下载
- 用户体验优化

## 质量保证

### 1. 测试重点
- 扫码功能测试
- 数据展示准确性
- 视频播放兼容性
- 网络异常处理

### 2. 部署要求
- 小程序审核合规
- 版本发布管理
- 用户反馈收集
- 数据安全保护

---

*本需求文档将根据开发进度和用户反馈持续更新完善*