silk/开发交接记录.md

# 开发交接记录

> **用途**：按 AGENTS.md 沟通规则，每完成一项交付（功能/模块/部署）后在此追加「做了什么、设计思路与决策依据、验证结果、回滚点」，供同事快速了解项目进展并接手。
> **阅读顺序**：时间倒序（最新在上）；先看「当前状态与剩余事项」了解全局，再按需阅读各模块明细。

## 总体背景

- 项目：智慧蚕房环境监测与智能调控系统（monorepo：`server-go` / `web` / `miniapp` / `wvp`）。
- 《后续工作计划》（2026-08-11 更新）确定混合架构：现有 Go 底座 + Python AI 微服务（`ai-service/`，规划中）；生产环境全部上云，本地仅开发/训练/测试。
- **YOLO 训练相关（计划 #1-4：数据集修复、训练环境、上传、基线训练）因物理机问题挂起**，当前按用户要求优先做「独立性强、见效快」的模块。
- 开发服务器：`100.83.103.1`（Ubuntu 22.04，用户 `pan`），通过 NetBird VPN 访问；部署规则见 AGENTS.md「部署到开发服务器」章节。

---

## 2026-08-12 模块：知识库初始版（计划 #10）

### 做了什么

- 后端（server-go）：
  - 新增 `Disease`（蚕病百科）与 `KnowledgeArticle`（知识文章）两张表；
  - 种子数据：9 个蚕病条目（4 类核心病种：核型多角体病、白僵病、软化病、微粒子病 + 5 个扩展病种）+ 1 篇 AI 结果解读，启动时幂等写入；
  - CRUD API：`/api/v1/knowledge/diseases`、`/api/v1/knowledge/articles`（列表支持 category/kind/keyword 过滤）；
  - 权限：新增 `knowledge:read` / `knowledge:write`，admin/operator 可写，viewer/farmer 只读。
- Web：新增「知识库」菜单页（蚕病百科 + AI 结果解读双 Tab，可增删改）。
- 小程序：设置页新增「知识库」入口 → 列表页 → 详情页。

### 思路与决策

- 选择理由：知识库是规格书 P0、完全独立、不依赖 YOLO 训练产物，符合「独立性强、见效快」的推进原则。
- 内容来源：全部取自规格书《蚕病智能防控平台规格说明书》3.6（知识库模块）、3.1.4（风险分级阈值）、附录 11.1（蚕病参考信息）、3.8（处置方向/排查清单），不自行编造。
- 「防治指南」字段是按规格书 3.8 的处置方向（内源扩散/外源侵入措施）与分病种排查清单整理的加工内容，非原文逐字。
- 权限设计沿用现有 RBAC 权限码模式，管理端可编辑、农户端只读。

### 验证

- 种子数据完整性测试（TDD 红→绿）：核心 4 病种齐全、必填字段非空、名称唯一、AI 解读存在；`go test/build/vet` 通过。
- Web `npm run lint && npm run build`、小程序 `npm run build:weapp` 通过。
- 部署后冒烟：登录 admin → `GET /api/v1/knowledge/diseases` 返回 9 条；`articles?kind=ai_guide` 返回 1 条；DB 计数 diseases=9 / articles=1。

### 部署与回滚

- 首次部署 2026-08-12；回滚点：DB dump `/home/pan/backups/silk-20260812-1111.dump`、旧二进制 `server-go-linux.bak`、旧 dist 打包；完整记录在服务器 `/home/pan/backups/rollback-20260812/README.md`。
- 相关提交：`13df3d5`（实施计划）、`50dcd65`（测试 RED）、`8e30234`（种子数据）、`3afc34d`（API/权限/迁移）、`b8af17d`（Web）、`93aa4ee`（小程序）。

---

## 2026-08-12 补充：LAMP 操作教程（规格书 P0）

### 做了什么

