From 0c67c2d428256f4554227949c8a154d8b3e11157 Mon Sep 17 00:00:00 2001 From: weijuesen Date: Thu, 13 Aug 2026 17:39:09 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=20README=20=E8=AF=B4?= =?UTF-8?q?=E6=98=8E=E6=96=87=E6=A1=A3=E4=B8=8E=E5=90=8E=E7=BB=AD=E5=B7=A5?= =?UTF-8?q?=E4=BD=9C=E8=AE=A1=E5=88=92=E8=BF=9B=E5=BA=A6=E7=8A=B6=E6=80=81?= =?UTF-8?q?=EF=BC=882026-08-13=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 94 ++++++++++++++++++++++++++++++++++++++++++++++--- 变更记录.md | 5 +++ 后续工作计划.md | 54 ++++++++++++++-------------- 开发交接记录.md | 18 ++++++++++ 4 files changed, 140 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 3651a54..e51fb8d 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,8 @@ 系统提供 **Web 后台**、**React Native 移动端 APP**、**微信小程序** 三端界面，后端统一由 **Go 服务**提供 API。 +> **最新进度**：AI 巡检闭环、知识库、分子检测、专家会诊、疫病溯源、天气预警、健康画像等已完成，详见根目录 `AGENTS.md`「已完成功能（截至 2026-08-13）」与 `开发交接记录.md`。 + ## 1. 核心能力 ### 1.1 环境实时监测 @@ -41,7 +43,7 @@ ### 1.5 RBAC 权限管理 - 4 个角色：`admin`（管理员）、`operator`（操作员）、`viewer`（查看者）、`farmer`（养殖员） -- 15 个权限码：涵盖看板、蚕房、设备、阈值、告警、视频、能耗、日志、用户、审计 +- 36 个权限码：基础看板/蚕房/设备/阈值/告警/视频/能耗/日志/用户/审计，并扩展知识库、巡检、蚕匾批次、分子检测、耗材、会诊、溯源、天气、订阅等 - 后端 `RequirePermission` 中间件校验权限码，admin 自动放行 - 前端路由守卫 + 菜单动态过滤 + `` 按钮级控制 - 新用户注册默认角色为 `viewer` @@ -58,6 +60,62 @@ - 设备能耗数据采集与统计 - 能耗趋势图表展示 +### 1.8 蚕匾 / 批次 / 饲养记录（计划 #7） + +- 蚕匾（`trays`）、蚕种批次（`batches`，含品种/蚕种来源/批次号/检疫证明/龄期/入房/上蔟）、饲养记录（`rearing_records`）三表 + CRUD +- Web「批次管理」页（批次 + 蚕匾 + 饲养记录）；小程序蚕房详情展示蚕匾与当前批次 + +### 1.9 AI 拍照巡检闭环（计划 #5/#6/#8/#9） + +- `ai-service/`：FastAPI + ONNX Runtime（默认 mock 模式；`POST /detect` 返回框/类别/置信度，`POST /stream-detect` 拉流抽帧骨架，`GET /metrics` 监控指标） +- 拍照上传 → AI 检测 → 风险评分（0-100 分，绿/黄/橙/红四级）→ 巡检记录（`inspection_records`，`Idempotency-Key` 幂等） +- 小程序「拍照巡检」页；Web「巡检记录」页（技术员复查） + +### 1.10 知识库与阶段风险提示（计划 #10/#13） + +- 蚕病百科（9 病种 + 「其它/未知」）、AI 风险分级解读、LAMP/SERS 教程、四季防控提醒 +- 症状图谱图片上传（S3 `silk-images`）；饲养阶段风险提示（`/knowledge/stage-hints`） +- Web「知识库」页 + 小程序知识库（列表/详情/阶段选择） + +### 1.11 分子检测与交叉验证（计划 #14/#15/#19/#20） + +- LAMP 检测任务单 + 标准 5 步流程 + 结果照片 + 结果录入 +- qPCR Ct 值自动判读（阈值可配）；SERS 光谱数据上传与光谱库；高光谱方式预留 +- 交叉验证：AI 结果 vs 检测结果（一致→确认诊断；不一致→建议专家会诊） +- 多检测方式推荐引擎（设备条件/紧急程度/操作者水平/成本偏好） +- Web「分子检测」页 + 小程序 LAMP 录入 + +### 1.12 专家会诊（计划 #18） + +- 会诊单 + 病例快照（照片/AI/检测/环境/批次/天气）+ 状态机（受理/出方案/归档）+ 专家意见与防控方案 +- Web「专家会诊」页 + +### 1.13 疫病溯源与区域统计（计划 #21/#22） + +- 三级溯源：一级自动（环境回溯/历史关联/传播推断→初报）、二级分病种排查清单（→分析报告）、三级专家/实验室记录 +- 区域发病统计（按蚕房区域聚合，柱状图/饼图）与年度发病规律 +- Web「疫病溯源」页 + +### 1.14 耗材管理（计划 #16） + +- 耗材库存、低库存/临期预警、采购建议（补足安全阈值） +- Web「耗材管理」页 + +### 1.15 天气与高发病预警（计划 #12） + +- 和风天气接入（实时 + 3 天预报）；按规格书 3.2.3 规则评估白僵病/核型多角体病/软化病风险 +- 定时（30 分钟）评估写入 `weather_alerts`；Web 告警中心与小程序告警页展示 + +### 1.16 蚕房健康画像与年度发病规律（计划 #24） + +- 单蚕房健康分（0-100）与评级（优/良/中/差）：聚合巡检风险、检测结果、会诊/溯源事件 +- Web 蚕房「健康画像」抽屉 + 年度发病折线图 + +### 1.17 微信订阅消息（计划 #11，骨架） + +- 用户 openid 绑定与订阅授权（`/wechat/bind|subscribe`）；巡检风险非绿异步触发 +- 真实推送需配置 `WECHAT_APPID/SECRET/TEMPLATE_*` 并申请订阅消息模板 + ## 2. 技术架构 ```text @@ -70,6 +128,8 @@ ┌────────────────┐ ┌──────────────────┐ ┌──────────────┐ │ Go 后端 :3000 │ │ recorder-go :9090 │ │ WVP :18080 │ │ (Gin + GORM) │ │ (连续录制服务) │ │ ZLM :8081 │ + │ ai-service:8000 │ │ │ │ │ + │ (FastAPI+ONNX) │ │ │ │ │ └───┬────┬───┬───┘ └────────┬─────────┘ └──────┬───────┘ │ │ │ │ │ ┌───────┘ │ └──────┐ │ │ @@ -91,14 +151,15 @@ | 层级 | 技术 | |---|---| -| Go 后端 | Go 1.22+、Gin、GORM、JWT、slog、WebSocket | +| Go 后端 | Go 1.23、Gin、GORM、JWT、slog、WebSocket | | 录制服务 | Go、AWS SDK v2（S3）、HTTP 拉流 | -| Web 前端 | React 18、Vite、Ant Design、Ant Design Pro、Axios、ECharts | +| Web 前端 | React 18、Vite、Ant Design、Ant Design Pro、Axios、ECharts、Vitest | | 移动端 APP | React Native 0.74、React Navigation、React Native Paper、Zustand | | 微信小程序 | Taro 4、React、TypeScript、SCSS | -| 业务数据库 | PostgreSQL 16 | +| 业务数据库 | PostgreSQL（开发服务器为 14） | | 时序数据库 | Apache IoTDB 2.0.8（REST API） | -| 缓存/通知 | Valkey（Redis 兼容） | +| AI 推理服务 | Python 3.10+、FastAPI、ONNX Runtime、OpenCV（`ai-service/`） | +| 缓存/通知 | Redis / Valkey（Redis 兼容） | | 设备通信 | VerneMQ（MQTT 3.1.1） | | 视频流媒体 | WVP-PRO 2.7.4、ZLMediaKit（GB28181） | | 对象存储 | Ceph RGW（S3 兼容） | @@ -156,6 +217,10 @@ silk/ │ │ ├─ components/ # StatCard、MiniChart │ │ └─ app.config.ts # 小程序配置（页面、TabBar） │ └─ package.json +├─ ai-service/ # Python AI 推理服务（FastAPI + ONNX Runtime，端口 8000） +│ ├─ app/ # main.py（/health、/detect、/stream-detect、/metrics） +│ ├─ tests/ # pytest 用例 +│ └─ requirements.txt ├─ tools/ │ ├─ simulator/ # MQTT 设备模拟器 │ └─ iotdb/ # 本地 Apache IoTDB 部署 @@ -188,6 +253,17 @@ silk/ | Permission | `handler/permission.go` | 权限码查询、角色权限查询 | | Audit | `handler/audit.go` | 审计日志（权限码 `audit:read`） | | Health | `handler/health.go` | PostgreSQL、Redis、IoTDB 健康检查 | +| Knowledge | `handler/knowledge.go` | 知识库（蚕病百科/文章/阶段提示/图片上传） | +| Inspection | `handler/inspection.go` | AI 巡检记录（上传→检测→评分，幂等） | +| TrayBatch | `handler/tray_batch.go` | 蚕匾/批次/饲养记录 CRUD | +| Lamp | `handler/lamp.go` | 分子检测（LAMP/qPCR/SERS）、步骤、光谱库 | +| Weather | `handler/weather.go` | 和风天气与高发病天气预警 | +| Wechat | `handler/wechat.go` | 微信订阅消息绑定与授权 | +| Consultation | `handler/consultation.go` | 专家会诊（病例快照/意见/方案） | +| Trace | `handler/trace.go` | 疫病溯源（三级）、区域/月度发病统计 | +| HealthProfile | `handler/health.go` | 蚕房健康画像（健康分/评级） | +| DetectionMethod | `handler/detection_method.go` | 多检测方式推荐 | +| Consumable | `handler/consumable.go` | 耗材库存、预警与采购建议 | | WebSocket | `ws/gateway.go` | `/ws` 实时通道，广播遥测与告警 | ## 6. 前端页面 @@ -407,6 +483,13 @@ C:\msys64\usr\bin\sshpass.exe -p "pan" C:\msys64\usr\bin\ssh.exe -o StrictHostKe | `S3_ACCESS_KEY` | `silk-app` | S3 Access Key | | `S3_SECRET_KEY` | `Silk-App-Secret-2026!` | S3 Secret Key | | `S3_BUCKET` | `silk-video-events` | S3 Bucket | +| `S3_BUCKET_IMAGES` | `silk-images` | 知识库/巡检/检测图片桶（对象公开读） | +| `AI_SERVICE_BASE` | `http://localhost:8000` | AI 推理服务地址 | +| `WECHAT_APPID` | （空） | 微信小程序 AppID（订阅消息，占位） | +| `WECHAT_SECRET` | （空） | 微信小程序 AppSecret（占位） | +| `WECHAT_TEMPLATE_ALARM` / `WECHAT_TEMPLATE_INSPECTION` | （空） | 订阅消息模板 ID（占位） | +| `QWEATHER_API_KEY` / `QWEATHER_LOCATION` | （空） | 和风天气 Key 与位置（经纬度或 LocationID，占位） | +| `QWEATHER_INTERVAL_MIN` | `30` | 天气预警定时评估间隔（分钟） | | `PORT` | `3000` | 监听端口 | | `DEFAULT_ADMIN_USERNAME` | `admin` | 默认管理员 | | `DEFAULT_ADMIN_PASSWORD` | `silk@123` | 默认密码 | @@ -420,6 +503,7 @@ cd e:\silk\web npm install npm run dev # 开发模式，端口 5173，代理 /api 到 :3000 npm run build # 生产构建 +npm test # Vitest 单元测试 ``` ### 12.2 React Native APP diff --git a/变更记录.md b/变更记录.md index b42d7ec..0852e33 100644 --- a/变更记录.md +++ b/变更记录.md @@ -273,6 +273,11 @@ - 切换触发条件：聚合报表/BI 需求复杂化且团队更熟标准 SQL、单机写入/查询出现瓶颈、生产上云规划；届时先做同数据量基准测试（写入吞吐/查询延迟/成本/许可）再定，并建议「双写灰度 + 数据对账」迁移 - 影响面（若切换）：存量数据迁移、`server-go` 时序读写服务重写、健康画像/天气回溯等查询调整 +### 文档同步（README / 后续工作计划） + +- `README.md`：新增 1.8-1.17 核心能力（蚕匾批次/巡检闭环/知识库/分子检测/会诊/溯源/耗材/天气/健康画像/微信订阅）；权限码 15→36；技术栈补 Go 1.23、FastAPI/ONNX/OpenCV、Vitest；目录结构补 `ai-service/`；后端模块表补 12 个模块；环境变量表补 `S3_BUCKET_IMAGES/AI_SERVICE_BASE/WECHAT_*/QWEATHER_*`；本地开发补 `npm test` +- `后续工作计划.md`：勾选 #5-#24、#27 完成状态，#23/#26 标记骨架完成，#1-4 标注挂起（物理机），顶部加完成状态说明 + ## 2026-07-17 安全与界面优化整改 ### 变更背景 diff --git a/后续工作计划.md b/后续工作计划.md index ede411e..f65e31a 100644 --- a/后续工作计划.md +++ b/后续工作计划.md @@ -1,5 +1,7 @@ # 后续工作计划 +> **完成状态（2026-08-13 更新）**：#5-#24、#27 已完成（详见 `开发交接记录.md`）；#1-4 因物理机问题挂起；#23/#26 骨架完成；微信/天气真实数据待凭证。 + ## 技术选型决策（2026-08-11 确定） **采用混合架构：现有 Go 底座 + Python AI 微服务** @@ -26,45 +28,45 @@ ## 一、前置准备（P0） -- [ ] 1. 修复数据集：按原始图重新划分 train/valid/test（消除 Roboflow 增强副本导致的跨集泄漏）；修正 `data.yaml`（`heathly` → `healthy`、绝对路径）；删除空标签 -- [ ] 2. 远程训练服务器（fnOS / i7-8700T / 62G / Tesla P4 8G）搭建环境：venv + PyTorch（cu121/cu124，兼容 P4）+ ultralytics -- [ ] 3. 数据集上传服务器 `/vol1/ai/datasets` -- [ ] 4. YOLOv8s 二分类基线训练（healthy/sick），产出 `best.pt` / `best.onnx` + 指标报告（mAP、混淆矩阵） +- [ ] 1. 修复数据集：按原始图重新划分 train/valid/test（消除 Roboflow 增强副本导致的跨集泄漏）；修正 `data.yaml`（`heathly` → `healthy`、绝对路径）；删除空标签（**挂起：物理机问题**） +- [ ] 2. 远程训练服务器（fnOS / i7-8700T / 62G / Tesla P4 8G）搭建环境：venv + PyTorch（cu121/cu124，兼容 P4）+ ultralytics（**挂起：物理机问题**） +- [ ] 3. 数据集上传服务器 `/vol1/ai/datasets`（**挂起：物理机问题**） +- [ ] 4. YOLOv8s 二分类基线训练（healthy/sick），产出 `best.pt` / `best.onnx` + 指标报告（mAP、混淆矩阵）（**挂起：物理机问题；ai-service 已预留 `MODEL_MODE=onnx` + `best.onnx` 接入**） ## 二、AI 巡检闭环（规格书阶段一，MVP） -- [ ] 5. 新建 `ai-service/`：FastAPI + ONNX Runtime，`POST /detect` 返回框/类别/置信度，部署在 P4 服务器（systemd 或 Docker + nvidia-container-toolkit） -- [ ] 6. Go 后端对接：AI client + AI 巡检记录表（`InspectionRecord`） -- [ ] 7. 蚕房/蚕匾/批次管理：现有蚕房/设备/传感器扩展蚕匾、批次、饲养记录、消毒记录、蚕种来源 -- [ ] 8. 农户小程序拍照巡检：拍照→上传→风险分级（绿/黄/橙/红）→预警→记录 -- [ ] 9. 风险评分引擎：0–100 分 = 0.5×AI 置信度 + 0.2×环境系数 + 0.15×饲养阶段系数 + 0.15×群体整齐度偏离度 -- [ ] 10. 知识库初始版：4 类蚕病症状图谱与防治指南、AI 结果解读 -- [ ] 11. 推送：保留 WebSocket，新增微信订阅消息（注意订阅次数限制） +- [x] 5. 新建 `ai-service/`（**骨架完成**：FastAPI + ONNX Runtime，`POST /detect`、`GET /health`、`/stream-detect`、`/metrics`；mock 模式运行于开发服务器 :8000；真实模型待训练恢复后 `MODEL_MODE=onnx`） +- [x] 6. Go 后端对接（**完成**：AI client + `inspection_records` + `/api/v1/inspections`，`Idempotency-Key` 幂等） +- [x] 7. 蚕房/蚕匾/批次管理（**完成蚕匾/批次/饲养记录**；消毒记录 P1、蚕种来源全链 P2 未做） +- [x] 8. 农户小程序拍照巡检（**完成**：拍照→上传→AI 结果→风险分级→记录；端侧推理为后续优化） +- [x] 9. 风险评分引擎（**完成**：0.5×AI + 0.2×环境 + 0.15×阶段 + 0.15×整齐度；整齐度暂无数据源恒为 0） +- [x] 10. 知识库初始版（**完成**：4 类核心 + 扩展病种、AI 结果解读、LAMP/SERS 教程、四季提醒、图谱图片上传；图谱素材待三个方向导入） +- [x] 11. 推送（**骨架完成**：WebSocket 保留 + 微信订阅消息绑定/授权/巡检触发；真实推送待 AppID/Secret/模板 ID） ## 三、环境监测 + LAMP 检测（规格书阶段二） -- [ ] 12. 天气数据接入与高发病天气预警规则（白僵病/软化病等触发条件） -- [ ] 13. 饲养阶段风险提示（按龄期提示高发病种） -- [ ] 14. LAMP 检测管理：检测任务单、分步操作引导、拍照判读 + AI 辅助判读、结果录入 -- [ ] 15. 交叉验证：AI 结果 vs 检测结果（一致→确认诊断；不一致→升级专家会诊） -- [ ] 16. 耗材管理：库存、低库存预警、批次效期、采购建议 -- [ ] 17. 技术员 Web 后台：检测任务处理、耗材、巡检复查（扩展现有 web） +- [x] 12. 天气数据接入与高发病天气预警规则（**完成**：和风天气 + `weather_alerts` + 定时评估；真实数据待 `QWEATHER_API_KEY/LOCATION`） +- [x] 13. 饲养阶段风险提示（**完成**：`/knowledge/stage-hints` + 小程序选择器） +- [x] 14. LAMP 检测管理（**完成**：任务单/5 步流程/照片/结果录入；AI 辅助判读待模型） +- [x] 15. 交叉验证（**完成**：一致→确认诊断，不一致→建议会诊） +- [x] 16. 耗材管理（**完成**：库存/低库存/临期预警/采购建议） +- [x] 17. 技术员 Web 后台（**完成**：检测任务/耗材/巡检复查） ## 四、专家诊断 + 多检测方式 + 疫病溯源（规格书阶段三） -- [ ] 18. 专家会诊：病例打包（照片+AI+检测+环境+饲养+历史趋势）、在线会诊、防控方案下发、归档 -- [ ] 19. qPCR/SERS/高光谱接入：Ct 值录入自动判读；SERS 数据回传与光谱库框架；高光谱接口预留 -- [ ] 20. 多检测方式推荐引擎（设备条件/紧急程度/成本/操作者水平） -- [ ] 21. 疫病溯源（V2.1 新增）：`TraceRecord` 数据模型；一级自动溯源（首发位置、72h 环境回溯、历史关联、传播途径推断、区域关联→溯源初报）；二级分病种排查清单与报告；三级专家/实验室记录 -- [ ] 22. 区域发病热力图（乡镇/县级可视化） -- [ ] 23. 摄像头流 AI 巡检：复用 WVP + ZLMediaKit + recorder-go，AI 服务拉流抽帧检测（建议二期，需补摄像头视角数据） +- [x] 18. 专家会诊（**完成**：病例快照/意见/防控方案/归档；在线会诊为表单版，实时音视频未做） +- [x] 19. qPCR/SERS/高光谱接入（**完成**：Ct 自动判读、SERS 光谱 + 光谱库、高光谱预留） +- [x] 20. 多检测方式推荐引擎（**完成**：设备/紧急/操作者/成本偏好加权） +- [x] 21. 疫病溯源（**完成**：三级溯源；区域关联 v1 用同房间历史） +- [x] 22. 区域发病热力图（**完成统计图表版**（柱状/饼图）；GeoJSON 乡镇/县级地图后续按需接入） +- [x] 23. 摄像头流 AI 巡检（**骨架完成**：`/stream-detect` 拉流抽帧检测；正式巡检编排二期，需摄像头视角数据） ## 五、数据分析与运维 -- [ ] 24. 蚕房健康画像、防控效果评估、年度发病规律 +- [x] 24. 蚕房健康画像、防控效果评估、年度发病规律（**健康画像与年度规律完成**；防控效果评估 P2 未做） - [x] 25. 时序存储决策：**MVP 沿用 IoTDB（现状）**；TDengine 作为生产规模化候选，在出现聚合报表/性能瓶颈或上云规划时先做基准测试再定（2026-08-13 决策） -- [ ] 26. AI 服务部署与 GPU 监控（P4 温度/显存） -- [ ] 27. 测试基建：后端 `go test` 骨架、前端 Vitest（建议，可延后） +- [x] 26. AI 服务部署与 GPU 监控（**骨架完成**：`/metrics` 含 nvidia-smi，开发服务器可读到 940MX；生产 T4 接入时复用） +- [x] 27. 测试基建（**完成**：Go 各模块单测 + Web Vitest + `npm test`） ## 依赖关系 diff --git a/开发交接记录.md b/开发交接记录.md index e7d5389..fb9d49b 100644 --- a/开发交接记录.md +++ b/开发交接记录.md @@ -595,6 +595,24 @@ MVP 沿用 IoTDB（现状）；TDengine 作为生产规模化候选（先基准 --- +## 2026-08-13 文档同步：README 与后续工作计划 + +### 做了什么 + +- `README.md`：补充已完成功能的核心能力章节（1.8-1.17）、权限码数量（36）、技术栈（Go 1.23 / FastAPI+ONNX+OpenCV / Vitest）、目录结构（ai-service）、后端模块表（12 个新模块）、环境变量表（S3_BUCKET_IMAGES、AI_SERVICE_BASE、WECHAT_*、QWEATHER_*）、本地开发命令（npm test）。 +- `后续工作计划.md`：按实际完成状态勾选 #5-#24、#27，#23/#26 标为骨架完成，#1-4 标注「挂起：物理机问题」，顶部加完成状态说明。 + +### 思路 + +- 说明文档（README）与进度文档（后续工作计划）长期未随功能迭代更新，本次一次性同步到 2026-08-13 状态； +- 详细设计/验证/回滚仍以 `开发交接记录.md` / `变更记录.md` 为准，README 只做概览。 + +### 相关提交 + +`待提交`（README、后续工作计划、变更记录、开发交接记录）。 + +--- + ## 环境与踩坑备忘（新同事必读） - **VPN**：开发服务器经 NetBird 访问；服务 Running 后需 `netbird up`，登录走 SSO（管理端 `115.191.19.95:6680`）。