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

# 产品管理员接口文档

## 概述

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

## 接口列表

### 1. 产品管理

#### 1.1 创建产品
- **接口地址**: `POST /api/v1/admin/products`
- **请求头**: 
  - `Authorization: Bearer {token}` (需要管理员权限)
- **请求体**:
```json
{
  "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关键词"
}
```
- **响应**:
```json
{
  "code": 201,
  "message": "产品创建成功",
  "data": null
}
```

#### 1.2 更新产品
- **接口地址**: `PUT /api/v1/admin/products/{id}`
- **请求头**: 
  - `Authorization: Bearer {token}` (需要管理员权限)
- **路径参数**:
  - `id`: 产品ID
- **请求体**: 同创建产品
- **响应**:
```json
{
  "code": 200,
  "message": "产品更新成功",
  "data": null
}
```

#### 1.3 删除产品
- **接口地址**: `DELETE /api/v1/admin/products/{id}`
- **请求头**: 
  - `Authorization: Bearer {token}` (需要管理员权限)
- **路径参数**:
  - `id`: 产品ID
- **响应**:
```json
{
  "code": 200,
  "message": "产品删除成功",
  "data": null
}
```

### 2. 分类管理

#### 2.1 创建分类
- **接口地址**: `POST /api/v1/admin/product-categories`
- **请求头**: 
  - `Authorization: Bearer {token}` (需要管理员权限)
- **请求体**:
```json
{
  "name": "分类名称",
  "code": "分类编号",
  "description": "分类描述",
  "parent_id": "父分类ID（可选）",
  "level": 1,
  "sort": 0,
  "is_enabled": true,
  "is_visible": true
}
```
- **响应**:
```json
{
  "code": 201,
  "message": "分类创建成功",
  "data": null
}
```

#### 2.2 更新分类
- **接口地址**: `PUT /api/v1/admin/product-categories/{id}`
- **请求头**: 
  - `Authorization: Bearer {token}` (需要管理员权限)
- **路径参数**:
  - `id`: 分类ID
- **请求体**: 同创建分类
- **响应**:
```json
{
  "code": 200,
  "message": "分类更新成功",
  "data": null
}
```

#### 2.3 删除分类
- **接口地址**: `DELETE /api/v1/admin/product-categories/{id}`
- **请求头**: 
  - `Authorization: Bearer {token}` (需要管理员权限)
- **路径参数**:
  - `id`: 分类ID
- **响应**:
```json
{
  "code": 200,
  "message": "分类删除成功",
  "data": null
}
```

### 3. 订阅管理

#### 3.1 更新订阅价格
- **接口地址**: `PUT /api/v1/admin/subscriptions/{id}/price`
- **请求头**: 
  - `Authorization: Bearer {token}` (需要管理员权限)
- **路径参数**:
  - `id`: 订阅ID
- **请求体**:
```json
{
  "price": 199.99
}
```
- **响应**:
```json
{
  "code": 200,
  "message": "订阅价格更新成功",
  "data": null
}
```

## 权限要求

所有管理员接口都需要：
1. **JWT认证**: 有效的JWT token
2. **管理员权限**: 用户必须具有管理员角色

## 错误处理

### 常见错误码

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

### 错误响应格式

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

## 业务规则

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

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

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

## 使用示例

### 创建产品示例

```bash
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,调用,服务"
  }'
```

### 创建分类示例

```bash
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
  }'
```

### 更新订阅价格示例

```bash
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. 错误消息使用中文，便于用户理解