# KnowHub 前端重构设计文档

> **注意**：本文档中的数据库字段和表名引用了旧 schema（JSONB 软关联、tool_table、atomic_capability 等）。新 schema 已迁移到关联表结构，详见 `schema.md`。实施时需按新 schema 调整。

本文档基于 `reference.html` 的视觉风格和交互范式，以及以 **”原子能力 (Capability)”** 为核心的数据库架构，详细规划 KnowHub 前端的重构方案。

## 核心设计理念

1. **扁平与沉浸式的现代 UI**：采用大圆角卡片、毛玻璃导航、动态阴影、高饱和响应式徽章，带来“现代操作系统”般的体验。
2. **连贯的钻取阅读模式 (SideDrawer)**：摒弃传统的多页面跳转，统一使用右侧滑出式的 `SideDrawer`（侧边抽屉）呈现任何实体的只读和交互详情，保持用户在上下文中的心流。
3. **数据驱动的四象限透视**：以 `需求 - 能力 - 工具 - 知识` 四个维度构建标签页，通过关联表穿透数据孤岛。

---

## 页面内容结构与详情页 (SideDrawer) 字段级映射设计

前端共划分为五个主要层级（通过顶部 Tab 切换）。每一个 UI 元素严格映射至 `knowhub_db` 核心图谱内的字段结构。

### 1. Dashboard (全局观测板)

**设计目标**：宏观了解系统中能力的沉淀和覆盖情况。

- **页面内容**：
  - **全景统计图**：总能力集、总需求集、被满足的业务诉求占比、活跃工具覆盖度。
  - **需求拓扑图 (Node Tree)**：从顶部类别到底部业务需求的树状图谱，根据节点产生的实际下发热度（如 `requirement_table.source_nodes` 中的 posts 值累加）决定背景热力色深和尺寸。

### 2. 需求库 (Requirement Library)

**设计目标**：展现前端业务需求（`requirement_table`）的落地情况。

- **列表卡片 (Requirement Matrix)**：
  - **主标题**：取自 `description`。
  - **核心指标**：横向展现关联的原子能力个数（遍历 `atomics` 数组的长度）和热度总权重（汇总 `source_nodes` 中所有的帖子数）。
  - **满足状态**：Badge 呈现 `status`，如“已满足”、“未满足”。支持点击卡片随时触发 SideDrawer。
- **SideDrawer (需求详情 - `req`)** 排版线框：

```text
========================================================== ✖ (关闭) ====
|                                                                      |
|  [BUSINESS REQUIREMENT] (浅色小字)                                   |
|  爆款短视频脚本自动化 (超大黑体)                                     |
|                                                                      |
|  [  🔴 未满足  ] (巨型状态排版区，可能带有呼吸灯动效)                |
|                                                                      |
|  ------- 匹配分析结果 (Match Result Text) ------------------------   |
|  "当前语言模型在'口播感'上仍有不足，语气过于生硬，且长文本分镜切     |
|  片缺乏镜头语言的训练，需要持续调研更垂直的视频侧面 Agent 框架。"    |
|  (大段具有引用格式的高排版正文)                                      |
|                                                                      |
|  ------- 调用的链条系统 (Associated Atomics) ---------------------   |
|                                                                      |
|  🧠 [创意文本自动化] (Cap2)                                          |
|                                                                      |
|  ------- 数据生成源/痛点来源 (Source Nodes) ----------------------   |
|                                                                      |
|  📍 来源于节点: [生活状态] (累计带来 14,895 观测热度)                |
|                                                                      |
========================================================================
```

### 3. 能力库 (Capability Library) - ⭐️ 系统核心

**设计目标**：原子能力表（`atomic_capability`）的展现和操作大盘。

- **网格卡片 (Capability Cards)** 排版线框：

```text
╭────────────────────────────────────────────────────────╮
│                                                        │
│  [✨ Capability Fully Ready]    (状态徽章)     [ 🧠 ]  │
│                                                        │
│  AI 高精视觉生成                                       │
│  基于扩散模型的高保真图像生成与风格迁移能力。          │
│                                                        │
│  ────────── (细分割线) ──────────────────────────────  │
│                                                        │
│  🛠 实现工具:                          知识源:         │
│  [Midjourney] [SDXL]               [📚 2 份知识文件]   │
╰────────────────────────────────────────────────────────╯
```

- **SideDrawer (能力详情 - `cap`)** 排版线框：

