v6ole/H3ConuMS-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dfa8fa62a8ddd47ceb9c8b68ea1466c3e34c914e
H3ConuMS-v2/CLAUDE.md
T
v6ole 381ea7085d 初始化
2026-04-02 23:40:04 +08:00

8.1 KiB
Raw Blame History

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

项目概述

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

当前版本: v0.5.0 开发状态: 核心功能已完成

已实现功能：

  • ✅ SSH 连接 H3C OLT 设备查询 ONU 状态（支持 More 分页）
  • ✅ Excel 数据导入和批量管理
  • ✅ 定时自动状态检查（每30分钟）+ 手动触发
  • ✅ Casdoor 统一认证和 JWT 令牌管理
  • ✅ 设备管理（列表、详情、筛选、分页）
  • ✅ 统计仪表板（总数、在线、离线）
  • ✅ 权限管理基础框架（RBAC）

技术栈：

  • 后端：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} - 获取设备详情

状态检查

  • POST /api/check/status - 手动触发状态检查

数据导入

  • POST /api/import/upload - 上传并导入 Excel 文件

统计信息

  • GET /api/stats/summary - 获取统计摘要（总数、在线、离线）

系统

  • 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

开发规则

环境配置

  • 开发环境使用 .env.development
  • 生产环境使用 .env.production
  • 不提交 .env 文件到 Git
  • 提供 .env.example 模板

测试要求

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

文档要求

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

部署规则

Docker 部署

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

环境变量

必需配置：

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

监控告警

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

项目结构

H3ConuMS2/
├── backend/              # Python 后端
│   ├── app/
│   │   ├── api/         # API 路由
│   │   ├── core/        # 核心配置
│   │   ├── models/      # 数据模型
│   │   ├── schemas/     # Pydantic 模式
│   │   ├── services/    # 业务逻辑
│   │   ├── tasks/       # Celery 任务
│   │   └── utils/       # 工具函数
│   ├── alembic/         # 数据库迁移
│   └── tests/           # 测试代码
├── frontend/            # Vue 前端
│   └── src/
│       ├── api/         # API 调用
│       ├── components/  # 组件
│       ├── router/      # 路由
│       ├── stores/      # 状态管理
│       ├── views/       # 页面
│       └── utils/       # 工具函数
├── deploy/              # 部署配置
│   ├── docker-compose.yml
│   └── nginx.conf
└── docs/                # 文档

核心业务逻辑

SSH 状态检查流程

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

权限控制逻辑

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

数据导入流程

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

开发指南

快速启动

后端：

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 app.core.celery_app worker --loglevel=info

Celery Beat：

cd backend
celery -A app.core.celery_app beat --loglevel=info

Docker 部署：

# 配置环境变量
cp backend/.env.example backend/.env

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

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

数据库迁移

# 创建迁移
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_* 配置
  • 检查回调地址配置

参考文档

Reference in New Issue View Git Blame Copy Permalink