# domain-backend

**Repository Path**: hengk/domain-backend

## Basic Information

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

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README


## 🚀 快速开始

### 环境要求

- Go 1.21+ (推荐 1.24.4)
- Git
- SQLite3 (默认) 或 MySQL 5.7+

### 1. 克隆项目

```bash
git clone https://gitee.com/hengk/domain-backend
cd domain-backend
```
### 2. 配置环境

编辑 `.env` 文件：

```env
# 服务端口
PORT=8080

# 数据库类型 (sqlite/mysql)
DB_TYPE=sqlite

# SQLite 配置 (默认)
DATABASE_URL=./payment_system.db

# MySQL 配置 (可选)
# DATABASE_URL=root:password@tcp(localhost:3306)/payment_system?charset=utf8mb4&parseTime=True&loc=Local

# 运行环境
ENVIRONMENT=development

# JWT密钥
JWT_SECRET=your-secret-key-here
```

### 3. 安装依赖

```bash
go mod download
go mod tidy
```
### 4. 运行项目

#### 使用 Mage（推荐）

```bash
# 开发模式
mage dev

# 后台运行
mage start

# 查看状态
mage status
```

#### 开发模式

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

#### 编译运行

```bash
# 使用 mage 构建
mage build
# 运行
./domain-system.exe

# 或手动编译
go build -o domain-system.exe .
./domain-system.exe
```

### 5. 验证服务

访问健康检查接口：

```bash
curl http://localhost:8080/health
```

预期响应：
```json
{
  "status": "ok",
  "message": "Payment system is running"
}
```


## 🛠️ Mage 任务管理

本项目使用 [Mage](https://magefile.org/) 作为构建工具，提供了便捷的任务管理功能。

### 安装 Mage

```bash
# 安装 mage 工具
go install github.com/magefile/mage@latest

# 或者直接使用 go run
go run mage.go [任务名]
```

### 可用任务

#### 构建相关

```bash
# 构建项目
mage build
# 或
go run mage.go build

# 清理构建文件
mage clean

# 运行测试
mage test

# 安装依赖
mage install
```

#### 服务管理

```bash
# 启动服务（后台运行）
mage start

# 停止服务
mage stop

# 重启服务
mage restart

# 查看服务状态
mage status

# 查看服务日志
mage logs

# 开发模式运行（前台运行）
mage dev
```

#### 部署相关

```bash
# 部署到生产环境（包含构建、测试、重启）
mage deploy
```

### 任务详细说明

| 任务 | 描述 | 用途 |
|------|------|------|
| `build` | 编译项目生成可执行文件 | 生产部署前的构建 |
| `clean` | 清理构建产物和临时文件 | 清理工作空间 |
| `test` | 运行所有单元测试 | 代码质量保证 |
| `start` | 后台启动服务 | 生产环境运行 |
| `stop` | 停止后台服务 | 服务维护 |
| `restart` | 重启服务 | 配置更新后重启 |
| `status` | 查看服务运行状态 | 服务监控 |
| `logs` | 查看服务日志 | 问题排查 |
| `dev` | 开发模式运行 | 开发调试 |
| `install` | 安装和整理依赖 | 环境准备 |
| `deploy` | 一键部署 | 生产环境部署 |

### 服务管理文件

使用 mage 启动服务后，会生成以下文件：
- `domain-system.pid`: 进程ID文件
- `domain-system.log`: 服务日志文件

### 使用示例

```bash
# 开发流程
mage install    # 安装依赖
mage test       # 运行测试
mage dev        # 开发模式运行

# 生产部署流程
mage build      # 构建项目
mage start      # 启动服务
mage status     # 检查状态
mage logs       # 查看日志

# 服务维护
mage stop       # 停止服务
mage clean      # 清理文件
mage restart    # 重启服务

# 一键部署
mage deploy     # 自动执行：清理 -> 构建 -> 测试 -> 重启
```

## 📚 API 文档

### 基础信息

- **Base URL**: `http://localhost:8080`
- **API Version**: `v1`
- **Content-Type**: `application/json`
- **认证方式**: JWT Token (部分接口需要)

### 接口列表

#### 系统接口

##### 1. 健康检查

```http
GET /health
```

**响应示例**:
```json
{
  "status": "ok",
  "message": "Payment system is running"
}
```

##### 2. 系统信息

```http
GET /info
```

**响应示例**:
```json
{
  "status": "ok",
  "message": "Payment system information",
  "database": "SQLite3",
  "version": "1.0.0",
  "environment": "development"
}
```

#### 支付接口

##### 3. 查询支付状态

```http
GET /api/v1/payment/status?group_id={群号}&applicant_id={申请人ID}
```

**参数**:
- `group_id` (string, required): 群号
- `applicant_id` (string, required): 申请人ID

**响应示例**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "group_id": "12345",
    "applicant_id": "user001",
    "amount": 100.00,
    "status": "paid",
    "transaction_id": "tx_123456789",
    "created_at": "2024-01-01T10:00:00Z",
    "updated_at": "2024-01-01T10:05:00Z"
  }
}
```

##### 4. 创建支付记录

```http
POST /api/v1/payment/create
```

**请求体**:
```json
{
  "group_id": "12345",
  "applicant_id": "user001",
  "amount": 100.00,
  "description": "群组费用支付"
}
```

**响应示例**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "group_id": "12345",
    "applicant_id": "user001",
    "amount": 100.00,
    "status": "pending",
    "transaction_id": "tx_123456789",
    "description": "群组费用支付",
    "created_at": "2024-01-01T10:00:00Z"
  },
  "message": "支付记录创建成功"
}
```

