会话及轮次等相关api

doc/会话api.md

@@ -0,0 +1,49 @@
+# 创建会话
+curl -X POST "/api/v1/chat/sessions" \
+  -H "Content-Type: application/json" \
+  -d "{\"user_id\": $CHAT_USER_ID}"
+
+# 获取会话
+curl "/api/v1/chat/sessions/{session_id}"
+
+# 按用户列出会话
+curl "/api/v1/chat/sessions?user_id=$CHAT_USER_ID"
+
+# 更新会话状态
+curl -X POST "/api/v1/chat/sessions/{session_id}/update" \
+  -H "Content-Type: application/json" \
+  -d '{"status":"PAUSED"}'
+
+# 关闭会话
+curl -X POST "/api/v1/chat/sessions/{session_id}/close"
+
+# 创建对话轮次
+curl -X POST "/api/v1/chat/sessions/{session_id}/turns" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_id": '"$CHAT_USER_ID"',
+    "user_query": "展示昨天订单GMV",
+    "intent": "METRIC_QUERY",
+    "ast_json": {"select":["gmv"],"where":{"dt":"yesterday"}},
+    "main_metric_ids": [1234],
+    "created_metric_ids": []
+  }'
+
+# 获取单条对话轮次
+curl "/api/v1/chat/turns/{turn_id}"
+
+# 列出会话下的轮次
+curl "/api/v1/chat/sessions/{session_id}/turns"
+
+# 写入检索结果
+curl -X POST "/api/v1/chat/turns/{turn_id}/retrievals" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "retrievals": [
+      {"item_type":"METRIC","item_id":"metric_foo","used_in_sql":true,"rank_no":1},
+      {"item_type":"SNIPPET","item_id":"snpt_bar","similarity_score":0.77,"rank_no":2}
+    ]
+  }'
+
+# 列出轮次的检索结果
+curl "/api/v1/chat/turns/{turn_id}/retrievals"

doc/指标生成.md

@@ -0,0 +1,83 @@
+某个用户的一句问话 → 解析成某轮 chat_turn → 这轮用了哪些指标/知识/会话（chat_turn_retrieval） →
+是否产生了新的指标（metric_def） →
+是否触发了指标调度运行（metric_job_run.turn_id） →
+最终产生了哪些指标结果（metric_result.metric_id + stat_time）。
+
+会话域
+schema
+会话表 chat_session
+
+会话轮次表 chat_turn
+
+会话轮次检索关联表 chat_turn_retrieval
+
+
+API
+1. 创建会话
+POST /api/v1/chat/sessions
+2. 更新会话轮次
+POST /api/v1/chat/sessions/{session_id}/update
+3. 结束会话
+POST /api/v1/chat/sessions/{session_id}/close
+4. 查询会话
+GET /api/v1/chat/sessions/{session_id}
+5. 会话列表查询（按用户、时间）
+GET /api/v1/chat/sessions
+6. 创建问答轮次（用户发起 query）
+POST /api/v1/chat/sessions/{session_id}/turns
+7. 查询某会话的所有轮次
+GET /api/v1/chat/sessions/{session_id}/turns
+8. 查看单轮问答详情
+GET /api/v1/chat/turns/{turn_id}
+9. 批量写入某轮的检索结果
+POST /api/v1/chat/turns/{turn_id}/retrievals
+10. 查询某轮的检索记录
+GET /api/v1/chat/turns/{turn_id}/retrievals
+11. 更新某轮的检索记录（in future）
+POST /api/v1/chat/turns/{turn_id}/retrievals/update
+
+元数据域
+schema
+指标定义表 metric_def
+
+
+API
+12. 创建指标（来自问答或传统定义）
+POST /api/v1/metrics
+13. 更新指标
+POST /api/v1/metrics/{id}
+14. 获取指标详情
+GET /api/v1/metrics
+
+执行调度域（暂定airflow）
+schema
+指标调度配置表 metric_schedule
+
+调度运行记录表 metric_job_run
+
+API
+1. 创建调度配置
+POST /api/v1/metric-schedules
+2. 更新调度配置
+POST /api/v1/metric-schedules/{id}
+3. 查询指标调度配置详情
+GET /api/v1/metrics/{metric_id}/schedules
+4. 手动触发一次指标运行（例如来自问数）
+POST /api/v1/metric-runs/trigger
+5. 查询运行记录列表
+GET /api/v1/metric-runs
+6. 查询单次运行详情
+GET /api/metric-runs/{run_id}
+
+数据域
+schema
+指标结果表（纵表）metric_result
+
+
+API
+1. 查询指标结果（按时间段 & 维度）
+GET /api/metric-results
+2. 单点查询（最新值）
+GET /api/metric-results/latest
+3. 批量写入指标结果
+POST /api/v1/metric-results/{metrics_id}