### YAML: Gopan Upload Service Configuration Example

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

This YAML snippet illustrates the configuration parameters for the Gopan upload service. It covers network settings, authentication secrets, RPC client configurations (Etcd), database connection strings, cache settings, local file paths, telemetry endpoints, and logging preferences.

```yaml
# Example: Upload service configuration (YAML)
Name: upload-api
Host: 0.0.0.0
Port: 8081
Timeout: 30000

Auth:
  AccessSecret: your-secret-key
  AccessExpire: 86400

RPC:
  Etcd:
    Hosts:
      - etcd:2379
    Key: upload.rpc

MysqlCluster:
  DataSource: root:password@tcp(mysql:3306)/gopan?charset=utf8mb4&parseTime=true

CacheRedis:
  - Host: redis-cluster:7001
  - Host: redis-cluster:7002
  - Host: redis-cluster:7003
  Type: cluster

FileLocalPath: /data/files/

Telemetry:
  Name: upload-api
  Endpoint: http://jaeger:14268/api/traces
  Sampler: 1.0
  Batcher: jaeger

Log:
  ServiceName: upload-api
  Mode: file
  Path: /var/log/gopan
  Level: info

```

--------------------------------

### Bash: Docker Compose Commands for Service Deployment

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

This set of bash commands utilizes Docker Compose to deploy and manage various services required by the Gopan project. It includes commands to start MySQL, Redis, and MinIO clusters, verify their status, and access their respective dashboards or consoles.

```bash
# Start MySQL InnoDB Cluster, Redis Cluster, MinIO Cluster
docker-compose -f docker-compose-env.yaml up -d

# Start MinIO cluster (4 nodes with 4 drives each)
docker-compose -f docker-compose-minio.yaml up -d

# Start Redis cluster (6 nodes: 3 masters + 3 slaves)
docker-compose -f docker-compose-redis.yaml up -d

# Verify all services are running
docker-compose ps

# Access services:
# - Traefik Dashboard: http://localhost:8080
# - Jaeger UI: http://localhost:16686
# - Prometheus: http://localhost:9090
# - Grafana: http://localhost:3000
# - Kibana: http://localhost:5601
# - MinIO Console: http://localhost:9001

```

--------------------------------

### Get User File List (Bash)

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Retrieves a list of all files associated with the authenticated user. This endpoint is useful for displaying a user's file inventory.

```bash
curl -X POST http://localhost:8080/filemeta/getUserfilemeta \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Get File Metadata (Bash)

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Retrieves detailed metadata for a file using its SHA1 hash. The returned information includes file ID, size, name, storage address, status, and timestamps.

```bash
curl -X POST http://localhost:8080/filemeta/getfilemeta \
  -H "Content-Type: application/json" \
  -d '{
    "fileSha1": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed"
  }'
```

--------------------------------

### User Authentication: Get User Information (API)

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Retrieves user profile information for a given user ID. This endpoint is protected by JWT authentication, requiring an Authorization header.

```bash
curl -X POST http://localhost:8080/account/userinfo \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "userId": 1001
  }'

# Response
{
  "code": 0,
  "message": "success",
  "data": {
    "Data": {
      "userId": 1001,
      "userNick": "张三",
      "userFace": "http://example.com/avatar.jpg",
      "userSex": 0,
      "userEmail": "user@example.com",
      "userPhone": "13800138000",
      "createTime": "2024-01-01T10:00:00Z",
      "updateTime": "2024-01-01T10:00:00Z"
    }
  }
}
```

--------------------------------

### Get File SHA1 Hash (Bash)

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Calculates and returns the SHA1 hash for an uploaded file. This is typically used by clients before uploading to check if the file already exists on the server, potentially allowing for instant upload.

```bash
curl -X POST http://localhost:8080/filemeta/getfilesha1 \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/document.pdf"
```

--------------------------------

### Initialize Multipart Upload (Bash)

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Initiates a chunked upload session for large files, enabling resume capabilities. It requires the file's SHA1 hash and size, returning an upload ID and chunk details. Redis is used to track upload progress.

```bash
curl -X POST http://localhost:8080/file/multipartupload/init \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "fileSha1": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
    "fileSize": 104857600
  }'
