silk/AGENTS.md

# AGENTS

## 沟通规则

1. 先说明结论，再说明影响和后续操作。
2. 除非项目约定另有要求，否则使用用户偏好的语言。
3. 交付说明应聚焦于修改的文件、验证结果和风险。
4. 对不清楚的需求或不可逆选择，执行前先向用户确认。
5. 创建或重写本指令文件前，询问用户该文件应使用哪种语言。
6. 每完成一项交付（功能/模块/部署），必须更新根目录 `开发交接记录.md`，追加「做了什么、设计思路与决策依据、验证结果、回滚点」，保证同事阅读后能快速接手；不得只做口头总结。

## 项目结构

本仓库是「智慧蚕房环境监测与智能调控系统」多模块 monorepo，各目录职责边界如下：

1. `server-go/` — Go 后端（Go 1.23，Gin + GORM），入口为 `cmd/server/main.go`；提供 REST API（默认 :3000）、WebSocket `/ws`、视频代理 `/live/proxy`；消费 MQTT 遥测并处理阈值告警、设备控制、RBAC；依赖 PostgreSQL、IoTDB、Valkey/Redis、Ceph S3、WVP/ZLM、recorder-go。
2. `web/` — Web 后台前端（Vite + React + TypeScript + Ant Design），开发端口 5173，`/api` 代理到后端 :3000。
3. `app/` — React Native 移动端（RN 0.74），后端地址通过 `.env` 配置（参考 `.env.example` 的 `API_BASE_URL`）。
4. `miniapp/` — 微信小程序（Taro 4 + React + TypeScript + Sass）；`project.config.json` 的 `miniprogramRoot` 指向 `dist/`，该目录是 Taro 构建产物，不得手改。
5. `wvp/` — WVP-PRO + ZLMediaKit 视频平台（`docker-compose.yml` 包含 WVP、ZLMediaKit、MySQL、Redis），并含 `recorder-go`（Go 连续录制服务，默认 :9090）与 Dockerfile。
6. 根目录文档 — `README.md`、`部署指南(物理机).md`、`变更记录.md`、`故障排查处理记录.md`、`物联网设备接口和数据格式.md`、`后续工作计划.md`（规格书 V2.1 的工作清单与技术选型决策）等为项目说明、规划与部署运维依据。
7. `ai-service/`（已建骨架，训练挂起期间 mock 模式）— Python FastAPI + ONNX Runtime AI 推理微服务（YOLO 蚕病检测、图像/光谱分析），生产部署于云 GPU 主机（NVIDIA T4 16G），与 Go 后端通过 HTTP 通信；模型训练在本地 fnOS/P4 物理机完成（当前物理机问题，训练挂起）。技术方向为「现有 Go 底座 + Python AI 微服务」混合架构，生产环境全部上云（业务云主机 + GPU 云主机 + 云对象存储），本地仅用于开发/训练/测试，详细规划见 `后续工作计划.md`。

生成文件及其来源命令：

1. `miniapp/dist/` — 由 `npm run dev:weapp` / `npm run build:weapp` 生成。
2. `web/dist/` — 由 `npm run build` 生成。
3. `app/android/app/build/outputs/apk/release/app-release.apk` — 由 `cd android && gradlew assembleRelease` 生成。
4. `server-go/server-go-linux` — 由 `go build -o server-go-linux ./cmd/server` 交叉编译生成。

## 已完成功能（截至 2026-08-17）

按《后续工作计划》推进（YOLO 训练相关 #1-4 因物理机问题挂起）。详细设计、验证与回滚点见根目录 `变更记录.md`、`开发交接记录.md` 及服务器 `/home/pan/backups/rollback-20260812/README.md`。

### 阶段一：AI 巡检闭环（#5-#11）

