# 拉了么小程序

**Repository Path**: libaicode/did-you-pull-it-mini-program

## Basic Information

- **Project Name**: 拉了么小程序
- **Description**: 这款拉了么小程序主要是围绕着用户的便便健康为中心来开发的，交互非常丝滑，数据完善，趣味性十足，欢迎体验
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-26
- **Last Updated**: 2026-01-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 拉了么小程序 - FastAPI 后端

这是一个基于 FastAPI 框架开发的便便打卡小程序后端API系统。

![输入图片说明](image.png)

## 功能特性

✅ 用户管理
- 用户登录/注册（微信小程序）
- 用户信息管理
- 用户数据清空

✅ 打卡系统
- 简单打卡
- 详细打卡（含多维度记录）
- 打卡限制（每天5次，间隔3分钟）
- 连续打卡天数计算
- 打卡历史查询
- 日历视图
- 每日详细记录

✅ 排行榜
- 省份排行榜
- 全国统计数据
- 用户排名

✅ 系统功能
- JWT认证
- API文档（Swagger）

## 技术栈

- **框架**: FastAPI 0.109.0
- **数据库**: MySQL + SQLAlchemy ORM
- **认证**: JWT (python-jose)
- **验证**: Pydantic 2.5.3
- **服务器**: Uvicorn

## 快速开始

### 1. 环境要求

- Python 3.8+
- MySQL 5.7+

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 配置环境变量

复制 `.env.example` 为 `.env` 并修改配置：

```bash
cp .env.example .env
```

编辑 `.env` 文件，配置数据库连接：

```ini
DATABASE_URL=mysql+pymysql://用户名:密码@localhost:3306/数据库名?charset=utf8mb4
SECRET_KEY=你的密钥
```

### 4. 创建数据库

```sql
CREATE DATABASE laleme_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### 5. 运行应用

```bash
# 开发模式（自动重载）
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 或者直接运行
python app/main.py
```

### 6. 访问API文档

启动后访问：
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## 目录结构

```
api/
├── app/
│   ├── main.py              # 应用入口
│   ├── config.py            # 配置文件
│   ├── database.py          # 数据库连接
│   ├── models/              # 数据库模型
│   │   ├── user.py
│   │   ├── checkin_record.py
│   │   ├── province_stats.py
│   │   └── global_stats.py
│   ├── schemas/             # Pydantic模型
│   │   ├── common.py
│   │   ├── user.py
│   │   ├── checkin.py
│   │   └── rank.py
│   ├── routers/             # 路由模块
│   │   ├── user.py          # 用户相关接口
│   │   ├── checkin.py       # 打卡相关接口
│   │   └── rank.py          # 排行榜接口
│   ├── services/            # 业务逻辑
│   │   └── checkin_service.py
│   └── utils/               # 工具函数
│       ├── auth.py          # JWT认证
│       ├── helpers.py       # 辅助函数
│       └── dependencies.py  # 依赖注入
├── requirements.txt         # 依赖列表
├── .env.example            # 环境变量示例
├── API接口文档.md          # 详细接口文档
└── README.md               # 本文件
```

## API接口概览

### 用户相关 `/api/v1/user`
- `POST /login` - 用户登录/注册
- `GET /info` - 获取用户信息
- `PUT /info` - 更新用户信息
- `DELETE /data` - 清空用户数据

### 打卡相关 `/api/v1/checkin`
- `GET /status` - 检查打卡状态
- `POST /simple` - 简单打卡
- `POST /detailed` - 详细打卡
- `GET /history` - 获取打卡历史
- `GET /calendar` - 获取日历数据
- `GET /day/{date}` - 获取某日详细记录

### 排行榜 `/api/v1/rank`
- `GET /province` - 省份排行榜
- `GET /national` - 全国统计
- `GET /user` - 用户排名

## 开发说明

### 认证机制

除登录接口外，所有接口都需要在请求头中携带JWT Token：

```
Authorization: Bearer {token}
```

### 响应格式

所有接口统一返回格式：

```json
{
  "code": 0,
  "message": "操作成功",
  "data": {}
}
```

### 错误码

| 错误码 | 说明 |
|-------|------|
| 0 | 成功 |
| 1001 | 参数错误 |
| 1002 | Token无效或过期 |
| 1003 | 用户不存在 |
| 2001 | 今日打卡次数已达上限 |
| 2002 | 打卡间隔时间不足 |
| 2003 | 打卡记录不存在 |
| 3001 | 数据库操作失败 |
| 9999 | 系统错误 |

## 部署建议

### 生产环境配置

1. 修改 `.env` 中的 `DEBUG=False`
2. 设置强密码的 `SECRET_KEY`
3. 配置 CORS 只允许特定域名
4. 使用 Gunicorn + Nginx 部署
5. 配置 HTTPS
6. 定时任务更新统计数据

### 使用 Gunicorn

```bash
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
```

## 注意事项

1. **微信登录**: 当前登录接口是模拟实现，生产环境需要对接微信小程序API
2. **数据库**: 首次运行会自动创建表结构
3. **打卡限制**: 每天最多5次，每次间隔3分钟
4. **省份统计**: 示例中使用模拟数据，生产环境需要实现定时统计任务

## 测试

启动服务后可以使用以下工具测试：
- Swagger UI (自带): http://localhost:8000/docs
- Postman
- curl

### 示例请求

```bash
# 登录
curl -X POST "http://localhost:8000/api/v1/user/login" \
  -H "Content-Type: application/json" \
  -d '{"code":"test123"}'

# 打卡（需要token）
curl -X POST "http://localhost:8000/api/v1/checkin/simple" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"status":"great"}'
```

## 许可证

MIT License

## 联系方式

如有问题，请查看 `API接口文档.md` 获取详细接口说明。