v6ole/silk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 同步 README 说明文档与后续工作计划进度状态（2026-08-13）

Browse Source
This commit is contained in:
weijuesen
2026-08-13 17:39:09 +08:00
parent c55e954368
commit 0c67c2d428
4 changed files with 140 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+89 -5
View File
@@ -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 自动放行
- 前端路由守卫 + 菜单动态过滤 + `<HasPermission>` 按钮级控制
- 新用户注册默认角色为 `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
变更记录.md
+5
View File
@@ -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 安全与界面优化整改
### 变更背景
后续工作计划.md
+28 -26
View File
@@ -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`）
## 依赖关系
开发交接记录.md
+18
View File
@@ -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`）。