- `ai-service`：FastAPI + ONNX Runtime 骨架——`GET /health`、`POST /detect`（返回框/类别/置信度）；默认 `MODEL_MODE=mock`，`ONNXDetector` 已实现 YOLOv8 后处理，训练恢复后放 `models/best.onnx` 即切真实推理（接口不变）。
- Go 对接（#6）：`inspection_records` 表；`POST/GET /api/v1/inspections`（图片→S3 `silk-images/inspections/`→AI→记录；`Idempotency-Key` 幂等）；权限 `inspection:create/read`；配置 `AI_SERVICE_BASE`。
- 蚕匾/批次/饲养记录（#7）：`trays`/`batches`/`rearing_records` 三表 + CRUD；Web「批次管理」页（批次+蚕匾+饲养记录）；小程序蚕房详情展示蚕匾与当前批次。
- 拍照巡检（#8）：小程序「拍照巡检」页——拍照→上传→AI 结果（类别/置信度/风险提示）→巡检历史。
- 风险评分引擎（#9）：`ComputeRiskScore`（0.5/0.2/0.15/0.15 权重）+ 分级（绿 0-30/黄 31-60/橙 61-80/红 81-100）+ 阶段/环境系数；巡检创建时自动评分落库。
- 知识库（#10）：蚕病百科（9 病种 + 「其它/未知」）、AI 风险分级解读、LAMP/SERS 教程、四季防控提醒、症状图谱图片上传（S3 `silk-images`，公开读）；`knowledge:read/write` 权限；Web「知识库」页 + 小程序知识库（列表/详情/阶段风险提示）。
- 微信订阅消息（#11，骨架）：`wechat_bindings` 表 + `/wechat/binding|bind|subscribe`；巡检风险非绿异步触发；配置 `WECHAT_APPID/SECRET/TEMPLATE_*` 占位（待凭证联调真实推送）。

### 阶段二：环境监测 + LAMP（#12-#17）

- 和风天气与高发病天气预警（#12）：`weather_alerts` 表、`GET /weather/now`、`GET /weather/alerts`、30 分钟定时评估；规则取自规格书 3.2.3（白僵病/核型多角体病/软化病）；配置 `QWEATHER_API_KEY/LOCATION` 占位。
- 饲养阶段风险提示（#13）：`GET /knowledge/stage-hints`（young/grown/late5/pupa）+ 小程序选择器。
- LAMP 检测管理（#14）：`lamp_tests`/`lamp_test_steps`（标准 5 步自动生成）+ 结果照片上传 + 结果录入；Web「分子检测」页 + 小程序录入。
- 交叉验证（#15）：LAMP 结果自动与同房间最近巡检比对（一致→确认诊断，不一致→建议会诊），`cross_status/cross_reason` 落库。
- 耗材管理（#16）：`consumables` 表 + CRUD + 低库存/临期预警 + 采购建议；Web「耗材管理」页。
- 技术员 Web 后台（#17）：「巡检记录」页（列表 + 详情抽屉，含 roomName 联查）；检测任务处理/耗材在 #14/#16 已落地。

### 阶段三：专家诊断 + 多检测 + 溯源（#18-#22）

- 专家会诊（#18）：`consultations` 表 + 病例快照打包（房间/巡检/LAMP/批次/天气）+ 状态机（受理/出方案/归档）+ 专家意见/防控方案；Web「专家会诊」页。
- 分子检测扩展（#19）：检测任务支持 lamp/qpcr/sers/hyperspectral；qPCR Ct 自动判读（`judge-qpcr`，阈值可配）；SERS 光谱上传（S3 `spectrum/`）+ `spectrum_entries` 光谱库；高光谱预留。
- 多检测方式推荐引擎（#20）：`GET /detection-methods/recommend`（设备/紧急/操作者/成本偏好加权）；Web 新建任务弹窗内置推荐工具。
- 疫病溯源（#21）：`trace_records` 三级溯源——一级自动（环境回溯/历史关联/传播推断→初报）、二级分病种排查清单（→分析报告）、三级专家/实验室备注；Web「疫病溯源」页。
- 区域发病统计（#22）：`rooms.region` 字段 + `GET /trace-records/region-stats`（柱状图/饼图表达热力趋势；GeoJSON 地图后续按需接入）。

### 数据分析与运维（#24、#27）

- 蚕房健康画像与年度发病规律（#24）：`GET /health-profiles/:roomId`（健康分+评级）、`GET /trace-records/monthly-stats`；Web 蚕房「健康画像」抽屉 + 年度折线图。
- 测试基建（#27）：Web 引入 Vitest + jsdom（`npm test`），`utils/format.ts` 公共函数与首批单测；Go 各模块已有单测。
- ai-service 扩展（#23 骨架 / #26）：`POST /stream-detect`（OpenCV 拉流抽帧检测骨架）；`GET /metrics`（请求量/延迟/GPU 信息，开发服务器可读到 940MX）。

### 整改 Task 0-14（2026-08-14）

