全栈开发指南

接口文档参考

1.查询产品列表

请求方式

请求方式	请求路径	是否需要登录
`GET`	`/api/v1/products`	否

query参数

参数	类型	必填	默认值	说明
`category`	string	否	无	产品分类；不传时查询全部有效产品

响应格式

json

[
    {
        "id": 4,
        "name": "复星联合星相守2号长期医疗险（个人版）",
        "clause_name": "复星联合优选二号长期住院医疗险(星相守2号)条款.pdf",
        "category": "medical",
        "insurer": "复星联合健康保险",
        "image_url": "https://files.huizecdn.com/file3/M00/AC/B9/rBYA3GlFEUWAWcX8AAO1o6m75Qg526.png",
        "description": "免赔额灵活可选，保证续保20年特需，外购药不限清单。",
        "min_premium": "148.00",
        "max_premium": "3605.00",
        "target_group": "1-55周岁（1-4类职业）",
        "highlights": [
            "长期医疗",
            "门急诊可选",
            "家庭保障"
        ],
        "status": "active"
    },
    {
        "id": 5,
        "name": "复星联合星相守2号长期医疗险（转保版）",
        "clause_name": "复星联合优选二号长期住院医疗险(星相守2号)条款.pdf",
        "category": "medical",
        "insurer": "复星联合健康保险",
        "image_url": "https://files.huizecdn.com/file3/M00/AC/B9/rBYA3GlFEUWAWcX8AAO1o6m75Qg526.png",
        "description": "免赔额灵活可选，保证续保20年特需，外购药不限清单。",
        "min_premium": "180.00",
        "max_premium": "4409.00",
        "target_group": "1-70周岁（1-4类职业）",
        "highlights": [
            "转保场景",
            "0免赔",
            "特需医疗"
        ],
        "status": "active"
    },
    {
        "id": 6,
        "name": "众安尊享e生百万医疗险2026版",
        "clause_name": "众安尊享e生百万医疗险2026版条款.pdf",
        "category": "medical",
        "insurer": "众安保险",
        "image_url": "https://files.huizecdn.com/file3/M00/B0/02/rBYA3GlTLeGAGS9sAAEwUtrU9VE280.png",
        "description": "百万医疗险产品，覆盖住院、特殊门诊等医疗责任。",
        "min_premium": "255.00",
        "max_premium": "1420.00",
        "target_group": "30天-70周岁（1-6类职业）",
        "highlights": [
            "百万医疗",
            "医疗保障",
            "责任免除清晰"
        ],
        "status": "active"
    }
]

2.查询推荐候选产品

请求方式

请求方式	请求路径	是否需要登录
`GET`	`/api/v1/products/candidates`	否

query参数

参数	类型	必填	默认值	说明
`categories`	string[]	是	无	产品分类，可传多个
`premium_min`	number	否	无	只返回最低保费小于该值的产品
`limit_per_category`	number	否	`5`	每个险种最多返回数量

响应格式

json

[
  {
    "id": 6,
    "name": "众安尊享e生百万医疗险2026版",
    "clause_name": "众安尊享e生百万医疗险2026版条款.pdf",
    "category": "medical",
    "insurer": "众安保险",
    "image_url": "https://files.huizecdn.com/file3/M00/B0/02/example.png",
    "description": "百万医疗险产品，覆盖住院、特殊门诊等医疗责任。",
    "min_premium": "255.00",
    "max_premium": "1420.00",
    "target_group": "30天-70周岁（1-6类职业）",
    "highlights": ["百万医疗", "医疗保障"],
    "status": "active"
  }
]

3.创建会话

请求方式

请求方式	请求路径	是否需要登录
`POST`	`/api/v1/chat-threads`	是

请求格式

json

POST /api/v1/chat-threads HTTP/1.1
Content-Type: application/json
x-user-id: 1

{"title":"保险咨询"}
# 注意：是Post的Body请求体传递参数

特别注意

虽然请求参数只有一个title，但有一个隐含的参数，就是user_id。

当前登录用户是谁，当前会话就必须属于谁，前端会通过请求头传递user_id给后端，我们必须通过请求头拿到user_id，组装会话数据，写入数据库。

响应格式

json

HTTP/1.1 200 OK
content-type: application/json

{
  "id": "11111111-1111-1111-1111-111111111111",
  "title": "保险咨询",
  "created_at": "2026-06-28T10:00:00.000000+08:00",
  "updated_at": "2026-06-28T10:00:00.000000+08:00"
}

