Common Conventions

3.1 请求方法

• GET：查询
• POST：创建/触发动作
• DELETE：删除

3.2 Query 参数约定

• 分页：page, page_size
• 时间窗口：days, hours, date_from, date_to
• TopN：top_n, limit

3.3 Request Body 约定

• JSON 编码，Content-Type: application/json
• 对于 POST /chat/send，question 必填

3.4 响应结构

{
  "success": true,
  "code": 0,
  "message": "ok",
  "data": {},
  "request_id": "uuid"
}

3.5 分页约定

• 请求：page 从 1 开始，page_size 通常上限 100
• 返回：total, page, page_size

3.6 日期筛选约定

• 推荐使用 ISO 日期（如 2026-04-07）或 ISO 时间戳
• 后端按 UTC 存储

3.7 反馈状态字段约定

• feedback_type: helpful / inaccurate
• processed: true / false
• process_note: 处理备注

3.8 参数校验错误示例（422）

{
  "code": 422,
  "detail": "请求参数错误",
  "errors": [
    {
      "loc": ["query", "limit"],
      "msg": "Input should be less than or equal to 20"
    }
  ]
}