photography/backend/api/desc/admin/photos.api

syntax = "v1"

import "common.api"

// 管理后台照片管理接口

// 获取照片列表请求
type GetAdminPhotoListRequest {
    PageRequest
    CategoryId int64  `form:"category_id,optional"`
    UserId     int64  `form:"user_id,optional"`
    Keyword    string `form:"keyword,optional"`
    Status     string `form:"status,optional"`     // published, draft, deleted
    Featured   string `form:"featured,optional"`   // true, false
    SortBy     string `form:"sort_by,optional,default=created_at_desc"` // 排序方式
    DateRange  string `form:"date_range,optional"` // 日期范围筛选
}

// 获取照片列表响应
type GetAdminPhotoListResponse {
    BaseResponse
    Data AdminPhotoListData `json:"data"`
}

type AdminPhotoListData {
    PageResponse
    Photos []AdminPhoto `json:"photos"`
}

// 获取照片详情请求
type GetAdminPhotoRequest {
    Id int64 `path:"id"`
}

// 获取照片详情响应
type GetAdminPhotoResponse {
    BaseResponse
    Data AdminPhotoDetail `json:"data"`
}

// 上传照片请求
type UploadAdminPhotoRequest {
    Title       string `json:"title" validate:"required"`
    Description string `json:"description,optional"`
    CategoryId  int64  `json:"category_id" validate:"required"`
    Tags        string `json:"tags,optional"`          // 标签 (逗号分隔)
    Featured    bool   `json:"featured,optional"`      // 是否精选
    Status      string `json:"status,optional,default=published"` // published, draft
}

// 上传照片响应
type UploadAdminPhotoResponse {
    BaseResponse
    Data AdminPhoto `json:"data"`
}

// 更新照片请求
type UpdateAdminPhotoRequest {
    Id          int64  `path:"id"`
    Title       string `json:"title,optional"`
    Description string `json:"description,optional"`
    CategoryId  int64  `json:"category_id,optional"`
    Tags        string `json:"tags,optional"`
    Featured    bool   `json:"featured,optional"`
    Status      string `json:"status,optional"`
}

// 更新照片响应
type UpdateAdminPhotoResponse {
    BaseResponse
    Data AdminPhoto `json:"data"`
}

// 删除照片请求
type DeleteAdminPhotoRequest {
    Id int64 `path:"id"`
}

// 删除照片响应
type DeleteAdminPhotoResponse {
    BaseResponse
}

// 设置精选照片请求
type SetAdminPhotoFeaturedRequest {
    Id       int64 `path:"id"`
    Featured bool  `json:"featured" validate:"required"`
}

// 设置精选照片响应
type SetAdminPhotoFeaturedResponse {
    BaseResponse
    Data AdminPhoto `json:"data"`
}

// 批量操作照片请求
type BatchAdminPhotoOperationRequest {
    PhotoIds  []int64 `json:"photo_ids" validate:"required"`
    Operation string  `json:"operation" validate:"required"` // publish, draft, delete, set_featured, unset_featured
    CategoryId int64   `json:"category_id,optional"`        // 批量修改分类
}

// 批量操作照片响应
type BatchAdminPhotoOperationResponse {
    BaseResponse
    Data BatchAdminPhotoOperationData `json:"data"`
}

type BatchAdminPhotoOperationData {
    SuccessCount int     `json:"success_count"`
    FailedCount  int     `json:"failed_count"`
    FailedIds    []int64 `json:"failed_ids"`
}

// 照片统计请求
type GetAdminPhotoStatsRequest {
    DateRange string `form:"date_range,optional,default=7d"` // 7d, 30d, 90d
}

// 照片统计响应
type GetAdminPhotoStatsResponse {
    BaseResponse
    Data AdminPhotoStatsData `json:"data"`
}

type AdminPhotoStatsData {
    TotalPhotos     int64 `json:"total_photos"`
    PublishedPhotos int64 `json:"published_photos"`
    DraftPhotos     int64 `json:"draft_photos"`
    FeaturedPhotos  int64 `json:"featured_photos"`
    NewPhotos       int64 `json:"new_photos"`      // 指定时间范围内新增照片
    GrowthRate      float64 `json:"growth_rate"`   // 增长率
    TotalViews      int64 `json:"total_views"`     // 总浏览量
    TotalStorage    int64 `json:"total_storage"`   // 总存储空间 (字节)
}

// 照片存储信息请求
type GetAdminPhotoStorageRequest {
    Id int64 `path:"id"`
}

// 照片存储信息响应
type GetAdminPhotoStorageResponse {
    BaseResponse
    Data AdminPhotoStorageData `json:"data"`
}

type AdminPhotoStorageData {
    OriginalUrl   string `json:"original_url"`
    ThumbnailUrl  string `json:"thumbnail_url"`
    FileSize      int64  `json:"file_size"`
    ThumbnailSize int64  `json:"thumbnail_size"`
    Format        string `json:"format"`
    Width         int    `json:"width"`
    Height        int    `json:"height"`
    ExifData      string `json:"exif_data,optional"` // EXIF 信息 (JSON 格式)
}

// 重新生成缩略图请求
type RegenerateAdminPhotoThumbnailRequest {
    Id int64 `path:"id"`
}

// 重新生成缩略图响应
type RegenerateAdminPhotoThumbnailResponse {
    BaseResponse
    Data AdminPhotoStorageData `json:"data"`
}

// 管理后台照片管理接口组 - 需要管理员认证
@server(
    group: admin_photos
    prefix: /admin/photos
    jwt: AdminAuth
)
service photography-api {
    @doc "获取照片列表"
    @handler getAdminPhotoList
    get / (GetAdminPhotoListRequest) returns (GetAdminPhotoListResponse)
    
    @doc "上传照片"
    @handler uploadAdminPhoto
    post / (UploadAdminPhotoRequest) returns (UploadAdminPhotoResponse)
    
    @doc "获取照片详情"
    @handler getAdminPhoto
    get /:id (GetAdminPhotoRequest) returns (GetAdminPhotoResponse)
    
    @doc "更新照片"
    @handler updateAdminPhoto
    put /:id (UpdateAdminPhotoRequest) returns (UpdateAdminPhotoResponse)
    
    @doc "删除照片"
    @handler deleteAdminPhoto
    delete /:id (DeleteAdminPhotoRequest) returns (DeleteAdminPhotoResponse)
    
    @doc "设置精选照片"
    @handler setAdminPhotoFeatured
    put /:id/featured (SetAdminPhotoFeaturedRequest) returns (SetAdminPhotoFeaturedResponse)
    
    @doc "获取照片存储信息"
    @handler getAdminPhotoStorage
    get /:id/storage (GetAdminPhotoStorageRequest) returns (GetAdminPhotoStorageResponse)
    
    @doc "重新生成缩略图"
    @handler regenerateAdminPhotoThumbnail
    post /:id/regenerate-thumbnail (RegenerateAdminPhotoThumbnailRequest) returns (RegenerateAdminPhotoThumbnailResponse)
    
    @doc "批量操作照片"
    @handler batchAdminPhotoOperation
    post /batch (BatchAdminPhotoOperationRequest) returns (BatchAdminPhotoOperationResponse)
    
    @doc "获取照片统计"
    @handler getAdminPhotoStats
    get /stats (GetAdminPhotoStatsRequest) returns (GetAdminPhotoStatsResponse)
}