# click

**Repository Path**: easy_code/click-in

## Basic Information

- **Project Name**: click
- **Description**: 日历打卡项目，go+html

- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 打卡系统 API

基于 Gin 框架和 MySQL 数据库的打卡系统，支持上班打卡、标签管理以及按月份查询打卡记录的功能。

## 项目结构

```
click-api/
├── cmd/                    # 应用入口（如有多应用可拆分）
├── config/                 # 配置管理
│   └── config.go          # 配置加载和定义
├── dto/                    # 数据传输对象
│   ├── request.go         # 请求DTO
│   └── response.go        # 响应DTO
├── internal/              # 内部应用代码（不对外暴露）
│   ├── bootstrap.go       # 基础设施初始化（数据库、日志）
│   ├── app.go             # 应用实例管理
│   ├── common/            # 通用工具
│   │   └── util.go        # 通用工具函数
│   ├── handlers/          # HTTP处理器层
│   │   ├── attendance.go  # 打卡相关处理器
│   │   ├── tag.go         # 标签相关处理器
│   │   └── handlers.go   # Handler初始化
│   ├── middleware/        # 中间件
│   │   ├── common.go      # 通用中间件（恢复、日志、认证）
│   │   └── cors.go        # 跨域中间件
│   ├── routes/            # 路由管理
│   │   └── routes.go      # 路由注册
│   └── service/           # 业务逻辑层
│       ├── attendance.go  # 打卡业务逻辑
│       ├── tag.go         # 标签业务逻辑
│       └── service.go     # 服务层定义
├── models/                # 数据模型
│   ├── attendance.go      # 打卡模型
│   ├── attendance_tag.go  # 打卡标签关联模型
│   └── tag.go             # 标签模型
├── utils/                 # 工具函数
│   ├── context.go         # 上下文处理
│   ├── validator.go       # 参数验证
│   └── response.go        # 统一响应格式
├── html/                  # 前端页面
│   ├── index.html         # 主页面（包含现代化健身启动页）
│   ├── splash-guide.html  # 功能指引页面
│   ├── styles.css         # 所有样式（包含启动页样式）
│   ├── app.js            # 核心配置和工具（包含启动页逻辑）
│   ├── calendar.js       # 日历渲染模块
│   ├── modal.js          # 弹窗管理模块
│   ├── checkin.js        # 打卡功能模块
│   ├── tags.js           # 标签管理模块
│   ├── chart.js          # 图表展示模块
│   └── navigation.js     # 导航切换模块
├── doc/                   # 文档
├── .env.example           # 环境变量示例
├── .gitignore             # Git忽略文件
├── go.mod                 # Go模块定义
├── go.sum                 # 依赖版本锁定
└── main.go                # 程序入口
```

## 功能特性

- ✅ 上班打卡
- ✅ 标签管理（创建、查询、删除）
- ✅ 打卡记录关联标签
- ✅ 按月份/年份查询打卡记录
- ✅ 统一的错误处理和响应格式
- ✅ 优雅的服务器关闭
- ✅ 结构化日志
- ✅ 跨域支持
- ✅ 软删除支持

## 技术栈

- Go 1.23+
- Gin Web 框架
- MySQL 数据库
- GORM ORM 框架
- Zap 日志库
- Godotenv 环境变量管理

## 快速开始

### 1. 环境准备

- Go 1.23 或更高版本
- MySQL 5.7 或更高版本

### 2. 克隆项目

```bash
git clone <your-repo-url>
cd click-api
```

### 3. 配置数据库

复制环境变量配置文件并根据实际情况修改：

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

编辑 `.env` 文件：

```env
SERVER_PORT=8080
GIN_MODE=debug

DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=click_system
```

### 4. 创建数据库

```sql
CREATE DATABASE click_system DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### 5. 创建数据表

参考 `doc/` 目录下的SQL脚本创建数据表。

### 6. 安装依赖

```bash
go mod download
```

### 7. 运行应用

```bash
go run main.go
```

服务器将在 `http://localhost:8080` 启动。

## 部署

### 编译

```bash
# Linux
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o click-api main.go

# Windows
go build -o click-api.exe main.go

# macOS
GOOS=darwin GOARCH=amd64 go build -o click-api main.go
```

### 运行

```bash
./click-api
```

## API 接口文档

### 基础路径

- 生产环境：`/api/v1`
- 兼容路径（向后兼容）：直接使用

### 打卡相关接口

#### 1. 上班打卡

- **接口地址**：`POST /api/v1/checkin`
- **请求头**：
  ```
  Content-Type: application/json
  ```
- **请求参数**：
  ```json
  {
    "user_id": 1,
    "date": "2026-03-11",
    "remark": "备注信息",
    "tag_ids": [1, 2, 3]
  }
  ```
- **响应示例**：
  ```json
  {
    "code": 200,
    "data": null,
    "msg": "success"
  }
  ```

#### 2. 查询打卡记录

- **接口地址**：`GET /api/v1/checkin`
- **查询参数**：
  - `user_id`: 用户ID（可选，默认为当前登录用户）
  - `month`: 月份（可选，格式：2026-03）
  - `year`: 年份（可选，格式：2026）
- **响应示例**：
  ```json
  {
    "code": 200,
    "data": {
      "2026-03-11": {
        "id": 1,
        "note": "备注信息",
        "tags": [
          {"id": 1, "name": "加班", "icon": "..."}
        ],
        "timestamp": "2026-03-11 09:00:00"
      }
    },
    "msg": "success"
  }
  ```

#### 3. 删除打卡记录

- **接口地址**：`DELETE /api/v1/checkin/:id`
- **路径参数**：
  - `id`: 打卡记录ID
- **响应示例**：
  ```json
  {
    "code": 200,
    "data": null,
    "msg": "success"
  }
  ```

### 标签相关接口

#### 1. 创建/更新标签

- **接口地址**：`POST /api/v1/tag`
- **请求参数**：
  ```json
  {
    "id": 0,
    "name": "加班",
    "icon": "https://example.com/icon.png"
  }
  ```
  - `id` 为 0 表示创建，非 0 表示更新

#### 2. 查询标签列表

- **接口地址**：`GET /api/v1/tag`
- **查询参数**：
  - `limit`: 返回数量（默认 100）
  - `offset`: 偏移量（默认 0）

#### 3. 删除标签

- **接口地址**：`DELETE /api/v1/tag/:id`

## 代码架构说明

### 分层架构

项目采用经典的分层架构：

1. **Handler 层**：处理 HTTP 请求和响应，参数验证，调用 Service 层
2. **Service 层**：实现业务逻辑，数据转换，事务管理
3. **Model 层**：定义数据模型，数据库映射

### 设计模式

- **依赖注入**：Service 通过构造函数注入依赖
- **接口隔离**：定义 Service 接口，便于测试和扩展
- **错误处理**：统一的错误定义和处理机制
- **响应格式**：统一的 JSON 响应格式

## 开发指南

### 添加新功能

1. 在 `models/` 中定义数据模型
2. 在 `dto/` 中定义请求和响应结构
3. 在 `internal/service/` 中实现业务逻辑
4. 在 `internal/handlers/` 中创建 HTTP 处理器
5. 在 `internal/routes/` 中注册路由

### 代码规范

- 遵循 Go 官方代码规范
- 使用 `gofmt` 格式化代码
- 使用 `golint` 检查代码
- 添加必要的注释和文档
- 编写单元测试

## 许可证

MIT License

## 联系方式

如有问题或建议，请提交 Issue 或 Pull Request。