tps-dashboard/logs/phase3_log.md

# Phase 3 开发日志

> 本文件记录 Phase 3（知识库基础设施）各 Task 的已完成事实。
> 续接快照（待办/决策）见单独文件，不混入本 log。

---

## Task 1 — embedding 最小链路验证 ✅（2026-05-26 完成）

### 目标
用最小代价验证 Phase 3 的命脉：文本能否转成正确维度的向量、整条「解析→embedding→入库→语义检索」链路能否跑通。不碰 schema、不碰前端、不碰 docx。

### 关键结论（地基事实，后续 Task 依赖）
- **embedding 服务确定为 MiniMax embo-01**。前期查证已排除 DeepSeek（官方无 embedding 接口）。
- **embo-01 输出维度 = 1536**，与 `001_init.sql` 中 `knowledge_embeddings.embedding vector(1536)` 完全匹配，无需改维度、无需改宪法。
- **embo-01 真实接口结构**（实测确认，非凭印象）：
  - 请求：`{"model":"embo-01", "texts":[...], "type":"db"|"query"}` —— 注意是 `texts` 数组，不是 OpenAI 的 `input`。
  - 返回：向量在 `vectors` 字段（`data["vectors"][0]`），不是 OpenAI 的 `data[0].embedding`。
  - 存文档用 `type="db"`，查询用 `type="query"`，不可混。
  - 调用需 `Authorization: Bearer {API_KEY}` + `GroupId` 两个凭证（MiniMax 特有 GroupId）。
- **检索方式**：使用 pgvector 数据库原生余弦距离算子 `<=>`，不在 Python 侧计算。
- **凭证管理**：API Key + GroupId 存于 `backend/.env`（`MINIMAX_EMBED_API_KEY` / `MINIMAX_GROUP_ID`），代码从 .env 读取，未进任何代码、未进 git（.env 已在 .gitignore）。
- 注意：embedding 接口地址 `https://api.minimax.chat/v1/embeddings`，与 Cline 写代码所用的 M2.7 chat 接口是两套独立配置，互不影响。

### 新增/改动文件（已 commit & push，commit 38873ac）
- `backend/requirements.txt`（+pgvector==0.2.5）
- `backend/app/core/config.py`（+引导凭证字段）
- `backend/app/models/knowledge.py`（新增，embedding 字段用 pgvector.Vector）
- `backend/app/services/embedding_service.py`（新增，embo-01 调用封装）
- `backend/app/services/knowledge_service.py`（新增，写库 + SQL 向量检索）
- `backend/scripts/test_embo01_api.py`（探路脚本）
- `backend/scripts/verify_embedding.py`（全链路验证脚本）
- `backend/sample_md/`（空目录，测试文件已清）

### 收尾
- 验证用测试数据已全部清除：knowledge_items = 0 行，knowledge_embeddings = 0 行，sample_md/ 空。
- 知识库当前为干净空库，等待真实笔记导入。

### 顺手核实到的现状（未处理，留待办）
- episodes 表当前仅 7 行。
- Phase 2 的「批量导入」前端有入口但从未真实导入过收视数据（制片人确认：是流程上没提醒导入，加上收视表里有测试数据不会删）。属 Phase 2 遗留债，记入 backlog，另行处理，不并入 Phase 3。

---

## Task 2 — 知识库管理后台（最小可用版）✅（2026-05-26 完成）

### 目标
做一条端到端跑通的链路：上传 .md 笔记 → 解析 yaml frontmatter → 入库（含语义向量）→ 列表展示 → 删除。不改 schema、不碰认证、不引向量索引以外的新依赖。

### 新增/改动文件（4 次独立 commit）

| 文件 | 动作 | 说明 |
|------|------|------|
| `backend/requirements.txt` | 改 | +python-frontmatter==1.1.0 |
| `backend/app/services/knowledge_service.py` | 扩展 | +parse_md_file() + delete_item() + list_items() + get_distinct_sources()；复用 EmbeddingService |
| `backend/app/api/knowledge.py` | 新增 | 4 个接口：POST /upload、GET /items、DELETE /items/{id}、GET /sources |
| `backend/app/main.py` | 改 | +app.include_router(knowledge_router) |
| `frontend/src/services/knowledgeService.js` | 新增 | 封装 4 个 API 调用 |
| `frontend/src/pages/KnowledgeBase/KnowledgeBase.jsx` | 重写 | 上传区(Dragger) + 筛选栏(Select) + 列表(Table) + 删除(Popconfirm) |

### yaml frontmatter 解析映射（按真实样本，写死）

