# 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