tyapi-server/docs/产品管理员接口文档.md

产品管理员接口文档

概述

本文档描述了产品域的管理员接口，包括产品管理、分类管理和订阅管理功能。

接口列表

1. 产品管理

1.1 创建产品

• 接口地址: POST /api/v1/admin/products
• 请求头:
  • Authorization: Bearer {token} (需要管理员权限)
• 请求体:

{
  "name": "产品名称",
  "code": "产品编号",
  "description": "产品描述",
  "content": "产品内容",
  "category_id": "分类ID",
  "price": 99.99,
  "is_enabled": true,
  "is_visible": true,
  "is_package": false,
  "seo_title": "SEO标题",
  "seo_description": "SEO描述",
  "seo_keywords": "SEO关键词"
}

• 响应:

{
  "code": 201,
  "message": "产品创建成功",
  "data": null
}

1.2 更新产品

• 接口地址: PUT /api/v1/admin/products/{id}
• 请求头:
  • Authorization: Bearer {token} (需要管理员权限)
• 路径参数:
  • id: 产品ID
• 请求体: 同创建产品
• 响应:

{
  "code": 200,
  "message": "产品更新成功",
  "data": null
}

1.3 删除产品

• 接口地址: DELETE /api/v1/admin/products/{id}
• 请求头:
  • Authorization: Bearer {token} (需要管理员权限)
• 路径参数:
  • id: 产品ID
• 响应:

{
  "code": 200,
  "message": "产品删除成功",
  "data": null
}

2. 分类管理

2.1 创建分类

• 接口地址: POST /api/v1/admin/product-categories
• 请求头:
  • Authorization: Bearer {token} (需要管理员权限)
• 请求体:

{
  "name": "分类名称",
  "code": "分类编号",
  "description": "分类描述",
  "parent_id": "父分类ID（可选）",
  "level": 1,
  "sort": 0,
  "is_enabled": true,
  "is_visible": true
}

• 响应:

{
  "code": 201,
  "message": "分类创建成功",
  "data": null
}

2.2 更新分类

• 接口地址: PUT /api/v1/admin/product-categories/{id}
• 请求头:
  • Authorization: Bearer {token} (需要管理员权限)
• 路径参数:
  • id: 分类ID
• 请求体: 同创建分类
• 响应:

{
  "code": 200,
  "message": "分类更新成功",
  "data": null
}

2.3 删除分类

• 接口地址: DELETE /api/v1/admin/product-categories/{id}
• 请求头:
  • Authorization: Bearer {token} (需要管理员权限)
• 路径参数:
  • id: 分类ID
• 响应:

{
  "code": 200,
  "message": "分类删除成功",
  "data": null
}

3. 订阅管理

3.1 更新订阅价格

• 接口地址: PUT /api/v1/admin/subscriptions/{id}/price
• 请求头:
  • Authorization: Bearer {token} (需要管理员权限)
• 路径参数:
  • id: 订阅ID
• 请求体:

{
  "price": 199.99
}

• 响应:

{
  "code": 200,
  "message": "订阅价格更新成功",
  "data": null
}

权限要求

所有管理员接口都需要：

1. JWT认证: 有效的JWT token
2. 管理员权限: 用户必须具有管理员角色

错误处理

常见错误码

• 400: 请求参数错误
• 401: 未认证或token无效
• 403: 权限不足（非管理员用户）
• 404: 资源不存在
• 500: 服务器内部错误

错误响应格式

{
  "code": 400,
  "message": "错误描述信息",
  "data": null
}

业务规则

产品管理

1. 产品编号必须唯一
2. 产品价格不能为负数
3. 产品必须关联到有效的分类
4. 删除产品时会进行软删除

分类管理

1. 分类编号必须唯一
2. 分类层级必须大于0
3. 父分类必须存在且有效
4. 不能删除有子分类的分类
5. 删除分类时会进行软删除

订阅管理

1. 订阅价格不能为负数
2. 只能修改现有订阅的价格
3. 价格修改会记录在日志中

使用示例

创建产品示例

curl -X POST http://localhost:8080/api/v1/admin/products \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API调用服务",
    "code": "API_CALL",
    "description": "提供API调用服务",
    "content": "详细的API调用服务说明",
    "category_id": "category-uuid",
    "price": 99.99,
    "is_enabled": true,
    "is_visible": true,
    "is_package": false,
    "seo_title": "API调用服务 - 专业API服务提供商",
    "seo_description": "提供高质量的API调用服务",
    "seo_keywords": "API,调用,服务"
  }'

创建分类示例

curl -X POST http://localhost:8080/api/v1/admin/product-categories \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API服务",
    "code": "API_SERVICE",
    "description": "API相关服务分类",
    "level": 1,
    "sort": 1,
    "is_enabled": true,
    "is_visible": true
  }'

更新订阅价格示例

curl -X PUT http://localhost:8080/api/v1/admin/subscriptions/subscription-uuid/price \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 199.99
  }'

注意事项

1. 所有接口都需要管理员权限，普通用户无法访问
2. 产品编号和分类编号必须唯一，重复时会返回错误
3. 删除操作都是软删除，数据不会真正从数据库中删除
4. 价格字段使用decimal类型，支持两位小数
5. 所有时间字段使用ISO 8601格式
6. 错误消息使用中文，便于用户理解