docs: README/部署指南/故障排查记录补全（ai-service、API、权限、踩坑合集）

README.md

@@ -338,6 +338,21 @@ Authorization: Bearer <accessToken>
 | `GET /video/recordings/active` | 活跃录制列表 |
 | `GET /notifications` | 站内通知列表 |
 | `GET /audit-logs` | 审计日志（`audit:read`） |
+| `GET /knowledge/diseases` / `GET/POST/PATCH/DELETE /knowledge/diseases/:id` | 蚕病百科 |
+| `GET /knowledge/articles` / `GET/POST/PATCH/DELETE /knowledge/articles/:id` | 知识文章（AI 解读/LAMP/SERS/季节提醒） |
+| `GET /knowledge/stage-hints` | 饲养阶段风险提示 |
+| `POST /knowledge/images` | 知识库图片上传（`knowledge:write`） |
+| `POST/GET /inspections` | AI 巡检创建/列表（`Idempotency-Key` 幂等） |
+| `GET/POST/PATCH/DELETE /trays`、`/batches`、`/rearing-records` | 蚕匾/批次/饲养记录 |
+| `GET/POST/PATCH/DELETE /lamp-tests(/:id)` | 分子检测任务单（含步骤/结果照片/judge-qpcr/spectrum/cross-validation） |
+| `GET/POST/DELETE /spectrum-entries` | SERS 光谱库 |
+| `GET /weather/now`、`GET /weather/alerts` | 天气与高发病预警 |
+| `GET/POST /wechat/binding`、`/wechat/bind`、`/wechat/subscribe` | 微信订阅绑定/授权 |
+| `GET/POST/PATCH /consultations(/:id)`、`/:id/resolve`、`/:id/archive` | 专家会诊 |
+| `GET/POST/PATCH/DELETE /trace-records(/:id)`、`/:id/auto`、`/:id/checklist`、`/region-stats`、`/monthly-stats` | 疫病溯源与区域/月度统计 |
+| `GET /health-profiles/:roomId` | 蚕房健康画像 |
+| `GET /detection-methods/recommend` | 多检测方式推荐 |
+| `GET/POST/PATCH/DELETE /consumables`、`/consumables/alerts`、`/consumables/purchase-suggestions` | 耗材管理 |
 
 ## 8. 权限矩阵
 
@@ -356,6 +371,19 @@ Authorization: Bearer <accessToken>
 | `video:record` | 视频录制 | ✓ | ✓ | - | - |
 | `energy:view` | 能耗查看 | ✓ | ✓ | ✓ | ✓ |
 | `log:read` | 日志查看 | ✓ | ✓ | - | - |
+| `knowledge:read` | 知识库查看 | ✓ | ✓ | ✓ | ✓ |
+| `knowledge:write` | 知识库管理 | ✓ | ✓ | - | - |
+| `inspection:create` | 巡检创建 | ✓ | ✓ | - | ✓ |
+| `inspection:read` | 巡检查看 | ✓ | ✓ | ✓ | ✓ |
+| `tray:read/write` | 蚕匾查看/管理 | ✓ | ✓ | 读 | 读 |
+| `batch:read/write` | 批次查看/管理 | ✓ | ✓ | 读 | 读 |
+| `rearing:read/write` | 饲养记录查看/管理 | ✓ | ✓ | 读 | 读 |
+| `notification:read/write` | 订阅查看/管理 | ✓ | ✓ | 读 | 读写 |
+| `weather:read` | 天气查看 | ✓ | ✓ | ✓ | ✓ |
+| `lamp:read/write` | LAMP 检测查看/管理 | ✓ | ✓ | 读 | 读 |
+| `consumable:read/write` | 耗材查看/管理 | ✓ | ✓ | 读 | 读 |
+| `consultation:read/write` | 会诊查看/管理 | ✓ | ✓ | 读 | 读 |
+| `trace:read/write` | 溯源查看/管理 | ✓ | ✓ | 读 | 读 |
 | `user:manage` | 用户管理 | ✓ | - | - | - |
 | `audit:read` | 审计查看 | ✓ | - | - | - |
 
@@ -554,6 +582,25 @@ npm run start
 密码：silk@123
 ```
 
+### 12.6 ai-service（AI 推理服务）
+
+```powershell
+cd e:\silk\ai-service
+python -m venv .venv
+.venv\Scripts\pip install -r requirements.txt   # Linux: .venv/bin/pip install -r requirements.txt
+.venv\Scripts\python -m pytest tests -q          # 单元测试
+MODEL_MODE=mock .venv\Scripts\python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+- 接口：`GET /health`、`POST /detect`（multipart 图片）、`POST /stream-detect`（摄像头流拉帧骨架）、`GET /metrics`（含 GPU 信息）
+- 默认 mock 模式；训练恢复后放 `models/best.onnx` 并设 `MODEL_MODE=onnx`（`MODEL_LABELS` 可配类别）
+- 开发服务器部署：`/home/pan/ai-service`（venv + `start.sh`，:8000），服务器 pip 源已配置清华镜像
+
+### 12.7 开发服务器部署摘要
+
+- 部署规则（备份/回滚/冒烟）见根目录 `AGENTS.md`「部署到开发服务器」；SSH/SFTP 工具为 `scripts/devssh.py`（`PAN_SSH_PASS` 环境变量传密码）
+- 服务清单：Go 后端 :3000、Web :5174、ai-service :8000、recorder-go :9090、PostgreSQL :5432、IoTDB :18081、VerneMQ :1883、Ceph RGW :7480、WVP :18080、ZLM :8081
+
 ## 13. Git 注意事项
 
 不要提交依赖目录和本地运行产物。`.gitignore` 应包含：