```

--------------------------------

### POST /file/multipartupload/init

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Initializes a multipart upload session for large files, allowing for chunked uploads and resume functionality. It returns essential details for subsequent chunk uploads.

```APIDOC
## POST /file/multipartupload/init

### Description
Starts a chunked upload session for large files with resume capability. This endpoint initializes the upload process and provides necessary identifiers for subsequent chunk uploads.

### Method
POST

### Endpoint
/file/multipartupload/init

### Parameters
#### Query Parameters
None

#### Request Body
- **fileSha1** (string) - Required - The SHA1 hash of the file to be uploaded.
- **fileSize** (integer) - Required - The total size of the file in bytes.

### Request Example
```json
{
  "fileSha1": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
  "fileSize": 104857600
}
```

### Response
#### Success Response (200)
- **code** (integer) - Indicates the success or failure of the operation.
- **message** (string) - A message describing the result of the operation.
- **data** (object) - Contains the upload initialization details.
  - **userId** (integer) - The ID of the user initiating the upload.
  - **fileSha1** (string) - The SHA1 hash of the file.
  - **fileSize** (integer) - The total size of the file in bytes.
  - **uploadId** (string) - A unique identifier for this upload session.
  - **chunkSize** (integer) - The recommended size for each file chunk in bytes.
  - **chunkCount** (integer) - The total number of chunks the file will be divided into.

#### Response Example
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "userId": 1001,
    "fileSha1": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
    "fileSize": 104857600,
    "uploadId": "550e8400-e29b-41d4-a716-446655440000",
    "chunkSize": 5242880,
    "chunkCount": 20
  }
}
```
```

--------------------------------

### Download File from MinIO (Bash)

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Downloads a file from MinIO storage using its SHA1 hash, file name, and storage address. The download is performed in parallel chunks and streamed to the client, with the Content-Disposition header setting the filename for browser downloads.

```bash
curl -X POST http://localhost:8080/file/download/minio \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "fileSha1": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
    "fileName": "document.pdf",
    "fileAddr": "minio/bucket/path/document.pdf"
  }' \
  -o downloaded_document.pdf
```

--------------------------------

### POST /file/download/minio

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Downloads a file from MinIO storage. This endpoint supports concurrent chunk downloads for efficient retrieval of large files.

```APIDOC
## POST /file/download/minio

### Description
Downloads a file from MinIO storage. This operation can be performed concurrently on chunks for improved download speed and efficiency.

### Method
POST

### Endpoint
/file/download/minio

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **fileSha1** (string) - Required - The SHA1 hash of the file to download.
- **fileName** (string) - Required - The name of the file.
- **fileAddr** (string) - Required - The address or path of the file within the MinIO storage.

### Request Example
```bash
curl -X POST http://localhost:8080/file/download/minio \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{ 
    "fileSha1": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
    "fileName": "document.pdf",
    "fileAddr": "minio/bucket/path/document.pdf"
  }' \
  -o downloaded_document.pdf
```

### Response
#### Success Response (200)
The file content is streamed directly to the output.

#### Response Example
(Binary file content)
```

--------------------------------

### Go: Asynchronous File Metadata Consumer and Processor

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

This Go service consumes file metadata from Kafka, parses it, and distributes it to multiple channels for concurrent processing. Each consumer goroutine then persists file and user-file relationships to a MySQL database. It's designed for high throughput with configurable concurrency and buffering.

