feat: 完成API接口隔离设计和定义

🚀 主要功能: - 创建前端公共展示API (/api/v1/public/*) - 创建前端用户认证API (/api/v1/auth/*) - 创建管理后台完整API (/admin/*) - 实现双重认证体系设计 📋 新增文件: - api/desc/frontend/public.api - 前端公共接口定义 - api/desc/frontend/auth.api - 前端认证接口定义 - api/desc/admin.api - 管理后台主入口 - api/desc/admin/auth.api - 管理员认证接口 - api/desc/admin/users.api - 用户管理接口 - api/desc/admin/photos.api - 照片管理接口 - api/desc/admin/categories.api - 分类管理接口 - api/desc/admin/dashboard.api - 仪表板统计接口 🔧 更新文件: - api/desc/common.api - 扩展类型定义支持前端和管理后台 - api/desc/photography.api - 更新为前端主入口 - etc/photographyapi-api.yaml - 修复中间件配置 📚 文档: - docs/API_SEPARATION_DESIGN.md - 接口隔离设计方案 - docs/API_REFACTORING_TASKS.md - 详细任务规划 - docs/COMPLETED_TASKS_ARCHIVE.md - 已完成任务归档 ✨ 特性亮点: - 前端和管理后台权限完全隔离 - 优化的数据结构去除敏感信息 - 完整的CRUD和统计功能 - 支持批量操作和高级筛选 - 详细的仪表板分析功能
2025-07-11 16:08:02 +08:00
parent 6efccae78a
commit 8a0792500e
16 changed files with 2150 additions and 25 deletions
--- a/backend/api/desc/admin/categories.api
+++ b/backend/api/desc/admin/categories.api
@ -0,0 +1,236 @@
+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)
+}