H3ConuMS-v2/CLAUDE.md

H3C ONU设备管理系统 - Claude开发指南

项目概述

这是一个基于 Python FastAPI + Vue 3 的 H3C OLT 设备监控管理系统，用于监控 4000+ ONU 设备的在线状态。

当前版本: v0.9.0 开发状态: 核心功能已完成，运维增强功能持续迭代

已实现功能：

• ✅ SSH 连接 H3C OLT 设备查询 ONU 状态（支持 More 分页、终端控制字符清理）
• ✅ Excel 数据导入和批量管理
• ✅ 定时自动状态检查（可配置间隔，最小5分钟）+ 手动触发
• ✅ Casdoor 统一认证和 JWT 令牌管理
• ✅ 设备管理（列表、详情、筛选、分页）
• ✅ 统计仪表板（总数、在线、离线）+ 区域分布饼图 + 7天趋势折线图
• ✅ 完整 RBAC 权限管理（角色、权限、用户管理页面）
• ✅ OLT 管理（增删改查、批量导入、区域动态同步）
• ✅ OLT 端口管理（查看端口状态、开关端口）
• ✅ 重复 MAC 检测与清除
• ✅ 新设备发现与信息补全（扫描发现 → 补全信息 → 入库）
• ✅ 快速扫描（多线程并发）
• ✅ 环路检测
• ✅ 系统设置（管理员可配置检查间隔，显示下次扫描时间/扫描中状态）
• ✅ 库存管理模块（物料、序列号设备、出入库、盘点）
• ✅ 每日状态快照（凌晨1点聚合，用于趋势图性能优化）
• ✅ 审计日志（全量操作记录、筛选查询、CSV 导出）
• ✅ 设备更换记录（MAC 地址更换历史，与库存序列号联动）
• ✅ 操作记录日志（查看指定设备的上下线事件历史）
• ✅ OLT 时间同步（NTP 服务器配置同步到所有 OLT）
• ✅ IMC 网管服务集成（ONU 远程重启、光功率查询）
• ✅ iOS PWA 主屏幕支持（standalone 模式 safe area 适配）

技术栈：

• 后端：Python FastAPI + PostgreSQL + Celery + Redis + Paramiko
• 前端：Vue 3 + Element Plus + Pinia + Axios
• 部署：Docker Compose

---

已实现的 API 端点

认证相关

• GET /api/auth/login - 获取 Casdoor 登录 URL
• POST /api/auth/callback - Casdoor 登录回调
• GET /api/auth/profile - 获取当前用户信息

设备管理

• GET /api/devices - 获取设备列表（分页、筛选）
• GET /api/devices/{id} - 获取设备详情
• PUT /api/devices/{id} - 更新设备信息
• GET /api/devices/{id}/events - 获取设备上下线事件记录
• POST /api/devices/{id}/reboot - 远程重启 ONU（IMC）
• GET /api/devices/{id}/optical-power - 获取 ONU 光功率（IMC）

状态检查

• POST /api/check/status - 手动触发全量状态检查（Celery 异步）
• GET /api/check/status/{task_id} - 查询检查任务进度
• POST /api/check/scan/{olt_id} - 扫描单台 OLT（预览，不入库）
• POST /api/check/discover/{olt_id} - 扫描单台 OLT 并入库新设备

OLT 管理

• GET /api/olt/devices - OLT 设备列表
• POST /api/olt/devices - 新增 OLT
• PUT /api/olt/devices/{id} - 编辑 OLT
• DELETE /api/olt/devices/{id} - 删除 OLT
• GET /api/olt/regions - 获取 OLT 区域列表
• POST /api/olt/quick-scan - 多线程快速扫描所有 OLT
• GET /api/olt/ports/{olt_id} - 获取 OLT 端口状态
• POST /api/olt/ports/{olt_id}/toggle - 开关 OLT 端口
• POST /api/olt/sync-ntp - 同步 NTP 时间服务器配置
• POST /api/olt/loopback-detection - 环路检测
• GET /api/olt/new-devices - 获取新发现设备列表
• PUT /api/olt/new-devices/{id} - 补全新设备信息
• DELETE /api/olt/new-devices/{id} - 忽略新设备

数据导入