##### 5. 更新支付状态

```http
PUT /api/v1/payment/status
```

**请求体**:
```json
{
  "transaction_id": "tx_123456789",
  "status": "paid"
}
```

**支付状态枚举**:
- `pending`: 待支付
- `paid`: 已支付
- `failed`: 支付失败
- `cancelled`: 已取消

**响应示例**:
```json
{
  "success": true,
  "message": "支付状态更新成功"
}
```

#### 帖子管理接口

##### 6. 创建帖子

```http
POST /api/v1/posts/
```

**请求头**:
- `Authorization: Bearer {JWT_TOKEN}`

**请求体**:
```json
{
  "title": "帖子标题",
  "content": "帖子内容",
  "circle_id": "circle_001",
  "tags": ["tag1", "tag2"],
  "visibility": "public"
}
```

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "id": "post_001",
    "title": "帖子标题",
    "content": "帖子内容",
    "user_id": "user_001",
    "circle_id": "circle_001",
    "like_count": 0,
    "comment_count": 0,
    "created_at": "2024-01-01T10:00:00Z"
  }
}
```

##### 7. 获取帖子详情

```http
GET /api/v1/posts/{id}
```

**路径参数**:
- `id` (string, required): 帖子ID

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "id": "post_001",
    "title": "帖子标题",
    "content": "帖子内容",
    "user_id": "user_001",
    "circle_id": "circle_001",
    "tags": ["tag1", "tag2"],
    "like_count": 10,
    "comment_count": 5,
    "is_liked": false,
    "created_at": "2024-01-01T10:00:00Z",
    "updated_at": "2024-01-01T10:00:00Z"
  }
}
```

##### 8. 更新帖子

```http
PUT /api/v1/posts/{id}
```

**请求头**:
- `Authorization: Bearer {JWT_TOKEN}`

**路径参数**:
- `id` (string, required): 帖子ID

**请求体**:
```json
{
  "title": "更新后的标题",
  "content": "更新后的内容",
  "tags": ["tag1", "tag3"]
}
```

**响应示例**:
```json
{
  "status": "success",
  "message": "帖子更新成功"
}
```

##### 9. 删除帖子

```http
DELETE /api/v1/posts/{id}
```

**请求头**:
- `Authorization: Bearer {JWT_TOKEN}`

**路径参数**:
- `id` (string, required): 帖子ID

**响应示例**:
```json
{
  "status": "success",
  "message": "帖子删除成功"
}
```

##### 10. 点赞帖子

```http
POST /api/v1/posts/{id}/like
```

**请求头**:
- `Authorization: Bearer {JWT_TOKEN}`

**路径参数**:
- `id` (string, required): 帖子ID

**响应示例**:
```json
{
  "status": "success",
  "message": "点赞成功"
}
```

##### 11. 取消点赞

