# checkin

**Repository Path**: sanmubird/checkin

## Basic Information

- **Project Name**: checkin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-25
- **Last Updated**: 2026-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 目标打卡系统 (Goal Tracker)

一个功能完整的目标追踪系统,帮助用户追踪目标完成进度,培养良好习惯。

## 功能特性

### 核心功能
- ✓ 项目创建与预计算(支持工作日过滤)
- ✓ 每日打卡与进度追踪
- ✓ 补卡功能(过去3天内)
- ✓ 今日视图(首页)
- ✓ 项目详情页(日历视图、每日明细)
- ✓ 项目总结自动生成
- ✓ 管理后台(仅管理员)

### 用户系统
- ✓ 用户注册/登录(支持用户名或邮箱)
- ✓ 密码加密存储(bcrypt)
- ✓ 忘记密码功能
- ✓ 权限分级(普通用户/管理员)

### 设计原则
- ✓ 数据固化原则(项目创建后应打卡日期不可修改)
- ✓ 幂等打卡原则(重复提交不影响结果)
- ✓ 状态驱动原则(打卡状态自动计算)
- ✓ 轻量外部依赖原则(仅创建时调用节假日API)

## 技术栈

### 后端
- Node.js + Express
- SQLite (数据库)
- JWT (认证)
- bcrypt (密码加密)
- dayjs (日期处理)
- axios (HTTP请求)

### 前端
- Vue 3 + Vite
- Pinia (状态管理)
- Vue Router (路由)
- Axios (HTTP客户端)

## 项目结构

```
checkin/
├── backend/                 # 后端服务
│   ├── src/
│   │   ├── config/         # 配置文件
│   │   │   ├── database.js # 数据库配置
│   │   │   └── index.js    # 应用配置
│   │   ├── middleware/     # 中间件
│   │   │   └── auth.js     # 认证中间件
│   │   ├── models/         # 数据模型(使用SQLite)
│   │   ├── routes/         # 路由
│   │   │   ├── auth.js     # 认证路由
│   │   │   ├── projects.js # 项目路由
│   │   │   ├── checkins.js # 打卡路由
│   │   │   ├── reports.js  # 报告路由
│   │   │   └── admin.js    # 管理后台路由
│   │   ├── services/       # 业务逻辑
│   │   │   ├── projectService.js    # 项目服务
│   │   │   ├── checkinService.js    # 打卡服务
│   │   │   └── reportService.js     # 报告服务
│   │   └── app.js          # 主应用
│   ├── .env                # 环境变量
│   └── package.json        # 依赖配置
├── frontend/               # 前端应用
│   ├── src/
│   │   ├── api/            # API接口
│   │   │   ├── index.js
│   │   │   ├── auth.js
│   │   │   ├── project.js
│   │   │   ├── checkin.js
│   │   │   └── report.js
│   │   ├── components/     # 组件
│   │   ├── router/         # 路由配置
│   │   │   └── index.js
│   │   ├── stores/         # 状态管理
│   │   │   └── user.js
│   │   ├── views/          # 页面
│   │   │   ├── Login.vue
│   │   │   ├── Register.vue
│   │   │   ├── Home.vue
│   │   │   ├── CreateProject.vue
│   │   │   ├── ProjectDetail.vue
│   │   │   └── Admin.vue
│   │   ├── App.vue
│   │   └── main.js
│   ├── index.html
│   ├── vite.config.js
│   └── package.json
└── doc/                    # 文档
    └── 目标打卡系统(Goal Tracker)产品需求文档(PRD).md
```

## 快速开始

### 方式一: Docker Compose 部署(推荐)

**适用于生产环境和快速部署**

#### 前置要求
- Docker >= 20.10
- Docker Compose >= 2.0

#### 快速启动

**Windows:**
```bash
docker-start.bat
```

**Linux/Mac:**
```bash
chmod +x docker-start.sh
./docker-start.sh
```

或手动启动:
```bash
# 配置环境变量
cp .env.example .env
# 编辑 .env 文件,修改 JWT_SECRET

# 启动服务
docker compose up -d

# 创建管理员账户
docker compose exec backend node create-admin.js
```

#### 访问应用
- 前端: http://localhost
- 后端: http://localhost:3000

