1

server/README.md

@@ -14,11 +14,11 @@
 | 套餐 | `config.yml` `plans` 节点配置三档套餐（改价 = 改配置重启），价格**整数分**（1000 / 5600 / 18000） |
 | 后台管理端 | `server_admin/`（Vue3 + Element Plus）管理页面：订单查询、账号/授权管理（手动授权/撤销）、App 版本管理；构建产物由后端 `/admin/` 托管，登录页输入 token 后以 `X-Admin-Token` 头鉴权（`config.yml admin.token`） |
 | 版本管理 | 后台管理端上传 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 抽象：dashscope 通义万相付费 API / localai 训练机 local-ai qwen-image，`config.yml imageGen` 节点切换，见配置说明）；AI 标注端点与训练机 SSH 为**全局配置，直接读 `config.yml`**（`localAi` / `training.ssh` 节点，改配置需重启服务）；图片落服务器 `app.datasetDir`/`datasets/<数据集名>/`，DB 存元数据 + 标注 JSON |
+| 数据训练（唯一入口） | 后台管理端「数据训练」一个菜单承载数据集全流程：**数据集卡片列表**（封面图/描述/图片数/已标注数/**训练状态徽标**），**卡片下方直接展示训练任务进度条与状态**（无独立训练页）；详情页为**图片与标注一体视图**：分页（每页 20 条）逐行「原图 ‖ 标注图」对照展示；**图片入库（手动上传/AI 生成）自动触发 RF-DETR 全图扫描标注**，进度条展示在页顶；页顶另有「全量标注」按钮可手动重标全部图片（覆盖各图已有标注）；点击原图/标注图弹窗放大，弹窗为**审核视图（不做手动画框）**：点击框选中，列表可确认疑似框/删除误检框/清空并保存——AI 自动标注结果直接作为标注，人工仅审核确认；封面（上传自动转 jpg + UUID 命名）/**描述**/AI 生成图片（provider 抽象：dashscope 通义万相付费 API / localai 训练机 local-ai qwen-image，`config.yml imageGen` 节点切换，见配置说明）；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/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 逻辑在服务端） |
+| 标注 | **图片入库自动触发**：手动上传/AI 生成成功后，新增图自动调 `config.yml` `localAi` 节点配置的 AI 端点做 RF-DETR 全图扫描（`label_task` 记录进度，页顶进度条展示；**localAi 未配置 → 上传/生成接口直接报错；已有标注任务在跑（忙）→ 不报错**，当前任务成功完成后自动补标未标注图）→ 扫描结果（**重叠去重**：NMS 风格按置信度降序保留，重叠比 > `localAi.overlapThreshold` 默认 0.3 的框剔除——重叠比 = 交叠面积/两框较小面积，RF-DETR 同目标常输出一大一小两框，此判据能命中，同目标只留置信度最高者）**直接写 `dataset_image.labels_json`**（覆盖该图已有标注，即重标语义）；点击弹窗放大进入**审核视图（不做手动画框）**：点击框选中，列表确认疑似框/删除误检框/清空 → 保存即整体覆写 `dataset_image.labels_json`（YOLO 归一化 JSON 数组，AI 标注直写、人工仅审核确认）；`POST /admin/label-tasks` 详情页「全量标注」按钮入口（另有自动触发），可发起全量/指定图重标；自动/手动/混合并存，训练前自动整理（prepare_yolo 逻辑在服务端） |
 
 ## 架构与数据流
 

server/biz/service/dataset.go

@@ -605,9 +605,11 @@ func (s *datasetService) buildPromptFromTemplate(ctx context.Context, datasetNam
 			species = pool[rand.Intn(len(pool))]
 		}
 	}
-	// 场景/动作按数据集习性取池（鸭水面、雉鸡灌丛……），未配置该数据集回退通用池
+	// 场景/动作/遮挡按数据集习性取池（鸭水面、雉鸡灌丛……），未配置该数据集回退通用池；
+	// 遮挡：身体完全暴露的个体对识别标注训练无意义，每张必带（程度轻~重随机）
 	scene := pickCfgByDataset(ctx, datasetName, "imageGen.sceneByDataset", "imageGen.scenes")
 	action := pickCfgByDataset(ctx, datasetName, "imageGen.actionByDataset", "imageGen.actions")
+	occlusion := pickCfgByDataset(ctx, datasetName, "imageGen.occlusionByDataset", "imageGen.occlusions")
 	light := pickCfg(ctx, "imageGen.lights")
 	// 轮廓色词按物种（白化个体如白雉鸡配浅色，默认深色剪影）
 	tone := g.Cfg().MustGet(ctx, "imageGen.speciesTone."+species, "深色").String()
