v6ole/silk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
93301f0bf3d65d594f8a3c7cc9e1ddc569ecc414
silk/开发交接记录.md
T

18 KiB
Raw Blame History

开发交接记录

用途：按 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 补充：Web 知识库图谱预览与保存修复（故障排查 #三十二）

做了什么

  • 修复 Web 知识库「蚕病百科」两个问题：编辑页图谱预览打不开（CSP 拦截跨源 S3 图片）、提交后 imageUrl 未保存（表单未注册该字段）。
  • web/src/pages/Knowledge.tsx：「症状图谱图片」后新增隐藏 Form.Item name="imageUrl"，保证 form.validateFields() 提交时携带图片 URL。
  • web/server.cjs：CSP img-src 放行 http://100.83.103.1:7480（开发 S3 源）。
  • 已部署并重启前端（新 bundle index-CSVEb7gG.js），并按用户确认直接改库把白僵病已上传的图谱 URL 补绑到 diseases.image_url。

思路与决策

  • 根因定位：日志显示上传 200、PATCH 200，但 image_url 为空 → 定位为前端表单未注册 imageUrl（antd validateFields() 只返回已注册字段），以及 CSP 跨源拦截预览。
  • 修复方式：用隐藏 Form.Item 注册字段（antd 标准做法），避免手工拼请求体；CSP 采用放行开发 S3 源，生产切云 OSS/COS 时再替换为 OSS/CDN 域名或改同源代理。
  • 数据补绑：用户明确选择「直接改库」，回滚点为备份的 diseases 表 dump 与逐行 UPDATE 反向语句。

验证

  • web：npm run lint 通过（仅既有无关警告）、npm run build 通过。
  • 机制红绿验证：用 rc-field-form 验证 validateFields() 会丢弃未注册的 imageUrl，注册/合并后可携带。
  • 部署验证：http://localhost:5174/ 200；CSP 头含 http://100.83.103.1:7480；新 bundle 200；/api/v1/health 200；bundle 中可见 name:"imageUrl", hidden:!0。
  • 数据验证：UPDATE 1；查询确认白僵病 image_url 已绑定；图片匿名 GET 200（image/jpeg）。
  • API 冒烟：admin 登录成功，GET /api/v1/knowledge/diseases 返回白僵病 imageUrl 已绑定（密码不写入文档）。

回滚点

  • 前端：/home/pan/backups/web-20260812-1605/（旧 dist、server.cjs、web.log）恢复后重启 node。
  • 数据：diseases 表 dump /home/pan/backups/diseases-20260812-1605.dump；或执行 UPDATE diseases SET image_url=NULL, updated_at=now() WHERE id='17b1cae4-21cc-4996-9db3-96f785aef800';

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）。

2026-08-12 补充：知识库其余内容（SERS 教程 / 四季防控提醒 / 「其它未知」病种）

做了什么

  • 种子数据：sers_guide 教程（原理、适用场景、设备清单、4 步操作流程、与 LAMP 对比）；seasonal_tip 春夏秋冬 4 篇防控要点；diseases 新增「其它/未知（不确定但有异常）」条目（AI 检出异常但无法归入已知病种时的引导，建议分子检测确认）。
  • 小程序：知识库页教程区合并展示 AI/LAMP/SERS（按类型徽标）；新增「季节性防控提醒」区块——当前季节高亮卡片 + 全部季节列表。
  • Web 无需改动。

思路与决策

  • 内容来源：SERS 取自规格书 3.3.2.2；季节提醒取自附录 11.1 季节性流行规律（春蚕期核型多角体病多发、夏秋高温闷热质型/浓核/软化病多发、湿度>75% 真菌病暴发、温湿度波动诱发潜伏感染）；「其它/未知」对应规格书 AI 检测输出类别（3.1.3）。
  • 季节匹配用文章标题前缀约定（春季/夏季/秋季/冬季），未新增 schema 字段，保持简单；后续如需按节气推送可扩展。
  • 幂等性：均为种子数据，无新增写接口。
  • 专家经验沉淀（P1）暂缓：依赖专家会诊（#18）功能落地后才能沉淀历史案例。

验证与回滚

  • 种子测试共 10 个全过（新增 SERS/四季/其它未知 3 个用例，TDD 红→绿）；三端验证通过；
  • 部署冒烟：sers=1、seasonal=4、diseases=10（含 other 类别）；
  • 相关提交：a5caa48（后端种子）、62fbbaf（小程序）；回滚见服务器 README（旧二进制 server-go-linux.old-20260812-7）。

