zsp-project/backend/readme.md

ZSP 后端管理系统

基于 Go + Gin + GORM + MySQL 构建的现代化合同管理与用户认证系统后端API。

📋 项目概述

ZSP 后端是一个用于供应链合同管理的企业级应用系统，提供用户认证、合同管理、文件存储等核心功能。系统采用微服务架构思想，具备高可扩展性和良好的开发体验。

主要特性

• 🔐 JWT 用户认证与授权
• 📄 合同全生命周期管理
• 🐳 Docker 容器化开发环境
• 🔄 热重载开发体验 (Air)
• 📊 MySQL 数据库支持
• 🧪 自动化数据库迁移
• 🔧 配置驱动架构

🏗️ 技术栈

后端框架

• Go 1.25.4 - 高性能编程语言
• Gin - 轻量级 Web 框架
• GORM - ORM 数据库工具
• JWT - 用户认证令牌

开发工具

• Docker & Docker Compose - 容器化开发环境
• Air - Go 应用热重载工具
• MySQL 8.0 - 关系型数据库

配置管理

• Viper - 配置管理库
• YAML 配置文件 - 结构化配置

📁 项目结构

zsp-backend/
├── cmd/api/                    # 应用入口
│   └── main.go                # 主程序入口
├── configs/                   # 配置文件
│   └── config.dev.yaml       # 开发环境配置
├── internal/                  # 内部包
│   ├── handler/              # HTTP 处理器
│   │   ├── user_handler.go   # 用户相关接口
│   │   └── contract_handler.go # 合同相关接口
│   ├── middleware/           # 中间件
│   │   └── auth.go          # 认证中间件
│   ├── model/               # 数据模型
│   │   ├── user.go          # 用户模型
│   │   ├── contract.go      # 合同模型
│   │   └── error.go         # 错误响应模型
│   ├── repository/          # 数据访问层
│   │   ├── user_repository.go
│   │   └── contract_repository.go
│   ├── service/             # 业务逻辑层
│   │   ├── user_service.go
│   │   └── contract_service.go
│   └── server/              # 服务器配置
│       └── router.go        # 路由配置
├── pkg/                     # 公共包
│   ├── config/             # 配置加载
│   └── database/           # 数据库连接
├── scripts/                # 脚本文件
│   └── init_database.sql   # 数据库初始化脚本
├── migrations/             # 数据库迁移文件
├── test/                   # 测试文件
├── web/                    # 前端文件（可选）
├── deployments/            # 部署配置
├── docs/                   # 文档
├── tmp/                    # 临时文件
└── bin/                    # 构建输出

🚀 快速开始

前提条件

• Docker & Docker Compose
• Go 1.25.4+ (可选，用于本地开发)

使用 Docker 开发环境（推荐）

1. 克隆项目

   git clone <repository-url>
   cd zsp-backend
   

2. 启动开发环境

   docker-compose -f docker-compose.dev.yml up --build
   

3. 访问应用

   • API 服务: http://localhost:8080
   • MySQL 数据库: localhost:3306

本地开发（不使用 Docker）

1. 安装依赖

   go mod download
   

2. 启动 MySQL 数据库

   # 使用 Docker 启动 MySQL
   docker run --name mysql-dev -e MYSQL_ROOT_PASSWORD=password \
     -e MYSQL_DATABASE=myapp -p 3306:3306 -d mysql:8.0
   

3. 运行应用

   # 使用 Air 热重载
   air -c .air.toml
   
   # 或直接运行
   go run cmd/api/main.go
   

🔧 配置说明

环境变量

创建 .env.dev 文件（参考 .env.dev.example）：

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=password
DB_NAME=myapp

# JWT 配置
JWT_SECRET=your-secret-key
JWT_EXPIRE_HOURS=24

配置文件 (configs/config.dev.yaml)

server:
  port: 8080
  mode: "debug"
  read_timeout: 30
  write_timeout: 30

database:
  host: "mysql"
  port: 3306
  user: "root"
  password: "password"
  dbname: "myapp"
  max_open_conns: 100
  max_idle_conns: 10
  reset_database: true

