# FTS - 文件传输服务

基于Go 1.26.5和Gin框架的现代化文件传输微服务

## 特性

- 🚀 **现代化架构**: 使用Go 1.26.5最新特性
- 📁 **多存储支持**: 支持本地存储和MinIO对象存储
- 🔧 **配置灵活**: 支持YAML配置文件，环境变量覆盖
- 🏥 **健康检查**: 完整的健康检查和监控端点
- 🔒 **安全性**: 文件类型检查，大小限制，JWT认证支持
- 📊 **可观测性**: 完整的日志记录和错误追踪
- 🐳 **容器化**: Docker和docker-compose开箱即用
- 🛠️ **开发友好**: 完整的Makefile工具链

## 快速开始

### 环境要求

- Go 1.26.5
- PostgreSQL / MySQL (可选)
- Redis (可选)
- MinIO (可选，用于对象存储)

### 安装依赖

```bash
make deps
```

### 运行服务

```bash
# 开发模式
make dev

# 或构建后运行
make build
make run
```

### 使用Docker

```bash
# 启动完整环境（包括数据库、Redis等）
docker-compose up -d

# 仅构建应用镜像
make docker-build
```

## API文档

### 健康检查

```http
GET /health         # 详细健康检查
GET /health/simple  # 简单健康检查
GET /version        # 版本信息
```

### 文件操作

```http
POST /fts/upload    # 文件上传
GET  /fts/download  # 文件下载
```

## 配置说明

主要配置文件：`etc/fts_dev.yaml`

```yaml
Service: fts
Host: 0.0.0.0
Port: 16290

# 数据库配置
Databases:
  Driver: postgres
  Source:
    - "postgres://user:pass@localhost/fts?sslmode=disable"

# 缓存配置
Cache: redis://localhost:6379/0

# 对象存储配置
MinioOss:
  Site: http://localhost:9000
  Endpoint: localhost:9000
  AccessKeyId: minioadmin
  AccessKeySecret: minioadmin
  UseSSL: false

# 本地存储配置
Local:
  Site: http://localhost:16290
  UploadDir: ./uploads/

# FTS特定配置
FtsConfig:
  InputKey: file
  MaxSize: 5368709120  # 5GB
  Allows:
    - .jpg
    - .png
    - .pdf
    - .doc
    # ... 更多支持的文件类型
```

## 开发工具

```bash
# 查看所有可用命令
make help

# 代码检查
make lint

# 运行测试
make test

# 安全扫描
make security

# 格式化代码
make fmt

# 更新依赖
make mod-update
```

## 构建和部署

```bash
# 构建所有平台
make build-all

# 构建Linux版本
make build-linux

# 构建Windows版本
make build-windows

# 构建macOS版本
make build-darwin
```

## 监控和运维

### 健康检查端点

- `GET /health` - 返回详细的服务状态，包括数据库、Redis、ETCD连接状态
- `GET /health/simple` - 返回简单的服务状态
- `HEAD /` - 快速健康检查

### 日志记录

服务支持结构化日志记录，日志级别可通过配置调整。

### 错误处理

统一的错误响应格式：

```json
{
  "code": 10001,
  "message": "错误描述",
  "trace_id": "request-trace-id"
}
```

## 项目结构

```
fts/
├── cmd/
│   ├── cli/          # CLI工具
│   └── main/         # 主服务入口
├── internal/
│   ├── config/       # 配置管理
│   ├── errors/       # 错误定义
│   ├── health/       # 健康检查
│   ├── impl/         # 服务实现
│   ├── logic/        # 业务逻辑
│   ├── models/       # 数据模型
│   ├── response/     # 响应处理
│   └── routers/      # 路由定义
├── etc/              # 配置文件
├── scripts/          # 脚本文件
├── test/             # 测试文件
├── build/            # 构建输出
├── Dockerfile        # Docker镜像构建
├── docker-compose.yml # Docker编排
├── Makefile          # 构建工具
└── README.md         # 项目文档
```

## 贡献指南

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](LICENSE) 文件了解详情。

## 联系方式

- 项目主页: [GitHub仓库地址]
- 问题反馈: [Issues页面]
- 邮箱: [team@example.com]