docs: add handover and deployment guides

docs/07_troubleshooting.md

@@ -0,0 +1,247 @@
+# 常见故障排查
+
+本文档用于接手人快速定位本地和云服务器常见问题。
+
+## 1. `/fastapi/docs` 打不开
+
+现象：
+
+- 浏览器访问 `http://8.160.178.88/fastapi/docs` 失败
+
+排查：
+
+```bash
+curl http://127.0.0.1:9000/docs
+docker compose ps
+docker compose logs --tail=200 fastapi
+```
+
+可能原因：
+
+- FastAPI 容器未启动
+- Nginx `/fastapi/` 代理配置错误
+- `.env` 中 `APP_ROOT_PATH` 未设置为 `/fastapi`
+
+处理：
+
+```bash
+cd /home/code/medical-ai
+docker compose up -d fastapi
+docker compose logs --tail=200 fastapi
+```
+
+## 2. `/api/v1/auth/me` 返回 401
+
+现象：
+
+```json
+{
+  "code": "AUTH_CREDENTIAL_REQUIRED"
+}
+```
+
+排查：
+
+- 是否携带 `Authorization: Bearer <access_token>`
+- token 是否过期
+- `AUTH_USER_ME_URL` 是否可访问
+- Django 容器是否正常
+
+验证：
+
+```bash
+curl "http://8.160.178.88/fastapi/api/v1/auth/me" \
+  -H "Authorization: Bearer <access_token>" \
+  -H "X-Entry-Scene: production_vue"
+```
+
+## 3. Django 用户中心不可达
+
+现象：
+
+```json
+{
+  "code": "AUTH_USER_CENTER_UNAVAILABLE"
+}
+```
+
+排查：
+
+```bash
+docker compose ps django
+docker compose logs --tail=200 django
+```
+
+处理：
+
+- 检查 `AUTH_USER_ME_URL`
+- 检查 Docker 网络
+- 检查 Django 服务是否能访问 MySQL
+
+## 4. MySQL 连接失败
+
+现象：
+
+- 服务启动时报数据库连接错误
+- `/health/ready` 不通过
+
+排查：
+
+```bash
+docker compose ps mysql
+docker compose logs --tail=100 mysql
+```
+
+检查 `.env`：
+
+```env
+DATABASE_URL=mysql+pymysql://root:<password>@mysql:3306/medical?charset=utf8mb4
+```
+
+Docker 内部访问应使用服务名 `mysql`，不是 `127.0.0.1`。
+
+## 5. Redis 连接失败
+
+排查：
+
+```bash
+docker compose ps redis
+docker compose logs --tail=100 redis
+```
+
+检查 `.env`：
+
+```env
+RUNTIME_MEMORY_BACKEND=redis
+REDIS_URL=redis://redis:6379/0
+```
+
+如果 Redis 不可用，短期会话 memory 会受影响。
+
+## 6. LLM 调用失败或很慢
+
+现象：
+
+- 流式问诊长时间无返回
+- 返回 `LLM_STREAM_FAILED`
+
+排查：
+
+- `LLM_BASE_URL`
+- `LLM_API_KEY`
+- `LLM_FAST_MODEL`
+- 网络是否能访问模型服务
+- 超时时间配置是否过短
+
+建议：
+
+- 先用 `/api/v1/learning-assistant/chat/stream` 测试最简单问题
+- 查看 FastAPI 日志
+- 确认模型服务账号额度
+
+## 7. AI 学习助手没有知识库来源
+
+现象：
+
+```text
+retrieval_hit=false
+retrieval_error=当前机构知识库暂未初始化或检索不可用...
+```
+
+说明：
+
+这是允许的降级行为。学习助手会继续用 LLM 通用回答。
+
+排查知识库：
+
+- 用户是否有 `institution_id`
+- 是否已有 `kb_knowledge_space`
+- Milvus 是否运行
+- Embedding 是否配置
+
+## 8. Milvus 连接失败
+
+排查：
+
+```bash
+docker compose ps milvus-standalone
+docker compose logs --tail=200 milvus-standalone
+```
+
+检查 `.env`：
+
+```env
+MILVUS_URI=http://milvus-standalone:19530
+MILVUS_HOST=milvus-standalone
+MILVUS_PORT=19530
+```
+
+## 9. PDF 下载失败
+
+现象：
+
+- 评价详情有，但 PDF 下载 404 或 500
+
+排查：
+
+- 评价是否属于当前 `user_id`
+- 是否已经调用过导出 PDF
+- `storage/reports` 是否挂载
+- 容器是否有写权限
+
+命令：
+
+```bash
+docker compose exec fastapi ls -lah /app/storage/reports
+```
+
+## 10. Docker build 失败
+
+排查：
+
+```bash
+docker compose build fastapi
+```
+
+常见原因：
+
+- `requirements.txt` 依赖下载失败
+- 网络无法访问 pip 源
+- Python 版本不兼容
+- 文件编码或语法错误
+
+本地先跑：
+
+```powershell
+.\backend\.venv\Scripts\python.exe -m compileall app scripts tests
+```
+
+## 11. API 文档和实际接口不一致
+
+排查：
+
+```bash
+curl http://8.160.178.88/fastapi/openapi.json
+```
+
+如果接口已改动：
+
+- 更新 `docs/03_api_design.md`
+- 运行 `tests/test_api_contract.py`
+- 再提交 Git
+
+## 12. Git 拉取后服务没变化
+
+处理：
+
+```bash
+cd /home/code/medical-ai/fastapi
+git log -1 --oneline
+
+cd /home/code/medical-ai
+docker compose build fastapi
+docker compose up -d fastapi
+docker compose logs --tail=200 fastapi
+```
+
+如果 `requirements.txt` 或 Dockerfile 有变动，必须重新 build。