# Runner

**Repository Path**: jackghosts/runner

## Basic Information

- **Project Name**: Runner
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-17
- **Last Updated**: 2025-11-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 运动打卡微信小程序

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen.svg)](https://nodejs.org/)
[![MongoDB](https://img.shields.io/badge/database-MongoDB-green.svg)](https://www.mongodb.com/)
[![WeChat Mini Program](https://img.shields.io/badge/platform-WeChat%20Mini%20Program-blue.svg)](https://developers.weixin.qq.com/miniprogram/dev/framework/)

一个专为跑步群组设计的运动打卡微信小程序，支持运动记录、目标管理、投票决策、请假申请等功能。通过数字化管理，提升团队运动参与度和治理效率。

## 📖 目录

- [项目概述](#项目概述)
- [主要功能](#主要功能)
- [技术架构](#技术架构)
- [快速开始](#快速开始)
- [项目结构](#项目结构)
- [部署说明](#部署说明)
- [开发指南](#开发指南)
- [API文档](#api文档)
- [图片资源](#图片资源)
- [贡献指南](#贡献指南)
- [许可证](#许可证)
- [支持与反馈](#支持与反馈)

## 🎯 项目概述

本项目是一个完整的运动打卡管理解决方案，包含微信小程序前端、Node.js后端API和MySQL数据库。通过民主投票、目标管理、执法官制度等机制，实现高效的群组运动管理。

### 核心理念

- **数字化管理**: 将传统纸质管理方式数字化，提高效率
- **民主治理**: 通过投票机制实现群组成员的民主决策
- **目标导向**: 设定周目标，跟踪完成情况，促进运动习惯养成
- **责任制度**: 执法官制度确保管理执行到位
- **透明公开**: 实时数据统计和公开透明的管理流程

## ✨ 主要功能

### 🏃 用户端功能

| 功能模块 | 功能描述 | 状态 |
|---------|---------|------|
| **用户认证** | 微信授权登录，用户信息管理 | ✅ 完成 |
| **运动打卡** | 记录跑步数据，上传证明图片，支持补卡 | ✅ 完成 |
| **数据统计** | 运动数据可视化，周/月统计报表 | ✅ 完成 |
| **目标管理** | 设置周目标，跟踪完成进度 | ✅ 完成 |
| **罚款管理** | 自动计算罚款，支持支付记录 | ✅ 完成 |
| **请假申请** | 提交请假申请，参与投票审批 | ✅ 完成 |
| **投票功能** | 参与群组决策，查看投票历史 | ✅ 完成 |
| **排行榜** | 运动数据排名，激励竞争 | ✅ 完成 |

### 👨‍💼 管理员功能

| 功能模块 | 功能描述 | 状态 |
|---------|---------|------|
| **数据概览** | 整体运营数据仪表板 | ✅ 完成 |
| **用户管理** | 用户信息管理，角色分配 | ✅ 完成 |
| **审核管理** | 打卡记录审核，请假审批 | ✅ 完成 |
| **执法管理** | 罚款确认，轮值安排 | ✅ 完成 |
| **投票管理** | 发起投票，查看结果统计 | ✅ 完成 |
| **系统配置** | 群组规则配置，参数设置 | ✅ 完成 |

### 🏛️ 治理功能

| 治理机制 | 实现方式 | 状态 |
|---------|---------|------|
| **民主投票** | 60%-75%赞成票阈值 | ✅ 完成 |
| **执法官制度** | 月度轮值，负责执行 | ✅ 完成 |
| **请假制度** | 月度3天限额，投票审批 | ✅ 完成 |
| **补卡机制** | 每季度1次补卡机会 | ✅ 完成 |
| **罚款制度** | 动态罚款标准，自动计算 | ✅ 完成 |

## 🏗️ 技术架构

### 前端架构
```
微信小程序 (WeChat Mini Program)
├── 原生小程序框架
├── 自定义组件系统
├── 样式管理 (WXSS)
├── 网络请求封装
└── 数据存储管理
```

### 后端架构
```
Node.js + Express.js
├── RESTful API 设计
├── JWT 认证机制
├── 中间件系统
├── 错误处理机制
└── 安全防护措施
```

### 数据库架构
```
MySQL 8.0+
├── 用户管理 (users)
├── 跑步记录 (running_records)
├── 目标统计 (weekly_goals)
├── 罚款管理 (fine_records)
├── 请假管理 (leave_requests)
├── 投票系统 (vote_proposals, vote_responses)
└── 群组配置 (groups)
```

### 技术栈详情

| 层级 | 技术选择 | 版本要求 | 说明 |
|------|---------|---------|------|
| **前端框架** | 微信小程序原生 | 2.19.0+ | 跨平台支持 |
| **后端语言** | Node.js | 14.0.0+ | 异步I/O，高性能 |
| **后端框架** | Express.js | 4.17+ | 轻量级Web框架 |
| **数据库** | MySQL | 8.0+ | 关系型数据库 |
| **ORM** | Sequelize | 6.0+ | 数据模型管理 |
| **认证** | JWT | - | Token认证 |
| **验证** | express-validator | - | 输入数据验证 |
| **安全** | helmet, bcrypt | - | 安全防护 |
| **测试** | Jest, Supertest | - | 单元测试框架 |
| **文档** | Markdown | - | 项目文档 |

## 🚀 快速开始

### 环境要求

- **Node.js**: ≥ 14.0.0
- **MySQL**: ≥ 8.0
- **微信开发者工具**: 最新版
- **Git**: 用于版本控制

### 安装步骤

#### 1. 克隆项目
```bash
git clone https://github.com/your-username/running-checkin-miniprogram.git
cd running-checkin-miniprogram
```

#### 2. 数据库设置
```bash
# 创建数据库
mysql -u root -p -e "CREATE DATABASE running_checkin DEFAULT CHARSET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 导入数据库结构
mysql -u root -p running_checkin < database/schema.sql

# 导入测试数据
mysql -u root -p running_checkin < database/test_data.sql
```

#### 3. 后端服务设置
```bash
cd backend
npm install

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，设置数据库连接等信息

# 启动开发服务器
npm run dev
```

#### 4. 微信小程序设置
```bash
cd miniprogram
# 使用微信开发者工具打开 miniprogram 目录
# 配置小程序的 AppID
# 预览或真机调试
```

#### 5. 访问应用
- **小程序**: 使用微信扫码或微信开发者工具预览
- **API服务**: http://localhost:5000
- **API文档**: http://localhost:5000/api-docs

## 📁 项目结构

```
running-checkin-miniprogram/
├── README.md                    # 项目说明文档
├── LICENSE                      # 许可证文件
├── CHANGELOG.md                 # 版本更新记录
├── CONTRIBUTING.md              # 贡献指南
├── FILE_STRUCTURE.md            # 文件结构说明
├── RELEASE_NOTES.md             # 版本发布说明
├── backend/                     # 后端服务
│   ├── src/                     # 源代码
│   ├── tests/                   # 测试文件
│   ├── api/                     # API文档
│   ├── docker-compose.yml       # Docker配置
│   └── package.json
├── miniprogram/                 # 微信小程序
│   ├── pages/                   # 页面文件
│   ├── components/              # 自定义组件
│   ├── utils/                   # 工具函数
│   ├── styles/                  # 样式文件
│   └── images/                  # 图片资源
├── database/                    # 数据库相关
│   ├── migrations/              # 数据库迁移
│   ├── schema.sql              # 数据库结构
│   └── test_data.sql           # 测试数据
├── docs/                       # 项目文档
│   ├── api.md                  # API接口文档
│   ├── vote_api.md             # 投票API文档
│   └── 图片资源说明.md         # 图片资源使用说明
├── browser/                    # 浏览器扩展
├── imgs/                       # 项目图片资源
│   ├── logo.jpg                # 小程序Logo
│   ├── running_hero.jpg        # 跑步主图
│   ├── default_avatar.jpg      # 默认头像
│   ├── success_icon.jpg        # 成功图标
│   ├── error_icon.jpg          # 错误图标
│   ├── warning_icon.jpg        # 警告图标
│   ├── target_icon.jpg         # 目标图标
│   ├── calendar_icon.jpg       # 日历图标
│   ├── vote_icon.jpg           # 投票图标
│   ├── admin_icon.jpg          # 管理图标
│   ├── award_icon.jpg          # 奖励图标
│   ├── ranking_icon.jpg        # 排行榜图标
│   ├── leave_icon.jpg          # 请假图标
│   ├── progress_icon.jpg       # 进度图标
│   ├── function_icons.jpg      # 功能图标集
│   ├── intro_bg.jpg            # 引导页背景
│   ├── loading_animation.jpg   # 加载动画
│   ├── stats_bg.jpg            # 统计数据背景
│   ├── gallery_bg.jpg          # 图片上传背景
│   └── empty_data_bg.jpg       # 空数据背景
```

详细的项目结构说明请查看 [FILE_STRUCTURE.md](FILE_STRUCTURE.md)

## 🚀 部署说明

### 开发环境部署

1. **本地开发环境**
   ```bash
   # 克隆项目
   git clone <repository-url>
   cd running-checkin-miniprogram
   
   # 安装后端依赖
   cd backend && npm install
   
   # 安装前端依赖 (如需要)
   # cd miniprogram && npm install
   
   # 配置数据库和启动服务
   # 详见快速开始章节
   ```

### 生产环境部署

#### 方式一：Docker 部署 (推荐)

```bash
# 构建并启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f
```

#### 方式二：手动部署

1. **服务器环境准备**
   ```bash
   # 安装 Node.js 16+
   curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
   sudo apt-get install -y nodejs
   
   # 安装 PM2 进程管理器
   npm install -g pm2
   
   # 安装 MySQL
   sudo apt-get install mysql-server
   ```

2. **项目部署**
   ```bash
   # 克隆项目
   git clone <repository-url>
   cd running-checkin-miniprogram
   
   # 安装依赖
   cd backend && npm install --production
   
   # 配置环境变量
   cp .env.example .env
   # 编辑配置文件
   
   # 启动服务
   pm2 start ecosystem.config.js
   pm2 save
   pm2 startup
   ```

### 部署检查清单

- [ ] 数据库连接正常
- [ ] API服务可访问
- [ ] 小程序可以正常请求API
- [ ] 文件上传功能正常
- [ ] 支付功能测试通过 (如适用)
- [ ] 安全配置检查
- [ ] 性能监控配置
- [ ] 日志记录正常

## 📚 开发指南

### 代码规范

请遵循项目的代码规范，具体要求请参考 [CONTRIBUTING.md](CONTRIBUTING.md)

### 开发流程

1. **功能开发**
   - 从 `main` 分支创建功能分支
   - 遵循代码规范进行开发
   - 编写相应的测试用例
   - 提交 Pull Request

2. **测试流程**
   - 单元测试：`npm test`
   - 集成测试：`npm run test:integration`
   - 端到端测试：`npm run test:e2e`

3. **发布流程**
   - 遵循语义化版本控制
   - 更新 CHANGELOG.md
   - 创建发布标签
   - 生成发布说明

### 常用命令

```bash
# 后端开发
cd backend
npm run dev          # 启动开发服务器
npm test            # 运行测试
npm run lint        # 代码检查
npm run build       # 构建生产版本

# 前端开发
cd miniprogram
# 使用微信开发者工具进行开发和调试

# 数据库操作
cd database
./db.sh init        # 初始化数据库
./db.sh migrate     # 运行迁移
./db.sh seed        # 填充测试数据
```

## 📖 API文档

完整的API文档请查看：

- **主API文档**: [backend/api/README.md](backend/api/README.md)
- **投票API文档**: [docs/vote_api.md](docs/vote_api.md)
- **交互式API文档**: 启动服务后访问 `http://localhost:5000/api-docs`

### 主要API端点

| 模块 | 基础路径 | 主要功能 |
|------|---------|---------|
| **认证** | `/api/auth` | 用户注册、登录、Token管理 |
| **用户** | `/api/users` | 用户信息管理、搜索、统计 |
| **跑步** | `/api/running` | 运动记录、统计、目标管理 |
| **罚款** | `/api/fines` | 罚款记录、支付、统计 |
| **投票** | `/api/votes` | 投票管理、结果统计 |
| **管理** | `/api/admin` | 管理员专用接口 |

## 🖼️ 图片资源

项目提供了完整的图片资源体系，包含20张精心设计的图片。

### 图片分类

| 类型 | 数量 | 主要用途 |
|------|------|---------|
| **品牌标识** | 3张 | Logo、引导页、加载动画 |
| **功能图标** | 10张 | 页面功能、操作按钮、状态指示 |
| **状态图标** | 3张 | 成功、失败、警告状态 |
| **默认图片** | 4张 | 头像占位、空数据、上传背景 |

### 核心图片

- **`logo.jpg`** - 小程序主Logo，蓝色渐变设计
- **`running_hero.jpg`** - 跑步主图，卡通风格剪影
- **`function_icons.jpg`** - 功能图标集，统一直径和风格
- **`success_icon.jpg`** - 成功状态图标，绿色对勾
- **`admin_icon.jpg`** - 执法官图标，金色天平设计

### 资源特点

- ✅ **统一直径**: 64x64px 标准图标尺寸
- ✅ **现代设计**: 扁平化、简洁线条风格  
- ✅ **色彩一致**: 蓝色主色调配合功能色
- ✅ **移动优化**: 适配小程序界面规范
- ✅ **响应式**: 支持不同设备屏幕

### 使用说明

详细的使用指南请查看 [图片资源说明.md](docs/图片资源说明.md)

```javascript
// 在小程序中引用
<image src="/imgs/logo.jpg" class="logo"></image>
<image src="/imgs/running_hero.jpg" class="hero-bg"></image>
```

## 🤝 贡献指南

我们欢迎各种形式的贡献！

### 如何贡献

1. **报告Bug**: 创建详细的问题报告
2. **提出新功能**: 提交功能需求
3. **完善文档**: 改进项目文档
4. **代码贡献**: 提交Pull Request

### 贡献流程

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

详细的贡献指南请查看 [CONTRIBUTING.md](CONTRIBUTING.md)

## 📊 路线图

### v1.0.1 (已完成)
- [x] ✅ 添加完整的图片资源系统
- [x] ✅ 优化用户界面视觉效果
- [x] ✅ 完善品牌视觉识别

### v1.1.0 (计划中)
- [ ] 增加运动类型支持（骑行、游泳等）
- [ ] 微信群机器人集成
- [ ] 运动数据分析增强
- [ ] 移动端适配优化

### v1.2.0 (计划中)
- [ ] 运动挑战功能
- [ ] 社交分享功能
- [ ] 运动装备管理
- [ ] 健康数据同步

### v2.0.0 (规划中)
- [ ] 多群组支持
- [ ] 高级数据分析
- [ ] AI推荐系统
- [ ] 第三方平台集成

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 🆘 支持与反馈

### 获取帮助

- **文档**: 查看项目文档和API文档
- **FAQ**: 常见问题解答
- **社区**: 参与社区讨论

### 联系方式

- **项目维护者**: [Your Name]
- **邮箱**: [your.email@example.com]
- **项目地址**: [https://github.com/your-username/running-checkin-miniprogram](https://github.com/your-username/running-checkin-miniprogram)

### 问题报告

如遇到问题，请提供以下信息：

1. **问题描述**: 详细描述遇到的问题
2. **复现步骤**: 如何重现该问题
3. **环境信息**: Node.js版本、微信开发者工具版本等
4. **错误日志**: 相关的错误信息和日志

## 🙏 致谢

感谢以下开源项目和服务：

- [Node.js](https://nodejs.org/) - 后端运行环境
- [Express.js](https://expressjs.com/) - Web应用框架
- [MySQL](https://www.mysql.com/) - 关系型数据库
- [Jest](https://jestjs.io/) - 测试框架
- [微信小程序](https://developers.weixin.qq.com/miniprogram/dev/framework/) - 移动应用平台
- [JWT](https://jwt.io/) - 认证标准
- [Helmet](https://helmetjs.github.io/) - 安全中间件

---

<div align="center">

**如果这个项目对您有帮助，请给我们一个 ⭐ Star！**

[⬆ 回到顶部](#运动打卡微信小程序)

</div>