```http
DELETE /api/v1/posts/{id}/like
```

**请求头**:
- `Authorization: Bearer {JWT_TOKEN}`

**路径参数**:
- `id` (string, required): 帖子ID

**响应示例**:
```json
{
  "status": "success",
  "message": "取消点赞成功"
}
```

##### 12. 获取帖子评论

```http
GET /api/v1/posts/{id}/comments
```

**路径参数**:
- `id` (string, required): 帖子ID

**查询参数**:
- `page` (int, optional): 页码，默认为1
- `limit` (int, optional): 每页数量，默认为20

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "comments": [
      {
        "id": "comment_001",
        "post_id": "post_001",
        "user_id": "user_002",
        "content": "评论内容",
        "created_at": "2024-01-01T10:05:00Z"
      }
    ],
    "total": 5,
    "page": 1,
    "limit": 20
  }
}
```

##### 13. 创建评论

```http
POST /api/v1/posts/{id}/comments
```

**请求头**:
- `Authorization: Bearer {JWT_TOKEN}`

**路径参数**:
- `id` (string, required): 帖子ID

**请求体**:
```json
{
  "content": "评论内容"
}
```

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "id": "comment_001",
    "post_id": "post_001",
    "user_id": "user_001",
    "content": "评论内容",
    "created_at": "2024-01-01T10:05:00Z"
  }
}
```

#### 圈子接口

##### 14. 获取圈子列表

```http
GET /api/v1/circles/
```

**响应示例**:
```json
{
  "status": "success",
  "data": [
    {
      "id": "global",
      "name": "全球圈",
      "description": "全球用户交流圈子",
      "post_count": 1000
    },
    {
      "id": "china",
      "name": "中国圈",
      "description": "中国用户交流圈子",
      "post_count": 500
    }
  ]
}
```

##### 15. 获取圈子帖子

```http
GET /api/v1/circles/{circle_id}/posts
```

**路径参数**:
- `circle_id` (string, required): 圈子ID

**查询参数**:
- `page` (int, optional): 页码，默认为1
- `limit` (int, optional): 每页数量，默认为20
- `sort` (string, optional): 排序方式，可选值：`latest`、`popular`

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "posts": [
      {
        "id": "post_001",
        "title": "帖子标题",
        "content": "帖子内容摘要...",
        "user_id": "user_001",
        "like_count": 10,
        "comment_count": 5,
        "created_at": "2024-01-01T10:00:00Z"
      }
    ],
    "total": 100,
    "page": 1,
    "limit": 20
  }
}
```

##### 16. 获取全球圈帖子

```http
GET /api/v1/circles/global/posts
```

**查询参数**:
- `page` (int, optional): 页码，默认为1
- `limit` (int, optional): 每页数量，默认为20
- `sort` (string, optional): 排序方式

##### 17. 获取国家圈帖子

```http
GET /api/v1/circles/country/{country}/posts
```

**路径参数**:
- `country` (string, required): 国家代码，如 "china"、"usa"

**查询参数**:
- `page` (int, optional): 页码，默认为1
- `limit` (int, optional): 每页数量，默认为20

##### 18. 获取城市圈帖子

```http
GET /api/v1/circles/city/{city}/posts
```

**路径参数**:
- `city` (string, required): 城市代码，如 "beijing"、"shanghai"

**查询参数**:
- `page` (int, optional): 页码，默认为1
- `limit` (int, optional): 每页数量，默认为20

#### 标签接口

##### 19. 获取标签列表

```http
GET /api/v1/tags/
```

**响应示例**:
```json
{
  "status": "success",
  "data": [
    {
      "id": "tag_001",
      "name": "技术",
      "post_count": 100
    },
    {
      "id": "tag_002",
      "name": "生活",
      "post_count": 80
    }
  ]
}
```

##### 20. 获取标签帖子

```http
GET /api/v1/tags/{tag_id}/posts
```

**路径参数**:
- `tag_id` (string, required): 标签ID

**查询参数**:
- `page` (int, optional): 页码，默认为1
- `limit` (int, optional): 每页数量，默认为20

#### 用户接口

##### 21. 获取用户帖子

```http
GET /api/v1/users/{user_id}/posts
```

**路径参数**:
- `user_id` (string, required): 用户ID

**查询参数**:
- `page` (int, optional): 页码，默认为1
- `limit` (int, optional): 每页数量，默认为20

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "posts": [
      {
        "id": "post_001",
        "title": "帖子标题",
        "content": "帖子内容摘要...",
        "like_count": 10,
        "comment_count": 5,
        "created_at": "2024-01-01T10:00:00Z"
      }
    ],
    "total": 50,
    "page": 1,
    "limit": 20
  }
}
```