• POST /api/import/upload - 上传并导入 Excel 文件
• GET /api/import/template - 下载导入模板

统计信息

• GET /api/stats/summary - 获取统计摘要
• GET /api/stats/trend - 7天趋势数据
• GET /api/stats/region-distribution - 区域分布

权限管理

• GET /api/roles - 角色列表
• POST /api/roles - 创建角色
• PUT /api/roles/{id} - 编辑角色
• DELETE /api/roles/{id} - 删除角色
• GET /api/permissions - 权限列表

用户管理

• GET /api/users - 用户列表
• PUT /api/users/{id} - 编辑用户
• DELETE /api/users/{id} - 删除用户

库存管理

• GET /api/inventory/materials - 物料列表
• POST /api/inventory/materials - 新增物料
• GET /api/inventory/serial-devices - 序列号设备
• POST /api/inventory/stock-in - 入库
• POST /api/inventory/stock-out - 出库
• POST /api/inventory/check - 盘点

审计日志

• GET /api/audit/logs - 审计日志列表（筛选、分页）
• GET /api/audit/logs/export - 导出审计日志 CSV

设备更换记录

• GET /api/devices/{id}/replacements - 查看设备更换历史
• GET /api/replacements - 全量更换记录列表

系统设置

• GET /api/settings - 获取系统设置
• PUT /api/settings - 更新系统设置

系统

• GET /health - 健康检查
• GET /docs - API 文档（Swagger UI）

---

Rules

代码规范

Python 后端规范

• 遵循 PEP 8 规范
• 使用 Black 进行代码格式化
• 使用 isort 进行导入排序
• 使用类型注解（Type Hints）
• 异步函数使用 async/await
• 错误处理使用自定义异常类

Vue 前端规范

• 使用 Composition API（setup script）
• 组件使用 PascalCase 命名
• 使用 TypeScript 类型检查
• 遵循 Vue 官方风格指南
• 使用 ESLint + Prettier 格式化

Git 提交规范

使用 Conventional Commits 格式：

<type>(<scope>): <subject>

类型：feat, fix, docs, style, refactor, test, chore
示例：feat(device): 添加设备导入功能

架构规则

后端架构

• 分层架构：API → Service → Model
• API 层：仅处理请求/响应，调用 Service
• Service 层：业务逻辑，不直接操作数据库
• Model 层：SQLAlchemy 模型定义
• 异步任务：耗时操作使用 Celery

前端架构

• 组件分类：
  • components/common/：通用组件
  • components/business/：业务组件
  • views/：页面组件
• 状态管理：使用 Pinia stores
• API 调用：统一在 api/ 目录封装

安全规则

数据安全

• SSH 密码必须加密存储（使用 Fernet 加密）
• 敏感信息通过环境变量配置
• 数据库连接使用 SSL
• 定期备份数据（90天历史记录）

应用安全

• 所有 API 端点需要认证（除登录接口）
• 实现 CSRF 保护
• 输入验证使用 Pydantic
• SQL 注入防护（使用 ORM）
• XSS 防护（前端转义）

访问控制

• 基于 RBAC 的权限控制
• 数据级权限过滤（按区域/学校）
• 操作审计日志记录
• 设备信息变更需要审核

性能规则

数据库优化

• 为常用查询字段添加索引
• 使用连接池（pool_size=20）
• 避免 N+1 查询问题
• 定期清理历史数据（保留90天）

缓存策略

• Redis 缓存热点数据（设备状态）
• 缓存过期时间：30分钟
• 手动刷新有5分钟冷却限制

异步处理

• SSH 状态检查使用 Celery 异步任务
• 批量导入使用后台任务
• 定时任务使用 Celery Beat

开发规则

提交前清理

• 每次提交前必须清理项目中不需要的文件
• 包括：测试文件（test_*.py）、调试脚本、不再使用的 shell 脚本、冗余 markdown 文档
• 检查是否有硬编码的敏感信息（密码、密钥、token）
• 检查 .gitignore 是否覆盖了所有不应提交的文件（*.pem、.env、__pycache__ 等）

环境配置

• 开发环境使用 .env.development
• 生产环境使用 .env.production
• 不提交 .env 文件到 Git
• 提供 .env.example 模板
• 敏感信息（数据库密码、Casdoor 密钥等）仅通过环境变量注入

