# H3C ONU设备管理系统 - 系统设计文档

## 项目概述
基于Python后端 + Vue前端的H3C OLT设备监控管理系统，用于监控4000+ ONU设备的在线状态，支持权限管理、数据导入、状态检查等功能。

## 设计讨论记录
**讨论时间**: 2026年4月1日
**参与人员**: 阿森、小柚（AI助手）

## 一、核心需求

### 1.1 设备状态监控
- 通过SSH连接H3C OLT设备查询ONU状态
- 支持不同插槽命令：`display onu slot 1`、`display onu slot 3`等
- 状态判断：返回结果包含"Up"为在线，"Offline"为离线
- 4000+设备MAC地址和物理位置信息管理

### 1.2 数据管理
- Excel表格导入（4000条记录）
- PostgreSQL数据库存储
- 设备信息包括：区域、学校名称、楼宇、场所类型、房间号、MAC地址、状态、备注

### 1.3 更新频率
- 自动更新：每30分钟
- 手动刷新：5分钟冷却限制
- 历史记录：保存90天

### 1.4 权限管理
- 多级用户权限（超级管理员、管理员、区域管理员、学校管理员、普通用户）
- Casdoor统一认证集成
- 基于RBAC的权限控制
- 设备信息变更审核流程

### 1.5 部署要求
- Docker Compose编排
- 外部PostgreSQL和Redis
- 环境变量配置（.env文件）
- 支持后续功能扩展（库存管理等）

## 二、系统架构

### 2.1 技术栈
**后端**:
- Python FastAPI
- PostgreSQL
- Paramiko (SSH)
- Celery + Redis (异步任务)
- Pandas (Excel处理)
- Casdoor SDK (认证)

**前端**:
- Vue 3 + Composition API
- Element Plus UI
- Axios
- Vue Router
- Pinia

### 2.2 部署架构
```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Nginx反向代理  │    │   FastAPI后端   │    │   Celery Worker  │
│                 │◄──►│                 │◄──►│                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                        │                        │
         ▼                        ▼                        ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Vue前端静态文件 │    │  PostgreSQL数据库 │    │     Redis      │
│                 │    │   (外部)         │    │    (外部)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                     ┌─────────────────┐
                     │    Casdoor      │
                     │  认证服务器     │
                     └─────────────────┘
```

## 三、数据库设计

### 3.1 核心表结构

#### olt_devices (OLT设备表)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | BIGSERIAL PRIMARY KEY | 主键 |
| ip_address | VARCHAR(45) | OLT设备IP地址 |
| username | VARCHAR(100) | SSH用户名 |
| password | TEXT | SSH密码（加密存储） |
| slot_command | VARCHAR(50) | 插槽命令，如"display onu slot 1" |
| description | TEXT | 设备描述 |
| created_at | TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | 更新时间 |

#### onu_devices (ONU设备表)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | BIGSERIAL PRIMARY KEY | 主键 |
| mac_address | VARCHAR(17) | MAC地址 (1484-7790-5200格式) |
| olt_id | BIGINT REFERENCES olt_devices(id) | 关联的OLT设备ID |
| slot_number | INTEGER | 插槽号 |
| port_number | INTEGER | 端口号 |
| region | VARCHAR(100) | 区域（共和乡） |
| school_name | VARCHAR(200) | 学校名称 |
| building | VARCHAR(100) | 楼宇 |
| location_type | VARCHAR(100) | 场所类型 |
| room_number | VARCHAR(50) | 房间号 |
| notes | TEXT | 备注 |
| created_at | TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | 更新时间 |

#### device_status_history (设备状态历史表)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | BIGSERIAL PRIMARY KEY | 主键 |
| onu_device_id | BIGINT REFERENCES onu_devices(id) | ONU设备ID |
| status | VARCHAR(20) | 状态（online/offline） |
| checked_at | TIMESTAMP | 检查时间 |
| response_data | TEXT | 原始响应数据 |
| created_at | TIMESTAMP | 创建时间 |

#### users (用户表 - Casdoor集成)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | BIGSERIAL PRIMARY KEY | 主键 |
| casdoor_id | VARCHAR(100) UNIQUE | Casdoor用户ID |
| username | VARCHAR(100) | 用户名 |
| email | VARCHAR(255) | 邮箱 |
| role | VARCHAR(50) | 角色 |
| assigned_area | VARCHAR(100) | 分配区域 |
| assigned_school | VARCHAR(200) | 分配学校 |
| is_active | BOOLEAN DEFAULT true | 是否激活 |
| last_login | TIMESTAMP | 最后登录 |
| sync_at | TIMESTAMP | 最后同步时间 |
| created_at | TIMESTAMP | 创建时间 |

