```

feat: 升级到v0.8.0版本并新增审计日志等功能

- 升级版本号从v0.7.0到v0.8.0
- 新增审计日志功能，支持全量操作记录、筛选查询和CSV导出
- 新增设备更换记录功能，支持MAC地址更换历史与库存序列号联动
- 新增iOS PWA主屏幕支持，实现standalone模式safe area适配
- 删除过时的技术流程文档
- 补充开发规范说明，包括Alembic迁移、Celery worker重建、区域管理员过滤等重要规则
```

CLAUDE.md

@@ -4,7 +4,7 @@
 
 这是一个基于 Python FastAPI + Vue 3 的 H3C OLT 设备监控管理系统，用于监控 4000+ ONU 设备的在线状态。
 
-**当前版本**: v0.7.0
+**当前版本**: v0.8.0
 **开发状态**: 核心功能已完成，权限与运维功能完善中
 
 **已实现功能**：
@@ -24,6 +24,9 @@
 - ✅ 系统设置（管理员可配置检查间隔，显示下次扫描时间/扫描中状态）
 - ✅ 库存管理模块（物料、序列号设备、出入库、盘点）
 - ✅ 每日状态快照（凌晨1点聚合，用于趋势图性能优化）
+- ✅ 审计日志（全量操作记录、筛选查询、CSV 导出）
+- ✅ 设备更换记录（MAC 地址更换历史，与库存序列号联动）
+- ✅ iOS PWA 主屏幕支持（standalone 模式 safe area 适配）
 
 **技术栈**：
 - 后端：Python FastAPI + PostgreSQL + Celery + Redis + Paramiko
@@ -253,6 +256,78 @@ docker compose rm -f backend && docker compose up -d backend
 docker compose exec backend alembic upgrade head
 ```
 
+### Alembic 迁移文件 revision ID 不能重复
+
+**问题**：手动创建迁移文件时，如果 `revision` 字段与已有文件重复，`alembic upgrade head` 会报 `Multiple head revisions are present` 错误。
+
+**规则**：手动创建迁移文件时，revision ID 使用不与现有文件冲突的唯一字符串（如 `h8i9j0k1l2m3`），并确认 `down_revision` 指向正确的上一个版本。
+
+### Celery worker 必须重建才能识别新任务
+
+**问题**：新增 Celery 任务模块后，如果只重建 backend 而不重建 celery-worker，worker 不会注册新任务，消息会被丢弃并报 `KeyError`。
+
+**规则**：新增任务模块后，backend 和 celery-worker 都必须重建：
+```bash
+docker compose build --no-cache backend celery-worker
+docker compose rm -f backend celery-worker
+docker compose up -d backend celery-worker
+```
+
+验证任务是否注册：
+```bash
+docker compose exec celery-worker celery -A celery_worker.celery_app inspect registered
+```
+
+### 区域管理员多区域过滤必须用 `.in_()` 而非 `==`
+
+**问题**：`assigned_area` 字段存储逗号分隔的多个区域（如 `"城区,郊区"`），用 `==` 只能匹配整个字符串，导致多区域管理员只能看到第一个区域的数据。
+
+**规则**：所有涉及 `assigned_area` 的过滤都必须先 split 再用 `.in_()`：
+```python
+areas = [a.strip() for a in current['assigned_area'].split(',') if a.strip()]
+query = query.filter(Model.region.in_(areas))
+```
+
+### Vite dev server 通过反向代理访问需配置 allowedHosts
+
+**问题**：通过域名反向代理访问 Vite dev server 时，会报 `Blocked request. This host is not allowed`。
+
+**解决**：在 `vite.config.js` 中设置：
+```js
+server: {
+  allowedHosts: ['all', 'your-domain.com'],
+}
+```
+
+### iOS PWA standalone 模式与 Safari 的 safe area 差异
+
+**问题**：`env(safe-area-inset-top)` 在 Safari 浏览器中为 0（有地址栏占位），在 standalone 模式（添加到主屏幕）下为真实刘海高度（44-59px）。直接使用会导致 Safari 中布局正常但 standalone 中顶栏/弹窗重叠。
+
+**规则**：所有 safe area 相关样式必须包在 `@media (display-mode: standalone)` 中，Safari 不受影响：
+```css
+@media (display-mode: standalone) {
+  .mobile-topbar {
+    height: calc(52px + env(safe-area-inset-top));
+  }
+}
+```
+
+`ElMessage` 的 offset 通过 `src/utils/message.js` 封装统一处理，所有页面从该文件导入而非直接从 `element-plus` 导入。
+
+### Docker healthcheck 镜像内无 curl
+
+**问题**：backend 镜像基于 Python slim，没有 `curl`，healthcheck 用 `curl` 会导致所有依赖服务启动失败。
+
+**规则**：healthcheck 使用 Python 内置模块：
+```yaml
+healthcheck:
+  test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
+  interval: 15s
+  timeout: 10s
+  retries: 5
+  start_period: 40s
+```
+
 ---
 
 ## 项目结构