```

feat(auth): 添加用户权限获取接口并完善JWT令牌角色信息

- 在JWT令牌中添加用户角色信息
- 新增get_my_permissions接口用于获取当前用户权限码列表
- 重构认证回调逻辑，增加错误日志记录
- 更新用户信息获取接口使用Authorization头验证
```

CLAUDE.md

@@ -4,17 +4,26 @@
 
 这是一个基于 Python FastAPI + Vue 3 的 H3C OLT 设备监控管理系统，用于监控 4000+ ONU 设备的在线状态。
 
-**当前版本**: v0.5.0
-**开发状态**: 核心功能已完成
+**当前版本**: v0.7.0
+**开发状态**: 核心功能已完成，权限与运维功能完善中
 
 **已实现功能**：
-- ✅ SSH 连接 H3C OLT 设备查询 ONU 状态（支持 More 分页）
+- ✅ SSH 连接 H3C OLT 设备查询 ONU 状态（支持 More 分页、终端控制字符清理）
 - ✅ Excel 数据导入和批量管理
-- ✅ 定时自动状态检查（每30分钟）+ 手动触发
+- ✅ 定时自动状态检查（可配置间隔，最小5分钟）+ 手动触发
 - ✅ Casdoor 统一认证和 JWT 令牌管理
 - ✅ 设备管理（列表、详情、筛选、分页）
-- ✅ 统计仪表板（总数、在线、离线）
-- ✅ 权限管理基础框架（RBAC）
+- ✅ 统计仪表板（总数、在线、离线）+ 区域分布饼图 + 7天趋势折线图
+- ✅ 完整 RBAC 权限管理（角色、权限、用户管理页面）
+- ✅ OLT 管理（增删改查、批量导入、区域动态同步）
+- ✅ OLT 端口管理（查看端口状态、开关端口）
+- ✅ 重复 MAC 检测与清除
+- ✅ 新设备发现与信息补全
+- ✅ 快速扫描（多线程并发）
+- ✅ 环路检测
+- ✅ 系统设置（管理员可配置检查间隔，显示下次扫描时间/扫描中状态）
+- ✅ 库存管理模块（物料、序列号设备、出入库、盘点）
+- ✅ 每日状态快照（凌晨1点聚合，用于趋势图性能优化）
 
 **技术栈**：
 - 后端：Python FastAPI + PostgreSQL + Celery + Redis + Paramiko
@@ -173,6 +182,79 @@
 
 ---
 
+## 部署陷阱与经验教训
+
+### 修改代码后必须重新构建镜像
+
+**问题**：修改了宿主机上的源码后，直接 `docker compose up -d` 或 `docker compose restart` **不会**让容器使用新代码。容器运行的是构建时打包进镜像的旧代码。
+
+**正确流程**：
+```bash
+# 1. 重新构建镜像（必须加 --no-cache 确保不用旧层）
+docker compose build --no-cache backend   # 或 frontend，或两者
+
+# 2. 重新创建容器（必须用 rm + up，或 up --force-recreate）
+docker compose rm -f backend
+docker compose up -d backend
+
+# 3. 如有数据库模型变更，执行迁移
+docker compose exec backend alembic upgrade head
+```
+
+**不要用**：
+- `docker compose restart`：只重启进程，不更新镜像
+- `docker compose up -d`（无 build）：容器配置变了会重建，但镜像不变
+
+### 端口被占用导致容器启动但无端口映射
+
+**问题**：如果宿主机端口已被其他容器占用，新容器会启动成功（`docker compose up` 不报错），但端口映射为空 `{}`，外部无法访问。
+
+**排查方法**：
+```bash
+# 检查端口映射是否正常
+docker inspect <container> --format '{{json .NetworkSettings.Ports}}'
+
+# 查看谁占用了端口
+docker ps | grep <port>
+```
+
+**解决方法**：先停掉占用端口的旧容器，再 `docker compose rm -f && docker compose up -d`。
+
+### frontend 容器必须配置 VITE_API_PROXY_TARGET
+
+**问题**：根目录 `docker-compose.yml` 的 frontend 服务如果没有配置 `VITE_API_PROXY_TARGET`，Vite 代理会默认打到 `http://localhost:8001`，导致所有 `/api` 请求 500 或无法到达后端。
+
+**必须在 docker-compose.yml 中配置**：
+```yaml
+frontend:
+  build: ./frontend
+  ports:
+    - "5173:5173"
+  environment:
+    - VITE_API_PROXY_TARGET=http://backend:8000
+```
+
+### 新增数据库模型后必须执行迁移
+
+**问题**：新增了 SQLAlchemy 模型（如 `DeviceDailySnapshot`、`SystemSetting`），重建镜像后如果不执行 `alembic upgrade head`，表不存在会导致 500 错误。
+
+**每次新增模型的完整流程**：
+```bash
+# 1. 创建迁移文件（在宿主机或容器内）
+docker compose exec backend alembic revision --autogenerate -m "描述"
+
+# 2. 重建镜像
+docker compose build --no-cache backend
+
+# 3. 重启容器
+docker compose rm -f backend && docker compose up -d backend
+
+# 4. 执行迁移
+docker compose exec backend alembic upgrade head
+```
+
+---
+
 ## 项目结构
 
 ```
@@ -281,7 +363,7 @@ docker-compose exec backend python scripts/init_db.py
 ```bash
 # 创建迁移
 alembic revision --autogenerate -m "描述"
-
+/home/v6ole/pyproject/H3ConuMS2/CLAUDE.md
 # 执行迁移
 alembic upgrade head