# automizatiomTask

**Repository Path**: hackerSnail/automizatiom-task

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-06
- **Last Updated**: 2026-11-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TrackLog · 轻量打卡考勤系统

TrackLog 是一个面向个人与小团队的打卡考勤工具：记录每日签到/签退与工作片段，自动统计工时，支持团队共享、附件上传、Excel 导出与批量导入。

界面参考 NoteLume：极简、直觉、无冗余功能。数据默认仅自己可见，加入团队并由创建者授权后才可查看他人内容。

## 功能

- **打卡**：一键签到 / 签退，自动计算工时，迟到 / 早退状态识别
- **工作记录**：按片段记录开始/结束时间、类别、内容与可见性
- **附件**：工作记录可上传 pdf/doc/xls/图片/zip，单文件 ≤ 20 MB
- **团队**：创建团队、邀请码加入、成员权限（查看他人内容）细粒度控制
- **统计**：月度汇总、每日工时趋势、工作类别分布（ECharts）
- **导出**：考勤 / 工作内容 Excel，文件名自动带查询范围
- **导入**：模板下载、行级校验、事务批量写入、重复日期自动覆盖
- **权限隔离**：所有查询默认只返回自己的数据；团队查询在服务端校验 `can_view_others`

## 技术栈

| 端 | 选型 |
| --- | --- |
| 后端 | Go 1.26 · Gin · GORM · SQLite（纯 Go 驱动）/ PostgreSQL · Viper · Zap · JWT · excelize |
| 前端 | Vue 3 · Vite 6 · Element Plus · Pinia · Vue Router 4 · Axios · ECharts · dayjs |

## 目录结构

```
tracklog/
├── backend/
│   ├── cmd/api/main.go          # 入口
│   ├── internal/
│   │   ├── config/              # Viper 配置
│   │   ├── database/            # GORM 初始化与 AutoMigrate
│   │   ├── handler/             # HTTP 处理层
│   │   ├── middleware/          # JWT / CORS / 日志
│   │   ├── model/               # GORM 模型
│   │   ├── dto/                 # 请求 / 响应结构
│   │   ├── repository/          # 数据访问层
│   │   ├── service/             # 业务逻辑层
│   │   └── router/              # 路由装配
│   ├── pkg/                     # response / errors / auth / upload / excel(timeutil) / logger
│   ├── configs/                 # dev.yaml / prod.yaml
│   ├── migrations/              # SQL 参考
│   └── uploads/                 # 附件存储（运行时生成）
├── frontend/
│   ├── src/api/                 # Axios 封装与接口
│   ├── src/components/          # AppLayout / FileUploader / TeamMemberCard
│   ├── src/views/               # Login / CheckIn / Records / WorkLogEdit / Team / Stats / Export / Settings
│   ├── src/stores/              # Pinia
│   └── src/router/
├── docker-compose.yml
├── Dockerfile（backend / frontend 各自）
└── CLAUDE.md
```

## 本地开发

### 环境要求

- Go 1.26+（`go version`）
- Node.js 20+ 与 npm 10+

### 启动后端

```bash
cd backend
go mod download
go run ./cmd/api
# 默认 http://localhost:8080，SQLite 数据位于 backend/data/tracklog.db
```

首次启动会自动创建数据库表并生成 `backend/uploads` 目录。

可通过环境变量覆盖配置（前缀 `TRACKLOG_`）：

```bash
TRACKLOG_SERVER_PORT=9090 \
TRACKLOG_DATABASE_DRIVER=postgres \
TRACKLOG_DATABASE_DSN="host=localhost user=tracklog password=tracklog dbname=tracklog port=5432 sslmode=disable" \
TRACKLOG_JWT_SECRET=your-secret \
go run ./cmd/api
```

### 启动前端

```bash
cd frontend
npm install
npm run dev
# http://localhost:5173 ，已配置 /api 代理到 :8080
```

### 常用命令

```bash
# 后端
cd backend
go build ./...
go vet ./...
make build            # 输出 bin/tracklog

# 前端
cd frontend
npm run build         # 生产构建
npm run lint          # ESLint
```

## Docker 一键启动

```bash
docker-compose up -d
# 前端 http://localhost:5173
# 后端 http://localhost:8080
# PostgreSQL 数据持久化在 tracklog_pgdata 卷
```

`docker-compose.yml` 使用 PostgreSQL 作为数据库，并通过环境变量注入 JWT 密钥与 DSN。生产部署前请务必修改 `TRACKLOG_JWT_SECRET`。

## API 概览

所有 `/api/*` 接口（除登录、注册、health）都需要 `Authorization: Bearer <token>`。

统一响应：

```json
{ "code": 0, "message": "ok", "data": {} }
```

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/auth/register` | 注册（返回 token） |
| POST | `/api/auth/login` | 登录 |
| GET | `/api/auth/profile` | 当前用户信息 |
| POST | `/api/attendance/check-in` | 签到 |
| POST | `/api/attendance/check-out` | 签退 |
| GET | `/api/attendance/today` | 今日考勤 |
| GET | `/api/attendance?date=` | 指定日期考勤 |
| GET | `/api/attendance/range?start=&end=` | 日期范围考勤 |
| POST | `/api/work-logs` | 新增工作记录 |
| GET | `/api/work-logs?attendance_id=` | 某考勤的工作记录 |
| GET | `/api/work-logs/:id` | 工作记录详情 |
| PATCH | `/api/work-logs/:id` | 更新工作记录 |
| DELETE | `/api/work-logs/:id` | 删除工作记录 |
| POST | `/api/uploads/work-log?work_log_id=` | 上传附件（multipart，字段 `file`） |
| GET | `/api/uploads/:id` | 预览/下载附件 |
| DELETE | `/api/uploads/:id` | 删除附件 |
| POST | `/api/teams` | 创建团队 |
| POST | `/api/teams/join` | 邀请码加入 |
| GET | `/api/teams/my` | 我的团队 |
| GET | `/api/teams/:id/members` | 成员列表 |
| PATCH | `/api/teams/:id/members/:user_id` | 调整成员角色 / 查看权限 |
| GET | `/api/teams/:id/work-logs?start=&end=` | 团队成员工作一览 |
| GET | `/api/teams/:id/attendances?start=&end=` | 团队成员考勤 |
| GET | `/api/export/attendance.xlsx?start=&end=&team_id=` | 导出考勤 |
| GET | `/api/export/work-logs.xlsx?start=&end=&team_id=` | 导出工作内容 |
| GET | `/api/export/template.xlsx` | 下载导入模板 |
| POST | `/api/import/attendance` | 批量导入考勤（multipart，字段 `file`） |
| GET | `/api/stats/summary?month=` | 月度统计 |
| GET | `/api/stats/daily?date=` | 单日统计 |

### 权限与安全

- 工作记录 / 附件：仅作者可写，读需作者或团队授权
- 团队查看：服务端校验 `TeamMember.can_view_others`，不依赖前端隐藏 UI
- 上传：扩展名白名单 + 真实 MIME 检测 + 大小限制 + 日期分桶存储
- 附件下载走登录鉴权的代理地址，不暴露文件系统路径
- 导出团队数据：需团队成员且具备查看权限（或 owner/admin）

## 数据模型

`User` · `Team` · `TeamMember` · `Attendance` · `WorkLog` · `WorkAttachment`

`Attendance` 在 `(user_id, date)` 上建唯一索引，重复导入同一天记录会自动覆盖。所有主业务表使用 GORM 软删除。

## 测试账号（本地开发）

首次使用请在登录页注册，无内置账号。开发库位于 `backend/data/tracklog.db`，删除该文件可重置。