初始化

2026-04-02 23:40:04 +08:00
commit 381ea7085d
107 changed files with 11858 additions and 0 deletions
@@ -0,0 +1,335 @@
+# 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)