# 产品列表接口订阅状态功能说明

## 概述

产品列表接口（`/api/v1/products`）现已支持可选认证和订阅状态功能。用户可以选择是否登录，登录后可以查看产品的订阅状态，并可以按订阅状态进行筛选。

## 功能特性

### 1. 可选认证
- 未登录用户：可以正常获取产品列表，但不会显示订阅状态
- 已登录用户：可以获取产品列表，并显示每个产品的订阅状态

### 2. 订阅状态显示
- 对于已登录用户，每个产品响应中会包含 `is_subscribed` 字段
- 该字段为 `true` 表示用户已订阅该产品，`false` 表示未订阅，`null` 表示未登录

### 3. 订阅状态筛选
- 已登录用户可以通过 `is_subscribed` 参数筛选产品
- `is_subscribed=true`：只显示已订阅的产品
- `is_subscribed=false`：只显示未订阅的产品
- 不传该参数：显示所有产品

## API 接口

### 请求地址
```
GET /api/v1/products
```

### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | int | 否 | 页码，默认1 |
| page_size | int | 否 | 每页数量，默认10 |
| keyword | string | 否 | 搜索关键词 |
| category_id | string | 否 | 分类ID |
| is_enabled | bool | 否 | 是否启用 |
| is_visible | bool | 否 | 是否可见 |
| is_package | bool | 否 | 是否组合包 |
| is_subscribed | bool | 否 | 是否已订阅（需要认证） |
| sort_by | string | 否 | 排序字段 |
| sort_order | string | 否 | 排序方向（asc/desc） |

### 响应格式

```json
{
  "code": 200,
  "message": "获取产品列表成功",
  "data": {
    "total": 100,
    "page": 1,
    "size": 10,
    "items": [
      {
        "id": "product-id",
        "name": "产品名称",
        "code": "PRODUCT001",
        "description": "产品描述",
        "price": 99.99,
        "is_enabled": true,
        "is_visible": true,
        "is_package": false,
        "is_subscribed": true,  // 新增字段：订阅状态
        "category": {
          "id": "category-id",
          "name": "分类名称"
        },
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}
```

## 使用示例

### 1. 未登录用户获取产品列表
```bash
curl -X GET "http://localhost:8080/api/v1/products?page=1&page_size=10"
```

### 2. 已登录用户获取产品列表
```bash
curl -X GET "http://localhost:8080/api/v1/products?page=1&page_size=10" \
  -H "Authorization: Bearer your-jwt-token"
```

### 3. 筛选已订阅的产品
```bash
curl -X GET "http://localhost:8080/api/v1/products?is_subscribed=true" \
  -H "Authorization: Bearer your-jwt-token"
```

### 4. 筛选未订阅的产品
```bash
curl -X GET "http://localhost:8080/api/v1/products?is_subscribed=false" \
  -H "Authorization: Bearer your-jwt-token"
```

## 技术实现

### 1. 数据库查询优化
- 使用 `EXISTS` 子查询来筛选订阅状态
- 批量查询用户订阅状态，减少数据库查询次数

### 2. 缓存策略
- 订阅状态查询结果会被缓存，提高查询性能
- 缓存时间设置为10分钟，可根据业务需求调整

### 3. 向后兼容
- 新功能完全向后兼容
- 未登录用户的使用体验不受影响
- 现有前端代码无需修改即可正常工作

## 注意事项

1. **认证要求**：`is_subscribed` 筛选功能需要用户登录
2. **性能考虑**：订阅状态查询会增加一定的数据库负载，建议合理使用
3. **缓存更新**：当用户订阅/取消订阅产品时，需要清除相关缓存
4. **错误处理**：如果用户ID无效，会返回空的产品列表

## 更新日志

- 2024-01-01：新增可选认证和订阅状态功能
- 2024-01-01：新增订阅状态筛选功能
- 2024-01-01：优化数据库查询性能