tyapi-server/docs/产品列表接口订阅状态功能说明.md

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

概述

产品列表接口（/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）

响应格式

{
  "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. 未登录用户获取产品列表

curl -X GET "http://localhost:8080/api/v1/products?page=1&page_size=10"

2. 已登录用户获取产品列表

curl -X GET "http://localhost:8080/api/v1/products?page=1&page_size=10" \
  -H "Authorization: Bearer your-jwt-token"

3. 筛选已订阅的产品

curl -X GET "http://localhost:8080/api/v1/products?is_subscribed=true" \
  -H "Authorization: Bearer your-jwt-token"

4. 筛选未订阅的产品

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：优化数据库查询性能