whole process

fish_api/README.md

@@ -25,7 +25,7 @@ FastAPI 网关：分块接收 **SVO2**（FishMeasure）与 **MP4**（FishAction
 | `MEDIA_ROOT` | 对外托管每次测量生成的 `*_left.mp4` / `*_right.mp4` | `<repo>/fish_api/.data/media` |
 | `FISH_MEASURE_ROOT` | `FishMeasure` 根目录 | 自动相对仓库 |
 | `FISH_ACTION_ROOT` | `FishAction` 根目录 | 自动相对仓库 |
-| `MEASURE_OUTPUT_ROOT` | 传给 `--save-output` 的目录 | `FishMeasure/output_weight_estimator` |
+| `MEASURE_OUTPUT_ROOT` | 传给 `--save-output` 的目录 | `<repo>/fish_api/.data/measure_output` |
 | `YOLO_MODEL` / `WEIGHT_CHECKPOINT` / `ACTION_CHECKPOINT` | 模型路径 | 与仓库内脚本默认一致 |
 | `SAM_DEVICE` | `cuda` 或 `cpu` | `cuda` |
 可在 `fish_api/.env` 中填写上述变量（`pydantic-settings` 会读取）。
@@ -37,7 +37,8 @@ cd fish_api
 uv sync
 # 可选：包含 httpx，便于本地用 FastAPI TestClient 做冒烟测试
 # uv sync --group dev
-bash start_fresh.sh    # 清空 SQLite / 缓存后启动；保留缓存用 start_no_fresh.sh
+bash start_fresh.sh    # 默认仅重置 client_id 投递进度，保留 SQLite 历史与快照
+# CLEAR_SQLITE_DATABASE=1 bash start_fresh.sh  # 需要时才彻底清 SQLite
 # 或：uv run uvicorn app.main:app --host 0.0.0.0 --port 8000（需自行 prestart）
 ```
 
@@ -85,6 +86,17 @@ MP4 将 `svo` 换成 `mp4`，本地文件换成 `clip.mp4`，轮询 `GET /api/v1
 
 FishMeasure 跑完后在输出目录查找 `*preview*.mp4`，复制到 `MEDIA_ROOT/`，文件名为 `{UTC时间戳}_{svo_stem}_left.mp4` / `_right.mp4`（每次测量不覆盖；仅一个预览文件时可能左右 URL 指向同一逻辑源经 SBS 拆分）。确保 `PUBLIC_BASE_URL` 与前端/文档中的域名端口一致。
 
+## Weight Rule (Current)
+
+最终体重 `pred_weight_g` 由以下规则链决定（按优先级从高到低）：
+
+1. **440g 全池均值保护**（规则 B）：若 `avg_g_filtered`（所有 candidates 均值）> `--mean-pool-fallback-max-if-over-g`（默认 440g），则 `pred_weight_g = max_predicted_weight_g_after_filter`，`pred_weight_rule = "max_after_filter_high_mean_pool_over_g"`。
+2. **400g mean-all fallback**（规则 A，仅 `--average-all-after-filter` 开启时）：若全池 mean > `--average-all-fallback-max-if-mean-over-g`（默认 400g），则 `pred_weight_g = max_predicted_weight_g_after_filter`，`pred_weight_rule = "max_after_filter_high_mean_all"`。
+3. **`--average-all-after-filter`**（默认关）：全部 candidates 均值作为最终值，`pred_weight_rule = "mean_all_filtered"`。
+4. **Top-K 聚合**（默认路径）：按 `--top-by-length`（默认开）选 top-K 帧，candidates < 5 用 max 否则用 mean，`pred_weight_rule = "top_k_aggregate"`。
+
+DGCNN 明细中同时输出 `mean_all_pred_g_after_filters`、`avg_topk_mean_pred_g` 等供对比参考。
+
 ## 演进建议
 
 - RTSP：用 `ffmpeg` 切段写入 MP4 后调用现有 `finalize` 逻辑