```go
package service

import (
    "Gopan/app/upload/model"
    "encoding/json"
    "gorm.io/gorm"
)

const (
    chanCount   = 10   // Number of concurrent consumer goroutines
    bufferCount = 1024 // Buffer size per channel
)

type Service struct {
    msgsChan []chan *model.NewUserFile
    MysqlDb  *gorm.DB
}

// Kafka consumer implementation
func (s *Service) Consume(key string, value string) error {
    // Parse batched messages from Kafka
    var data []*model.NewUserFile
    if err := json.Unmarshal([]byte(value), &data); err != nil {
        return err
    }

    // Distribute messages to channels by userId for parallel processing
    for _, d := range data {
        s.msgsChan[d.UserId%chanCount] <- d
    }

    return nil
}

// Consumer goroutine processes messages and writes to database
func (s *Service) consume(ch chan *model.NewUserFile) {
    for message := range ch {
        file := model.File{
            FileSha1:   message.FileSha1,
            FileName:   message.FileName,
            FileSize:   message.FileSize,
            FileAddr:   message.FileAddr,
            Status:     message.Status,
            CreateTime: message.CreateTime,
            UpdateTime: message.UpdateTime,
        }

        // Insert file metadata (deduplication handled by unique constraint)
        s.MysqlDb.Create(&file)

        // Insert user-file relationship
        userfile := model.UserFile{
            UserId:   message.UserId,
            FileSha1: message.FileSha1,
            FileName: message.FileName,
            FileSize: message.FileSize,
            Status:   message.Status,
        }
        s.MysqlDb.Create(&userfile)
    }
}

// Start 10 parallel consumers for high throughput
// Messages batched in upload service before sending to Kafka

```

--------------------------------

### UserFile Model Definition

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Defines the UserFile database model, which maps users to files, allowing multiple users to reference the same file. It includes fields for user ID, file SHA1, file size, file name, and timestamps. This model supports compound indexing for efficient queries and utilizes Redis caching, with the cache key structure illustrated.

```go
package model

import (
    "time"
    "gorm.io/gorm"
)

type UserFile struct {
    Id         int64          `gorm:"column:id;primaryKey" db:"id"
    UserId     int64          `gorm:"column:user_id;index" db:"user_id"
    FileSha1   string         `gorm:"column:file_sha1;index" db:"file_sha1"
    FileSize   int64          `gorm:"column:file_size" db:"file_size"
    FileName   string         `gorm:"column:file_name" db:"file_name"
    CreateTime time.Time      `gorm:"column:create_time" db:"create_time"
    UpdateTime time.Time      `gorm:"column:update_time" db:"update_time"
    DeleteTime gorm.DeletedAt `gorm:"index" db:"delete_time"
    Status     int64          `gorm:"column:status" db:"status"
}

// Query user's file with compound index and cache
userFile, err := userFileModel.FindOneByUserIdFileSha1(
    ctx,
    1001,
    "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed"
)
// Cache key: cache:userFile:userId:fileSha1:1001:2aae6c35c94fcfb415dbe95f408b9ce91ee846ed
```

--------------------------------

### File Upload: Regular File Upload (API)

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Uploads a file to a specified storage backend (Local, MinIO, Tencent COS, Aliyun OSS, Qiniu). The file is first saved locally and then asynchronously transferred. SHA1 hash is computed for deduplication.

```bash
curl -X POST http://localhost:8080/file/upload \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -F "file=@/path/to/document.pdf" \
  -F "currentStoreType=2"

# currentStoreType: 1=Local, 2=MinIO, 3=Tencent COS, 4=Aliyun OSS, 5=Qiniu

# Response
{
  "code": 0,
  "message": "success",
  "data": null
}

# File is saved locally first, then asynchronously transferred to storage backend
# SHA1 hash is calculated for deduplication and instant upload capability
```

--------------------------------

### Download File from Tencent COS (Bash)

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Downloads a file from Tencent Cloud Object Storage (COS) using its SHA1 hash, file name, and storage address. This operation leverages the Tencent COS SDK for chunked downloads and stores the file locally before streaming.

```bash
curl -X POST http://localhost:8080/file/download/cos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "fileSha1": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
    "fileName": "presentation.pptx",
    "fileAddr": "cos/bucket/path/presentation.pptx"
  }' \
  -o downloaded_presentation.pptx