4.查询会话列表

请求方式

请求方式	请求路径	是否需要登录
`GET`	`/api/v1/chat-threads`	是

请求参数

shell

GET /api/v1/chat-threads HTTP/1.1
x-user-id: 1

请求响应

json

HTTP/1.1 200 OK
content-type: application/json

[
    {
        "id": "137e4a78-cb19-407f-89ed-5450ae98a06d",
        "title": "保险咨询",
        "created_at": "2026-09-21T12:31:05.186960Z",
        "updated_at": "2026-09-21T12:31:05.186960Z"
    },
    {
        "id": "7e4a0588-39f4-46cf-9657-0944b83b7f47",
        "title": "保险咨询",
        "created_at": "2026-09-21T11:24:27.893781Z",
        "updated_at": "2026-09-21T11:24:27.893781Z"
    }
]

5.重命名会话

请求方式	PATCH
请求路径	`/api/v1/chat-threads/{thread_id}`
请求头	`x-user-id: 1`
请求体	`{"title": "医疗险咨询"}`
响应结果	重命名后的会话信息

注意

注意：重命名必须做校验，如果会话不存在，或者会话属于其他用户，都统一返回会话不存在，避免泄露其他用户的会话信息。

6.删除会话

请求方式	DELETE
请求路径	`/api/v1/chat-threads/{thread_id}`
请求头	`x-user-id: 1`
请求体	无
响应结果	`204 No Content`

7.基础对话

请求方式

请求方式	请求路径	是否需要登录
`POST`	`/api/v1/chat`	是

请求体字段

字段	类型	必填	说明
`thread_id`	`UUID`	是	通过会话管理接口创建的会话 ID
`message`	`string`	是	用户本轮发送的消息

注意

这里的请求头中的x-user-id别忘记了。

json

POST /api/v1/chat HTTP/1.1
Content-Type: application/json
x-user-id: 1

{
  "thread_id": "11111111-1111-1111-1111-111111111111",
  "message": "我 30 岁，预算一年 8000，想配置保险"
}

请求响应

HTTP

HTTP/1.1 200 OK
content-type: application/text

"AI的回答"

8.查询指定会话的历史消息

字段	内容
请求方式	GET
请求路径	/api/v1/chat-threads/{thread_id}/messages
请求头	x-user-id: 1
请求体	无
响应结果	参考响应参数
用途	查询指定会话的历史消息

响应参数

字段	类型	说明
`thread_id`	string	会话 ID
`messages`	array	前端可展示的历史消息
`messages[].role`	string	`user` 或 `assistant`
`messages[].content`	string	消息正文

响应示例：

json

{
  "thread_id": "11111111-1111-1111-1111-111111111111",
  "messages": [
    {
      "role": "user",
      "content": "我想买保险，预算一年 8000"
    },
    {
      "role": "assistant",
      "content": "可以，我先给你规划一套医疗险、重疾险和意外险组合。",
    }
  ]
}

只展示 role=user 和 role=assistant 的消息。
不展示工具调用消息。

9.删除会话

需要通过checkpointer一并删除对应的会话记忆消息。

字段	内容
请求方式	DELETE
请求路径	/api/v1/chat-threads/
请求头	x-user-id: 1
请求体	无
响应结果	204 No Content
用途	删除会话及其 Checkpoint 状态（接口完善）

接口文档参考 ​

1.查询产品列表 ​

请求方式 ​

query参数 ​

响应格式 ​

2.查询推荐候选产品 ​

请求方式 ​

query参数 ​

响应格式 ​

3.创建会话 ​

请求方式 ​

请求格式 ​

响应格式 ​

4.查询会话列表 ​

请求方式 ​

请求参数 ​

请求响应 ​

5.重命名会话 ​

6.删除会话 ​

7.基础对话 ​

请求方式 ​

请求体字段 ​

请求响应 ​

8.查询指定会话的历史消息 ​

响应参数 ​

响应示例： ​

9.删除会话 ​

接口文档参考

1.查询产品列表

请求方式

query参数

响应格式

2.查询推荐候选产品

请求方式

query参数

响应格式

3.创建会话

请求方式

请求格式

响应格式

4.查询会话列表

请求方式

请求参数

请求响应

5.重命名会话

6.删除会话

7.基础对话

请求方式

请求体字段

请求响应

8.查询指定会话的历史消息

响应参数

响应示例：

9.删除会话