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

Implementation Plan: 对话历史租户分组展示 (conversation-tenant-view)

Overview

将对话历史页面从扁平会话列表改造为两层结构：第一层按 tenant_id 分组展示租户汇总卡片，第二层展示租户下的会话列表。改造涉及 ConversationHistoryManager 业务逻辑层、Flask API 层、前端 dashboard.js 三个层面。交互模式与知识库租户分组视图保持一致。

Tasks

• 1. ConversationHistoryManager 新增 get_tenant_summary 方法

  • 1.1 在 src/dialogue/conversation_history.py 中新增 get_tenant_summary() 方法

    • 使用 SQLAlchemy GROUP BY ChatSession.tenant_id 聚合所有 ChatSession 记录
    • 计算每个租户的 session_count（会话总数）、message_count（消息总数，sum of message_count）、active_session_count（status=='active' 的会话数）、last_active_time（max of updated_at）
    • 按 last_active_time 降序排列
    • 数据库异常时返回空列表 []，记录 error 日志
    • 无 ChatSession 记录时返回空列表 []
    • Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6

  • * 1.2 为 get_tenant_summary 编写属性测试

    • Property 1: Tenant summary aggregation correctness
    • Property 2: Tenant summary sorted by last_active_time descending
    • 使用 hypothesis 生成随机 ChatSession 列表（混合 tenant_id、status、message_count），验证聚合正确性和排序
    • Validates: Requirements 1.1, 1.2, 1.3, 1.4, 1.5

• 2. ConversationHistoryManager 现有方法增加 tenant_id 过滤

  • 2.1 为 get_sessions_paginated() 增加 tenant_id 可选参数

    • 在 src/dialogue/conversation_history.py 中修改方法签名，增加 tenant_id: Optional[str] = None
    • 当 tenant_id 不为 None 时，在查询中增加 ChatSession.tenant_id == tenant_id 过滤条件
    • 返回结构不变，仅过滤范围缩小
    • Requirements: 2.1, 2.2, 2.3, 2.5

  • * 2.2 为 get_sessions_paginated 的 tenant_id 过滤编写属性测试

    • Property 3: Session filtering by tenant, status, and search
    • Property 4: Pagination consistency with tenant filter
    • Validates: Requirements 2.1, 2.2, 2.3

  • 2.3 为 get_conversation_analytics() 增加 tenant_id 可选参数

    • 当 tenant_id 不为 None 时，所有统计查询增加 ChatSession.tenant_id == tenant_id 和 Conversation.tenant_id == tenant_id 过滤
    • 返回结构不变
    • Requirements: 8.3, 8.4

  • * 2.4 为 get_conversation_analytics 的 tenant_id 过滤编写属性测试

    • Property 7: Analytics scoped to tenant
    • Validates: Requirements 8.3, 8.4

• 3. Checkpoint - 确保后端业务逻辑层完成

  • Ensure all tests pass, ask the user if questions arise.

• 4. Conversations API 层新增和修改端点

  • 4.1 在 src/web/blueprints/conversations.py 中新增 GET /api/conversations/tenants 端点

    • 调用 history_manager.get_tenant_summary() 返回租户汇总 JSON 数组
    • 使用 try/except 包裹，异常时返回 HTTP 500
    • Requirements: 1.1, 1.5, 1.6, 1.7

  • 4.2 修改 GET /api/conversations/sessions 端点，增加 tenant_id 查询参数支持

    • 从 request.args 获取 tenant_id 参数，传递给 history_manager.get_sessions_paginated()
    • Requirements: 2.1, 2.2, 2.3, 2.4

  • 4.3 修改 GET /api/conversations/analytics 端点，增加 tenant_id 查询参数支持

    • 从 request.args 获取 tenant_id 参数，传递给 history_manager.get_conversation_analytics()
    • Requirements: 8.3, 8.4

  • * 4.4 为新增和修改的 API 端点编写单元测试

    • 测试 /api/conversations/tenants 返回正确的汇总数据
    • 测试各端点的 tenant_id 参数过滤行为
    • 测试空数据和异常情况
    • Requirements: 1.1, 1.6, 1.7, 2.4

• 5. Checkpoint - 确保后端 API 层完成

  • Ensure all tests pass, ask the user if questions arise.