#### permissions (权限表)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | BIGSERIAL PRIMARY KEY | 主键 |
| name | VARCHAR(100) | 权限名称 |
| code | VARCHAR(50) UNIQUE | 权限代码 |
| module | VARCHAR(50) | 所属模块 |
| description | TEXT | 权限描述 |

#### role_permissions (角色权限关联表)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| role_id | BIGINT | 角色ID |
| permission_id | BIGINT | 权限ID |
| PRIMARY KEY (role_id, permission_id) | | |

#### device_change_requests (设备变更请求表)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | BIGSERIAL PRIMARY KEY | 主键 |
| device_id | BIGINT REFERENCES onu_devices(id) | 设备ID |
| requested_by | BIGINT REFERENCES users(id) | 请求用户 |
| change_type | VARCHAR(50) | 变更类型 |
| current_data | JSONB | 当前数据 |
| requested_data | JSONB | 请求数据 |
| status | VARCHAR(20) | 状态 |
| reviewed_by | BIGINT REFERENCES users(id) | 审核人 |
| reviewed_at | TIMESTAMP | 审核时间 |
| change_reason | TEXT | 变更原因 |
| created_at | TIMESTAMP | 创建时间 |

## 四、API接口设计

### 4.1 认证相关
```
POST   /api/auth/login          # Casdoor登录回调
GET    /api/auth/profile        # 获取用户信息
POST   /api/auth/logout         # 退出登录
```

### 4.2 设备管理
```
GET    /api/devices             # 获取设备列表（分页、筛选）
GET    /api/devices/{id}        # 获取设备详情
GET    /api/devices/{id}/history # 获取设备历史状态
POST   /api/devices/import      # 导入Excel文件
PUT    /api/devices/{id}        # 更新设备信息（管理员）
POST   /api/devices/{id}/change-request # 提交变更请求
```

### 4.3 状态检查
```
POST   /api/check/status        # 手动触发状态检查
GET    /api/check/progress      # 获取检查进度
GET    /api/check/history       # 获取检查历史
GET    /api/check/schedule      # 获取定时任务配置
PUT    /api/check/schedule      # 更新定时任务配置
```

### 4.4 统计信息
```
GET    /api/stats/summary       # 获取统计摘要
GET    /api/stats/trend         # 获取趋势数据
GET    /api/stats/area          # 按区域统计
GET    /api/stats/school        # 按学校统计
```

### 4.5 权限管理
```
GET    /api/users               # 获取用户列表
GET    /api/users/{id}          # 获取用户详情
PUT    /api/users/{id}          # 更新用户信息
GET    /api/roles               # 获取角色列表
GET    /api/permissions         # 获取权限列表
GET    /api/change-requests     # 获取变更请求列表
PUT    /api/change-requests/{id}/review # 审核变更请求
```

## 五、前端界面设计

### 5.1 页面结构
1. **登录页面** - Casdoor统一登录
2. **仪表板** - 统计卡片、图表、手动刷新
3. **设备列表** - 表格展示、筛选、搜索
4. **设备详情** - 详细信息、历史图表
5. **数据导入** - Excel上传、预览、历史
6. **审核中心** - 变更请求审核
7. **系统设置** - OLT设备管理、任务配置
8. **用户管理** - 用户列表、权限分配

### 5.2 权限控制
- **页面级权限**：路由守卫控制
- **组件级权限**：v-permission指令
- **数据级权限**：API过滤用户数据
- **操作级权限**：按钮显示控制

## 六、Casdoor集成方案

### 6.1 配置参数
```python
CASDOOR = {
    "endpoint": "https://casdoor.example.com",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "certificate": "your_certificate",
    "org_name": "your_org_name",
    "app_name": "h3c-onu-ms",
    "redirect_url": "http://localhost:8000/api/auth/callback"
}
```

### 6.2 登录流程
1. 前端重定向到Casdoor登录页
2. 用户登录后回调到系统
3. 后端验证code获取用户信息
4. 同步用户信息到本地数据库
5. 生成JWT令牌返回前端

### 6.3 权限映射
- Casdoor角色 → 系统角色（配置映射）
- Casdoor属性 → 分配区域/学校
- 支持动态权限同步

## 七、Docker部署配置

