tps-dashboard/logs/phase3_log_task1.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 反馈（已实现）。