测试要求

• 核心业务逻辑需要单元测试
• API 端点需要集成测试
• 测试覆盖率目标：≥80%

文档要求

• API 变更及时更新 Swagger 文档
• 复杂业务逻辑添加注释
• 重要配置添加说明

部署规则

Docker 部署

• 使用 Docker Compose 编排
• 外部 PostgreSQL 和 Redis（不在容器内）
• 日志挂载到宿主机
• 使用 Nginx 反向代理

环境变量

必需配置：

• DATABASE_URL：PostgreSQL 连接字符串
• REDIS_URL：Redis 连接字符串
• CASDOOR_*：Casdoor 认证配置
• SECRET_KEY：应用密钥

监控告警

• 健康检查端点：/health
• 性能指标端点：/metrics
• 日志级别：生产环境使用 INFO

---

部署陷阱与经验教训

修改代码后必须重新构建镜像

问题：修改了宿主机上的源码后，直接 docker compose up -d 或 docker compose restart 不会让容器使用新代码。容器运行的是构建时打包进镜像的旧代码。

正确流程：

# 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 不报错），但端口映射为空 {}，外部无法访问。

排查方法：

# 检查端口映射是否正常
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 中配置：

frontend:
  build: ./frontend
  ports:
    - "5173:5173"
  environment:
    - VITE_API_PROXY_TARGET=http://backend:8000

新增数据库模型后必须执行迁移

问题：新增了 SQLAlchemy 模型（如 DeviceDailySnapshot、SystemSetting），重建镜像后如果不执行 alembic upgrade head，表不存在会导致 500 错误。

每次新增模型的完整流程：

# 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

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 都必须重建：

docker compose build --no-cache backend celery-worker
docker compose rm -f backend celery-worker
docker compose up -d backend celery-worker

验证任务是否注册：

docker compose exec celery-worker celery -A celery_worker.celery_app inspect registered

区域管理员多区域过滤必须用 .in_() 而非 ==

问题：assigned_area 字段存储逗号分隔的多个区域（如 "城区,郊区"），用 == 只能匹配整个字符串，导致多区域管理员只能看到第一个区域的数据。

规则：所有涉及 assigned_area 的过滤都必须先 split 再用 .in_()：

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 中设置：

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 不受影响：

@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 内置模块：

healthcheck:
  test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
  interval: 15s
  timeout: 10s
  retries: 5
  start_period: 40s

More 分页标记清除不能使用 [^\n]* 删除整行

问题：_clean_output 中 ---- More ----[^\n]* 会将 ---- More ---- 及其后同行所有内容删除。当 OLT 输出的 More 提示与下一页第一条设备数据出现在同一行时（如 ---- More ----\r\r 1484-778f-aa60 ...），该设备行会被错误丢弃，导致部分设备扫描不到。

规则：仅移除 More 标记文本本身，保留同行后续内容：

# 错误：删除整行
output = re.sub(r'---- More ----[^\n]*', '', output)

# 正确：仅移除标记文本
output = re.sub(r'---- More ----', '', output)

此问题在 OLT 172.16.0.18（大化县新城初中）上发现：93 台设备仅解析出 90 台，丢失 3 台。

---

项目结构

H3ConuMS2/
├── backend/              # Python 后端
│   ├── app/
│   │   ├── api/v1/      # API 路由
│   │   ├── core/        # 核心配置
│   │   ├── middleware/  # 中间件（权限、审计）
│   │   ├── models/      # 数据模型
│   │   ├── schemas/     # Pydantic 模式
│   │   ├── services/    # 业务逻辑（SSH、IMC、导入等）
│   │   └── tasks/       # Celery 任务
│   ├── alembic/         # 数据库迁移
│   ├── scripts/         # 初始化脚本
│   └── templates/       # Excel 导入模板
├── frontend/            # Vue 3 前端
│   └── src/
│       ├── api/         # API 调用封装
│       ├── components/  # 公共组件
│       ├── composables/ # 组合式函数
│       ├── router/      # 路由
│       ├── stores/      # Pinia 状态管理
│       ├── styles/      # 主题样式
│       ├── utils/       # 工具函数
│       └── views/       # 页面组件
├── deploy/              # 部署配置
│   ├── docker-compose.yml
│   ├── nginx/
│   └── scripts/
├── docs/                # 文档
└── docker-compose.yml   # 主部署文件