```

--------------------------------

### User Authentication API

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Provides endpoints for user registration, login, and profile management.

```APIDOC
## POST /account/sendcode

### Description
Sends a verification code to the user's phone number for registration or login.

### Method
POST

### Endpoint
`/account/sendcode`

### Parameters
#### Request Body
- **userPhone** (string) - Required - The user's phone number.

### Request Example
```json
{
  "userPhone": "13800138000"
}
```

### Response
#### Success Response (200)
- **code** (integer) - 0 for success.
- **message** (string) - "success".
- **data** (object) - Contains verification code details.
  - **veCode** (string) - The verification code.

#### Response Example
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "veCode": "123456"
  }
}
```
```

```APIDOC
## POST /account/register

### Description
Automatic registration or login using phone number and verification code, returns JWT tokens.

### Method
POST

### Endpoint
`/account/register`

### Parameters
#### Request Body
- **userPhone** (string) - Required - The user's phone number.
- **veCode** (string) - Required - The verification code sent to the user's phone.

### Request Example
```json
{
  "userPhone": "13800138000",
  "veCode": "123456"
}
```

### Response
#### Success Response (200)
- **code** (integer) - 0 for success.
- **message** (string) - "success".
- **data** (object) - Contains user and token details.
  - **userId** (integer) - The unique identifier for the user.
  - **accessToken** (string) - The JWT access token for authenticated requests.
  - **refreshToken** (string) - The JWT refresh token for obtaining new access tokens.

#### Response Example
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "userId": 1001,
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```
```

```APIDOC
## POST /account/login

### Description
Login using phone number or email with password authentication.

### Method
POST

### Endpoint
`/account/login`

### Parameters
#### Request Body
- **phoneOrEmail** (string) - Required - The user's phone number or email address.
- **PassWord** (string) - Required - The user's password (hashed).

### Request Example
```json
{
  "phoneOrEmail": "13800138000",
  "PassWord": "5f4dcc3b5aa765d61d8327deb882cf99"
}
```

### Response
#### Success Response (200)
- **code** (integer) - 0 for success.
- **message** (string) - "success".
- **data** (object) - Contains user and token details.
  - **userId** (integer) - The unique identifier for the user.
  - **accessToken** (string) - The JWT access token for authenticated requests.
  - **refreshToken** (string) - The JWT refresh token for obtaining new access tokens.

#### Response Example
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "userId": 1001,
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```
```

```APIDOC
## GET /account/github/login

### Description
Initiate GitHub OAuth authentication flow for third-party login. This endpoint redirects the user to GitHub's authorization page.

### Method
GET

### Endpoint
`/account/github/login`

### Parameters
None

### Request Example
```bash
curl -X GET http://localhost:8080/account/github/login
```

### Response
#### Success Response (302 Found)
Redirects the user to GitHub's OAuth page.

### Note
After successful GitHub authentication, GitHub will redirect the user back to a callback URL (e.g., `/account/github/callback?code=xxx`), which is handled by the system to complete the login process and return JWT tokens.
```

```APIDOC
## POST /account/userinfo

### Description
Retrieve user profile information. This is a JWT protected endpoint and requires an Authorization header.

### Method
POST

### Endpoint
`/account/userinfo`

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication (e.g., `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`).

#### Request Body
- **userId** (integer) - Required - The ID of the user whose information is to be retrieved.

### Request Example
```json
{
  "userId": 1001
}
```

### Response
#### Success Response (200)
- **code** (integer) - 0 for success.
- **message** (string) - "success".
- **data** (object) - Contains user profile details.
  - **Data** (object) - User profile information.
    - **userId** (integer) - The user's unique identifier.
    - **userNick** (string) - The user's nickname.
    - **userFace** (string) - URL to the user's profile picture.
    - **userSex** (integer) - The user's gender (e.g., 0 for unspecified).
    - **userEmail** (string) - The user's email address.
    - **userPhone** (string) - The user's phone number.
    - **createTime** (string) - The timestamp when the user account was created (ISO 8601 format).
    - **updateTime** (string) - The timestamp when the user account was last updated (ISO 8601 format).

#### Response Example
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "Data": {
      "userId": 1001,
      "userNick": "张三",
      "userFace": "http://example.com/avatar.jpg",
      "userSex": 0,
      "userEmail": "user@example.com",
      "userPhone": "13800138000",
      "createTime": "2024-01-01T10:00:00Z",
      "updateTime": "2024-01-01T10:00:00Z"
    }
  }
}
```
```

--------------------------------

### Database Models

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Details on the database models used for storing file and user file information.

```APIDOC
## Database Models

