Jeason
7013e9db70
- 新增 ConversationHistoryManager.get_tenant_summary() 按租户聚合会话统计 - get_sessions_paginated() 和 get_conversation_analytics() 增加 tenant_id 过滤 - 新增 GET /api/conversations/tenants 租户汇总端点 - sessions 和 analytics API 端点支持 tenant_id 查询参数 - 前端实现租户卡片列表视图和租户详情会话表格视图 - 实现面包屑导航、搜索范围限定、统计面板上下文切换 - 会话删除后自动检测空租户并返回列表视图 - dashboard.html 添加租户视图 DOM 容器 - 交互模式与知识库租户分组视图保持一致
103 lines
7.7 KiB
Markdown
103 lines
7.7 KiB
Markdown
# Requirements Document
|
||
|
||
## Introduction
|
||
|
||
知识库租户分组展示功能。当前知识库管理页面以扁平列表展示所有知识条目，缺乏租户（市场）维度的组织结构。本功能将知识库页面改造为两层结构：第一层按租户分组展示汇总信息，第二层展示某个租户下的具体知识条目。数据库模型 `KnowledgeEntry` 已有 `tenant_id` 字段，后端需新增按租户聚合的 API，前端需实现分组视图与钻取交互。
|
||
|
||
## Glossary
|
||
|
||
- **Dashboard**: Flask + Jinja2 + Bootstrap 5 构建的 Web 管理后台主页面（`dashboard.html`）
|
||
- **Knowledge_Tab**: Dashboard 中 `#knowledge-tab` 区域，用于展示和管理知识库条目
|
||
- **Knowledge_API**: Flask Blueprint `knowledge_bp`，提供知识库相关的 REST API（`/api/knowledge/*`）
|
||
- **Knowledge_Manager**: `KnowledgeManager` 类，封装知识库的数据库查询与业务逻辑
|
||
- **Tenant**: 租户，即市场标识（如 `market_a`、`market_b`），通过 `KnowledgeEntry.tenant_id` 字段区分
|
||
- **Tenant_Summary**: 租户汇总信息，包含租户 ID、知识条目总数等聚合数据
|
||
- **Tenant_List_View**: 第一层视图，以卡片或列表形式展示所有租户的汇总信息
|
||
- **Tenant_Detail_View**: 第二层视图，展示某个租户下的具体知识条目列表（含分页、筛选）
|
||
- **KnowledgeEntry**: SQLAlchemy 数据模型，包含 `tenant_id`、`question`、`answer`、`category`、`confidence_score`、`usage_count`、`is_verified` 等字段
|
||
|
||
## Requirements
|
||
|
||
### Requirement 1: 租户汇总 API
|
||
|
||
**User Story:** 作为管理员，我希望后端提供按租户分组的知识库汇总接口，以便前端展示每个租户的知识条目统计。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN a GET request is sent to `/api/knowledge/tenants`, THE Knowledge_API SHALL return a JSON array of Tenant_Summary objects, each containing `tenant_id`, `entry_count`, `verified_count`, and `category_distribution`
|
||
2. THE Knowledge_API SHALL only count active knowledge entries (`is_active == True`) in the Tenant_Summary aggregation
|
||
3. THE Knowledge_API SHALL sort the Tenant_Summary array by `entry_count` in descending order
|
||
4. WHEN no active knowledge entries exist, THE Knowledge_API SHALL return an empty JSON array with HTTP status 200
|
||
5. IF a database query error occurs, THEN THE Knowledge_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/knowledge`, THE Knowledge_API SHALL return only the knowledge entries belonging to the specified Tenant
|
||
2. THE Knowledge_API SHALL support pagination via `page` and `per_page` query parameters when filtering by `tenant_id`
|
||
3. THE Knowledge_API SHALL support `category` and `verified` query parameters for further filtering within a Tenant
|
||
4. WHEN the `tenant_id` parameter value does not match any existing entries, THE Knowledge_API SHALL return an empty knowledge list with `total` equal to 0 and HTTP status 200
|
||
5. THE Knowledge_Manager SHALL provide a method that accepts `tenant_id` as a filter parameter and returns paginated results
|
||
|
||
### Requirement 3: 租户列表视图（第一层）
|
||
|
||
**User Story:** 作为管理员，我希望知识库页面首先展示按租户分组的汇总卡片，以便快速了解各市场的知识库规模。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN the Knowledge_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（租户名称）, entry_count（知识条目总数）, verified_count（已验证条目数）
|
||
3. WHEN the Tenant_List_View is loading data, THE Dashboard SHALL display a loading spinner in the Knowledge_Tab area
|
||
4. WHEN no tenants exist, THE Dashboard SHALL display a placeholder message indicating that no knowledge entries 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 knowledge entries for the selected Tenant
|
||
2. THE Tenant_Detail_View SHALL display each knowledge entry with the following fields: question, answer, category, confidence_score, usage_count, is_verified status
|
||
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 category and verification status
|
||
|
||
### Requirement 5: 租户详情视图中的知识条目操作
|
||
|
||
**User Story:** 作为管理员，我希望在租户详情视图中能对知识条目执行添加、删除、验证等操作，以便维护知识库内容。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHILE viewing the Tenant_Detail_View, THE Dashboard SHALL provide buttons for adding, deleting, verifying, and unverifying knowledge entries
|
||
2. WHEN a user adds a new knowledge entry in the Tenant_Detail_View, THE Knowledge_API SHALL associate the new entry with the currently selected Tenant by setting the `tenant_id` field
|
||
3. WHEN a user performs a batch operation (batch delete, batch verify, batch unverify) in the Tenant_Detail_View, THE Dashboard SHALL refresh the Tenant_Detail_View to reflect the updated data
|
||
4. WHEN a user deletes all entries for a Tenant, THE Dashboard SHALL navigate back to the Tenant_List_View and remove the empty Tenant card
|
||
5. IF a knowledge entry operation fails, THEN THE Dashboard SHALL display an error notification with the failure reason
|
||
|
||
### Requirement 6: 搜索功能适配
|
||
|
||
**User Story:** 作为管理员，我希望在租户详情视图中搜索知识条目时，搜索范围限定在当前租户内，以便精确查找。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHILE viewing the Tenant_Detail_View, THE Dashboard SHALL scope the knowledge search to the currently selected Tenant
|
||
2. WHEN a search query is submitted in the Tenant_Detail_View, THE Knowledge_API SHALL filter search results by the specified `tenant_id`
|
||
3. WHEN the search query is cleared, THE Dashboard SHALL restore the full paginated list for the current Tenant
|
||
4. THE Knowledge_Manager search method SHALL accept an optional `tenant_id` parameter to limit search scope
|
||
|
||
### Requirement 7: 统计信息适配
|
||
|
||
**User Story:** 作为管理员，我希望知识库统计面板在租户列表视图时展示全局统计，在租户详情视图时展示当前租户的统计，以便获取准确的上下文信息。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHILE the Tenant_List_View is displayed, THE Dashboard SHALL show global knowledge statistics (total entries across all tenants, total verified entries, average confidence)
|
||
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/knowledge/stats`, THE Knowledge_API SHALL return statistics filtered by the specified Tenant
|
||
4. WHEN the `tenant_id` parameter is omitted from the stats request, THE Knowledge_API SHALL return global statistics across all tenants
|