1

server/README.md

@@ -16,8 +16,8 @@
 | 版本管理 | 后台管理端上传 Android APK + 更新说明，APK 存服务器 `app.apkDir`（默认 `./workspace/`，与 `./data` 平级、挂载持久化）**固定文件名 `observer-latest.apk`，上传即覆盖，目录永远只保留最新一个文件**；**版本号从文件名识别**：文件须命名为 `observer-x.y.z.apk`（Flutter 打包产物即此命名，版本号取自 pubspec）；客户端启动时 `GET /api/v1/app/update` 检查更新：服务器版本高于本地版本即弹更新提示（不可跳过）。**仅 Android 检查，iOS 不做版本下发**（iOS 走 App Store 自行更新）。版本记录可删除：删最新版本联动删除 APK 文件，删历史版本仅删记录 |
 | 数据训练（唯一入口） | 后台管理端「数据训练」一个菜单承载数据集全流程：**数据集卡片列表**（封面图/描述/图片数/已标注数/**训练状态徽标**），**卡片下方直接展示训练任务进度条与状态**（无独立训练页）；详情页为**图片与标注一体视图**：分页（每页 20 条）逐行「原图 ‖ 标注图」对照展示；**图片入库（手动上传/AI 生成）自动触发 RF-DETR 全图扫描标注**，进度条展示在页顶；页顶另有「全量标注」按钮可手动重标全部图片（覆盖各图已有标注）；点击原图/标注图弹窗放大，弹窗内 canvas 直接画框/点框删除/清空并保存——AI 自动标注结果直接作为标注，人工可修改/清理全部框；封面（上传自动转 jpg + UUID 命名）/**描述**/AI 生成图片（provider 抽象，默认 qwen-image/DashScope 付费 API）；AI 标注端点与训练机 SSH 为**全局配置，直接读 `config.yml`**（`localAi` / `training.ssh` 节点，改配置需重启服务）；图片落服务器 `app.datasetDir`/`datasets/<数据集名>/`，DB 存元数据 + 标注 JSON |
 | 模型训练 | 从数据集卡片「开始训练」一键触发（参数 imgsz/epochs/batch/device 默认走 `config.yml` `training` 节点，部署级配置）：进度/日志/指标监控（每 epoch 粒度）、取消；训练通道 `training` 节点可配置 subprocess（与 Go 服务同机直接起 python）/ ssh（异机执行，SSH 凭据取 `config.yml` `training.ssh` 节点），并发度 1（GPU 独占）；训练脚本 `server/training/train_server.py`（随项目迁移，2026-08-26）参数化，产物（best.tflite/best.pt/曲线）拉回服务器；训练收尾自动做 **tflite 产物自检**（输入/输出 shape 校验，原 `inspect_tflite.py` 逻辑内嵌脚本），自检失败任务置失败并带出原因；`dump_graph.py` 留作训练机人工深度调试 |
-| 模型版本与热更新 | **每数据集一个模型**：训练完成后一键「发布」（训练任务操作列）——tflite 落 `workspace/models/<数据集>/latest.tflite` + sha256/指标/类别名入 `model_version`（按数据集独立版本序列 m1.0.0 递增）。管理端**无模型管理界面**（版本记录仅支撑客户端下发）。**App 模型热更新**：`GET /api/v1/app/update` 扩展返回 `models` 目录数组，客户端独立检查，新模型下载校验替换，失败回退旧模型——模型迭代不再重打包 APK |
-| 模型目录与多模型推理 | `GET /api/v1/models`（登录态）返回全部数据集当前生效模型（数据集/版本/类别/大小/sha256/下载地址），下载 URL `/download/models/<数据集>/latest.tflite`；**App 模型管理页**用户自由下载/删除/启用模型，识别时**加载全部已启用模型并行推理 + 跨模型 NMS 合并**（按类别名），内置 assets 模型兜底 |
+| 模型版本与热更新 | **每数据集一个模型**：训练完成后一键「发布」（训练任务操作列）——tflite 落 `workspace/trainings/<数据集名>.tflite` + sha256/指标/类别名入 `model_version`（按数据集独立版本序列 m1.0.0 递增）。管理端**无模型管理界面**（版本记录仅支撑客户端下发）。**App 模型热更新**：`GET /api/v1/app/update` 扩展返回 `models` 目录数组，客户端独立检查，新模型下载校验替换，失败回退旧模型——模型迭代不再重打包 APK |
+| 模型目录与多模型推理 | `GET /api/v1/models`（登录态）返回全部数据集当前生效模型（数据集/版本/类别/大小/sha256/下载地址），下载 URL `/download/trainings/<数据集名>.tflite`；**App 模型管理页**用户自由下载/删除/启用模型，识别时**加载全部已启用模型并行推理 + 跨模型 NMS 合并**（按类别名），内置 assets 模型兜底 |
 | 标注 | **图片入库自动触发**：手动上传/AI 生成成功后，新增图自动调 `config.yml` `localAi` 节点配置的 AI 端点做 RF-DETR 全图扫描（`label_task` 记录进度，页顶进度条展示；**localAi 未配置 → 上传/生成接口直接报错；已有标注任务在跑（忙）→ 不报错**，当前任务成功完成后自动补标未标注图）→ 扫描结果（**重叠去重**：NMS 风格按置信度降序保留，重叠比 > `localAi.overlapThreshold` 默认 0.3 的框剔除——重叠比 = 交叠面积/两框较小面积，RF-DETR 同目标常输出一大一小两框，此判据能命中，同目标只留置信度最高者）**直接写 `dataset_image.labels_json`**（覆盖该图已有标注，即重标语义）；点击弹窗放大后在 canvas 上画框/点框删除/清空/改类别 → 保存即整体覆写 `dataset_image.labels_json`（YOLO 归一化 JSON 数组，AI 与人工框同存，人工可修改/清理）；`POST /admin/label-tasks` 详情页「全量标注」按钮入口（另有自动触发），可发起全量/指定图重标；自动/手动/混合并存，训练前自动整理（prepare_yolo 逻辑在服务端） |
 
 ## 架构与数据流