### File Model

Stores unique file metadata with SHA1-based deduplication.

```go
package model

import (
    "time"
    "gorm.io/gorm"
)

type File struct {
    Id         int64          `gorm:"column:id;primaryKey" db:"id"`
    FileSha1   string         `gorm:"column:file_sha1;unique" db:"file_sha1"`
    FileName   string         `gorm:"column:file_name" db:"file_name"`
    FileSize   int64          `gorm:"column:file_size" db:"file_size"`
    FileAddr   string         `gorm:"column:file_addr" db:"file_addr"`
    Status     int64          `gorm:"column:status" db:"status"`
    CreateTime time.Time      `gorm:"column:create_time" db:"create_time"`
    UpdateTime time.Time      `gorm:"column:update_time" db:"update_time"`
    DeleteTime gorm.DeletedAt `gorm:"column:delete_time" db:"delete_time"`
}

// Query by SHA1 with Redis cache
// file, err := fileModel.FindOneByFileSha1(ctx, "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed")
// Cache key: cache:file:fileSha1:2aae6c35c94fcfb415dbe95f408b9ce91ee846ed
```

### UserFile Model

Maps users to files, enabling multiple users to reference the same file.

```go
package model

import (
    "time"
    "gorm.io/gorm"
)

type UserFile struct {
    Id         int64          `gorm:"column:id;primaryKey" db:"id"`
    UserId     int64          `gorm:"column:user_id;index" db:"user_id"`
    FileSha1   string         `gorm:"column:file_sha1;index" db:"file_sha1"`
    FileSize   int64          `gorm:"column:file_size" db:"file_size"`
    FileName   string         `gorm:"column:file_name" db:"file_name"`
    CreateTime time.Time      `gorm:"column:create_time" db:"create_time"`
    UpdateTime time.Time      `gorm:"column:update_time" db:"update_time"`
    DeleteTime gorm.DeletedAt `gorm:"index" db:"delete_time"`
    Status     int64          `gorm:"column:status" db:"status"`
}

// Query user's file with compound index and cache
// userFile, err := userFileModel.FindOneByUserIdFileSha1(
//     ctx,
//     1001,
//     "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed"
// )
// Cache key: cache:userFile:userId:fileSha1:1001:2aae6c35c94fcfb415dbe95f408b9ce91ee846ed
```
```

--------------------------------

### File Upload: Instant Upload (Fast Upload) (API)

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Checks for the existence of a file using its SHA1 hash before uploading. If the file exists, the upload is skipped, improving efficiency. Requires JWT authentication.

```bash
curl -X POST http://localhost:8080/file/fastupload \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "fileSha1": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed"
  }'

# Response if file exists
{
  "code": 0,
  "message": "success",
  "data": null
}

# Response if file doesn't exist
{
  "code": 40004,
  "message": "文件不存在,请正常上传",
  "data": null
}
```

--------------------------------

### User Authentication: Register or Login with Verification Code (API)

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Performs automatic registration or login using a phone number and a verification code. It returns JWT access and refresh tokens upon successful authentication.

```bash
curl -X POST http://localhost:8080/account/register \
  -H "Content-Type: application/json" \
  -d '{
    "userPhone": "13800138000",
    "veCode": "123456"
  }'

