baodan/docs/API_curl示例.md

# API 接口 curl 示例

> 所有需认证接口需在 Header 中携带 `Authorization: Bearer <JWT_TOKEN>`

---

## 一、认证鉴权（A1）

### A1.1.1 企微登录
```bash
curl -X POST http://localhost:5001/api/auth/wework-login \
  -H "Content-Type: application/json" \
  -d '{"code": "企微授权码", "state": "random"}'
```

### A1.1.2 账密登录
```bash
curl -X POST http://localhost:5001/api/auth/password-login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "hashed_password"}'
# 返回：{"code":0,"data":{"token":"eyJhbGci...","expires_in":7200}}
```

### A1.1.3 刷新 Token
```bash
curl -X POST http://localhost:5001/api/auth/refresh-token \
  -H "Authorization: Bearer <旧Token>"
```

### A1.1.4 退出登录
```bash
curl -X POST http://localhost:5001/api/auth/logout \
  -H "Authorization: Bearer <Token>"
```

---

## 二、智能问答（A2）

### A2.1.1 发送消息（SSE 流式）
```bash
curl -X POST http://localhost:5001/api/chat/message \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{"message": "重疾险等待期多少天？", "session_id": "", "filters": {"险种": "重疾险"}}' \
  --no-buffer
# 返回 SSE 流：
# data: {"type":"delta","data":"根据"}
# data: {"type":"delta","data":"XX重疾险条款规定，等待期为90天。"}
# data: {"type":"source","data":{"doc_name":"XX重疾险条款.md","chunk":"等待期为...","score":0.92}}
# data: {"type":"done","data":{"message_id":"msg-001","conversation_id":"conv-001"}}
```

### A2.1.2 获取会话列表
```bash
curl http://localhost:5001/api/chat/sessions?page=1&page_size=20 \
  -H "Authorization: Bearer <Token>"
```

### A2.1.3 创建会话
```bash
curl -X POST http://localhost:5001/api/chat/sessions \
  -H "Authorization: Bearer <Token>"
```

### A2.1.4 删除会话
```bash
curl -X DELETE http://localhost:5001/api/chat/sessions/sess-001 \
  -H "Authorization: Bearer <Token>"
```

### A2.1.5 获取消息记录
```bash
curl http://localhost:5001/api/chat/sessions/sess-001/messages \
  -H "Authorization: Bearer <Token>"
```

### A2.1.6 提交反馈
```bash
curl -X POST http://localhost:5001/api/chat/messages/msg-001/feedback \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{"rating": "not_helpful", "comment": "等待期应该是180天"}'
```

### A2.2.2 推荐追问
```bash
curl -X POST http://localhost:5001/api/chat/suggest \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{"message": "根据条款规定，重疾险等待期为90天。"}'
```

---

## 三、方案生成（A3）

### A3.1.1 生成推荐方案
```bash
curl -X POST http://localhost:5001/api/recommend/generate \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "name": "李四", "age": 35, "gender": "male",
      "health_status": "健康", "occupation": "工程师",
      "annual_income": 300000, "monthly_budget": 2000
    },
    "insurance_types": ["重疾险", "医疗险"],
    "coverage_amount": 500000,
    "coverage_period": "终身",
    "existing_policies": []
  }'
# 返回：{"code":0,"data":{"task_id":"1","status":"processing"}}
```

### A3.1.2 查询生成状态
```bash
curl http://localhost:5001/api/recommend/generate/1 \
  -H "Authorization: Bearer <Token>"
```

### A3.1.3 方案导出
```bash
curl -X POST http://localhost:5001/api/recommend/1/export \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{"format": "pdf"}'
```

### A3.1.4 生成分享链接
```bash
curl -X POST http://localhost:5001/api/recommend/1/share \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{"expire_hours": 72}'
```

---

## 四、知识库（A4）

### A4.1.1 上传文档
```bash
curl -X POST http://localhost:5001/api/kb/documents/upload \
  -H "Authorization: Bearer <Token>" \
  -F "files=@条款1.md" \
  -F "files=@条款2.md" \
  -F "险种=重疾险" \
  -F "保司=XX人寿"
```

### A4.1.2 文档列表
```bash
curl "http://localhost:5001/api/kb/documents?page=1&page_size=20&险种=重疾险" \
  -H "Authorization: Bearer <Token>"
```

### A4.1.5 更新文档元数据
```bash
curl -X PATCH http://localhost:5001/api/kb/documents/doc-001 \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{"编号": "CJ-XX-002", "tags": ["产品条款", "核保"]}'
```

### A4.2.1 数据源列表
```bash
curl http://localhost:5001/api/kb/datasources \
  -H "Authorization: Bearer <Token>"
```

---

## 五、管理后台（A5 + A6）

### A5.1.1 用户列表
```bash
curl "http://localhost:5001/api/admin/users?page=1&role=sales" \
  -H "Authorization: Bearer <Token>"
```

### A5.1.3 角色列表
```bash
curl http://localhost:5001/api/admin/roles \
  -H "Authorization: Bearer <Token>"
```

### A6.1.2 连通性测试
```bash
curl -X POST http://localhost:5001/api/admin/llm-configs/llm-001/ping \
  -H "Authorization: Bearer <Token>"
```

---

## 六、统计报表（A7 + A8）

### A7.1.1 问答记录查询
```bash
curl "http://localhost:5001/api/admin/logs/chat?page=1&keyword=重疾险&rating=not_helpful" \
  -H "Authorization: Bearer <Token>"
```

### A8.1.1 使用概览
```bash
curl http://localhost:5001/api/stats/overview \
  -H "Authorization: Bearer <Token>"
```

### A8.1.4 Token 消耗统计
```bash
curl "http://localhost:5001/api/stats/token-cost?group_by=model" \
  -H "Authorization: Bearer <Token>"
```

---

## 七、企微回调

### URL 验证（GET）
```bash
curl "http://localhost:5001/api/wecom/callback?msg_signature=xxx&timestamp=xxx&nonce=xxx&echostr=xxx"
```

### 消息接收（POST）
```bash
curl -X POST http://localhost:5001/api/wecom/callback \
  -H "Content-Type: application/xml" \
  -d '<xml>...</xml>'
# 必须在 5 秒内返回 "success"
```

### 健康检查
```bash
curl http://localhost:5001/api/health
# 返回：{"status": "ok"}
```