336 lines
8.1 KiB
Markdown
336 lines
8.1 KiB
Markdown
# 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. 返回导入结果（成功/失败记录）
|
||
|
||
---
|
||
|
||
## 开发指南
|
||
|
||
### 快速启动
|
||
|
||
**后端**：
|
||
```bash
|
||
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
|
||
```
|
||
|
||
**前端**：
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
**Celery Worker**：
|
||
```bash
|
||
cd backend
|
||
celery -A app.core.celery_app worker --loglevel=info
|
||
```
|
||
|
||
**Celery Beat**：
|
||
```bash
|
||
cd backend
|
||
celery -A app.core.celery_app beat --loglevel=info
|
||
```
|
||
|
||
**Docker 部署**：
|
||
```bash
|
||
# 配置环境变量
|
||
cp backend/.env.example backend/.env
|
||
|
||
# 启动所有服务
|
||
docker-compose up -d
|
||
|
||
# 初始化数据库
|
||
docker-compose exec backend python scripts/init_db.py
|
||
```
|
||
|
||
### 数据库迁移
|
||
|
||
```bash
|
||
# 创建迁移
|
||
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 文档](https://fastapi.tiangolo.com/)
|
||
- [Vue 3 文档](https://vuejs.org/)
|
||
- [Element Plus 文档](https://element-plus.org/)
|
||
- [Casdoor 文档](https://casdoor.org/)
|
||
- [项目详细设计](./系统设计文档.md)
|
||
- [开发计划](./开发计划.md)
|