# checkin

**Repository Path**: bibisky2049/checkin

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-31
- **Last Updated**: 2026-04-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CheckIn - 每日打卡应用

轻量级的日常打卡系统，帮助用户建立和维持良好的习惯。通过打卡记录与积分激励机制增强用户粘性。

## 技术栈

| 层 | 技术 |
|---|------|
| 后端 | Rust · Axum · SQLx · SQLite |
| 前端 | React · TypeScript · Vite · Tailwind CSS |
| 认证 | JWT (Access + Refresh Token 轮转) |

## 功能

- **每日打卡** - 一天一次，支持附言
- **补签机制** - 消耗 50 积分补签过去 7 天内的遗漏，每月限 1 次
- **连续打卡** - 自动检测连续天数，7 天奖励 +50，30 天奖励 +200
- **积分系统** - 完整的积分获取/消耗闭环与流水记录
- **数据统计** - 总打卡天数、连续天数、最长连续、月度打卡率
- **日历视图** - 月度打卡日历，直观展示打卡记录与连续段
- **暗黑模式** - 支持明暗主题切换，自动跟随系统偏好
- **响应式** - 桌面端顶栏导航，移动端底栏 Tab

## 项目结构

```
checkin/
├── backend/                  # Rust 后端
│   ├── src/
│   │   ├── main.rs           # 入口，路由装配
│   │   ├── lib.rs            # 库模块导出
│   │   ├── config.rs         # 环境变量配置
│   │   ├── error.rs          # 统一错误响应
│   │   ├── bin/seed.rs       # 种子数据脚本
│   │   ├── handlers/         # API 处理器
│   │   │   ├── auth.rs       # 注册/登录/刷新/登出/用户信息
│   │   │   ├── checkin.rs    # 打卡/补签/历史/日历/统计
│   │   │   └── points.rs     # 积分余额/流水
│   │   ├── models/           # 数据模型
│   │   ├── db/               # 数据库仓库层
│   │   └── middleware/       # JWT 认证/时区提取
│   ├── migrations/           # SQLite 迁移文件
│   └── tests/                # 集成测试
│
├── frontend/                 # React 前端
│   └── src/
│       ├── api/              # API 客户端
│       ├── hooks/            # React Hooks (认证状态)
│       ├── components/       # 通用组件 (Layout/导航)
│       ├── pages/            # 页面组件
│       │   ├── LoginPage.tsx
│       │   ├── RegisterPage.tsx
│       │   ├── DashboardPage.tsx
│       │   ├── HistoryPage.tsx
│       │   └── PointsPage.tsx
│       └── index.css         # Tailwind + CSS 变量主题
│
└── openspec/                 # 设计规格文档
    └── specs/                # 能力规格 (user-auth, checkin, points, frontend-ui)
```

## 快速开始

### 环境要求

- Rust 1.85+
- Node.js 20+
- sqlx-cli (`cargo install sqlx-cli --no-default-features --features sqlite`)

### 后端

```bash
cd backend

# 配置环境变量
cp .env.example .env
# 编辑 .env 设置 JWT_SECRET 等

# 初始化数据库
sqlx database create --database-url "sqlite:data/checkin.db"
sqlx migrate run --database-url "sqlite:data/checkin.db"

# (可选) 填充测试数据 - 创建 demo/password123 用户，35 天打卡记录
DATABASE_URL="sqlite:data/checkin.db" cargo run --bin seed

# 启动服务
cargo run
```

后端默认监听 `http://localhost:3000`。

### 前端

```bash
cd frontend

npm install
npm run dev
```

前端默认监听 `http://localhost:5173`，自动代理 API 请求到后端。

### 生产部署

```bash
# 构建前端
cd frontend && npm run build

# 启用静态文件托管
ENABLE_STATIC_FILES=1 cargo run
```

后端将同时托管前端静态文件和 API，单端口部署。

## API 概览

所有 API 路径前缀为 `/api/v1/`。

| 方法 | 路径 | 说明 | 认证 |
|------|------|------|------|
| POST | /auth/register | 用户注册 | - |
| POST | /auth/login | 用户登录 | - |
| POST | /auth/refresh | 刷新 Token | - |
| POST | /auth/logout | 退出登录 | Yes |
| GET | /auth/me | 当前用户信息 | Yes |
| POST | /checkin | 提交打卡 | Yes |
| POST | /checkin/makeup | 补签 (消耗 50 积分) | Yes |
| GET | /checkin/today | 今日打卡状态 | Yes |
| GET | /checkin/history | 打卡历史 (分页) | Yes |
| GET | /checkin/calendar | 月度打卡日历 | Yes |
| GET | /checkin/streak | 连续打卡天数 | Yes |
| GET | /checkin/stats | 打卡统计 | Yes |
| GET | /points/balance | 积分余额 | Yes |
| GET | /points/history | 积分流水 (分页) | Yes |

**错误响应格式:**

```json
{
  "code": "CONFLICT",
  "message": "Already checked in today"
}
```

## 积分规则

| 事件 | 积分 |
|------|------|
| 每日打卡 | +10 |
| 连续 7 天 | +50 |
| 连续 30 天 | +200 |
| 补签消耗 | -50 |

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| DATABASE_URL | sqlite:data/checkin.db | SQLite 数据库路径 |
| JWT_SECRET | (必填) | JWT 签名密钥 |
| JWT_ACCESS_EXPIRY | 3600 | Access Token 有效期 (秒) |
| JWT_REFRESH_EXPIRY | 2592000 | Refresh Token 有效期 (秒) |
| CORS_ORIGIN | http://localhost:5173 | CORS 允许源 |
| SERVE_ADDR | 0.0.0.0:3000 | 监听地址 |
| ENABLE_STATIC_FILES | (未设置) | 启用前端静态文件托管 |

## 测试

```bash
# 后端集成测试
cd backend && cargo test

# 前端构建检查
cd frontend && npm run build
```

## License

MIT