docs: 部署规则与交接记录规范，开发交接记录、变更记录更新

2026-08-12 14:43:09 +08:00
parent 7647705f3b
commit 9c8388d220
4 changed files with 224 additions and 4 deletions
@@ -7,6 +7,7 @@
 3. 交付说明应聚焦于修改的文件、验证结果和风险。
 4. 对不清楚的需求或不可逆选择，执行前先向用户确认。
 5. 创建或重写本指令文件前，询问用户该文件应使用哪种语言。
+6. 每完成一项交付（功能/模块/部署），必须更新根目录 `开发交接记录.md`，追加「做了什么、设计思路与决策依据、验证结果、回滚点」，保证同事阅读后能快速接手；不得只做口头总结。

 ## 项目结构

@@ -49,6 +50,39 @@
 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`。
@@ -1,5 +1,69 @@
 # 变更记录

+## 2026-08-12 知识库初始版开发与部署
+
+### 变更背景
+
+依据《后续工作计划》#10，先跳过 YOLO 训练相关项（物理机问题），优先交付独立、见效快的模块「知识库初始版」（蚕病百科 + AI 结果解读）。蚕病内容全部取自规格书 3.6、3.1.4（风险分级阈值）与附录 11.1，不自行编造。
+
+### 后端变更（server-go）
+
+| 文件 | 变更 |
+|------|------|
+| `internal/model/knowledge.go`（新增） | `Disease` / `KnowledgeArticle` 模型（`diseases`、`knowledge_articles` 表） |
+| `internal/model/knowledge_seed.go`（新增） | 种子数据：9 个蚕病条目 + 1 篇 AI 结果解读，启动幂等写入 |
+| `internal/model/knowledge_seed_test.go`（新增） | seed 数据完整性单元测试（TDD 红→绿） |
+| `internal/handler/knowledge.go`（新增） | 知识库 CRUD API：`/api/v1/knowledge/diseases`、`/api/v1/knowledge/articles` |
+| `internal/model/permission_seed.go` | 新增权限 `knowledge:read` / `knowledge:write` 及角色映射 |
+| `internal/database/db.go` | AutoMigrate 注册两表 + `seedKnowledge` 幂等种子 |
+| `cmd/server/main.go` | 注册知识库路由 |
+
+### Web 变更（web）
+
+- `src/dal/knowledge.ts`（新增）：知识库 API 封装与类型
+- `src/pages/Knowledge.tsx`（新增）：蚕病百科 + AI 结果解读双 Tab，可增删改（按权限）
+- `src/router.tsx`、`src/layout/BasicLayout.tsx`：新增 `/knowledge` 路由与「知识库」菜单
+
+### 小程序变更（miniapp）
+
+- `src/api/knowledge.ts`（新增）、`src/types/index.ts`：知识库接口与类型
+- `src/pages/knowledge/`（新增）：知识库列表页 + 详情页
+- `src/pages/settings/index.tsx`：设置页新增「知识库」入口
+- `src/app.config.ts`：注册新页面
+
+### 部署（开发服务器 100.83.103.1）
+
+- 部署内容：Go 后端二进制 `server-go-linux`（含知识库 API 与两表迁移）+ Web `dist`（知识库页面）
+- 回滚点：数据库 `pg_dump` `/home/pan/backups/silk-20260812-1111.dump`；旧二进制 `/home/pan/backups/rollback-20260812/server-go-linux.bak`（原位另有 `server-go-linux.old-20260812`）；旧 dist `/home/pan/backups/rollback-20260812/web-dist-20260812.tar.gz`（原位另有 `dist.old-20260812`）；完整回滚命令见服务器 `/home/pan/backups/rollback-20260812/README.md`
+- 验证结果：`/api/v1/health` 200；登录 admin → `GET /api/v1/knowledge/diseases` 返回 9 条；`GET /api/v1/knowledge/articles?kind=ai_guide` 返回 1 条；`http://localhost:5174/` 200；DB `diseases=9`、`knowledge_articles=1`
+
+### 风险与备注
+
+- `start.sh` 中 `WVP_API_BASE=18978`，与当前 WVP 实际端口 18080 不一致（既有问题，未随本次修改）
+- 服务器 PostgreSQL 为 14（部署指南记录为 16，以实际为准）
+- 服务器无 silk 主仓库 git（仅有 wvp-src），代码回滚以文件备份 + 本地 commit 为准
+- 前端测试基建（Vitest）未配置，属计划 #27，UI 验证以 lint + 构建为准
+
+### 补充：LAMP 操作教程（P0）
+
+- `server-go/internal/model/knowledge_seed.go`：新增 `lamp_guide` 种子文章（原理、适用场景、设备清单、5 步操作流程、结果判读、各病种检测靶标现状），内容取自规格书 3.3.2.1
+- `server-go/internal/model/knowledge_seed_test.go`：新增 LAMP 教程存在性测试（TDD 红→绿）
+- `miniapp/src/api/knowledge.ts`、`miniapp/src/pages/knowledge/index.tsx`：知识库列表增加「LAMP 教程」入口
+- `miniapp/src/pages/knowledge/detail/index.tsx`：修复非 disease 类型（如 lamp_guide）误走病种详情接口的问题
+- Web 无需改动（文章 Tab 已支持 `lamp_guide` 类型）
+- 二次部署：后端二进制更新（sha256 `742ffb54…`），验证 `ai_guide=1`、`lamp_guide=1`，`GET /api/v1/knowledge/articles?kind=lamp_guide` 返回 1 条；回滚点见服务器 `/home/pan/backups/rollback-20260812/README.md`（原位旧二进制 `server-go-linux.old-20260812-2`）
+
+### 补充：症状图谱图片上传（P0）
+
+- `server-go/internal/handler/knowledge_image.go`（新增）：`POST /api/v1/knowledge/images`（multipart 字段 `file`，限 jpg/jpeg/png/webp、≤5MB），对象键 `knowledge/<日期>/<随机>.ext`，权限 `knowledge:write`
+- `server-go/internal/handler/knowledge_image_test.go`（新增）：校验/类型/键生成 5 个单元测试（TDD 红→绿）
+- `server-go/internal/service/s3.go`：新增 `EnsureBucket`（不存在则创建 + bucket 公开读）、`UploadImage`（对象公开读，Ceph 需对象级 ACL）、`Endpoint`
+- `server-go/internal/config/config.go`：新增 `S3_BUCKET_IMAGES`（默认 `silk-images`）
+- Web：病种表单增加「症状图谱图片」上传 + 预览（antd Upload 自定义请求）
+- 小程序：病种详情页顶部展示症状图（有 `imageUrl` 时）
+- 三次部署（含 ACL 修复）：上传 1x1 PNG 冒烟通过——URL 匿名 GET 200（`image/png`），病种 `imageUrl` 绑定成功（测试数据已清空）；回滚点见服务器 `/home/pan/backups/rollback-20260812/README.md`（原位旧二进制 `server-go-linux.old-20260812-5`）
+- 说明：开发环境图片存 Ceph `silk-images` 桶（公开读），生产切云 OSS/COS 时由桶策略或 CDN 承担公开访问，代码仅需改配置
+
 ## 2026-07-17 安全与界面优化整改

 ### 变更背景
