117 lines
9.2 KiB
Markdown
117 lines
9.2 KiB
Markdown
|
# Requirements Document
|
|||
|
|
|
|||
|
|
## Introduction
|
|||
|
|
|
|||
|
|
对话历史租户分组展示功能。当前对话历史页面以扁平的会话列表展示所有 `ChatSession` 记录，缺乏租户（市场）维度的组织结构。本功能将对话历史页面改造为两层结构：第一层按租户分组展示汇总信息（会话总数、消息总数、最近活跃时间等），第二层展示某个租户下的具体会话列表。点击具体会话仍可查看消息详情（保留现有功能）。交互模式与知识库租户分组视图保持一致，包括卡片视图、面包屑导航、搜索范围限定和统计面板上下文切换。
|
|||
|
|
|
|||
|
|
## Glossary
|
|||
|
|
|
|||
|
|
- **Dashboard**: Flask + Jinja2 + Bootstrap 5 构建的 Web 管理后台主页面（`dashboard.html`）
|
|||
|
|
- **Conversation_Tab**: Dashboard 中 `#conversation-history-tab` 区域，用于展示和管理对话历史
|
|||
|
|
- **Conversation_API**: Flask Blueprint `conversations_bp`，提供对话相关的 REST API（`/api/conversations/*`）
|
|||
|
|
- **History_Manager**: `ConversationHistoryManager` 类，封装对话历史的数据库查询与业务逻辑
|
|||
|
|
- **Tenant**: 租户，即市场标识（如 `market_a`、`market_b`），通过 `ChatSession.tenant_id` 字段区分
|
|||
|
|
- **Tenant_Summary**: 租户汇总信息，包含租户 ID、会话总数、消息总数、活跃会话数、最近活跃时间等聚合数据
|
|||
|
|
- **Tenant_List_View**: 第一层视图，以卡片形式展示所有租户的对话汇总信息
|
|||
|
|
- **Tenant_Detail_View**: 第二层视图，展示某个租户下的具体会话列表（含分页、筛选）
|
|||
|
|
- **ChatSession**: SQLAlchemy 数据模型，包含 `tenant_id`、`session_id`、`title`、`status`、`message_count`、`source`、`created_at`、`updated_at` 等字段
|
|||
|
|
- **Conversation**: SQLAlchemy 数据模型，表示单条对话消息，包含 `tenant_id`、`session_id`、`user_message`、`assistant_response` 等字段
|
|||
|
|
|
|||
|
|
## Requirements
|
|||
|
|
|
|||
|
|
### Requirement 1: 租户汇总 API
|
|||
|
|
|
|||
|
|
**User Story:** 作为管理员，我希望后端提供按租户分组的对话会话汇总接口，以便前端展示每个租户的对话统计。
|
|||
|
|
|
|||
|
|
#### Acceptance Criteria
|
|||
|
|
|
|||
|
|
1. WHEN a GET request is sent to `/api/conversations/tenants`, THE Conversation_API SHALL return a JSON array of Tenant_Summary objects, each containing `tenant_id`, `session_count`, `message_count`, `active_session_count`, and `last_active_time`
|
|||
|
|
2. THE Conversation_API SHALL compute `session_count` by counting all ChatSession records for each Tenant
|
|||
|
|
3. THE Conversation_API SHALL compute `message_count` by summing the `message_count` field of all ChatSession records for each Tenant
|
|||
|
|
4. THE Conversation_API SHALL compute `active_session_count` by counting ChatSession records with `status == 'active'` for each Tenant
|
|||
|
|
5. THE Conversation_API SHALL sort the Tenant_Summary array by `last_active_time` in descending order
|
|||
|
|
6. WHEN no ChatSession records exist, THE Conversation_API SHALL return an empty JSON array with HTTP status 200
|
|||
|
|
7. IF a database query error occurs, THEN THE Conversation_API SHALL return an error response with HTTP status 500 and a descriptive error message
|
|||
|
|
|
|||
|
|
### Requirement 2: 租户会话列表 API
|
|||
|
|
|
|||
|
|
**User Story:** 作为管理员，我希望后端提供按租户筛选的会话分页接口，以便在点击某个租户后查看该租户下的具体会话列表。
|
|||
|
|
|
|||
|
|
#### Acceptance Criteria
|
|||
|
|
|
|||
|
|
1. WHEN a GET request with query parameter `tenant_id` is sent to `/api/conversations/sessions`, THE Conversation_API SHALL return only the ChatSession records belonging to the specified Tenant
|
|||
|
|
2. THE Conversation_API SHALL support pagination via `page` and `per_page` query parameters when filtering by `tenant_id`
|
|||
|
|
3. THE Conversation_API SHALL support `status` and `search` query parameters for further filtering within a Tenant
|
|||
|
|
4. WHEN the `tenant_id` parameter value does not match any existing ChatSession records, THE Conversation_API SHALL return an empty session list with `total` equal to 0 and HTTP status 200
|
|||
|
|
5. THE History_Manager SHALL accept `tenant_id` as a filter parameter in the `get_sessions_paginated` method and return paginated results scoped to the specified Tenant
|
|||
|
|
|
|||
|
|
### Requirement 3: 租户列表视图（第一层）
|
|||
|
|
|
|||
|
|
**User Story:** 作为管理员，我希望对话历史页面首先展示按租户分组的汇总卡片，以便快速了解各市场的对话活跃度。
|
|||
|
|
|
|||
|
|
#### Acceptance Criteria
|
|||
|
|
|
|||
|
|
1. WHEN the Conversation_Tab is activated, THE Dashboard SHALL display a Tenant_List_View showing one card per Tenant
|
|||
|
|
2. THE Tenant_List_View SHALL display the following information for each Tenant: tenant_id（租户名称）, session_count（会话总数）, message_count（消息总数）, active_session_count（活跃会话数）, last_active_time（最近活跃时间）
|
|||
|
|
3. WHEN the Tenant_List_View is loading data, THE Dashboard SHALL display a loading spinner in the Conversation_Tab area
|
|||
|
|
4. WHEN no tenants exist, THE Dashboard SHALL display a placeholder message indicating that no conversation sessions are available
|
|||
|
|
5. THE Tenant_List_View SHALL refresh its data when the user clicks a refresh button
|
|||
|
|
|
|||
|
|
### Requirement 4: 租户详情视图（第二层）
|
|||
|
|
|
|||
|
|
**User Story:** 作为管理员，我希望点击某个租户卡片后能查看该租户下的具体会话列表，以便管理和审查对话内容。
|
|||
|
|
|
|||
|
|
#### Acceptance Criteria
|
|||
|
|
|
|||
|
|
1. WHEN a user clicks on a Tenant card in the Tenant_List_View, THE Dashboard SHALL transition to the Tenant_Detail_View showing ChatSession records for the selected Tenant
|
|||
|
|
2. THE Tenant_Detail_View SHALL display each ChatSession with the following fields: title（会话标题）, message_count（消息数）, status（状态）, source（来源）, created_at（创建时间）, updated_at（最近更新时间）
|
|||
|
|
3. THE Tenant_Detail_View SHALL provide a breadcrumb navigation showing "对话历史 > {tenant_id}" to indicate the current context
|
|||
|
|
4. WHEN the user clicks the breadcrumb "对话历史" link, THE Dashboard SHALL navigate back to the Tenant_List_View
|
|||
|
|
5. THE Tenant_Detail_View SHALL support pagination with configurable page size
|
|||
|
|
6. THE Tenant_Detail_View SHALL support filtering by session status and date range
|
|||
|
|
|
|||
|
|
### Requirement 5: 会话详情查看（第三层保留）
|
|||
|
|
|
|||
|
|
**User Story:** 作为管理员，我希望在租户详情视图中点击某个会话后能查看该会话的消息详情，以便审查具体对话内容。
|
|||
|
|
|
|||
|
|
#### Acceptance Criteria
|
|||
|
|
|
|||
|
|
1. WHEN a user clicks on a ChatSession row in the Tenant_Detail_View, THE Dashboard SHALL display the message detail view showing all Conversation records for the selected ChatSession
|
|||
|
|
2. THE Dashboard SHALL retain the existing message detail display logic and UI layout
|
|||
|
|
3. THE Dashboard SHALL provide a breadcrumb navigation showing "对话历史 > {tenant_id} > {session_title}" in the message detail view
|
|||
|
|
4. WHEN the user clicks the breadcrumb "{tenant_id}" link, THE Dashboard SHALL navigate back to the Tenant_Detail_View for the corresponding Tenant
|
|||
|
|
|
|||
|
|
### Requirement 6: 会话管理操作
|
|||
|
|
|
|||
|
|
**User Story:** 作为管理员，我希望在租户详情视图中能对会话执行删除操作，以便维护对话历史数据。
|
|||
|
|
|
|||
|
|
#### Acceptance Criteria
|
|||
|
|
|
|||
|
|
1. WHILE viewing the Tenant_Detail_View, THE Dashboard SHALL provide a delete button for each ChatSession row
|
|||
|
|
2. WHEN a user deletes a ChatSession in the Tenant_Detail_View, THE Conversation_API SHALL delete the ChatSession and all associated Conversation records
|
|||
|
|
3. WHEN a user deletes a ChatSession, THE Dashboard SHALL refresh the Tenant_Detail_View to reflect the updated data
|
|||
|
|
4. WHEN a user deletes all ChatSession records for a Tenant, THE Dashboard SHALL navigate back to the Tenant_List_View and remove the empty Tenant card
|
|||
|
|
5. IF a ChatSession deletion fails, THEN THE Dashboard SHALL display an error notification with the failure reason
|
|||
|
|
|
|||
|
|
### Requirement 7: 搜索功能适配
|
|||
|
|
|
|||
|
|
**User Story:** 作为管理员，我希望在租户详情视图中搜索会话时，搜索范围限定在当前租户内，以便精确查找。
|
|||
|
|
|
|||
|
|
#### Acceptance Criteria
|
|||
|
|
|
|||
|
|
1. WHILE viewing the Tenant_Detail_View, THE Dashboard SHALL scope the session search to the currently selected Tenant
|
|||
|
|
2. WHEN a search query is submitted in the Tenant_Detail_View, THE Conversation_API SHALL filter search results by the specified `tenant_id`
|
|||
|
|
3. WHEN the search query is cleared, THE Dashboard SHALL restore the full paginated session list for the current Tenant
|
|||
|
|
4. THE History_Manager search method SHALL accept an optional `tenant_id` parameter to limit search scope
|
|||
|
|
|
|||
|
|
### Requirement 8: 统计信息适配
|
|||
|
|
|
|||
|
|
**User Story:** 作为管理员，我希望对话历史统计面板在租户列表视图时展示全局统计，在租户详情视图时展示当前租户的统计，以便获取准确的上下文信息。
|
|||
|
|
|
|||
|
|
#### Acceptance Criteria
|
|||
|
|
|
|||
|
|
1. WHILE the Tenant_List_View is displayed, THE Dashboard SHALL show global conversation statistics (total sessions across all tenants, total messages, total active sessions)
|
|||
|
|
2. WHILE the Tenant_Detail_View is displayed, THE Dashboard SHALL show statistics scoped to the selected Tenant
|
|||
|
|
3. WHEN a GET request with query parameter `tenant_id` is sent to `/api/conversations/analytics`, THE Conversation_API SHALL return analytics data filtered by the specified Tenant
|
|||
|
|
4. WHEN the `tenant_id` parameter is omitted from the analytics request, THE Conversation_API SHALL return global analytics across all tenants
|