- 已完成安全与正确性整改：AI 风险语义、Mock 隔离、WebSocket 越权、AI 流 SSRF、视频访问与密钥输出、用户级巡检幂等；
- 已完成工程可靠性与业务闭环：版本化迁移、可靠通知/Outbox、统一检测任务/样本/发病事件、生物安全、离线巡检、会诊治理、知识审核、效果评估、可观测性；
- 已完成规格追踪、核心 E2E 用例和发布门禁文档，见 `docs/acceptance/`；
- 整改基线已合并到 `dev_wjs` 并部署开发服务器；开发服务器当前 schema v8，本地新增 v9 尚未部署；
- 开发服务器已验证：Go/Web/AI 健康检查通过，E2E/登录态/负载/恢复演练结果见 `开发交接记录.md`、`变更记录.md` 和 `docs/operations/`。

### 本地 v9 补充（2026-08-15~17）

- 对象授权：`organizations`/`organization_members` + `rooms.org_id`，房间/设备/传感器/阈值/告警/遥测/控制/录像/巡检/检测/会诊/溯源/生物安全按组织隔离，HTTP 越权返回 403，WS 订阅双重校验；
- 运营能力：设备维护、产量损失统计、脱敏案例库、实验室结构化结果，Web「运营能力」页；
- 组织管理：`GET /organizations/:id/members` + Web「组织管理」页，支持组织新增/编辑、成员添加/移除；
- 当前本地 `CurrentSchemaVersion=9`，开发服务器仍为 v8；v9 未提交、未部署。

### 待办与外部依赖

- #23 摄像头流 AI 巡检：拉流抽帧骨架已就绪（`/stream-detect`）；正式巡检任务编排需摄像头视角数据，仍按计划二期。
- #25 时序存储决策：**已定（2026-08-13）——MVP 沿用 IoTDB（现状），TDengine 作为生产规模化候选**（聚合报表/性能瓶颈或上云规划时先基准测试再评估）。
- #26 GPU 监控：`/metrics` 骨架已就绪（nvidia-smi 可选采集）；生产 T4 主机接入时可直接复用。
- 微信订阅真实推送：需小程序 AppID/Secret 与订阅消息模板 ID。
- 和风天气真实数据：需 `QWEATHER_API_KEY` 与位置。
- YOLO 训练（#1-4）：物理机问题修复后恢复（数据集修复→训练→`best.onnx` 接入 ai-service）。

## 编码规则

1. 遵循现有命名、分层、错误处理和格式化约定。
2. 将修改范围限制在用户请求的任务内。
3. 不得覆盖用户无关的已有修改。
4. 不得猜测或编造缺失的需求、事实、约定或技术决策。
5. 根据用户明确输入、仓库文件、配置、文档或命令输出验证相关结论。
6. 如果相关细节不确定、有歧义、存在冲突或无法验证，必须停止并先向用户确认，再继续操作。
7. 不得手改生成产物（如 `miniapp/dist/`、`web/dist/`、编译后的 APK、`server-go-linux`）；需要改动时先修改源文件或源 schema，再重新生成。

## 安装与配置

1. 后端：`cd server-go && go build -o server-go-linux ./cmd/server`；开发运行用 `go run ./cmd/server`。必需环境变量以 README「Go 后端环境变量」为准：`PG`、`REDIS`、`JWT_SECRET`、`JWT_EXPIRES_IN`、`MQTT`、`IOTDB_URL`、`WVP_API_BASE`、`ZLM_API_BASE`、`RECORDER_API_BASE`、`S3_ENDPOINT`、`S3_ACCESS_KEY`、`S3_SECRET_KEY`、`S3_BUCKET`、`PORT`、`DEFAULT_ADMIN_USERNAME`、`DEFAULT_ADMIN_PASSWORD`。
2. Web 前端：`cd web && npm install && npm run dev`；生产构建 `npm run build`。
3. React Native APP：`cd app && npm install`，按 `app/.env.example` 配置 `API_BASE_URL`，然后 `npm start` / `npm run android`。
4. 微信小程序：`cd miniapp && npm install && npm run dev:weapp`；生产构建 `npm run build:weapp`，产物输出到 `dist/`。
5. WVP 视频平台：`cd wvp && docker compose up -d`。
6. 选择未明确指定的技术栈、包管理器、数据库、运行时、部署目标或外部服务前，必须先获得用户确认。
7. 初始化项目时，如果技术栈尚未明确，应先让用户选择技术栈，再创建项目文件。
8. 不得将密钥写入需要提交的文件；需要环境配置时使用占位值创建 `.env.example`。
9. AI 推理服务（规划中）：Python 3.11 + 虚拟环境，PyTorch（cu121/cu124 wheel，兼容 Tesla P4）+ ultralytics；模型训练在本地 fnOS 服务器（i7-8700T / 62G / Tesla P4 8G，数据集路径 `/vol1/ai/datasets`）完成，导出 ONNX 后部署到云 GPU 主机（T4 16G）由 FastAPI 服务加载。