jwt:
  secret: "your-jwt-secret-key"
  expire_hours: 24

📖 API 文档

用户认证

用户注册

POST /api/v1/users/register
Content-Type: application/json

{
  "username": "testuser",
  "email": "test@example.com",
  "password": "password123"
}

用户登录

POST /api/v1/users/login
Content-Type: application/json

{
  "email": "test@example.com",
  "password": "password123"
}

响应：

{
  "message": "Login successful",
  "user": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

合同管理

创建合同

POST /api/v1/contracts
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "name": "采购合同",
  "contract_type": "采购",
  "contract_code": "CG2024001",
  "buy_party": "买方公司",
  "sell_party": "卖方公司",
  "count_party": "计数方",
  "unit_price": "1000.00",
  "bl_number": "BL123456",
  "delivery_time": "2024-12-31",
  "pickup_time": "2024-12-30",
  "packaging": "标准包装",
  "remarks": "备注信息",
  "file_path": "/uploads/contract.pdf"
}

获取合同列表

GET /api/v1/contracts
Authorization: Bearer <jwt-token>

🗄️ 数据模型

用户表 (users)

字段	类型	描述
id	uint	主键
username	string(50)	用户名，唯一
email	string(100)	邮箱，唯一
password	string(255)	密码哈希
created_at	datetime	创建时间
updated_at	datetime	更新时间

合同表 (contracts)

字段	类型	描述
id	uint	主键
name	string(100)	合同名称
contract_type	string(50)	合同类型
contract_code	string(50)	合同编码
buy_party	string(100)	买方
sell_party	string(100)	卖方
count_party	string(100)	计数方
unit_price	string(50)	单价
bl_number	string(50)	提单号
delivery_time	string(50)	交付时间
pickup_time	string(50)	提货时间
packaging	string(50)	包装方式
remarks	string(255)	备注
file_path	string(255)	文件路径

🐳 Docker 开发环境

开发环境配置 (docker-compose.dev.yml)

• 应用服务: Go + Air 热重载
• 数据库服务: MySQL 8.0
• 网络配置: 自定义网络 app-network
• 卷挂载: 代码实时同步，Go 模块缓存

构建自定义镜像

# 构建开发镜像
docker build -f Dockerfile.dev -t zsp-backend-dev .

# 运行容器
docker run -p 8080:8080 -v $(pwd):/workspace zsp-backend-dev

🧪 测试

运行测试

# 运行所有测试
go test ./...

# 运行特定包测试
go test ./internal/handler

# 运行测试并显示覆盖率
go test -cover ./...

测试数据库

测试环境使用独立的数据库 myapp_test，通过初始化脚本自动创建。

🔄 数据库迁移

自动迁移

在开发环境中，设置 reset_database: true 会自动执行数据库迁移：

if cfg.Database.ResetDatabase {
    err = database.AutoMigrate(db)
    // ...
}

手动迁移

1. 创建迁移文件在 migrations/ 目录
2. 使用 GORM 的 AutoMigrate 或手动执行 SQL

📊 部署

生产环境构建

# 构建生产镜像
docker build -t zsp-backend-prod .

# 使用生产配置
docker run -p 8080:8080 \
  -v /path/to/config.yaml:/app/config.yaml \
  zsp-backend-prod

环境变量配置

生产环境建议使用环境变量覆盖配置文件：

export DB_HOST=production-db
export DB_PASSWORD=secure-password
export JWT_SECRET=production-secret

🛠️ 开发工具

Air 热重载配置 (.air.toml)

• 自动检测文件变化并重新编译
• 排除测试文件和构建目录
• 自定义构建命令和输出目录

代码规范

• 使用 go fmt 格式化代码
• 遵循 Go 官方代码规范
• 使用有意义的包和函数命名

🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

📞 支持

如有问题或建议，请：

1. 查看 Issues
2. 提交新的 Issue
3. 联系项目维护者

---

最后更新: 2024年1月 版本: 1.0.0-dev