AI 聊天助手 - 接口文档与对接规范

1. JWT 鉴权规范

1.1 签发参数

参数	值
算法	HS256
Secret Key	.env 中的 JWT_SECRET_KEY
过期时间	.env 中的 JWT_EXPIRES_HOURS（默认 24 小时）

1.2 Payload 格式

{
  "user_id": 1,
  "username": "张三",
  "iat": 1710000000,
  "exp": 1710086400
}

字段	类型	必填	说明	对应 user 表字段
user_id	int	是	用户主键	user.user_id
username	string	是	用户昵称	user.nickname
iat	int	是	签发时间（UTC 时间戳）	-
exp	int	是	过期时间（UTC 时间戳）	-

1.3 前端传递方式

请求 Header：

Authorization: Bearer <token>

前端登录成功后需将 token 存入 localStorage：

localStorage.setItem('token', data.token);
localStorage.setItem('username', data.username);

1.4 可直接调用的签发函数

from auth import generate_token

token = generate_token(user_id=user.user_id, username=user.nickname)

---

2. 鉴权拦截规则

2.1 白名单（不需要 token）

方法	路径	说明
GET	/	首页
GET	/login	登录页面
POST	/api/login	登录接口

2.2 拦截范围

• 所有 /api/* 路径（白名单除外）均需要在 Header 中携带有效的 JWT token
• 非 /api 路径和静态资源不拦截

2.3 鉴权失败响应

HTTP 状态码：401

{"success": false, "error": "未提供认证令牌"}
{"success": false, "error": "无效的令牌"}
{"success": false, "error": "令牌已过期，请重新登录"}

前端收到 401 后会清除 localStorage 中的 token 并跳转到 /login。

---

3. 数据库表结构

3.1 user 表（用户表）

字段	类型	约束	说明
user_id	INT	PK, AUTO_INCREMENT	用户ID
email	VARCHAR(255)	NOT NULL, UNIQUE	邮箱
nickname	VARCHAR(100)	NOT NULL	钉钉用户名称
password	VARCHAR(255)	NOT NULL	密码（建议存 bcrypt 哈希）
created_at	DATETIME	NOT NULL, DEFAULT NOW	创建时间
updated_at	DATETIME	NOT NULL, AUTO UPDATE	更新时间

3.2 conversation 表（会话表）

字段	类型	约束	说明
id	VARCHAR(36)	PK	会话ID（UUID）
user_id	INT	NOT NULL, FK -> user.user_id	用户ID
title	VARCHAR(255)	NOT NULL, DEFAULT '未命名对话'	会话标题
provider	VARCHAR(50)	NULL	模型提供商
model_name	VARCHAR(100)	NULL	模型名称
mode	VARCHAR(20)	NOT NULL, DEFAULT 'chat'	模式：chat/image
created_at	DATETIME	NOT NULL, DEFAULT NOW	创建时间
updated_at	DATETIME	NOT NULL, AUTO UPDATE	更新时间

3.3 message 表（消息表）

字段	类型	约束	说明
id	BIGINT	PK, AUTO_INCREMENT	消息ID
conversation_id	VARCHAR(36)	NOT NULL, FK -> conversation.id	会话ID
role	VARCHAR(20)	NOT NULL	角色：user/assistant
content	TEXT	NOT NULL	消息内容
provider	VARCHAR(50)	NULL	模型提供商
model_name	VARCHAR(100)	NULL	模型名称
prompt_tokens	INT	NULL	输入 token 数
completion_tokens	INT	NULL	输出 token 数
total_tokens	INT	NULL	总 token 数
created_at	DATETIME	NOT NULL, DEFAULT NOW	创建时间

---

4. 接口清单

4.1 登录（不需要鉴权）

POST /api/login

临时测试接口，后续由登录模块替换。

请求：

{
  "username": "admin",
  "password": "admin123"
}

成功响应（200）：

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "user_id": 1,
  "username": "admin"
}

失败响应（401）：

{
  "success": false,
  "error": "用户名或密码错误"
}

临时测试账号：

• admin / admin123（user_id=1）
• test / test123（user_id=2）

---

4.2 会话管理（需要鉴权）

以下接口均需在 Header 中携带 Authorization: Bearer <token>。

GET /api/conversations

获取当前用户的会话列表，按更新时间倒序。

响应：

{
  "success": true,
  "conversations": [
    {
      "id": "uuid-xxx",
      "user_id": 1,
      "title": "关于Python的问题",
      "provider": "deepseek",
      "model_name": "deepseek-chat",
      "mode": "chat",
      "created_at": "2024-03-10T12:00:00",
      "updated_at": "2024-03-10T12:30:00"
    }
  ]
}

POST /api/conversations

创建新会话。

请求：

{
  "title": "未命名对话",
  "provider": "deepseek",
  "model_name": "deepseek-chat",
  "mode": "chat"
}

响应（201）：

{
  "success": true,
  "conversation": { ... }
}

GET /api/conversations/:id

获取会话详情，包含全部消息。

响应：

{
  "success": true,
  "conversation": {
    "id": "uuid-xxx",
    "title": "关于Python的问题",
    "messages": [
      {
        "id": 1,
        "conversation_id": "uuid-xxx",
        "role": "user",
        "content": "你好",
        "provider": "deepseek",
        "model_name": "deepseek-chat",
        "prompt_tokens": null,
        "completion_tokens": null,
        "total_tokens": null,
        "created_at": "2024-03-10T12:00:00"
      },
      {
        "id": 2,
        "role": "assistant",
        "content": "你好！有什么可以帮你的？",
        "prompt_tokens": 10,
        "completion_tokens": 20,
        "total_tokens": 30,
        "created_at": "2024-03-10T12:00:01"
      }
    ]
  }
}

PUT /api/conversations/:id

更新会话信息（重命名、切换模型等），所有字段可选。

请求：

{
  "title": "新标题",
  "provider": "openai",
  "model_name": "gpt-4",
  "mode": "chat"
}

响应：

{
  "success": true,
  "conversation": { ... }
}

DELETE /api/conversations/:id

删除会话，级联删除所有消息。

响应：

{
  "success": true
}

---

4.3 AI 对话（需要鉴权）

POST /api/chat

发送聊天消息，自动存储用户消息和 AI 回复到会话中。

请求：

{
  "provider": "deepseek",
  "model": "deepseek-chat",
  "prompt": "你好",
  "conversation_id": "uuid-xxx",
  "system_prompt": null
}

响应：

{
  "success": true,
  "response": "你好！有什么可以帮你的？",
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

支持的 provider 和 model：

provider	可选 model
deepseek	deepseek-chat, deepseek-coder
tongyi	qwen-max, qwen-plus, qwen-turbo
openai	gpt-4, gpt-3.5-turbo
kimi	moonshot-v1-8k, moonshot-v1-32k, moonshot-v1-128k

POST /api/generate-image

生成图片，自动存储到会话中。

请求：

{
  "prompt": "一只可爱的猫咪",
  "size": "1024x1024",
  "model": "dall-e-3",
  "conversation_id": "uuid-xxx"
}

响应：

{
  "success": true,
  "image_urls": ["https://..."]
}

支持的 size：1024x1024、1792x1024、1024x1792

---

5. 统一错误响应格式

所有接口错误时返回：

{
  "success": false,
  "error": "错误描述信息"
}

常见 HTTP 状态码：

• 401 - 未认证 / token 过期
• 404 - 资源不存在（会话不存在等）
• 500 - 服务器内部错误

---

6. 登录模块对接清单

同事开发登录模块时需要完成以下工作：

1. 实现 POST /api/login 接口：查询 user 表验证密码，调用 from auth import generate_token 签发 token
2. 提供 /login 页面：登录表单，成功后执行 localStorage.setItem('token', token) 并跳转到 /
3. 密码存储：user 表的 password 字段建议使用 bcrypt 哈希存储，不要存明文
4. 上线后清理：删除 auth.py 中第 72-98 行的临时测试登录代码（TEST_USERS 和 /api/login 路由）