### 7.1 docker-compose.yml
```yaml
version: '3.8'

services:
  backend:
    build: ./backend
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://user:pass@host:5432/dbname
      - REDIS_URL=redis://host:6379/0
      - CASDOOR_CONFIG=${CASDOOR_CONFIG}
    volumes:
      - ./logs:/app/logs
    depends_on:
      - redis
    restart: unless-stopped

  celery-worker:
    build: ./backend
    command: celery -A app.celery_app worker --loglevel=info
    environment:
      - DATABASE_URL=postgresql://user:pass@host:5432/dbname
      - REDIS_URL=redis://host:6379/0
    volumes:
      - ./logs:/app/logs
    depends_on:
      - redis
    restart: unless-stopped

  celery-beat:
    build: ./backend
    command: celery -A app.celery_app beat --loglevel=info
    environment:
      - DATABASE_URL=postgresql://user:pass@host:5432/dbname
      - REDIS_URL=redis://host:6379/0
    volumes:
      - ./logs:/app/logs
    depends_on:
      - redis
    restart: unless-stopped

  frontend:
    build: ./frontend
    ports:
      - "8080:80"
    environment:
      - VITE_API_BASE_URL=http://localhost:8000
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./ssl:/etc/nginx/ssl
    depends_on:
      - backend
      - frontend
    restart: unless-stopped

  redis:
    image: redis:alpine
    restart: unless-stopped
```

### 7.2 .env.example
```env
# 数据库配置
DATABASE_URL=postgresql://username:password@host:5432/dbname
REDIS_URL=redis://host:6379/0

# Casdoor配置
CASDOOR_ENDPOINT=https://casdoor.example.com
CASDOOR_CLIENT_ID=your_client_id
CASDOOR_CLIENT_SECRET=your_client_secret
CASDOOR_CERTIFICATE=your_certificate
CASDOOR_ORG_NAME=your_org
CASDOOR_APP_NAME=h3c-onu-ms

# 应用配置
SECRET_KEY=your-secret-key-here
DEBUG=false
ALLOWED_HOSTS=localhost,127.0.0.1

# SSH配置
SSH_TIMEOUT=30
SSH_MAX_CONNECTIONS=10
```

## 八、后续功能规划

### 8.1 库存管理模块
- 设备库存管理
- 出入库记录
- 库存预警
- 供应商管理

### 8.2 告警通知模块
- 设备离线告警
- 库存预警通知
- 支持邮件、企业微信、钉钉通知
- 告警规则配置

### 8.3 报表导出模块
- 设备状态报表
- 历史记录报表
- 统计图表导出
- 自定义报表模板

### 8.4 移动端适配
- 响应式移动端界面
- PWA支持
- 移动端专属功能

## 九、开发计划

### 9.1 第一阶段（基础功能）
1. 项目框架搭建
2. 数据库设计和迁移
3. Casdoor集成
4. 基础API开发
5. 前端框架搭建

### 9.2 第二阶段（核心功能）
1. Excel导入功能
2. SSH连接和状态检查
3. 设备列表和详情页
4. 定时任务调度
5. 基础权限控制

### 9.3 第三阶段（高级功能）
1. 权限管理系统
2. 变更审核流程
3. 统计图表
4. 系统设置页面
5. 性能优化

### 9.4 第四阶段（扩展功能）
1. 库存管理模块
2. 告警通知系统
3. 报表导出功能
4. 移动端适配

## 十、风险评估和应对

### 10.1 技术风险
1. **SSH连接稳定性**
   - 风险：网络波动导致连接失败
   - 应对：连接池、重试机制、超时设置

2. **性能问题**
   - 风险：4000+设备查询性能
   - 应对：异步处理、分批查询、缓存优化

3. **安全性**
   - 风险：SSH凭证存储安全
   - 应对：加密存储、访问控制、审计日志

### 10.2 业务风险
1. **数据准确性**
   - 风险：设备状态误判
   - 应对：多重验证、人工复核机制

2. **用户接受度**
   - 风险：操作复杂度过高
   - 应对：用户培训、简化流程、良好UI

## 十一、总结

本系统设计基于实际业务需求，采用现代化的技术栈和架构，具备良好的扩展性和维护性。通过Casdoor集成实现统一认证，基于RBAC的权限管理系统支持复杂的权限控制需求，Docker化部署确保环境一致性。

系统将分阶段实施，优先保证核心功能的稳定运行，逐步扩展高级功能。建议在开发过程中保持与业务人员的密切沟通，及时调整需求。

---
**文档版本**: v1.0
**最后更新**: 2026年4月1日
**下次评审**: 2026年4月15日