详细文档请查看: [DOCKER_DEPLOYMENT.md](DOCKER_DEPLOYMENT.md)

---

### 方式二: 本地开发

**适用于开发和调试**

#### 环境要求
- Node.js >= 16.0.0
- npm >= 8.0.0

#### 安装依赖

**后端:**
```bash
cd backend
npm install
```

**前端:**
```bash
cd frontend
npm install
```

#### 配置环境变量

编辑 `backend/.env`:
```
PORT=3000
JWT_SECRET=your-secret-key-change-in-production
DB_PATH=./database.sqlite
MAX_USERS=100
```

#### 启动服务

**后端:**
```bash
cd backend
npm run dev
```
后端服务将在 `http://localhost:3000` 启动

**前端:**
```bash
cd frontend
npm run dev
```
前端应用将在 `http://localhost:5173` 启动

#### 访问应用

打开浏览器访问 `http://localhost:5173`

首次使用需要注册账号,系统支持最多100名用户。

### 创建管理员账户

管理员账户需要直接在数据库中创建:

```javascript
// 在backend/src/config/database.js中临时添加
const bcrypt = require('bcryptjs');
const hashedPassword = await bcrypt.hash('admin123', 10);
db.run('INSERT INTO users (username, email, password, role) VALUES (?, ?, ?, ?)',
  ['admin', 'admin@example.com', hashedPassword, 'admin']);
```

然后重启后端服务。

## API接口文档

### 认证接口
- `POST /api/auth/register` - 用户注册
- `POST /api/auth/login` - 用户登录
- `POST /api/auth/reset-password` - 重置密码

### 项目接口
- `POST /api/projects` - 创建项目
- `GET /api/projects` - 获取项目列表
- `GET /api/projects/:id` - 获取项目详情
- `DELETE /api/projects/:id` - 删除项目

### 打卡接口
- `POST /api/checkins/:projectId` - 打卡
- `POST /api/checkins/:projectId/makeup` - 补卡
- `GET /api/checkins/:projectId/today` - 获取今日进度
- `GET /api/checkins/:projectId/progress` - 获取项目进度
- `GET /api/checkins/:projectId/daily/:date` - 获取每日打卡记录

### 报告接口
- `GET /api/reports/:projectId` - 获取项目报告
- `POST /api/reports/:projectId/generate` - 生成报告

### 管理后台接口
- `GET /api/admin/users` - 获取用户列表
- `GET /api/admin/users/:id` - 获取用户详情
- `GET /api/admin/projects` - 获取项目列表
- `GET /api/admin/projects/:id` - 获取项目详情
- `GET /api/admin/stats` - 获取系统统计

## 数据库设计

### 用户表 (users)
- id: 用户ID
- username: 用户名
- email: 邮箱
- password: 密码(加密)
- role: 角色(user/admin)
- created_at: 创建时间

### 项目表 (projects)
- id: 项目ID
- user_id: 用户ID
- name: 项目名称
- goal_type: 目标类型
- daily_target: 每日目标值
- start_date: 开始日期
- end_date: 结束日期
- only_workdays: 是否仅工作日
- should_checkin_days: 应打卡天数
- should_checkin_dates: 应打卡日期列表(JSON)
- created_at: 创建时间

### 打卡记录表 (checkins)
- id: 记录ID
- project_id: 项目ID
- user_id: 用户ID
- checkin_date: 打卡日期
- value: 打卡值
- is_makeup: 是否补卡
- created_at: 创建时间

### 项目总结表 (project_reports)
- id: 报告ID
- project_id: 项目ID
- total_days: 总天数
- should_checkin_days: 应打卡天数
- actual_checkin_days: 实际打卡天数
- missed_days: 漏打天数
- makeup_count: 补卡次数
- longest_streak: 最长连续达标天数
- max_daily_value: 单日最高完成量
- max_daily_date: 单日最高完成日期
- generated_at: 生成时间

## 注意事项

1. **数据安全**: 生产环境请修改JWT_SECRET为强密码
2. **节假日API**: 系统使用外部API获取节假日数据,如API不可用将使用默认工作日(周一到周五)
3. **用户限制**: 系统最多支持100名用户,超出限制后新用户无法注册
4. **定时任务**: 项目总结报告在项目结束日期的次日00:00自动生成

## 许可证

MIT License