@@ -51,7 +51,7 @@ Flutter App ── POST /auth/register|login ─► 账号注册/登录，签发
 | `dataset` | 训练数据集 | `id`(PK)、`name`(UNIQUE)、`source`(manual/ai)、`image_count`、`labeled_count`、`status`(building/synced/labeled)、`cover`(封面文件名，UUID 命名 jpg，如 `9f2a...-xx.jpg`)、`description`、`created_at`、`updated_at`（图片文件在 `app.datasetDir`/`datasets/<name>/`，DB 只存元数据；AI 标注/训练机 SSH 配置走 `config.yml` 的 `localAi` / `training.ssh` 节点） |
 | `dataset_image` | 数据集图片 | `id`(PK)、`dataset_id`、`filename`、`source`(manual/ai)、`prompt`(AI 生成图记录提示词)、`labels_json`(标注 JSON 数组：YOLO 归一化 xywh+类别+置信度，AI 自动标注与人工标注同存、人工可修改/清理，null/''/'[]'=未标注)、`created_at` |
 | `model_training` | 训练任务 | `id`(PK)、`name`、`status`(running/success/failed)、`dataset`(训练机数据集名)、`imgsz`/`epochs`/`batch`/`device`(参数快照)、`current_epoch`/`total_epochs`、`metrics`(JSON)、`log_tail`、`pid`、`error`、`started_at`/`finished_at`、`created_at` |
-| `model_version` | 模型版本（每数据集独立序列） | `id`(PK)、`dataset_id`、`version`(m1.0.0 递增, 同数据集 UNIQUE)、`training_id`、`artifact_file`(workspace 相对路径)、`metrics`(JSON)、`labels`(JSON 类别名数组)、`sha256`、`size_bytes`、`is_latest`、`notes`、`created_at`（模型文件不落表：发布即写 `models/<数据集名>/latest.tflite`，客户端固定下载，无存档回退） |
+| `model_version` | 模型版本（每数据集独立序列） | `id`(PK)、`dataset_id`、`version`(m1.0.0 递增, 同数据集 UNIQUE)、`training_id`、`metrics`(JSON)、`labels`(JSON 类别名数组)、`sha256`、`size_bytes`、`is_latest`、`notes`、`created_at`（模型文件不落表：发布即写 `trainings/<数据集名>.tflite`，客户端固定下载，无存档回退） |
 | `label_task` | 标注任务 | `id`(PK)、`dataset_id`、`filenames`(JSON 选中图片列表，NULL=全量)、`status`(running/done)、`total`/`done`、`created_at`、`finished_at` |
 
 建表与迁移见 `技术设计.md`（新库直接建表；存量库以 `PRAGMA user_version` 版本化迁移）。
@@ -160,7 +160,7 @@ App 版本更新检查（公开接口，无需 token，未登录/旧版本均可
 - 检测到新版本（服务器版本高于本地版本）即**强制更新**，客户端弹不可关闭的全屏提示，必须跳转更新后才能继续使用；本地已是新版本则不提示
 - 客户端以「语义化版本号」比较：`1.10.0 > 1.9.9`（按数字段比较，禁止字符串比较）
 - 下载地址为固定静态路径：`/download/observer-latest.apk`（`app.apkDir` 目录下永远只有最新一个文件，由后端静态托管），客户端拼 `apiBaseUrl` 访问
-- **模型热更新（与 APK 更新独立通道）**：服务器有已发布模型时响应额外返回 `models` 数组（与 `GET /api/v1/models` 同构：datasetId/datasetName/version/labels/sizeBytes/sha256/downloadUrl）；客户端启动与 APK 更新**独立检查**——某数据集服务器版本高于本地已下载版本即下载 `/download/models/<数据集>/latest.tflite` 到应用私有目录，sha256 校验后原子替换，下次识别生效；**非强制**，失败回退旧模型下次启动重试。App 模型管理页列出服务器全部可用模型，用户自由下载/删除/启用；识别时加载全部已启用模型**并行推理 + 跨模型 NMS 合并**（按类别名），内置 assets 模型兜底。无发布模型时不返回 models 字段（旧 App 忽略新字段、新 App 兼容旧服务器）
+- **模型热更新（与 APK 更新独立通道）**：服务器有已发布模型时响应额外返回 `models` 数组（与 `GET /api/v1/models` 同构：datasetId/datasetName/version/labels/sizeBytes/sha256/downloadUrl）；客户端启动与 APK 更新**独立检查**——某数据集服务器版本高于本地已下载版本即下载 `/download/trainings/<数据集名>.tflite` 到应用私有目录，sha256 校验后原子替换，下次识别生效；**非强制**，失败回退旧模型下次启动重试。App 模型管理页列出服务器全部可用模型，用户自由下载/删除/启用；识别时加载全部已启用模型**并行推理 + 跨模型 NMS 合并**（按类别名），内置 assets 模型兜底。无发布模型时不返回 models 字段（旧 App 忽略新字段、新 App 兼容旧服务器）
 
 ### GET /download-page