# Response
{
  "code": 0,
  "message": "success",
  "data": {
    "userId": 1001,
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

--------------------------------

### User Authentication: GitHub OAuth Login (API)

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Initiates and handles the GitHub OAuth authentication flow for third-party login. It involves redirecting the user to GitHub and processing the callback.

```bash
# Step 1: Redirect user to GitHub OAuth
curl -X GET http://localhost:8080/account/github/login

# Step 2: GitHub callback (handled automatically)
# Returns user to: http://localhost:8080/account/github/callback?code=xxx

# Response after callback
{
  "code": 0,
  "message": "success",
  "data": {
    "userId": 1002,
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

--------------------------------

### Complete Multipart Upload (Bash)

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Finalizes the multipart upload process by merging all uploaded chunks and transferring the complete file to its final storage. It requires upload details and storage type. The system validates chunks, merges them, and sends metadata to Kafka.

```bash
curl -X POST http://localhost:8080/file/multipartupload/completeuploadpart \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "currentStoreType": 2,
    "fileSha1": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
    "fileName": "large_video.mp4",
    "fileSize": 104857600,
    "uploadId": "550e8400-e29b-41d4-a716-446655440000",
    "chunkCount": 20
  }'
```

--------------------------------

### File Upload API

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Endpoints for uploading files to various cloud storage backends.

```APIDOC
## POST /file/upload

### Description
Upload a file to the specified storage backend. The file is initially saved locally and then asynchronously transferred to the chosen storage backend. The SHA1 hash is calculated for deduplication and instant upload capability.

### Method
POST

### Endpoint
`/file/upload`

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication (e.g., `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`).

#### Form Data
- **file** (file) - Required - The file to upload.
- **currentStoreType** (integer) - Required - Specifies the storage backend type.
  - `1`: Local
  - `2`: MinIO
  - `3`: Tencent COS
  - `4`: Aliyun OSS
  - `5`: Qiniu

### Request Example
```bash
curl -X POST http://localhost:8080/file/upload \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -F "file=@/path/to/document.pdf" \
  -F "currentStoreType=2"
```

### Response
#### Success Response (200)
- **code** (integer) - 0 for success.
- **message** (string) - "success".
- **data** (null) - No specific data returned on successful upload.

#### Response Example
```json
{
  "code": 0,
  "message": "success",
  "data": null
}
```
```

```APIDOC
## POST /file/fastupload

### Description
Checks if a file already exists in the storage by its SHA1 hash. If the file exists, the upload is skipped, enabling instant upload functionality.

### Method
POST

### Endpoint
`/file/fastupload`

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication (e.g., `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`).

#### Request Body
- **fileSha1** (string) - Required - The SHA1 hash of the file to check.

### Request Example
```json
{
  "fileSha1": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed"
}
```

### Response
#### Success Response (200)
- **code** (integer) - 0 for success.
- **message** (string) - "success".
- **data** (null) - Indicates the file exists and upload is skipped.

#### File Not Found Response (40004)
- **code** (integer) - 40004.
- **message** (string) - "文件不存在,请正常上传" (File does not exist, please upload normally).
- **data** (null)

#### Response Example (File Exists)
```json
{
  "code": 0,
  "message": "success",
  "data": null
}
```

#### Response Example (File Not Found)
```json
{
  "code": 40004,
  "message": "文件不存在,请正常上传",
  "data": null
}
```
```

--------------------------------

### POST /filemeta/getUserfilemeta

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Retrieves a list of all files associated with the authenticated user. This endpoint is useful for displaying a user's file inventory.

```APIDOC
## POST /filemeta/getUserfilemeta

### Description
Retrieves a list of all files associated with the currently authenticated user. This endpoint is useful for displaying a user's file inventory or managing their uploaded files.

### Method
POST

### Endpoint
/filemeta/getUserfilemeta

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (Authentication is typically handled via headers, e.g., Authorization Bearer token).

### Request Example
```bash
curl -X POST http://localhost:8080/filemeta/getUserfilemeta \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

### Response
#### Success Response (200)
- **code** (integer) - Indicates the success or failure of the operation.
- **message** (string) - A message describing the result of the operation.
- **data** (object)
  - **fileList** (array of objects) - A list of file metadata objects for the user.
    - Each object in the array represents a file and contains fields similar to the `fileMeta` object in the `/filemeta/getfilemeta` endpoint (e.g., `fileSha1`, `fileName`, `fileSize`, `createTime`).

#### Response Example
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "fileList": [
      {
        "fileSha1": "abc123...",
        "fileName": "report.docx",
        "fileSize": 102400,
        "createTime": "2024-01-02T11:00:00Z"
      },
      {
        "fileSha1": "def456...",
        "fileName": "image.jpg",
        "fileSize": 2048000,
        "createTime": "2024-01-03T12:00:00Z"
      }
    ]
  }
}
```
```

--------------------------------

### POST /file/download/cos

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Downloads a file from Tencent Cloud Object Storage (COS). It utilizes the Tencent COS SDK for efficient, chunked downloads.

```APIDOC
## POST /file/download/cos

### Description
Downloads a file from Tencent Cloud Object Storage (COS). This endpoint leverages the Tencent COS SDK to perform chunked downloads, ensuring efficient retrieval of potentially large files.

### Method
POST

### Endpoint
/file/download/cos

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **fileSha1** (string) - Required - The SHA1 hash of the file to download.
- **fileName** (string) - Required - The name of the file.
- **fileAddr** (string) - Required - The address or path of the file within the Tencent COS storage.

### Request Example
```bash
curl -X POST http://localhost:8080/file/download/cos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{ 
    "fileSha1": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
    "fileName": "presentation.pptx",
    "fileAddr": "cos/bucket/path/presentation.pptx"
  }' \
  -o downloaded_presentation.pptx
```

### Response
#### Success Response (200)
The file content is downloaded and saved to the specified output file.

#### Response Example
(Binary file content)
```

--------------------------------

### POST /filemeta/getfilemeta

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Retrieves the metadata for a file, identified by its SHA1 hash. This includes details like file size, name, and storage location.

```APIDOC
## POST /filemeta/getfilemeta

### Description
Retrieves the metadata associated with a file, using its SHA1 hash as the identifier. This endpoint provides comprehensive information about the file, such as its size, name, storage path, and creation timestamps.

### Method
POST

### Endpoint
/filemeta/getfilemeta

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **fileSha1** (string) - Required - The SHA1 hash of the file whose metadata is to be retrieved.

### Request Example
```json
{
  "fileSha1": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed"
}
```

### Response
#### Success Response (200)
- **code** (integer) - Indicates the success or failure of the operation.
- **message** (string) - A message describing the result of the operation.
- **data** (object)
  - **fileMeta** (object) - An object containing the file's metadata.
    - **id** (integer) - The unique identifier of the file record.
    - **fileSha1** (string) - The SHA1 hash of the file.
    - **fileSize** (integer) - The size of the file in bytes.
    - **fileName** (string) - The name of the file.
    - **fileAddr** (string) - The storage path or address of the file.
    - **status** (integer) - The current status of the file.
    - **createTime** (string) - The timestamp when the file metadata was created (ISO 8601 format).
    - **updateTime** (string) - The timestamp when the file metadata was last updated (ISO 8601 format).

#### Response Example
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "fileMeta": {
      "id": 1,
      "fileSha1": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
      "fileSize": 1048576,
      "fileName": "document.pdf",
      "fileAddr": "/data/files/2aae6c35/document.pdf",
      "status": 0,
      "createTime": "2024-01-01T10:00:00Z",
      "updateTime": "2024-01-01T10:00:00Z"
    }
  }
}
```
```