- 后端：`lamp_guide` 种子文章（原理、适用场景、设备清单、5 步操作流程、结果判读、各病种检测靶标现状）；
- 小程序：知识库列表增加「LAMP 教程」入口；修复详情页对非 disease 类型（如 lamp_guide）误走病种接口的问题；
- Web 无需改动（文章 Tab 已支持 `lamp_guide` 类型）。

### 思路与决策

- LAMP 教程是规格书 3.6 的 P0 项，且 LAMP 是「目前蚕业领域最务实的分子检测方案」（规格书 3.3.2.1），优先补齐；
- 内容全部取自规格书 3.3.2.1（含操作流程表、设备清单、病种靶标研究现状），无编造；
- 规格书要求「视频+图文」，当前先做图文，视频素材后续补充。

### 验证与回滚

- 新增存在性测试（TDD 红→绿），5 个种子测试全过；`build:weapp` 通过；二次部署后 `ai_guide=1`、`lamp_guide=1`，API 冒烟返回教程内容。
- 相关提交：`0d3124f`（种子数据）、`8bb93ad`（小程序入口 + 类型判断修复）；回滚见服务器 README（旧二进制 `server-go-linux.old-20260812-2`）。

---

## 2026-08-12 补充：症状图谱图片上传（规格书 P0）

### 做了什么

- 后端：`POST /api/v1/knowledge/images`（multipart 字段 `file`，限 jpg/jpeg/png/webp、≤5MB，权限 `knowledge:write`），写入 S3 `silk-images` 桶，对象键 `knowledge/<日期>/<随机>.ext`，返回可公开访问的 URL；
- 配置：新增 `S3_BUCKET_IMAGES`（默认 `silk-images`）；
- Web：病种编辑表单增加「症状图谱图片」上传 + 预览；
- 小程序：病种详情页顶部展示症状图。

### 思路与决策

- 规格书只规定「蚕病百科要有症状图谱」和通用图片存储链路（对象存储 + CDN），没有规定图谱图片来源；采用「通用上传能力 + 后续多来源导入」策略，避免手动塞数据库；
- 素材来源三方向（后续）：YOLO 训练数据集选图、专家/合作单位素材、巡检照片沉淀；
- 存储复用现有 S3 服务（开发 Ceph、生产云 OSS/COS 仅改配置）；
- v1 先做「每病种一张主图」（单 `imageUrl`），多图图谱后续用子表扩展。

### 踩坑记录（重要）

- **Ceph 的 bucket 级 public-read 不覆盖对象读取**，必须给对象本身设置 public-read（`PutObjectInput.ACL`），否则 Web/小程序无法直接展示图片；生产 OSS 同样注意桶策略或 CDN 配置。
- 服务器上运行中的二进制不能被 `cp` 覆盖（`text file busy`）→ 必须先 `mv` 旧文件再 `cp` 新文件。

### 验证与回滚

- 5 个单元测试（大小/扩展名/Content-Type/键生成）TDD 红→绿；三端构建通过；
- 部署冒烟：上传 1x1 PNG → URL 匿名 GET 200（`image/png`）→ 病种 `imageUrl` 绑定成功（测试数据已清空）；
- 相关提交：`c8aa213`（上传接口）、`3bb1efa`（Web+小程序）、`7647705`（对象公开读修复）；回滚见服务器 README（旧二进制 `server-go-linux.old-20260812-5`）。

---

## 2026-08-12 模块：饲养阶段风险提示（计划 #13）

### 做了什么

- 后端：新增 `GET /api/v1/knowledge/stage-hints?stage=young|grown|late5|pupa`（只读 GET，天然幂等），返回该阶段高发病种（含病种 id，可直接跳知识详情）；不传 stage 返回全部；
- 种子数据：4 个阶段（小蚕期 young / 大蚕期 grown / 5龄后期 late5 / 蛹期 pupa）及其高发病种与原因；
- 小程序：知识库页新增「饲养阶段风险提示」区块——龄期选择器 + 提示卡片，点击病种跳详情。

