更新数据导入脚本、前端仪表盘和测试指南

- import_hk_songs.py: 优化数据导入逻辑（+157行）
- serve_l2_dashboard.py: 增强仪表盘服务功能（+231行）
- l2_review_dashboard.html: 前端页面微调
- 测试流程指南.md: 补充测试文档

@@ -947,6 +947,7 @@
       const params = new URLSearchParams({
       const params = new URLSearchParams({
         path: dataPath(),
         path: dataPath(),
         top_k: state.topK,
         top_k: state.topK,
+        mode: state.mode,
         q: els.searchInput.value.trim(),
         q: els.searchInput.value.trim(),
         page: String(state.page),
         page: String(state.page),
         page_size: String(state.pageSize)
         page_size: String(state.pageSize)

@@ -2,6 +2,108 @@
 
 
 本文档说明如何运行 L2 歌词召回测试、查看测试产物，并启动前端页面做人工复核。
 本文档说明如何运行 L2 歌词召回测试、查看测试产物，并启动前端页面做人工复核。
 
 
+## 0. 当前导入流程 2000 条 smoke 测试
+
+先确认 `.env` 中有：
+
+```text
+TARGET_TABLE_NAME_TMP=hk_songs_import_staging
+```
+
+第一次跑前，在目标库执行暂存表建表 SQL：
+
+```bash
+create_hk_songs_import_staging.sql
+```
+
+目标库已清空时，先跑第一阶段导入。这个阶段会边去重边导入：
+
+- 判定为 `new` 的记录会按批次写入目标库。
+- 判定为 `merge` 的记录不会插入新行，会写入暂存表和审核/记录清单。
+- 判定为 `review` 的记录不会插入目标库，会进入暂存表等待业务人工审核。
+- 所有 `new / merge / review` 结果都会写入 `TARGET_TABLE_NAME_TMP`。
+- 输出 `output/reports/review_decisions_*.csv`，供复核页面展示 `new / merge / review` 全量结果。
+
+### 0.1 第一阶段：跑 2000 条导入 smoke
+
+```bash
+uv run python import_hk_songs.py \
+  --limit 2000 \
+  --offset 0 \
+  --batch-size 500 \
+  --workers 8 \
+  --load-existing-lyrics \
+  --l2-recall topk \
+  --l2-recall-top-k 20
+```
+
+如果想先不上传 OSS、只验证数据库写入和去重流程，可以加：
+
+```bash
+  --skip-oss
+```
+
+### 0.2 启动人工审核页面
+
+```bash
+uv run python serve_l2_dashboard.py --host 127.0.0.1 --port 8765
+```
+
+打开：
+
+```text
+http://127.0.0.1:8765
+```
+
+页面会自动扫描 `output/reports/review_decisions_*.csv`。业务人员在页面里查看：
+
+- 已经入库的 `new` 数据。
+- 判定重复的 `merge` 样本。
+- 需要人工审核的 `review` 样本。
+
+对 `review` 样本，业务人员标注：
+
+- `确认重复`：不入库。
+- `确认不重复`：第二阶段入库。
+- `待确认`：暂不入库。
+
+### 0.3 第二阶段：页面按钮入库审核通过项
+
+业务人员完成所有 `review` 样本审核后，在页面点击：
+
+```text
+入库审核通过
+```
+
+服务端会自动生成：
+
+```text
+output/reports/review_import_approved_YYYYMMDD_HHMMSS.csv
+```
+
+并自动执行第二阶段导入：
+
+```bash
+uv run python import_hk_songs.py \
+  --review-result-csv output/reports/review_import_approved_YYYYMMDD_HHMMSS.csv \
+  --load-existing-lyrics
+```
+
+如果需要手动执行第二阶段，也可以使用上面的命令，把文件名替换成页面生成的实际 CSV。
+
+### 0.4 smoke 后检查
+
+第一阶段完成后，重点看日志里的：
+
+```text
+插入: <new 入库数量>
+L2合并命中=<merge 数量>
+L2待审=<review 数量>
+人工审核清单: output/reports/review_decisions_*.csv
+```
+
+第二阶段完成后，确认日志里的 `插入` 数量等于本次人工审核确认入库数量。
+
 ## 1. 运行 L2 测试脚本
 ## 1. 运行 L2 测试脚本
 
 
 在项目根目录执行：
 在项目根目录执行：