---

核心业务逻辑

SSH 状态检查流程

1. 从数据库获取 OLT 设备配置
2. 建立 SSH 连接（使用连接池）
3. 执行命令：display onu slot {slot_number}
4. 解析返回结果：
   • 包含 "Up" → 在线
   • 包含 "Offline" → 离线
5. 更新设备状态到数据库
6. 记录历史状态

权限控制逻辑

• 超级管理员：所有权限
• 管理员：管理所有设备和用户
• 区域管理员：管理指定区域的设备
• 学校管理员：管理指定学校的设备
• 普通用户：只读权限

数据导入流程

1. 上传 Excel 文件
2. 使用 Pandas 解析数据
3. 数据验证（MAC 地址格式、必填字段）
4. 批量插入数据库
5. 返回导入结果（成功/失败记录）

---

开发指南

快速启动

Docker 部署（推荐）：

# 1. 配置环境变量
cp backend/.env.example backend/.env
# 编辑 .env 填入实际配置

# 2. 启动所有服务
docker compose up -d

# 3. 初始化数据库
docker compose exec backend python scripts/init_db.py

本地开发：

# 后端
cd backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 前端
cd frontend
npm install && npm run dev

# Celery Worker
cd backend
celery -A celery_worker.celery_app worker --loglevel=info

# Celery Beat
cd backend
celery -A celery_worker.celery_app beat --loglevel=info --schedule=/tmp/celerybeat-schedule

数据库迁移

# 创建迁移
alembic revision --autogenerate -m "描述"

# 执行迁移
alembic upgrade head

# 回滚
alembic downgrade -1

添加新功能

1. 后端 API：

   • 在 app/api/v1/ 创建路由文件
   • 在 app/services/ 创建服务文件
   • 在 app/schemas/ 定义请求/响应模式
   • 在 app/models/ 定义数据模型（如需要）

2. 前端页面：

   • 在 views/ 创建页面组件
   • 在 api/ 添加 API 调用
   • 在 router/ 添加路由配置
   • 在 stores/ 添加状态管理（如需要）

---

常见问题

SSH 连接失败

• 检查网络连通性
• 验证 SSH 凭证
• 检查防火墙设置
• 查看日志：docker-compose logs backend

数据库连接失败

• 检查 DATABASE_URL 配置
• 验证数据库服务状态
• 检查网络权限

Casdoor 登录失败

• 检查 Casdoor 服务状态
• 验证 CASDOOR_* 配置
• 检查回调地址配置

---

参考文档

• FastAPI 文档
• Vue 3 文档
• Element Plus 文档
• Casdoor 文档
• 现场ONU故障排查指南

MCP Tools: code-review-graph

IMPORTANT: This project has a knowledge graph. ALWAYS use the code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore the codebase. The graph is faster, cheaper (fewer tokens), and gives you structural context (callers, dependents, test coverage) that file scanning cannot.

When to use graph tools FIRST

• Exploring code: semantic_search_nodes or query_graph instead of Grep
• Understanding impact: get_impact_radius instead of manually tracing imports
• Code review: detect_changes + get_review_context instead of reading entire files
• Finding relationships: query_graph with callers_of/callees_of/imports_of/tests_for
• Architecture questions: get_architecture_overview + list_communities

Fall back to Grep/Glob/Read only when the graph doesn't cover what you need.

Key Tools

Tool	Use when
detect_changes	Reviewing code changes — gives risk-scored analysis
get_review_context	Need source snippets for review — token-efficient
get_impact_radius	Understanding blast radius of a change
get_affected_flows	Finding which execution paths are impacted
query_graph	Tracing callers, callees, imports, tests, dependencies
semantic_search_nodes	Finding functions/classes by name or keyword
get_architecture_overview	Understanding high-level codebase structure
refactor_tool	Planning renames, finding dead code

Workflow

1. The graph auto-updates on file changes (via hooks).
2. Use detect_changes for code review.
3. Use get_affected_flows to understand impact.
4. Use query_graph pattern="tests_for" to check coverage.