### 思路与决策

- 选择理由：规格书 3.2.2 的 P1 项，独立、见效快，直接复用蚕病知识库；
- 内容来源：规格书附录 11.1 高发阶段 + 3.2.3 蚕病环境风险规则（如核型多角体病 5龄后期温度突变 >30℃/<20℃ 诱发），无编造；
- 幂等性：新增接口为只读 GET，天然幂等；后续新增写接口时按需实现幂等（如幂等键）；
- v1 用选择器而非自动联动：自动按蚕房龄期提示需等「蚕匾/批次管理」（#7，含龄期记录）落地后接入；
- Web 端本次未加，保持快速交付，后续需要再补。

### 验证与回滚

- 5 个单元测试（阶段 key 合法、病种引用存在、按阶段过滤、未知阶段报错）TDD 红→绿；`go test/build/vet`、`build:weapp` 通过；
- 部署冒烟：`all=4` 阶段；`grown` 返回软化病 + 核型多角体病（含 id）；`young` 返回曲霉病提示；未知阶段 400；
- 相关提交：`6d9cfc7`（后端）、`6dc6c27`（小程序）；回滚见服务器 README（旧二进制 `server-go-linux.old-20260812-6`）。

---

## 环境与踩坑备忘（新同事必读）

- **VPN**：开发服务器经 NetBird 访问；服务 Running 后需 `netbird up`，登录走 SSO（管理端 `115.191.19.95:6680`）。
- **npm**：本机 npm 12 默认禁止 remote tarball，安装需 `npm install --allow-remote=all`；miniapp 因 webpack 版本冲突需再加 `--legacy-peer-deps`（不改 package.json）。
- **服务器代码形态**：开发服务器**没有 silk 主仓库 git**（仅有 wvp-src），代码回滚以「文件备份 + 本地 commit」为准；部署前必做 pg_dump（涉及 schema 变更时）并保留旧二进制/旧 dist。
- **服务启动**：后端 `start.sh`（导出环境变量后 nohup 启动）；注意 `start.sh` 中 `WVP_API_BASE=18978` 与当前 WVP 实际端口 `18080` 不一致（既有问题，未修）。
- **数据库**：服务器 PostgreSQL 实际为 **14**（部署指南写 16，以实际为准）；库名 `silk`，用户 postgres；默认管理员 `admin / silk@123`（README/config 默认值，部署指南里的 admin123 已过时）。
- **部署流程与回滚命令**：见 AGENTS.md「部署到开发服务器」章节与服务器 `/home/pan/backups/rollback-20260812/README.md`。

---

## 当前状态与剩余事项

### 知识库（#10）内部剩余

- SERS 操作教程（P1）、专家经验沉淀（P1）、季节性防控提醒（P2）——文章类型已预留，待补内容；
- AI 检测输出「其它/未知」类别暂无对应病种条目；
- 多图图谱（每病种多张）待扩展；
- 图谱图片素材等待三个方向（数据集/专家/巡检）导入。

### 下一候选模块（方案已给出、待用户确认）

- ~~饲养阶段风险提示（#13）~~：已于 2026-08-12 完成（见上方模块记录）。

### 计划中的其他模块（按《后续工作计划》）

- AI 巡检闭环：#5 ai-service、#6 Go 对接、#7 蚕匾/批次管理、#8 拍照巡检、#9 风险评分引擎、#11 推送；
- 环境监测 + LAMP：#12 天气接入、#14 LAMP 检测管理、#15 交叉验证、#16 耗材管理、#17 技术员后台；
- 专家诊断 + 溯源：#18 专家会诊、#19 qPCR/SERS/高光谱、#21 疫病溯源、#22 区域热力图、#23 摄像头流巡检；
- 数据分析与运维：#24 健康画像、#25 时序存储决策、#26 GPU 监控、#27 测试基建。