```python
# 类型 → source_type（硬映射，不猜测）
杂志文章/军报 → military_report
节目文稿 → manuscript
报题单 → baoti

# 标题
名称 或 标题 → title

# 作者
作者 或 编导 → author

# 出处详情（存 JSONB 的 source_detail）
期刊 + 期号 → 拼接，如"航空知识 2026年第1期"

# 播出日期
容错"待补充"等非日期文本 → null

# 权重
原样存 JSONB（不展示不排序，Phase 4 排序用）

# 双链 [[...]]
_extract_double_brackets() 原样存入 JSONB 预留给 Phase 4
```

### 关键设计决策

1. **source_detail 存 JSONB 不 ALTER**：Task Brief 说"不要新增表字段"，`tags` JSONB 列已用于存权重，故 source_detail 也放进来，不 ALTER TABLE。查询时从 `tags->>'source_detail'` 解压。
2. **来源筛选动态从 DB 取**：`get_distinct_sources()` 查库里所有 `tags->>'source_detail'` DISTINCT 值，下拉选项不写死，新增一本杂志自动出现。
3. **embedding 复用**：直接调用 `EmbeddingService.embed_single(content_md, embed_type="db")`，1536 维向量已验证，不重写。
4. **删除 CASCADE**：数据库层已有 `ON DELETE CASCADE`，Python 侧只删 `KnowledgeItem` 即可。

### 测试结果（已验证）

| 验收项 | 结果 |
|--------|------|
| 两篇 md 均成功入库 | ✅ id=27(光辉之路)、id=28(超级战舰) |
| 杂志篇显示作者"钱峰"，无播出时间 | ✅ author=钱峰, publish_date=null |
| 节目篇显示编导"左鑫"，播出日期"待补充"不显示 | ✅ author=左鑫, publish_date=null |
| source_detail 正确存下（"航空知识 2026年第1期"） | ✅ tags 中可见 |
| 来源筛选下拉可据此筛 | ✅ /api/knowledge/sources 返回 `航空知识 2026年第1期` |
| knowledge_embeddings 有对应行（向量已生成） | ✅ 两行，19207/19174 字符（1536 维） |
| 删除有二次确认，确认后条目+向量一并消失 | ✅ 删除 id=27 验证，embeddings 级联消失 |

### commit 历史
- `779429a` feat: 添加 python-frontmatter 依赖用于解析 md yaml frontmatter
- `7b6ae24` feat: 知识库管理后台上传/列表/删除API，含frontmatter解析
- `7155a18` feat: 知识库管理前端页面，含上传/列表/筛选/删除

### 潜在风险
1. **windows CRLF 警告**：每次 commit 都有 CRLF→LF 警告，不影响功能但难看，属 git 全局配置问题（core.autocrlf），下次提醒用户设一下。
2. **"待补充"播出日期**：节目文稿的播出日期"待补充"正确存为 null，列表"播出/发表时间"格无值时不显示（render: val || null）。
3. **删除后 sources 下拉残留**：删除后 `get_distinct_sources()` 重新查会去掉已删条目的 source_detail，正常。
4. **embo-01 调用失败时整条上传失败**：当前是 try-except 包装，失败时返回 errors 数组，不污染已入库数据（因为单条原子），但前端需要展示 errors 反馈（已实现）。

---

## Task 3 — 知识库树形视图（路线B 按来源分组）✅（2026-05-27 完成）

> 本段为追加内容，接续 phase3_log 的 Task 1 / Task 2 之后。
> Task 3 实际分三轮（Task 3 主体 + 3.1 修复 + 3.2 调整）完成并验收。

### 目标
在 Task 2 的扁平列表外，包一层"可展开/收起的树形导航"，按"来源"两层分组，
点树节点 → 右侧列表联动过滤。保留原有上传/筛选/删除。不改 schema。

### 路线选择（已定）
- **走路线B：按来源分组**（制片人拍板）。理由：现有字段（source_type + source_detail）即可建树，零返工。
- 路线A（按主题分组：涉及装备/技术等）的原料其实已在库（related_entities / tags JSONB），
  将来转 A 路大概率无需补字段重传，只改分组层 + 映射表。
- **解耦红线**：交互层（KnowledgeTree.jsx）与数据分组层（useKnowledgeGrouping.js + 后端 get_grouped_items）分离，
  转 A 路只改分组层一处，树组件不动。

### 三轮各自做了什么

**Task 3（树主体）**
- 两层树：来源大类 → 二级（出处）。"全部"为根节点；空大类规则、_none_ 不泄漏。
- 交互：展开/收起、全部展开/全部收起、节点高亮、右侧联动。

