fix(server-go): 巡检 roomId UUID 校验（400）；文档更新

开发交接记录.md

@@ -169,6 +169,36 @@
 
 ---
 
+## 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）下一轮再做。
+
+---
+
 ## 环境与踩坑备忘（新同事必读）
 
 - **VPN**：开发服务器经 NetBird 访问；服务 Running 后需 `netbird up`，登录走 SSO（管理端 `115.191.19.95:6680`）。