--------------------------------

### POST /filemeta/updatauserfilemeta

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Updates the metadata for a user's file, specifically allowing renaming of the file.

```APIDOC
## POST /filemeta/updatauserfilemeta

### Description
Updates the metadata for a user's file, allowing for renaming.

### Method
POST

### Endpoint
/filemeta/updatauserfilemeta

### Parameters
#### Query Parameters
None

#### Request Body
- **fileName** (string) - Required - The new name for the file.
- **fileSha1** (string) - Required - The SHA1 hash of the file to identify it.

### Request Example
```json
{
  "fileName": "important_document.pdf",
  "fileSha1": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed"
}
```

### Response
#### Success Response (200)
- **code** (integer) - Indicates the status of the operation (0 for success).
- **message** (string) - A message describing the result of the operation.
- **data** (null) - This field is null upon successful update.

#### Response Example
```json
{
  "code": 0,
  "message": "success",
  "data": null
}
```
```

--------------------------------

### User Authentication: Password-Based Login (API)

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Handles user login using either a phone number or email combined with a password. Successful authentication returns JWT access and refresh tokens.

```bash
curl -X POST http://localhost:8080/account/login \
  -H "Content-Type: application/json" \
  -d '{
    "phoneOrEmail": "13800138000",
    "PassWord": "5f4dcc3b5aa765d61d8327deb882cf99"
  }'

# Response
{
  "code": 0,
  "message": "success",
  "data": {
    "userId": 1001,
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

--------------------------------

### File Model Definition

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Defines the File database model used for storing unique file metadata. It includes fields for file identification, hashing, naming, size, address, status, and timestamps. The model supports SHA1-based deduplication and integrates with GORM for database operations, with a note on Redis caching for queries.

```go
package model

