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/photos.api
+++ b/backend/api/desc/admin/photos.api
@ -0,0 +1,216 @@
+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)
+}