• 6. 前端 Tenant_List_View（租户列表视图）

  • 6.1 在 src/web/static/js/dashboard.js 中实现 loadConversationTenantList() 函数

    • 请求 GET /api/conversations/tenants 获取租户汇总数据
    • 渲染租户卡片列表，每张卡片展示 tenant_id、session_count、message_count、active_session_count、last_active_time
    • 添加加载中 spinner 状态
    • 无租户时展示空状态占位提示
    • 卡片点击事件绑定，调用 loadConversationTenantDetail(tenantId)
    • Requirements: 3.1, 3.2, 3.3, 3.4

  • 6.2 实现刷新按钮功能

    • 在对话历史 tab 区域添加刷新按钮，点击时重新调用 loadConversationTenantList()
    • Requirements: 3.5

• 7. 前端 Tenant_Detail_View（租户详情视图）

  • 7.1 实现 loadConversationTenantDetail(tenantId, page) 函数

    • 请求 GET /api/conversations/sessions?tenant_id=X&page=P&per_page=N 获取会话列表
    • 渲染会话表格，展示 title、message_count、status、source、created_at、updated_at
    • 实现分页控件
    • 支持 status 和 date_filter 筛选
    • Requirements: 4.1, 4.2, 4.5, 4.6

  • 7.2 实现面包屑导航 renderConversationBreadcrumb(tenantId, sessionTitle)

    • 展示 "对话历史 > {tenant_id}" 面包屑（租户详情视图）
    • 展示 "对话历史 > {tenant_id} > {session_title}" 面包屑（消息详情视图）
    • 点击 "对话历史" 链接时调用 loadConversationTenantList() 返回租户列表视图
    • 点击 "{tenant_id}" 链接时调用 loadConversationTenantDetail(tenantId) 返回租户详情视图
    • 管理 conversationCurrentTenantId 状态变量控制视图层级
    • Requirements: 4.3, 4.4, 5.3, 5.4

  • 7.3 在 Tenant_Detail_View 中集成会话管理操作

    • 每行会话提供删除按钮，调用 DELETE /api/conversations/sessions/<session_id>
    • 删除成功后刷新当前租户详情视图
    • 删除所有会话后自动返回租户列表视图并移除空租户卡片
    • 操作失败时通过 showNotification 展示错误提示
    • Requirements: 6.1, 6.2, 6.3, 6.4, 6.5

  • * 7.4 为删除操作编写属性测试

    • Property 5: Session deletion removes session and all associated messages
    • Validates: Requirements 6.2

• 8. 前端搜索和统计面板适配

  • 8.1 修改搜索功能 searchConversationSessions()

    • 在 Tenant_Detail_View 中搜索时自动附加 tenant_id 参数
    • 清空搜索时恢复当前租户的完整分页列表
    • Requirements: 7.1, 7.2, 7.3

  • * 8.2 为搜索范围限定编写属性测试

    • Property 6: Search results scoped to tenant
    • Validates: Requirements 7.1, 7.2

  • 8.3 修改 loadConversationStats(tenantId) 函数

    • 当 conversationCurrentTenantId 为 null 时请求全局统计
    • 当 conversationCurrentTenantId 有值时请求 GET /api/conversations/analytics?tenant_id=X
    • Requirements: 8.1, 8.2

• 9. 前端 HTML 模板更新

  • 9.1 在 src/web/templates/dashboard.html 的 #conversation-history-tab 区域添加必要的 DOM 容器
    • 添加面包屑容器、租户卡片列表容器、租户详情容器
    • 确保与现有 Bootstrap 5 样式一致，与知识库租户视图风格统一
    • Requirements: 3.1, 4.3

• 10. Final checkpoint - 确保所有功能集成完成

  • Ensure all tests pass, ask the user if questions arise.

Notes

• Tasks marked with * are optional and can be skipped for faster MVP
• Each task references specific requirements for traceability
• Checkpoints ensure incremental validation
• Property tests validate universal correctness properties from the design document
• 数据模型 ChatSession 和 Conversation 已有 tenant_id 字段且已建索引，无需数据库迁移
• 交互模式与知识库租户分组视图 (knowledge-tenant-view) 保持一致