@@ -623,8 +625,8 @@ func (s *datasetService) buildPromptFromTemplate(ctx context.Context, datasetNam
 	out := tpl
 	for k, v := range map[string]string{
 		"{scene}": scene, "{species}": species, "{count}": countWord,
-		"{action}": action, "{light}": light, "{distanceWord}": distWord, "{sizeHint}": sizeHint,
+		"{action}": action, "{occlusion}": occlusion, "{light}": light,
-		"{tone}": tone,
+		"{distanceWord}": distWord, "{sizeHint}": sizeHint, "{tone}": tone,
 	} {
 		out = strings.ReplaceAll(out, k, v)
 	}

server/config.yml

@@ -44,7 +44,7 @@ imageGen:
   # 物种只写名字不写羽毛细节（细节会把镜头拉近，详见技术设计）。不带拍摄角度描述（2026-08-28）：
   # 角度描述会与目标位置耦合，仰拍使贴地目标沉底、固定俯拍构图单一——交由模型平视先验自由构图，
   # 目标自然落在中部/上部
-  promptTemplate: "野外大远景实拍：广角镜头下{scene}，{distanceWord}有且仅有{count}{species}的小小身影{sizeHint}在{action}，{species}离镜头很远，只是很小的{tone}轮廓，隐约可辨，画面绝大部分是{scene}，没有任何靠近镜头的动物，{light}，写实野外摄影，真实照片质感"
+  promptTemplate: "野外大远景实拍：广角镜头下{scene}，{distanceWord}有且仅有{count}{species}的小小身影{sizeHint}在{action}，{occlusion}，{species}离镜头很远，只是很小的{tone}轮廓，隐约可辨，画面绝大部分是{scene}，没有任何靠近镜头的动物，{light}，写实野外摄影，真实照片质感"
   speciesByDataset:            # 数据集名 → 物种池（表单未填动物名称时随机取一个）
     鸽子: [家鸽,火斑鸠,虎纹斑鸠,珠颈斑鸠,灰斑鸠]
     雉鸡: [雉鸡,白雉鸡]
@@ -91,6 +91,36 @@ imageGen:
     兔子: [低头啃食草叶, 警觉地竖起耳朵, 小步跳跃前行, 蹲坐不动, 啃食草叶]
     鸭子: [缓缓游动于水面, 低头潜入水中觅食, 水面梳理羽毛, 缓慢划水前行, 岸边泥滩觅食]
     鹌鹑: [低头啄食, 草丛间觅食, 小步疾走, 停歇不动]
+  # 遮挡描述池（模板 {occlusion} 占位，插在「在{action}」之后）：身体完全暴露的个体对识别/标注训练
+  # 无意义，每张必取一条（全池覆盖轻~重遮挡，程度随机）；遮挡物多样（杂草/树叶/枝条等），须与场景自洽
+  occlusions:                # 通用遮挡池（未配置 occlusionByDataset 的数据集回退此池）
+    - "身体部分被前景的杂草遮挡"
+    - "大半个身体隐入草丛，只露出头背"
+    - "身体被身前的杂草枝条半遮半掩"
+    - "只有头背部从茂密草丛中露出"
+    - "身体部分被低垂的树叶和枝条遮挡"
+    - "大半个身体隐在枝叶间，只露出头背"
+  occlusionByDataset:        # 数据集名 → 遮挡池（按动物习性与场景配置；未配置回退通用 occlusions）
+    雉鸡:
+      - "身体部分被前方的草丛和矮灌丛遮挡"
+      - "大半个身子隐入灌丛枝叶间，只露出头颈"
+      - "身体被身前的枯草丛半遮半掩"
+      - "只有头背部从密草丛中露出"
+      - "身体藏在树影下，被垂落的树叶半遮"
+    兔子:
+      - "身体部分被荒草遮挡，只露出头部"
+      - "大半身体隐入草丛，一对长耳竖在草尖上方"
+      - "身体被身前的枯黄野草半掩"
+      - "身体部分被林缘的树叶和枝条遮挡"
+    鸭子:
+      - "身体部分隐入岸边芦苇丛中"
+      - "半身没入水面，只露出头背"
+      - "身体被岸边的芦苇和杂草半遮"
+      - "身体部分隐入岸边垂落的枝叶间"
+    鹌鹑:
+      - "身体隐在密草丛中，只露出头部"
+      - "大半身体藏进草丛，隐约只见头和背部"
+      - "身体藏在草叶和落叶之间，只露出头部"
   # 目标尺寸提示（sizeHint）：按「体高 × focalPx ÷ 表单距离」算出目标在图中的像素高与占比，
   # 注入模板 {sizeHint}——把「厘米」换算成「米」再参与投影公式；focalPx = 图高/2 ÷ tan(vfov/2)
   assumedVfovDeg: 52          # 镜头垂直视场角(度)，固定为手机默认主摄（2026-08-28 用户定案；