assist/.kiro/specs/conversation-tenant-view/requirements.md

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