import (
    "time"
    "gorm.io/gorm"
)

type File struct {
    Id         int64          `gorm:"column:id;primaryKey" db:"id"
    FileSha1   string         `gorm:"column:file_sha1;unique" db:"file_sha1"
    FileName   string         `gorm:"column:file_name" db:"file_name"
    FileSize   int64          `gorm:"column:file_size" db:"file_size"
    FileAddr   string         `gorm:"column:file_addr" db:"file_addr"
    Status     int64          `gorm:"column:status" db:"status"
    CreateTime time.Time      `gorm:"column:create_time" db:"create_time"
    UpdateTime time.Time      `gorm:"column:update_time" db:"update_time"
    DeleteTime gorm.DeletedAt `gorm:"column:delete_time" db:"delete_time"
}

// Query by SHA1 with Redis cache
file, err := fileModel.FindOneByFileSha1(ctx, "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed")
// Cache key: cache:file:fileSha1:2aae6c35c94fcfb415dbe95f408b9ce91ee846ed
```

--------------------------------

### POST /file/multipartupload/completeuploadpart

Source: https://context7.com/liuxianloveqiqi/gopan/llms.txt

Completes the multipart upload process by merging all uploaded chunks into a single file. It triggers the finalization of the file transfer and storage.

```APIDOC
## POST /file/multipartupload/completeuploadpart

### Description
Completes the multipart upload session by signaling that all chunks have been uploaded. The system then merges the chunks, uploads them to the final storage, and persists metadata.

### Method
POST

### Endpoint
/file/multipartupload/completeuploadpart

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **currentStoreType** (integer) - Required - The type of storage to use for the completed file.
- **fileSha1** (string) - Required - The SHA1 hash of the file.
- **fileName** (string) - Required - The name of the file.
- **fileSize** (integer) - Required - The total size of the file in bytes.
- **uploadId** (string) - Required - The unique identifier for the multipart upload session.
- **chunkCount** (integer) - Required - The total number of chunks that were uploaded.

### Request Example
```json
{
  "currentStoreType": 2,
  "fileSha1": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed",
  "fileName": "large_video.mp4",
  "fileSize": 104857600,
  "uploadId": "550e8400-e29b-41d4-a716-446655440000",
  "chunkCount": 20
}
```

### Response
#### Success Response (200)
- **code** (integer) - Indicates the success or failure of the operation.
- **message** (string) - A message describing the result of the operation.
- **data** (null) - Typically null upon successful completion.

#### Response Example
```json
{
  "code": 0,
  "message": "success",
  "data": null
}
```
```