@@ -878,5 +942,3 @@ UPDATE cameras SET gb_channel_id = '44010201001320000001' WHERE gb_device_id = '
 - `npm run build` 通过，无 TS 诊断错误
 - 前端已部署到 `http://100.83.103.1:5174/videos`（5174 端口正常监听）
 - 编辑摄像头不再崩溃，"认证密码"正确回显，"码流类型"字段已移除且不再出现残留值
-
-
@@ -1,7 +1,5 @@
 # 后续工作计划

-> 依据：《蚕病智能防控平台规格说明书》V2.1（2026-08-11，来源 `.cc-connect/attachments/蚕病智能防控平台规格说明书.md`）
-
 ## 技术选型决策（2026-08-11 确定）

 **采用混合架构：现有 Go 底座 + Python AI 微服务**
@@ -0,0 +1,126 @@
+# 开发交接记录
+
+> **用途**：按 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`）。
+
+---
+
+## 环境与踩坑备忘（新同事必读）
+
+- **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，规格书 P1）：后端阶段风险种子 + `GET /knowledge/stage-hints` + 小程序选择器，内容取自规格书附录 11.1 与 3.2.3；自动按龄期提示需等「蚕匾/批次管理」（#7）落地后联动。
+
+### 计划中的其他模块（按《后续工作计划》）
+
+- 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 测试基建。