# staking

**Repository Path**: jack1995/staking

## Basic Information

- **Project Name**: staking
- **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-07-22
- **Last Updated**: 2026-07-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SF 质押系统 API

基于 **Gin + PostgreSQL (GORM) + Swagger** 的 Go Web 服务，提供「质押记录」与「快照表」两张表的增删改查接口。

## 技术栈

- [Gin](https://github.com/gin-gonic/gin) — Web 框架
- [GORM](https://gorm.io) + PostgreSQL 驱动 — ORM / 数据库
- [swaggo/swag](https://github.com/swaggo/swag) — Swagger 文档自动生成

## 目录结构

```
staking/
├── main.go                       # 入口，含 Swagger 顶层注解
├── config/                       # 环境变量配置
├── internal/
│   ├── database/                 # 数据库连接与自动迁移
│   ├── models/                   # 数据模型（staking_record / snapshot）
│   ├── handlers/                 # CRUD 接口处理器
│   ├── response/                 # 统一响应结构
│   └── router/                   # 路由注册
├── docs/                         # swag 生成的 Swagger 文档
├── .env.example                  # 环境变量示例
└── go.mod
```

## 数据表

### 质押记录表 `staking_records`

| 字段 | 说明 |
| --- | --- |
| id | 记录ID（系统生成） |
| wallet_address | 钱包地址 |
| staked_usdt | 质押 USDT |
| obtained_sf | 获得 SF |
| ratio | 比例（如 `1:10`） |
| status | 状态（默认「成功」） |
| created_at / updated_at | 时间 |

### 快照表 `holder_snapshots`（SF Holder Snapshot）

| 字段 | 说明 |
| --- | --- |
| id | 记录ID |
| snapshot_date | 快照日期 |
| address | 钱包地址 |
| balance | SF 数量 |
| snapshot_time | 快照创建时间 |
| created_at / updated_at | 时间 |

## 快速开始

### 1. 准备数据库

确保本地有 PostgreSQL，并创建数据库：

```bash
createdb staking
```

### 2. 配置环境变量

```bash
cp .env.example .env
# 按需修改 .env 中的数据库连接信息
```

### 3. 运行

```bash
go run .
```

启动后表会自动迁移创建。服务默认监听 `:8080`。

### 4. 查看 Swagger 文档

浏览器打开：<http://localhost:8080/swagger/index.html>

## 重新生成 Swagger 文档

修改接口注解后，重新生成文档：

```bash
go install github.com/swaggo/swag/cmd/swag@latest
swag init -g main.go -o docs
```

## API 一览（前缀 `/api/v1`）

### 质押记录
- `POST   /staking-records`        创建
- `GET    /staking-records`        列表（分页，支持 `wallet_address`、`status` 过滤）
- `GET    /staking-records/{id}`   详情
- `PUT    /staking-records/{id}`   更新
- `DELETE /staking-records/{id}`   删除

### 快照表
- `POST   /snapshots`        创建
- `GET    /snapshots`        列表（分页，支持 `address`、`snapshot_date` 过滤）
- `GET    /snapshots/{id}`   详情
- `PUT    /snapshots/{id}`   更新
- `DELETE /snapshots/{id}`   删除

## 请求示例

```bash
# 创建质押记录
curl -X POST http://localhost:8080/api/v1/staking-records \
  -H "Content-Type: application/json" \
  -d '{"wallet_address":"0x1234","staked_usdt":100,"obtained_sf":1000,"ratio":"1:10"}'

# 创建快照
curl -X POST http://localhost:8080/api/v1/snapshots \
  -H "Content-Type: application/json" \
  -d '{"snapshot_date":"2026-06-01","address":"0x1234","balance":1000}'
```