photography/backend/api/desc/admin/categories.api

syntax = "v1"

import "common.api"

// 管理后台分类管理接口

// 获取分类列表请求
type GetAdminCategoryListRequest {
    PageRequest
    Keyword   string `form:"keyword,optional"`
    Status    string `form:"status,optional"`     // active, inactive
    SortBy    string `form:"sort_by,optional,default=sort_order_asc"` // 排序方式
    WithStats bool   `form:"with_stats,optional"` // 是否包含统计信息
}

// 获取分类列表响应
type GetAdminCategoryListResponse {
    BaseResponse
    Data AdminCategoryListData `json:"data"`
}

type AdminCategoryListData {
    PageResponse
    Categories []AdminCategory `json:"categories"`
}

// 获取分类详情请求
type GetAdminCategoryRequest {
    Id int64 `path:"id"`
}

// 获取分类详情响应
type GetAdminCategoryResponse {
    BaseResponse
    Data AdminCategoryDetail `json:"data"`
}

// 创建分类请求
type CreateAdminCategoryRequest {
    Name        string `json:"name" validate:"required"`
    Description string `json:"description,optional"`
    SortOrder   int    `json:"sort_order,optional,default=0"`  // 排序权重
    Status      string `json:"status,optional,default=active"` // active, inactive
    CoverImage  string `json:"cover_image,optional"`           // 分类封面图
}

// 创建分类响应
type CreateAdminCategoryResponse {
    BaseResponse
    Data AdminCategory `json:"data"`
}

// 更新分类请求
type UpdateAdminCategoryRequest {
    Id          int64  `path:"id"`
    Name        string `json:"name,optional"`
    Description string `json:"description,optional"`
    SortOrder   int    `json:"sort_order,optional"`
    Status      string `json:"status,optional"`
    CoverImage  string `json:"cover_image,optional"`
}

// 更新分类响应
type UpdateAdminCategoryResponse {
    BaseResponse
    Data AdminCategory `json:"data"`
}

// 删除分类请求
type DeleteAdminCategoryRequest {
    Id int64 `path:"id"`
}

// 删除分类响应
type DeleteAdminCategoryResponse {
    BaseResponse
}

// 分类排序请求
type SortAdminCategoriesRequest {
    Categories []AdminCategorySortItem `json:"categories" validate:"required"`
}

type AdminCategorySortItem {
    Id        int64 `json:"id" validate:"required"`
    SortOrder int   `json:"sort_order" validate:"required"`
}

// 分类排序响应
type SortAdminCategoriesResponse {
    BaseResponse
}

// 更新分类状态请求
type UpdateAdminCategoryStatusRequest {
    Id     int64  `path:"id"`
    Status string `json:"status" validate:"required"` // active, inactive
}

// 更新分类状态响应
type UpdateAdminCategoryStatusResponse {
    BaseResponse
    Data AdminCategory `json:"data"`
}

// 批量操作分类请求
type BatchAdminCategoryOperationRequest {
    CategoryIds []int64 `json:"category_ids" validate:"required"`
    Operation   string  `json:"operation" validate:"required"` // activate, deactivate, delete
}

// 批量操作分类响应
type BatchAdminCategoryOperationResponse {
    BaseResponse
    Data BatchAdminCategoryOperationData `json:"data"`
}

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

// 分类统计请求
type GetAdminCategoryStatsRequest {
    DateRange string `form:"date_range,optional,default=7d"` // 7d, 30d, 90d
}

// 分类统计响应
type GetAdminCategoryStatsResponse {
    BaseResponse
    Data AdminCategoryStatsData `json:"data"`
}

type AdminCategoryStatsData {
    TotalCategories  int64 `json:"total_categories"`
    ActiveCategories int64 `json:"active_categories"`
    EmptyCategories  int64 `json:"empty_categories"`  // 没有照片的分类
    NewCategories    int64 `json:"new_categories"`    // 指定时间范围内新增分类
    PopularCategories []AdminCategoryPopularItem `json:"popular_categories"` // 热门分类
}

type AdminCategoryPopularItem {
    Id         int64  `json:"id"`
    Name       string `json:"name"`
    PhotoCount int64  `json:"photo_count"`
    ViewCount  int64  `json:"view_count"`
}

// 分类照片统计请求
type GetAdminCategoryPhotoStatsRequest {
    Id int64 `path:"id"`
}

// 分类照片统计响应
type GetAdminCategoryPhotoStatsResponse {
    BaseResponse
    Data AdminCategoryPhotoStatsData `json:"data"`
}

type AdminCategoryPhotoStatsData {
    CategoryId      int64 `json:"category_id"`
    TotalPhotos     int64 `json:"total_photos"`
    PublishedPhotos int64 `json:"published_photos"`
    DraftPhotos     int64 `json:"draft_photos"`
    FeaturedPhotos  int64 `json:"featured_photos"`
    TotalViews      int64 `json:"total_views"`
    RecentPhotos    []AdminPhoto `json:"recent_photos"` // 最近上传的照片
}

// 上传分类封面图请求
type UploadAdminCategoryCoverRequest {
    Id int64 `path:"id"`
}

// 上传分类封面图响应
type UploadAdminCategoryCoverResponse {
    BaseResponse
    Data UploadAdminCategoryCoverData `json:"data"`
}

type UploadAdminCategoryCoverData {
    CoverImageUrl string `json:"cover_image_url"`
}

// 管理后台分类管理接口组 - 需要管理员认证
@server(
    group: admin_categories
    prefix: /admin/categories
    jwt: AdminAuth
)
service photography-api {
    @doc "获取分类列表"
    @handler getAdminCategoryList
    get / (GetAdminCategoryListRequest) returns (GetAdminCategoryListResponse)
    
    @doc "创建分类"
    @handler createAdminCategory
    post / (CreateAdminCategoryRequest) returns (CreateAdminCategoryResponse)
    
    @doc "获取分类详情"
    @handler getAdminCategory
    get /:id (GetAdminCategoryRequest) returns (GetAdminCategoryResponse)
    
    @doc "更新分类"
    @handler updateAdminCategory
    put /:id (UpdateAdminCategoryRequest) returns (UpdateAdminCategoryResponse)
    
    @doc "删除分类"
    @handler deleteAdminCategory
    delete /:id (DeleteAdminCategoryRequest) returns (DeleteAdminCategoryResponse)
    
    @doc "更新分类状态"
    @handler updateAdminCategoryStatus
    put /:id/status (UpdateAdminCategoryStatusRequest) returns (UpdateAdminCategoryStatusResponse)
    
    @doc "上传分类封面图"
    @handler uploadAdminCategoryCover
    post /:id/cover (UploadAdminCategoryCoverRequest) returns (UploadAdminCategoryCoverResponse)
    
    @doc "获取分类照片统计"
    @handler getAdminCategoryPhotoStats
    get /:id/photo-stats (GetAdminCategoryPhotoStatsRequest) returns (GetAdminCategoryPhotoStatsResponse)
    
    @doc "分类排序"
    @handler sortAdminCategories
    post /sort (SortAdminCategoriesRequest) returns (SortAdminCategoriesResponse)
    
    @doc "批量操作分类"
    @handler batchAdminCategoryOperation
    post /batch (BatchAdminCategoryOperationRequest) returns (BatchAdminCategoryOperationResponse)
    
    @doc "获取分类统计"
    @handler getAdminCategoryStats
    get /stats (GetAdminCategoryStatsRequest) returns (GetAdminCategoryStatsResponse)
}