2026-08-12 模块：AI 巡检闭环后端（计划 #5 + #6）

做了什么

  • ai-service/：FastAPI + ONNX Runtime 检测服务骨架（GET /health、POST /detect 返回框/类别/置信度）。默认 MODEL_MODE=mock（MockDetector 返回固定结果并校验图片可解析）；ONNXDetector 已实现 YOLOv8 常见输出格式解析（letterbox + NMS），训练恢复后放 models/best.onnx 即切真实推理，接口不变。
  • Go 后端：AI client（AIClient.Detect，multipart 上传 + 超时/错误处理）；inspection_records 表；POST/GET /api/v1/inspections——图片存 S3 silk-images/inspections/ → 调 /detect → 写记录；Idempotency-Key 幂等；roomId 校验。
  • 权限：inspection:create / inspection:read；配置 AI_SERVICE_BASE。

思路与决策

  • 按规格书 3.1：AI 服务只做检测（框/类别/置信度），风险评分留在 Go 端（#9 公式），职责单一；
  • 幂等性：/detect 无状态天然幂等；POST /inspections 用客户端 Idempotency-Key（唯一索引）+ 并发冲突兜底，重试不会产生重复巡检记录；
  • YOLO 训练挂起不阻塞：mock 模式先跑通端到端链路，模型就位后只改环境变量；
  • 图片复用 silk-images 桶（inspections/ 前缀），不新建桶；
  • 踩坑记录：服务器缺 python3.10-venv（需 apt 安装）；pip 直连慢，改用清华镜像；原 .gitignore 全局 *.py 规则会忽略 ai-service，已加例外。

验证与部署

  • 本地：ai-service pytest 6/6；Go 新增 AI client 3 用例 + UUID 校验用例，go test/build/vet 通过；
  • 服务器：ai-service 部署 /home/pan/ai-service（:8000，mock，start.sh），pytest 6/6，health 200；Go 第六次部署（schema 变更前 pg_dump silk-20260812-1635.dump）；
  • 冒烟：巡检创建 201（mock healthy/0.95）→ 同 key 重试返回同记录 → 列表 → 图片 URL 200；非法 roomId 400（测试数据已清理）；
  • 相关提交：99137a6、b89ad5e（ai-service + gitignore）、210bd6c（Go 对接）；回滚见服务器 README（旧二进制 server-go-linux.old-20260812-9）。

说明

  • 巡检风险分级（绿/黄/橙/红）与评分引擎属计划 #9，本期只落数据字段；
  • 小程序拍照巡检 UI（#8）下一轮再做。

2026-08-12 模块：小程序拍照巡检（计划 #8）

做了什么

  • 新增 pages/inspection/：拍照/相册选图（压缩）→ 预览 → 上传 POST /api/v1/inspections（multipart，自动生成 Idempotency-Key 防重复）→ 结果卡片（AI 类别 + 置信度 + 风险提示文案）→ 巡检历史列表（最近 10 条）。
  • 设置页「监控管理」新增「拍照巡检」入口；app.config.ts 注册页面。

思路与决策

  • 复用 #5/#6 已部署的后端接口，本期纯小程序端，无服务端改动；
  • 上传用 Taro.uploadFile（不是通用 request 封装），因为需要文件流 + 自定义头（Authorization / Idempotency-Key）；
  • 幂等键客户端生成（时间戳 + 随机串），弱网重试不会重复创建巡检记录；
  • 结果展示先按二分类（healthy/sick）映射，风险分级（绿/黄/橙/红）等 #9 评分引擎落地后接入；7 类病种扩展后补充类名映射。

验证

  • npm run build:weapp 编译通过；后端接口此前已冒烟（创建→幂等重试→列表→图片 200）。
  • 相关提交：8274cc8。

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

  • 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）、季节性防控提醒（P2）、「其它/未知」类别：已于 2026-08-12 完成；
  • 专家经验沉淀（P1）：依赖专家会诊（#18）落地后沉淀历史案例，暂缓；
  • 多图图谱（每病种多张）待扩展；
  • 图谱图片素材等待三个方向（数据集/专家/巡检）导入。

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

  • 饲养阶段风险提示（#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 测试基建。
Reference in New Issue View Git Blame Copy Permalink