**Task 3.1（修复）**
- 修出处筛选下拉为空（根因：前端从未调用 listSources，用 items.length 误判；改为调 /sources 动态填充）。
- 修页面宽度跳动（右侧容器加 minWidth:0 约束）。
- 表格列宽规划；上传区收成一行按钮；隐藏"入库时间"列（仅前端隐藏，DB 字段保留）。

**Task 3.2（调整）**
- 大类固定排序：节目文稿 → 杂志文章 → 报题单 → 其他。
- 节目文稿按作者(author)归堆二级（如"左鑫"）；映射表 SECONDARY_GROUP_FIELD 落地。
- 左右两列对齐（曾尝试 flex→Grid 重构，连续改坏，最终回退 flex 止损，保留功能改进）。
- 空大类(0条)不显示。

### 关键设计决策
1. **二级分组维度按大类不同**：manuscript→author，military_report→source_detail，其余 None。
   做成**可配置映射表**（前端 useKnowledgeGrouping.js + 后端 knowledge_service.py 同名映射），改一处即可调整。
   ⚠️ 此设计使"第二层维度"在不同大类下含义不同，是制片人知情拍板的临时方案；
   将来宜把"按编导看稿"迁为独立筛选（见快照 Backlog#3）。
2. **点击筛选为前端本地计算**：displayedItems 基于已拉取全量 items + 选中节点实时算，不发网络请求，稳定。
3. **过滤按大类用对应字段**：manuscript 比 author，military_report 比 source_detail（Task 3.2 最终修对的关键）。
4. **空大类不显示根因**：初始化时 type_groups 预建所有大类空列表，致 continue 失效；改为动态收集真实出现的 source_type。

### 改动文件
| 文件 | 动作 |
|------|------|
| `backend/app/services/knowledge_service.py` | 新增 get_grouped_items()；SOURCE_TYPE_ORDER；SECONDARY_GROUP_FIELD；空大类动态收集 |
| `backend/app/api/knowledge.py` | 新增 GET /api/knowledge/grouped |
| `frontend/src/services/knowledgeService.js` | 新增 getGroupedItems() |
| `frontend/src/hooks/useKnowledgeGrouping.js` | 新增（数据分组层，解耦核心） |
| `frontend/src/components/KnowledgeTree/KnowledgeTree.jsx` | 新增（树交互组件） |
| `frontend/src/components/KnowledgeTree/KnowledgeTree.css` | 新增 |
| `frontend/src/pages/KnowledgeBase/KnowledgeBase.jsx` | 重构左右分栏；按 type 分支过滤；上传区收小；隐藏入库时间列 |

### 验收结果（制片人真实点页面逐条验，已通过）
| 验收项 | 结果 |
|--------|------|
| 树两层、大类固定顺序（节目文稿在前） | ✅ |
| 节目文稿 → 左鑫 → 点击右侧出现超级战舰 | ✅ |
| 杂志文章 → 航空知识2026年第1期 → 点击右侧出现对应2篇 | ✅ |
| 点"全部"/各节点联动正确 | ✅ |
| 全部展开/全部收起、宽度不跳、上传按钮收小 | ✅ |
| 空大类(报题单/其他 0条)不显示 | ✅ |
| 原有上传/筛选/删除无回归 | ✅ |

### commit 历史
- 树主体与修复多次提交，最终修复 commit `3409d48`（前序含 `769a048` 等）。

### 教训（重要，下次接手避雷）
1. **Cline 自检多次虚标 ✅**：完工报告打勾项实测多坏。纪律：不信自检，制片人真实点页面验；禁止用会误报的检查方式（如跨多行正则）。
2. **key 两端对齐反复踩坑**：树节点 key 格式改动时生成端与过滤端未同步，致点节点筛不出。改 key 属高风险，改后必实测联动。
3. **布局别轻易换实现方式**：flex→Grid 整体重构连续改坏，靠"回退 flex + 保留功能"止损。已验证好用的布局不为对齐而重构。
4. **排查 > 盲改**：Cline 报告自相矛盾或与页面不符时，让制片人直接发源码文件给顾问看，一眼定位胜过反复试错。
5. **见好就收**：像素级打磨边际收益递减，记 backlog 改天连同视觉规范统一弄。

### 潜在风险 / 遗留
1. 界面像素级未到位：上传按钮框与筛选栏框上下精确对齐未做到；整体配色/字号属"能接受"非"精致"，记 backlog。
2. 200+ 笔记尚未批量录入：需先试 10 篇验证解析，且宜等 pdf 存储方案定后再全量（见快照 Backlog#1、#2）。
3. Phase 3 内"语义搜索"尚未做（向量已就位，随时可开），是下一刀候选。