227 lines
6.8 KiB
Markdown
227 lines
6.8 KiB
Markdown
# QA History & Floating Chat — Implementation Plan
|
||
|
||
**Scope:** Split QA dialog from history records. Global floating chat button. Session-based history with pagination.
|
||
**Placement:** Floating button bottom-right (all pages) + QA Records tab (history only)
|
||
|
||
---
|
||
|
||
## Part 1 — DB Changes
|
||
|
||
### New: `qa_sessions` table
|
||
```
|
||
id
|
||
user_id
|
||
title -- auto-generated from first question (1 line)
|
||
project_id -- nullable, context project if asked from project page
|
||
started_at
|
||
last_message_at -- used for session grouping (30min gap = new session)
|
||
message_count
|
||
created_at
|
||
```
|
||
|
||
### Update: `qa_records` table
|
||
```
|
||
-- add:
|
||
session_id -- FK to qa_sessions
|
||
turn_index -- message order within session (1, 2, 3...)
|
||
```
|
||
|
||
### Session grouping rule
|
||
- Same user, same day, messages within 30 minutes → same session
|
||
- Gap > 30 minutes → new session auto-created
|
||
- Session title = first question truncated to 30 chars
|
||
|
||
---
|
||
|
||
## Part 2 — API Endpoints
|
||
|
||
### Sessions
|
||
- [x] `GET /api/qa-sessions?page=1&page_size=20&date_from=&date_to=` — paginated session list, sorted by last_message_at desc
|
||
- [x] `GET /api/qa-sessions/{id}` — full session detail with all messages
|
||
- [x] `DELETE /api/qa-sessions/{id}` — delete session + all its records
|
||
|
||
### Records
|
||
- [x] `POST /api/qa-records/{id}/feedback` — submit rating (unchanged)
|
||
- [x] `GET /api/qa-records/export?date_from=&date_to=&rating=` — full export as JSONL, no pagination, admin only
|
||
|
||
---
|
||
|
||
## Part 3 — Floating Chat Button
|
||
|
||
Global, appears on all pages. Bottom-right corner, fixed position.
|
||
|
||
### Button states
|
||
```
|
||
Default: ✦ (purple, 48x48px round button)
|
||
Unread: ✦ + red dot (new auto-reply from Feishu RAG)
|
||
Active: ✦ (darker, drawer open)
|
||
```
|
||
|
||
### Chat drawer
|
||
Slides in from right, 420px wide, full page height. Does not cover left nav.
|
||
|
||
**Drawer header:**
|
||
```
|
||
✦ AI 管家 [历史] [×]
|
||
```
|
||
- `历史` button → switches drawer content to session history view (see Part 4)
|
||
- `×` → closes drawer
|
||
|
||
**Conversation area:**
|
||
- Messages listed top to bottom, newest at bottom
|
||
- User messages: right-aligned, blue bubble
|
||
- AI messages: left-aligned, gray bubble
|
||
- Each AI message shows: source citation + response time + 👍 👎 inline
|
||
- Retains last 10 turns as context for next question
|
||
|
||
**Input area (fixed at drawer bottom):**
|
||
```
|
||
┌─────────────────────────────────┐
|
||
│ 输入问题... │
|
||
└─────────────────────────────────┘
|
||
[提问]
|
||
```
|
||
|
||
**On 👍 click (inline, non-blocking):**
|
||
```
|
||
这条回答对你有多大帮助？
|
||
● 完全解决 ○ 部分有用 ○ 可以更好
|
||
[跳过] [提交]
|
||
```
|
||
|
||
**On 👎 click (inline, expands below message):**
|
||
```
|
||
哪里有问题？（可多选）
|
||
☐ 答案错误 ☐ 来源错误 ☐ 不完整 ☐ 答非所问 ☐ 其他
|
||
|
||
正确答案：（选填）
|
||
┌──────────────────┐
|
||
│ │
|
||
└──────────────────┘
|
||
[提交]
|
||
```
|
||
|
||
After feedback submitted: rating badge appears on message, form collapses.
|
||
|
||
**Loading state:**
|
||
```
|
||
🤖 正在检索知识库...
|
||
```
|
||
Shows which domains are being searched (db / docs / feishu / pmflow).
|
||
|
||
---
|
||
|
||
## Part 4 — Session History View (inside drawer)
|
||
|
||
Triggered by clicking `历史` in drawer header. Replaces conversation area, back button returns to current chat.
|
||
|
||
**Two-panel layout inside drawer:**
|
||
|
||
```
|
||
[← 返回对话]
|
||
|
||
今天
|
||
健身项目状态咨询 14:23 3轮 →
|
||
开票系统宪章查询 11:05 2轮 →
|
||
|
||
昨天
|
||
信号处理相关问题 09:30 5轮 →
|
||
团队负载查询 08:15 1轮 →
|
||
|
||
更早（点击展开）
|
||
|
||
[加载更多]
|
||
```
|
||
|
||
Clicking a session → expands inline to show full conversation thread:
|
||
|
||
```
|
||
[← 会话列表]
|
||
健身项目状态咨询 · 2026-03-02 · 3轮对话
|
||
|
||
Q: 健身项目目前是什么状态？
|
||
A: 活跃状态，但所有任务均未开始...
|
||
来源：Project database · 耗时 3.9s · 👍 已评价
|
||
|
||
Q: 那宪章进度呢？
|
||
A: 宪章草稿阶段，0份宪章...
|
||
来源：Project database · 👎 已标记问题
|
||
|
||
Q: 帮我看看信号源
|
||
A: 当前有9条有效信号...
|
||
来源：Project database · 未评价 [👍] [👎]
|
||
```
|
||
|
||
- Sessions older than 30 days collapsed under "更早", not auto-loaded
|
||
- Each session shows: title / date / turn count / last message time
|
||
- Pagination: 20 sessions per page, "加载更多" button at bottom
|
||
- No infinite scroll (prevents performance issues with large history)
|
||
|
||
---
|
||
|
||
## Part 5 — QA Records Tab (history only, no chat)
|
||
|
||
Tab in AI Steward page. Only for browsing, rating, and exporting. Chat box removed entirely from this tab.
|
||
|
||
**Top bar:**
|
||
```
|
||
[ Search questions... ] [ All ratings ▾ ] [ This week ▾ ] [ Export JSONL ]
|
||
```
|
||
|
||
**Session list with pagination:**
|
||
|
||
Each row = one session (not one message):
|
||
```
|
||
2026-03-02 14:23 健身项目状态咨询 3轮 👍 2 👎 0 未评价 1 [展开]
|
||
2026-03-02 11:05 开票系统宪章查询 2轮 👍 0 👎 1 未评价 1 [展开]
|
||
```
|
||
|
||
Click `展开` → session expands inline showing all messages with rating controls.
|
||
|
||
**Pagination:**
|
||
- 20 sessions per page
|
||
- Page controls at bottom: `← 上一页 第1页/共8页 下一页 →`
|
||
|
||
**Stats bar (top of tab):**
|
||
```
|
||
总会话 68 总问答 342 已评价 89% 平均帮助度 4.2/5 可导出训练对 156
|
||
```
|
||
|
||
**Export:**
|
||
- `Export JSONL` button → exports ALL records matching current filters, no pagination limit
|
||
- Admin only
|
||
- Format: one JSON object per line, includes session_id, turn_index, question, answer, sources, rating, correct_answer
|
||
|
||
---
|
||
|
||
## Part 6 — Session Auto-title Generation
|
||
|
||
- [x] On session creation, first question is used as title (truncated to 30 chars)
|
||
- [x] If first question is very short (<5 chars), wait for second message to generate title
|
||
- [x] Title stored in `qa_sessions.title`, editable by user (click to rename in history view)
|
||
|
||
---
|
||
|
||
## Implementation Order
|
||
|
||
| Task | Time |
|
||
|------|------|
|
||
| DB: add `qa_sessions` table, add `session_id` + `turn_index` to `qa_records` | Day 1 |
|
||
| Session grouping logic (30min gap rule) + session auto-title | Day 1 |
|
||
| Session list + detail API endpoints | Day 2 |
|
||
| Floating chat button + drawer UI (conversation area + input) | Day 3–4 |
|
||
| Session history view inside drawer (list + inline expand) | Day 5 |
|
||
| QA Records tab: remove chat box, add session-grouped list + pagination | Day 6 |
|
||
| 👍👎 inline feedback in drawer (non-blocking forms) | Day 7 |
|
||
| Export JSONL with session metadata | Day 8 |
|
||
| End-to-end test + performance check (large history load) | Day 9–10 |
|
||
|
||
---
|
||
|
||
## Out of scope
|
||
|
||
- Search within a session
|
||
- Session sharing between users
|
||
- Session pinning / starring
|
||
- Voice input
|