```text
========================================================== ✖ (关闭) ====
|                                                                      |
|  [ATOMIC CAPABILITY] (浅色小字)                                      |
|  AI 高精视觉生成 (超大黑体)                                          |
|                                                                      |
|  [  🎯 核心评估标准 (Criterion)                            ]         |
|  [  "构图准确度 > 90%, 角色特征保持率 > 85%, 出图无变形"   ] (高亮区)|
|                                                                      |
|  ------- 下发工具执行链 (Implements Detail) ----------------------   |
|                                                                      |
|  ⚙️ Midjourney                                                       |
|  > 通过 /imagine 命令生成图像，效果优秀但不支持中文提示词。          |
|                                                                      |
|  ⚙️ Stable Diffusion XL                                              |
|  > 开源生态最丰富的图像生成引擎，支持本地部署，显卡显存需>16G。      |
|                                                                      |
|  ------- 辐射的需求矩阵 (Requirements) ---------------------------   |
|                                                                      |
|  [⚡ 需求] 生成二次元风格角色封面                                    |
|                                                                      |
|  ------- 支撑该能力的知识沉淀 (Source Knowledge) -----------------   |
|                                                                      |
|  🔗 [经验] 角色一致性控制方案 (#k1-xxxx)                             |
|  🔗 [工序] SDXL 采样器最优步数实验 (#k3-xxxx)                        |
|                                                                      |
========================================================================
```

### 4. 工具库 (Tool Library)

**设计目标**：展示系统中可利用的具集（`tool_table`）。

- **瀑布流 / 扁平卡片 (Tool Card)** 排版线框：

```text
╭────────────────────────────────────────────────────────╮
│                                                        │
│  [  Wrench Icon ]                  [🟢 可用] (Status)  │
│                                                        │
│  Midjourney (标题)      [ v6.0 ] (次级标签 version)    │
│                                                        │
│  全球领先的 AI 艺术生成工具，支持高精细节还原。        │
│                                                        │
│   ✨ MATURE 工具成熟率 (Based on case_knowledge)       │
│   ■■■■■■■■■■■■■■■■■■■■□□□□□□                 45 案例 │
╰────────────────────────────────────────────────────────╯
```

- **SideDrawer (工具详情 - `tool`)** ：
  - **图谱知识分布 (Knowledge Breakdown)**：将工具的知识关联拆成三张计分卡横排：**工具基础知识** (`tool_knowledge` 长)、**工序执行标准** (`process_knowledge` 长)、**落地实操案例** (`case_knowledge` 长)。
  - **详细技术指标**：区块化分别显式输出 `input` 和 `output` 的预设规格。
  - **操作向导**：全文区域化呈现 `tutorial`，支持代码与指令的高亮。
  - **驱动的能力**：提供 `capabilities` 反向能力关联标签。
  - **运维指标**：在卡片边缘呈现 `updated_time` 时间戳转换后的相对时间格式。

### 5. 知识库 (K-Data Center)

**设计目标**：沉淀生产、方法论（`knowledge`）的最佳实践。

- **数据表格视图**：
  - 列表呈现文章的主旨任务 (`task`)。
  - `types` 数组使用多种配色的独立标签进行并排呈现（如：工序/用例/工具/经验/定义/User Profile）。
  - 根据 `eval` 字典内的 `score` 字段展示可读带星级的评定结果。
- **SideDrawer (知识详情 - `know`)**：
  - **评估明细窗 (Eval)**：详细展示 `eval` 内部的四个核心参数键值（`score`、`harmful`、`helpful`、`confidence`）。
  - **业务标签系 (Tags)**：遍历解析 `tags` 字典以 KV 徽章组的形式排版。
  - **正文区**：宽体排版并呈现大面积 `content`。
  - **追溯属性 (Lineage/Source)**：横截面栏位展现创作者所属 `owner`、以及此条目生成的具体分类与端侧来源 (`source.category`, `source.agent_id`)。
  - **支撑实体挂载点 (Supports)**：罗列出这条知识最终是在辅助哪个原子能力 (`support_capability` 数组) 抑或是对齐着什么工具 (`tools` 数组)。

---

## 需增加/完善的后端 API 接口确认

> [!WARNING]
> 在目前的 `server.py` 中，主要暴露了关于 Resources 和 Knowledge 的 API 端点。要支撑上述完整的连贯体验，我们必须确保后端能够提供以下核心表的全量及详情查询接口，请用户确认是否已经实现或需要一并在此次迭代中增加：

1. `GET /api/atomic_capabilities`
2. `GET /api/requirements`
3. `GET /api/tools`
4. 数据聚合统计接口，如 `GET /api/dashboard/stats`（或由前端缓存上述列表自行聚合）

## 用户确认点

> [!IMPORTANT]
>
> 1. **前端框架选择**：因为原本是用 FastAPI 的 Jinja + Vanilla JS 做，而 `reference.html` 是基于 **React + Tailwind**。本次重构您希望使用工程化的 Vite 等完整前端方案，还是像 demo 那样以单文件 HTML + CDN 的极简无构建方式实现？
> 2. **后端 API 是否齐备**：目前 `server.py` 尚未看到 Capabilities、Requirements 等数据的访问路由。是否希望在这轮一并为您用 FastAPI 写好供前端调用的 REST API？