##### 22. 关注用户

```http
POST /api/v1/users/{user_id}/follow
```

**请求头**:
- `Authorization: Bearer {JWT_TOKEN}`

**路径参数**:
- `user_id` (string, required): 要关注的用户ID

**响应示例**:
```json
{
  "status": "success",
  "message": "关注成功"
}
```

##### 23. 取消关注

```http
DELETE /api/v1/users/{user_id}/follow
```

**请求头**:
- `Authorization: Bearer {JWT_TOKEN}`

**路径参数**:
- `user_id` (string, required): 要取消关注的用户ID

**响应示例**:
```json
{
  "status": "success",
  "message": "取消关注成功"
}
```

#### 认证接口

##### 24. 用户注册

```http
POST /api/v1/auth/register
```

**请求体**:
```json
{
  "phone": "13800138000",
  "password": "password123",
  "username": "testuser",
  "nickname": "测试用户"
}
```

**响应示例**:
```json
{
  "status": "success",
  "message": "注册成功",
  "data": {
    "user_id": "user_001",
    "username": "testuser",
    "nickname": "测试用户",
    "phone": "13800138000",
    "is_active": true,
    "created_at": "2024-01-01T10:00:00Z"
  }
}
```

##### 25. 用户登录

```http
POST /api/v1/auth/login
```

**请求体**:
```json
{
  "phone": "13800138000",
  "password": "password123"
}
```

**响应示例**:
```json
{
  "status": "success",
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "user_id": "user_001",
      "username": "testuser",
      "nickname": "测试用户",
      "phone": "13800138000"
    }
  }
}
```

##### 26. 获取用户资料

```http
GET /api/v1/user/profile
```

**请求头**:
- `Authorization: Bearer {JWT_TOKEN}`

**响应示例**:
```json
{
  "status": "success",
  "data": {
    "user_id": "user_001",
    "username": "testuser",
    "nickname": "测试用户",
    "phone": "13800138000",
    "is_active": true,
    "created_at": "2024-01-01T10:00:00Z",
    "updated_at": "2024-01-01T10:00:00Z"
  }
}
```

##### 27. 用户注销

```http
POST /api/v1/user/logout
```

**请求头**:
- `Authorization: Bearer {JWT_TOKEN}`

**响应示例**:
```json
{
  "status": "success",
  "message": "注销成功"
}
```

##### 28. 注销账户

```http
DELETE /api/v1/user/deactivate
```

**请求头**:
- `Authorization: Bearer {JWT_TOKEN}`

**响应示例**:
```json
{
  "status": "success",
  "message": "账户已注销"
}
```
### 错误响应格式

所有接口在出现错误时，都会返回统一的错误格式：

```json
{
  "status": "error",
  "message": "错误描述",
  "code": "ERROR_CODE"
}
```

**常见错误码**:
- `400`: 请求参数错误
- `401`: 未授权访问
- `403`: 权限不足
- `404`: 资源不存在
- `500`: 服务器内部错误

### 认证说明

需要认证的接口需要在请求头中包含 JWT Token：

```http
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

获取 Token 的方式请参考用户认证相关接口文档。

## 🗄️ 数据库配置

### SQLite3 (默认推荐)

```env
DB_TYPE=sqlite
DATABASE_URL=./payment_system.db
```

**优势**:
- 零配置，开箱即用
- 适合开发和小规模部署
- 数据文件便于备份和迁移

### MySQL

```env
DB_TYPE=mysql
DATABASE_URL=root:password@tcp(localhost:3306)/payment_system?charset=utf8mb4&parseTime=True&loc=Local
```

**优势**:
- 适合生产环境
- 支持高并发
- 丰富的管理工具

**MySQL 数据库创建**:
```sql
CREATE DATABASE payment_system CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

## 🧪 测试


