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

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