## 部署到开发服务器（dev：100.83.103.1）

环境依据：`部署指南(物理机).md`。SSH 主机 `100.83.103.1`、用户 `pan`，密码不写入提交文件，通过环境变量 `PAN_SSH_PASS` 传入；SSH/SFTP 辅助脚本为 `scripts/devssh.py`（不含任何密钥）。部署范围目前为 Go 后端（:3000）与 Web（:5174），小程序走微信开发者工具发布流程，不属于本服务器部署。

### 部署前置（每次发布必做）

1. 本地验证必须全部通过：后端 `go test ./...`、`go build ./...`、`go vet ./...`；Web `npm run lint`、`npm run build`；涉及小程序时 `npm run build:weapp`。
2. 代码可回滚检查（先于任何覆盖操作）：
   - 检查开发服务器 git 仓库状态：`git status`、`git branch --show-current`、`git log -1 --oneline`，确认服务器代码与发布基线的关系；记录服务器当前 commit。
   - 为服务器当前状态打可回滚标记：`git tag pre-<YYYYMMDD-HHMMSS>`（或把 commit hash 写入部署记录）。
   - 服务器工作区有未提交改动且与发布内容冲突时，不得强制 checkout/reset，先与用户确认。
3. 数据库可回滚检查：本次涉及 schema 变更（新增表/列/索引、数据迁移）时，发布前必须 `pg_dump` 全库备份到 `/home/pan/backups/silk-<YYYYMMDD-HHMMSS>.dump`，并记录恢复命令；纯代码发布可不强制，但每次发布前至少确认存在最近一份可用备份。
4. 运行环境检查：`df -h`（磁盘空间）、`ss -tlnp`（3000/5174/9090/5432 等端口监听）、服务进程存在性；有异常先记录并停止发布。

### 部署步骤

1. Go 后端：本机交叉编译 `GOOS=linux GOARCH=amd64 go build -o silk-server-go-linux ./cmd/server/` → 上传服务器 → 保留旧二进制（如 `silk-server-go-linux.bak-<时间戳>`）→ 按 `start_sh.txt` / 部署指南方式重启（`source .env` 或导齐环境变量）→ `curl http://localhost:3000/api/v1/health` 健康检查 → 检查启动日志无 panic/连接错误。
2. Web：`npm run build` → 上传 `dist` → 备份旧 dist → 重启 `server.cjs` → `curl -s -o /dev/null -w '%{http_code}' http://localhost:5174/` 应为 200。
3. 新接口/新功能冒烟：用登录 token 调用新增 API（如 `/api/v1/knowledge/diseases`）验证返回；检查后端日志无 5xx。
4. 部署后：更新 `变更记录.md`（日期、内容、验证结果、回滚点），并把服务器 commit/备份路径记入部署记录；同时按沟通规则追加 `开发交接记录.md`。

### 回滚预案

1. 代码回滚：服务器 git `git checkout <pre-commit>`，或恢复 `.bak` 二进制/旧 dist，重启服务并做健康检查。
2. 数据库回滚：仅在新 schema 有问题时执行 `pg_restore` 恢复备份；恢复前先再次备份当前状态并确认影响范围。
3. 回滚后更新部署记录与 `变更记录.md`。

### 禁止事项

1. 未完成备份/未记录回滚点前，不得覆盖服务器代码、二进制或数据库。
2. 不得在服务器上直接修改生成产物；需要修复时改源文件后重新构建部署。
3. 服务器密钥/密码不得写入提交文件；一律通过环境变量注入。

## 验证

1. 常规修改的针对性检查：Go 后端 `go build ./...`；Web `npm run lint` 与 `npm run build`；APP `npm run lint` 与 `npm run tsc`；小程序 `npm run build:weapp`。
2. 共享行为修改或发布工作执行更广泛检查：后端 `go test ./...`、`go vet ./...`，前端构建产物可用性检查。
3. 如果检查无法运行（缺少依赖、网络受限等），必须清楚报告确切命令和失败原因。

## 代码审查

1. 审查修改的正确性、回归风险、安全性、可维护性和测试覆盖率。
2. 按严重程度排列审查发现，并尽可能提供文件和行号引用。
3. 具体问题优先于总结；如果没有发现问题，应明确说明。
4. 指出影响发布风险的未验证行为、缺失测试或尚未解决的不确定项。