### 单元测试

```bash
# 运行所有测试
go test ./tests/... -v

# 运行特定模块测试
go test ./tests/ -run TestAuthTestSuite -v          # 认证模块测试
go test ./tests/ -run TestPaymentTestSuite -v       # 支付模块测试
go test ./tests/ -run TestPostTestSuite -v          # 帖子模块测试
go test ./tests/ -run TestOpenIMServiceTestSuite -v # OpenIM服务测试
# 运行测试并显示覆盖率
go test ./tests/... -v -cover

# 生成测试覆盖率报告
go test ./tests/... -coverprofile=coverage.out
go tool cover -html=coverage.out -o coverage.html

# 运行基准测试
go test ./tests/ -bench=. -benchmem

# 运行特定测试用例
go test ./tests/ -run TestAuthTestSuite/TestLogin -v
go test ./tests/ -run TestPaymentTestSuite/TestCreatePayment -v
go test ./tests/ -run TestPostTestSuite/TestCreatePost -v
```

### 功能测试

```bash
# 1. 启动服务
go run main.go

# 2. 健康检查
curl http://localhost:8080/health

# 3. 创建支付记录
curl -X POST http://localhost:8080/api/v1/payment/create \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "12345",
    "applicant_id": "user001",
    "amount": 100.00,
    "description": "测试支付"
  }'

# 4. 查询支付状态
curl "http://localhost:8080/api/v1/payment/status?group_id=12345&applicant_id=user001"

# 5. 更新支付状态
curl -X PUT http://localhost:8080/api/v1/payment/status \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "返回的交易ID",
    "status": "paid"
  }'
```

### 性能测试

```bash
# 使用 Apache Bench 进行压力测试
ab -n 1000 -c 10 http://localhost:8080/health

# 运行 Go 基准测试
go test ./tests/ -bench=BenchmarkCreatePayment -benchmem
go test ./tests/ -bench=BenchmarkCheckPaymentStatus -benchmem
go test ./tests/ -bench=BenchmarkHealthCheck -benchmem
```

## 🔧 开发指南

### 代码结构说明

- **main.go**: 程序入口，负责初始化和启动服务
- **config/**: 配置管理，支持环境变量和 .env 文件
- **database/**: 数据库连接和初始化逻辑
- **models/**: 数据模型定义，使用 GORM 标签
- **handlers/**: HTTP 请求处理器，处理路由逻辑
- **services/**: 业务逻辑层，处理具体业务操作
- **routes/**: 路由配置，定义 API 端点

### 添加新功能

1. 在 `models/` 中定义数据模型
2. 在 `services/` 中实现业务逻辑
3. 在 `handlers/` 中添加 HTTP 处理器
4. 在 `routes/` 中注册新路由

### 代码规范

- 使用 `gofmt` 格式化代码
- 遵循 Go 官方命名规范
- 添加必要的注释和文档
- 使用 `go vet` 检查代码质量

## 🚨 故障排除

### 常见问题

1. **端口被占用**
   ```bash
   # 查找占用端口的进程
   netstat -ano | findstr :8080
   # 终止进程
   taskkill /PID <进程ID> /F
   ```

2. **数据库连接失败**
   - 检查 `.env` 文件配置
   - 确认 MySQL 服务是否启动
   - 验证数据库用户权限

3. **编译失败**
   - 检查 Go 版本是否符合要求
   - 运行 `go mod tidy` 整理依赖
   - 检查网络连接和代理设置

4. **权限问题**
   - 以管理员身份运行
   - 检查文件夹读写权限
   - 关闭杀毒软件干扰

### 日志调试

```bash
# 启用详细日志
export GIN_MODE=debug
go run main.go

# 查看数据库查询日志
# 在 database.go 中启用 GORM 日志
```

## 📈 性能优化

### 数据库优化

- 为查询字段添加索引
- 使用连接池管理数据库连接
- 定期清理过期数据

### 应用优化

- 启用 Gin 的生产模式
- 使用缓存减少数据库查询
- 配置适当的超时时间

## 🔒 安全建议

- 修改默认的 JWT_SECRET
- 使用 HTTPS 部署生产环境
- 实施 API 限流和认证
- 定期更新依赖包版本
- 配置防火墙规则