From 7999fd14c8e543c1ad80b840d6f2f171497fbe88 Mon Sep 17 00:00:00 2001
From: simonkoson <28867558@qq.com>
Date: Tue, 26 May 2026 18:59:39 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20phase3=5Flog=20Tas?=
 =?UTF-8?q?k=202=20=E5=AE=8C=E5=B7=A5=E8=AE=B0=E5=BD=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 logs/phase3_log_task1.md | 75 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)

diff --git a/logs/phase3_log_task1.md b/logs/phase3_log_task1.md
index 4cbd4f2..cbe1957 100644
--- a/logs/phase3_log_task1.md
+++ b/logs/phase3_log_task1.md
@@ -39,3 +39,78 @@
 ### 顺手核实到的现状（未处理，留待办）
 - 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 反馈（已实现）。