v6ole/H3ConuMS-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

```

Browse Source 
feat: 升级到v0.8.0版本并新增审计日志等功能

- 升级版本号从v0.7.0到v0.8.0
- 新增审计日志功能，支持全量操作记录、筛选查询和CSV导出
- 新增设备更换记录功能，支持MAC地址更换历史与库存序列号联动
- 新增iOS PWA主屏幕支持，实现standalone模式safe area适配
- 删除过时的技术流程文档
- 补充开发规范说明，包括Alembic迁移、Celery worker重建、区域管理员过滤等重要规则
```
This commit is contained in:
v6ole
2026-04-08 16:59:24 +08:00
parent f1f8518985
commit dcb2435514
17 changed files with 77 additions and 3630 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+76 -1
View File
@@ -4,7 +4,7 @@
这是一个基于 Python FastAPI + Vue 3 的 H3C OLT 设备监控管理系统，用于监控 4000+ ONU 设备的在线状态。
**当前版本**: v0.7.0
**当前版本**: v0.8.0
**开发状态**: 核心功能已完成，权限与运维功能完善中
**已实现功能**：
@@ -24,6 +24,9 @@
- ✅ 系统设置（管理员可配置检查间隔，显示下次扫描时间/扫描中状态）
- ✅ 库存管理模块（物料、序列号设备、出入库、盘点）
- ✅ 每日状态快照（凌晨1点聚合，用于趋势图性能优化）
- ✅ 审计日志（全量操作记录、筛选查询、CSV 导出）
- ✅ 设备更换记录（MAC 地址更换历史，与库存序列号联动）
- ✅ iOS PWA 主屏幕支持（standalone 模式 safe area 适配）
**技术栈**：
- 后端：Python FastAPI + PostgreSQL + Celery + Redis + Paramiko
@@ -253,6 +256,78 @@ docker compose rm -f backend && docker compose up -d backend
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 都必须重建：
```bash
docker compose build --no-cache backend celery-worker
docker compose rm -f backend celery-worker
docker compose up -d backend celery-worker
```
验证任务是否注册：
```bash
docker compose exec celery-worker celery -A celery_worker.celery_app inspect registered
```
### 区域管理员多区域过滤必须用 `.in_()` 而非 `==`
**问题**：`assigned_area` 字段存储逗号分隔的多个区域（如 `"城区,郊区"`），用 `==` 只能匹配整个字符串，导致多区域管理员只能看到第一个区域的数据。
**规则**：所有涉及 `assigned_area` 的过滤都必须先 split 再用 `.in_()`：
```python
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` 中设置：
```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 不受影响：
```css
@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 内置模块：
```yaml
healthcheck:
test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
interval: 15s
timeout: 10s
retries: 5
start_period: 40s
```
---
## 项目结构
MAC关联OLT流程.md
-34
View File
@@ -1,34 +0,0 @@
MAC 地址关联OLT的流程应该是这样：
1. 先远程连接上OLT设备，然后输入 `dis onu slot 1`命令，查看olt设备中已经注册的ONU设备信息。注意有“---- More ----”的时候需要键入空格查看更多信息。
```
[16OLT]dis onu slot 1
---------------------------------- Olt1/0/1 ---------------------------------
MAC LOID LLID Dist(M) Port Model/Version Sft/Epm State Aging
1484-778f-cb20 N/A N/A Onu1/0/1:1 N/A N/A Offline N/A
1484-7790-2d20 N/A N/A Onu1/0/1:2 N/A N/A Offline N/A
1484-778f-d620 N/A N/A Onu1/0/1:3 N/A N/A Offline N/A
1484-7790-6220 N/A N/A Onu1/0/1:4 N/A N/A Offline N/A
1484-778f-8e80 N/A N/A Onu1/0/1:5 N/A N/A Offline N/A
1484-778f-a420 N/A N/A Onu1/0/1:6 N/A N/A Offline N/A
---------------------------------- Olt1/0/2 ---------------------------------
MAC LOID LLID Dist(M) Port Model/Version Sft/Epm State Aging
1484-778e-b7e0 1 12384 Onu1/0/2:1 WA6520H-EGPON/A 106/ Up N/A
1484-778e-b4a0 2 12364 Onu1/0/2:2 WA6520H-EGPON/A 106/ Up N/A
1484-778e-a860 4 12414 Onu1/0/2:4 WA6520H-EGPON/A 106/ Up N/A
1484-778e-bce0 5 12387 Onu1/0/2:5 WA6520H-EGPON/A 106/ Up N/A
1484-778e-b400 6 12388 Onu1/0/2:6 WA6520H-EGPON/A 106/ Up N/A
1484-778f-49c0 7 12364 Onu1/0/2:7 WA6520H-EGPON/A 106/ Up N/A
1484-778f-22a0 8 12384 Onu1/0/2:8 WA6520H-EGPON/A 106/ Up N/A
1484-778e-b9c0 9 12417 Onu1/0/2:9 WA6520H-EGPON/A 106/ Up N/A
1484-778f-1aa0 N/A N/A Onu1/0/2:3 N/A N/A Offline N/A
1484-778f-1dc0 N/A N/A Onu1/0/2:10 N/A N/A Offline N/A
1484-778e-f1e0 N/A N/A Onu1/0/2:11 N/A N/A Offline N/A
---------------------------------- Olt1/0/3 ---------------------------------
MAC LOID LLID Dist(M) Port Model/Version Sft/Epm State Aging
---- More ----
```
2. 将OLT返回的信息分析后返回到前端的“设备列表”，并展示给用户。比如“1484-778e-b7e0”这个MAC地址，表示的离OLT的距离是12384米，在Onu1/0/2:1端口中，它的状态是Up（在线）。只需要向前端提供这三个信息就好了。然后再将这个MAC地址关联到这台OLT下。
3. 在数据库中创建一个表，用于存储MAC地址和olt设备之间的关联关系。这个表应该包含三个字段：MAC地址、olt设备ID和olt设备端口。
1. 将设备列表页面的MAC地址变为可以点击，点击后弹出对话框，可以显示距离(12384米)、端口(Onu1/0/2:1)，以及后续可能需要新增的编辑按钮、业务下发按钮等等帮我
MAC关联OLT流程改进建议.md
-434
View File
@@ -1,434 +0,0 @@
# MAC关联OLT流程改进建议
## 文档信息
- **分析时间**: 2026年4月2日
- **分析对象**: `MAC关联OLT流程.md`
- **分析重点**: 与系统设计匹配度、40个OLT设备扩展性
- **目标读者**: 后端开发同事
## 一、当前流程分析
### 1.1 文档描述流程
1. 远程连接OLT设备 → 执行`dis onu slot 1`命令
2. 解析返回的ONU设备信息
3. 提取MAC地址、距离、端口、状态信息
4. 将信息展示给前端并关联到OLT
### 1.2 系统实现现状
**匹配度评分**: 70%
| 功能点 | 文档描述 | 系统实现 | 状态 |
|--------|----------|----------|------|
| SSH连接 | 远程连接OLT | `SSHService.connect()` | ✅ 已实现 |
| 命令执行 | `dis onu slot 1` | `execute_command()` | ✅ 已实现 |
| 分页处理 | "---- More ----" | 空格键继续 | ✅ 已实现 |
| MAC地址提取 | 1484-778f-cb20格式 | `parse_onu_status()` | ✅ 已实现 |
| 状态解析 | Up/Offline | 解析状态字段 | ✅ 已实现 |
| 距离提取 | 12384米 | ❌ 未实现 | ❌ 缺失 |
| 端口解析 | Onu1/0/2:1 | ❌ 未完整解析 | ⚠️ 需改进 |
| 数据关联 | 关联到OLT | `olt_id`外键 | ✅ 已实现 |
### 1.3 主要问题
1. **数据提取不完整**: 当前只解析状态，未提取距离和详细端口信息
2. **数据库字段缺失**: 缺少`distance`字段存储距离信息
3. **端口解析不足**: 需要从"Onu1/0/2:1"解析为`slot_number`和`port_number`
## 二、40个OLT设备扩展性挑战
### 2.1 当前方案问题（串行执行）
| 问题 | 影响程度 | 说明 |
|------|----------|------|
| 执行效率低 | 高 | 40个OLT串行检查，预计20-40分钟 |
| SSH连接开销 | 中 | 每个OLT独立连接，建立/断开开销大 |
| 网络延迟累积 | 中 | 网络不佳的OLT会阻塞整个流程 |
| 资源占用 | 中 | 可能同时维护多个SSH连接 |
| 错误传播 | 高 | 一个OLT失败可能影响后续检查 |
### 2.2 性能预估
| 方案 | 40个OLT检查时间 | 资源占用 | 实现复杂度 | 推荐度 |
|------|----------------|----------|------------|--------|
| 当前串行 | ~20-40分钟 | 低 | 低 | ⭐ |
| 并行10并发 | ~2-4分钟 | 中 | 中 | ⭐⭐⭐⭐⭐ |
| 并行20并发 | ~1-2分钟 | 高 | 高 | ⭐⭐⭐ |
## 三、改进方案建议
### 3.1 方案一：并行处理 + 连接池（推荐）
#### 3.1.1 架构设计
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Celery主任务 │───▶│ OLT检查任务分发 │───▶│ 并行执行检查 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ SSH连接池管理 │◄───│ 连接复用机制 │◄───│ 并发控制(10) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
#### 3.1.2 核心组件
1. **任务分发器**: 将40个OLT检查拆分为独立Celery任务
2. **连接池管理器**: 复用SSH连接，减少建立/断开开销
3. **并发控制器**: 限制最大并发数（建议10个）
4. **结果聚合器**: 收集各OLT检查结果，统一存储
#### 3.1.3 代码实现建议
**A. SSH连接池实现**
```python
# app/services/ssh_pool.py
import paramiko
from typing import Dict, Optional
from threading import Lock
class SSHConnectionPool:
"""SSH连接池，支持连接复用"""
def __init__(self, max_connections: int = 10):
self.pool: Dict[str, paramiko.SSHClient] = {}
self.lock = Lock()
self.max_connections = max_connections
def get_connection(self, host: str, username: str, password: str) -> paramiko.SSHClient:
"""获取或创建SSH连接"""
key = f"{host}:{username}"
with self.lock:
if key in self.pool:
client = self.pool[key]
# 检查连接是否仍然有效
try:
transport = client.get_transport()
if transport and transport.is_active():
return client
except:
pass
# 创建新连接
if len(self.pool) >= self.max_connections:
# 清理最久未使用的连接
self._cleanup_oldest()
client = paramiko.SSHClient()
client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
client.connect(hostname=host, username=username, password=password, timeout=30)
self.pool[key] = client
return client
def _cleanup_oldest(self):
"""清理最久未使用的连接"""
# 简化实现：清理第一个连接
if self.pool:
key = next(iter(self.pool))
try:
self.pool[key].close()
except:
pass
del self.pool[key]
```
**B. 增强的解析器**
```python
# app/services/onu_parser.py
import re
from typing import Dict, List, Optional
from dataclasses import dataclass
@dataclass
class ONUInfo:
"""ONU设备完整信息"""
mac_address: str
status: str # online/offline
distance_m: Optional[int] = None # 距离（米）
slot_number: Optional[int] = None # 插槽号
port_number: Optional[int] = None # 端口号
loid: Optional[str] = None # LOID
model: Optional[str] = None # 设备型号
class ONUParser:
"""增强的ONU信息解析器"""
@staticmethod
def parse_output(output: str) -> List[ONUInfo]:
"""解析OLT命令输出"""
devices = []
lines = output.split('\n')
current_slot = None
for line in lines:
# 检测新的插槽区域
slot_match = re.search(r'Olt(\d+)/(\d+)/(\d+)', line)
if slot_match:
current_slot = int(slot_match.group(1))
continue
# 跳过表头行
if 'MAC' in line and 'LOID' in line:
continue
# 解析设备行
device = ONUParser._parse_device_line(line, current_slot)
if device:
devices.append(device)
return devices
@staticmethod
def _parse_device_line(line: str, slot: Optional[int]) -> Optional[ONUInfo]:
"""解析单行设备信息"""
# 匹配MAC地址
mac_match = re.search(r'([0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4})', line, re.IGNORECASE)
if not mac_match:
return None
mac = mac_match.group(1).lower()
# 提取状态
status = 'offline'
if 'Up' in line:
status = 'online'
# 提取距离
distance = None
dist_match = re.search(r'(\d+)\s*Dist\(M\)', line)
if dist_match:
distance = int(dist_match.group(1))
# 提取端口信息
slot_num, port_num = None, None
port_match = re.search(r'Onu(\d+)/(\d+)/(\d+):(\d+)', line)
if port_match:
slot_num = int(port_match.group(1))
port_num = int(port_match.group(4))
# 提取LOID
loid = None
loid_match = re.search(r'\s+(\d+)\s+', line)
if loid_match:
loid = loid_match.group(1)
return ONUInfo(
mac_address=mac,
status=status,
distance_m=distance,
slot_number=slot_num or slot,
port_number=port_num,
loid=loid
)
```
**C. 并行检查任务**
```python
# app/tasks/parallel_check_tasks.py
from celery import group
from app.tasks.check_tasks import check_single_olt
from app.models.device import OLTDevice
from sqlalchemy.orm import Session
def check_all_olts_parallel(db: Session, max_concurrent: int = 10):
"""并行检查所有OLT设备"""
# 获取所有OLT设备
olts = db.query(OLTDevice).all()
if not olts:
return {"message": "没有可检查的OLT设备"}
# 创建任务组
tasks = []
for olt in olts:
tasks.append(check_single_olt.s(olt.id))
# 分批执行，控制并发数
results = []
for i in range(0, len(tasks), max_concurrent):
batch = tasks[i:i + max_concurrent]
job = group(batch)
result = job.apply_async()
results.extend(result.get()) # 等待批次完成
return {
"total_olts": len(olts),
"completed": len([r for r in results if r.get("success")]),
"failed": len([r for r in results if not r.get("success")]),
"results": results
}
```
### 3.2 方案二：数据库优化
#### 3.2.1 新增字段建议
```sql
-- 在onu_devices表中新增字段
ALTER TABLE onu_devices ADD COLUMN IF NOT EXISTS distance_m INTEGER;
ALTER TABLE onu_devices ADD COLUMN IF NOT EXISTS loid VARCHAR(50);
ALTER TABLE onu_devices ADD COLUMN IF NOT EXISTS model VARCHAR(100);
ALTER TABLE onu_devices ADD COLUMN IF NOT EXISTS last_seen TIMESTAMP;
-- 在olt_devices表中新增字段
ALTER TABLE olt_devices ADD COLUMN IF NOT EXISTS max_concurrent INTEGER DEFAULT 5;
ALTER TABLE olt_devices ADD COLUMN IF NOT EXISTS check_timeout INTEGER DEFAULT 60;
```
#### 3.2.2 数据模型更新
```python
# app/models/device.py - 更新ONUDevice模型
class ONUDevice(Base):
__tablename__ = "onu_devices"
# 现有字段...
distance_m = Column(Integer) # 新增：距离（米）
loid = Column(String(50)) # 新增：LOID
model = Column(String(100)) # 新增：设备型号
last_seen = Column(TIMESTAMP) # 新增：最后在线时间
# 索引优化
__table_args__ = (
Index('idx_mac_olt', 'mac_address', 'olt_id'),
Index('idx_status_checked', 'status', 'last_seen'),
)
```
### 3.3 方案三：监控与告警增强
#### 3.3.1 检查任务监控
```python
# app/services/monitor_service.py
class CheckMonitor:
"""检查任务监控服务"""
@staticmethod
def get_check_stats(db: Session):
"""获取检查统计信息"""
stats = {
"total_olts": db.query(OLTDevice).count(),
"total_onus": db.query(ONUDevice).count(),
"online_onus": db.query(ONUDevice)
.join(DeviceStatusHistory)
.filter(DeviceStatusHistory.status == 'online')
.distinct().count(),
"recent_checks": db.query(DeviceStatusHistory)
.order_by(DeviceStatusHistory.checked_at.desc())
.limit(10).all()
}
return stats
@staticmethod
def check_olt_health(olt: OLTDevice) -> Dict:
"""检查OLT健康状态"""
# 测试连接
ssh = SSHService(olt.ip_address, olt.username, olt.password)
try:
start_time = time.time()
ssh.connect()
connect_time = time.time() - start_time
# 执行简单命令测试
output = ssh.execute_command("display version")
return {
"olt_id": olt.id,
"status": "healthy",
"connect_time": connect_time,
"response_time": len(output) / 1024, # KB/s
"timestamp": datetime.utcnow()
}
except Exception as e:
return {
"olt_id": olt.id,
"status": "unhealthy",
"error": str(e),
"timestamp": datetime.utcnow()
}
finally:
ssh.close()
```
## 四、实施计划建议
### 4.1 第一阶段：基础改进（1-2天）
1. 增强ONU信息解析器，提取完整字段
2. 更新数据库模型，新增必要字段
3. 修改现有检查逻辑，存储完整信息
### 4.2 第二阶段：并行化改造（3-5天）
1. 实现SSH连接池
2. 改造Celery任务为并行执行
3. 添加并发控制和错误处理
4. 测试10个OLT并发场景
### 4.3 第三阶段：优化与监控（2-3天）
1. 添加检查任务监控
2. 实现健康检查机制
3. 优化数据库查询性能
4. 添加告警通知功能
### 4.4 第四阶段：压力测试（1-2天）
1. 模拟40个OLT并发检查
2. 测试网络异常情况
3. 验证系统稳定性
4. 性能调优
## 五、风险与应对
### 5.1 技术风险
| 风险 | 可能性 | 影响 | 应对措施 |
|------|--------|------|----------|
| OLT连接超时 | 中 | 高 | 实现超时重试机制 |
| 并发连接过多 | 低 | 中 | 限制最大并发数 |
| 内存泄漏 | 低 | 高 | 添加连接池清理机制 |
| 数据库锁竞争 | 中 | 中 | 优化事务处理，使用批量操作 |
### 5.2 业务风险
| 风险 | 可能性 | 影响 | 应对措施 |
|------|--------|------|----------|
| 检查结果不一致 | 低 | 中 | 添加数据校验机制 |
| 检查时间过长 | 中 | 高 | 实现增量检查，优化查询 |
| 用户等待时间 | 中 | 中 | 提供进度查询接口 |
## 六、预期收益
### 6.1 性能提升
- **检查时间**: 从20-40分钟缩短到2-4分钟（10倍提升）
- **资源利用率**: SSH连接复用减少50%连接开销
- **系统稳定性**: 错误隔离避免单点故障影响全局
### 6.2 功能增强
- **数据完整性**: 完整记录距离、端口、LOID等信息
- **监控能力**: 实时监控检查任务状态和OLT健康度
- **扩展性**: 支持未来扩展到更多OLT设备
### 6.3 运维改善
- **故障诊断**: 详细的检查日志和错误信息
- **性能分析**: 检查任务性能统计和趋势分析
- **容量规划**: 基于实际负载的资源规划依据
## 七、后续建议
### 7.1 短期建议（1个月内）
1. 实现基础并行检查功能
2. 完成数据库字段扩展
3. 添加基础监控告警
### 7.2 中期建议（1-3个月）
1. 实现智能调度（基于OLT负载和网络状况）
2. 添加检查结果分析和报表
3. 集成自动化运维工具
### 7.3 长期建议（3-6个月）
1. 机器学习预测设备故障
2. 自动化故障恢复机制
3. 多数据中心部署支持
---
**文档维护**:
- 本文档应随系统改进同步更新
- 重大架构变更需更新本文档
- 实际实施中的调整应记录在案
**联系方式**:
- 如有疑问或建议，请通过项目沟通渠道反馈
- 实施过程中遇到问题及时记录并分享解决方案
OLT输出.md
-32
View File
@@ -1,32 +0,0 @@
<16OLT>dis onu slot 1
---------------------------------- Olt1/0/1 ---------------------------------
MAC LOID LLID Dist(M) Port Model/Version Sft/Epm State Aging
1484-7790-5200 12 <1000 Onu1/0/1:1 WA6520H-EGPON/A 106/ Up N/A
1484-7790-4e20 13 <1000 Onu1/0/1:2 WA6520H-EGPON/A 106/ Up N/A
1484-7790-3900 N/A N/A Onu1/0/1:3 N/A N/A Offline N/A
---------------------------------- Olt1/0/2 ---------------------------------
MAC LOID LLID Dist(M) Port Model/Version Sft/Epm State Aging
34dc-99c8-8320 5 <1000 Onu1/0/2:1 WA6520H-EGPON/A 106/ Up N/A
1484-778f-7b80 N/A N/A Onu1/0/2:2 N/A N/A Offline N/A
---------------------------------- Olt1/0/3 ---------------------------------
MAC LOID LLID Dist(M) Port Model/Version Sft/Epm State Aging
1484-778f-ba60 3 <1000 Onu1/0/3:1 WA6520H-EGPON/A 106/ Up N/A
1484-778f-5480 2 <1000 Onu1/0/3:2 WA6520H-EGPON/A 106/ Up N/A
1484-778f-eb80 N/A N/A Onu1/0/3:3 N/A N/A Offline N/A
1484-778f-b280 N/A N/A Onu1/0/3:4 N/A N/A Offline N/A
1484-778f-00c0 N/A N/A Onu1/0/3:5 N/A N/A Offline N/A
---------------------------------- Olt1/0/4 ---------------------------------
MAC LOID LLID Dist(M) Port Model/Version Sft/Epm State Aging
1484-778f-8960 13 <1000 Onu1/0/4:1 WA6520H-EGPON/A 106/ Up N/A
1484-778f-e9e0 8 <1000 Onu1/0/4:2 WA6520H-EGPON/A 106/ Up N/A
---- More ----
OLT可能会遇到多个MAC地址在不同端口的情况，这个情况是因为之前这个MAC已经在某个端口上，但是后来因为其他原因更换了端口，但是旧的端口上还有它的记录。如果是这种情况，需要把这个MAC记录下来，在OLT管理页面中新增一个“重复MAC地址”的按钮，后续可以通过命令删除这些旧的MAC地址（后期再实现）。
再帮我优化一下设备列表页面：
1. “状态”新增“未知”选项
2. 点击“全部更新”按钮后，执行所有OLT扫描功能，并更新设备状态（不需要入库，只需要更新MAC的在线情况和距离）。
再帮我优化一下OLT管理功能：
1.
frontend/vite.config.js
+1
View File
@@ -6,6 +6,7 @@ export default defineConfig({
server: {
host: '0.0.0.0',
port: 5173,
allowedHosts: ['all', 'onu.dhdx.fun'],
proxy: {
'/api': {
target: process.env.VITE_API_PROXY_TARGET || 'http://localhost:8001',
下发业务流程.md
-22
View File
@@ -1,22 +0,0 @@
# H3C ONU设备下发上网业务步骤
1. 先查看需要下发业务的设备MAC在OLT的哪个口下面，需要进入OLT对应的槽位，如slot 1
`display onu slot 1 | include 1484-778e-a860`
• OLT返回内容
`1484-778e-a860 4 12414 Onu1/0/2:4 WA6520H-EGPON/A 106/ Up N/A`
2. 进入系统配置
`system-view`
3. 进入端口设备的端口
`interface Onu1/0/2:4`
4. 配置ONU
```
uni 1 vlan-mode trunk pvid 4094 2000 to 2000 3000 to 3010
port link-type trunk
undo port trunk permit vlan 1
port trunk permit vlan 2000 3000 to 3010 4094
```
5. 保存（输入save force后需要稍等一下才会出现Saved the current configuration to mainboard device successfully.）
```
[16OLT-Onu1/0/2:4]save force
Validating file. Please wait...
Saved the current configuration to mainboard device successfully.
```
关闭OLT端口.md
-53
View File
@@ -1,53 +0,0 @@
1. 查看所有接口简要状态`
`,olt输出示例如下：“Olt1/0/1”就是OLT的端口名称，“UP”表示当前端口是开启的状态；“DOWN”表示当前端口是关闭的状态；
```
<8OLT>display interface brief
Brief information on interfaces in route mode:
Link: ADM - administratively down; Stby - standby
Protocol: (s) - spoofing
Interface Link Protocol Primary IP Description
InLoop0 UP UP(s) --
Loop100 UP UP(s) 172.16.0.72
NULL0 UP UP(s) --
REG0 UP -- --
Vlan100 UP UP 172.16.3.29
Vlan2000 UP UP 172.21.35.254 WIFI-user
Vlan3000 UP UP 172.31.35.254 PC-user
Vlan4094 UP UP 172.17.36.254 AP-Manage
Brief information on interfaces in bridge mode:
Link: ADM - administratively down; Stby - standby
Speed: (a) - auto
Duplex: (a)/A - auto; H - half; F - full
Type: A - access; T - trunk; H - hybrid
Interface Link Speed Duplex Type PVID Description
GE1/0/9 DOWN auto A A 1
GE1/0/10 DOWN auto A A 1
GE1/0/11 DOWN auto A A 1
GE1/0/12 DOWN auto A A 1
GE1/0/13 DOWN auto A A 1
GE1/0/14 DOWN auto A A 1
GE1/0/15 DOWN auto A A 1
GE1/0/16 UP 1G(a) F(a) T 100 TO-DH-BLCWXZHL-2F-3610
Olt1/0/1 UP -- -- T 1
Olt1/0/2 UP -- -- T 1
Olt1/0/3 UP -- -- T 1
Olt1/0/4 DOWN -- -- T 1
Olt1/0/5 UP -- -- T 1
Olt1/0/6 DOWN -- -- T 1
Olt1/0/7 UP -- -- T 1
Olt1/0/8 DOWN -- -- T 1
Onu1/0/1:1 DOWN -- -- T 1
Onu1/0/1:2 DOWN -- -- T 1
Onu1/0/1:3 DOWN -- -- T 1
Onu1/0/1:4 DOWN -- -- T 1
Onu1/0/1:5 DOWN -- -- T 1
Onu1/0/1:6 UP -- -- T 1
Onu1/0/1:7 UP -- -- T 1
Onu1/0/1:8 DOWN -- -- T 1
```
2. 进入系统视图`system-view`
3. 进入端口视图`interface Olt1/0/1`
4. 关闭端口`shutdown`& 开启端口`undo shutdown`
5. 退出`quit`
启动指南.md
-58
View File
@@ -1,58 +0,0 @@
# 快速启动指南
## ✅ 当前状态
- 后端服务：http://localhost:8000 ✅ 运行中
- 前端服务：http://localhost:5173 ✅ 运行中
- 数据库：已初始化 ✅
- API 文档：http://localhost:8000/docs ✅
## 访问系统
打开浏览器访问：**http://localhost:5173**
---
## 后端服务
### 启动命令
```bash
cd backend
source venv/bin/activate
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```
### 停止服务
按 `Ctrl+C`
## 前端服务
### 启动命令
```bash
cd frontend
npm run dev
```
### 访问地址
- 前端：http://localhost:5173
- 后端 API：http://localhost:8000
- API 文档：http://localhost:8000/docs
## 环境配置
确保 `backend/.env` 文件已配置：
- DATABASE_URL
- REDIS_URL
- CASDOOR_* 配置
- SECRET_KEY
## 故障排除
### 后端启动失败
1. 检查虚拟环境：`source venv/bin/activate`
2. 检查依赖：`pip list`
3. 检查 .env 配置
### 数据库连接失败
检查 DATABASE_URL 配置是否正确
---
**最后更新**：2026-04-01
审计日志系统设计方案.md
-535
View File
@@ -1,535 +0,0 @@
# H3C ONU设备管理系统 - 审计日志系统设计方案
## 项目概述
本方案为 H3C ONU 设备管理系统设计一套完整的审计日志系统，用于记录所有用户操作（手动和自动触发），支持误操作恢复和问责追溯。
## 设计目标
1. **全面记录**：记录所有用户操作，包括认证、设备管理、OLT端口操作等
2. **详细审计**：记录操作详情（用户、时间、IP、参数、结果等）
3. **快速查询**：提供超级管理员查询界面
4. **长期存储**：日志保留90天，支持自动清理
5. **性能友好**：异步执行，不影响主业务流程
6. **Docker友好**：支持容器化部署，日志映射到宿主机
## 系统架构
### 整体架构图
```
用户操作 → API请求 → 审计日志中间件 → 异步任务队列 →
↓
[数据库] 记录核心信息 + [文件系统] 记录详细日志
↓
查询界面 ← 日志服务 ← 定期清理任务
```
### 技术栈
- **后端框架**：FastAPI + SQLAlchemy + Celery
- **数据库**：PostgreSQL（核心信息）+ 文件系统（详细日志）
- **消息队列**：Redis（Celery broker）
- **存储**：Docker卷映射到宿主机
## 详细设计
### 1. 数据库设计
#### 1.1 审计日志表 (`audit_logs`)
```sql
CREATE TABLE audit_logs (
id SERIAL PRIMARY KEY,
-- 用户信息
user_id VARCHAR(100) NOT NULL,
username VARCHAR(100) NOT NULL,
user_role VARCHAR(50),
-- 操作信息
action_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
action_type VARCHAR(50) NOT NULL, -- 操作类型
action_subtype VARCHAR(50), -- 操作子类型
-- 请求信息
ip_address VARCHAR(45),
user_agent TEXT,
request_method VARCHAR(10),
request_path VARCHAR(500),
-- 操作结果
status VARCHAR(20) NOT NULL, -- success, failed, error
status_code INTEGER,
-- 资源信息
resource_type VARCHAR(50), -- device, olt, port, user, etc.
resource_id VARCHAR(100),
resource_name VARCHAR(200),
-- 简要信息
description TEXT NOT NULL,
-- 详细日志
request_params JSONB,
response_data JSONB,
error_message TEXT,
-- 文件存储
details_file_path VARCHAR(500),
-- 元数据
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);
-- 索引设计
CREATE INDEX idx_audit_logs_action_time ON audit_logs(action_time);
CREATE INDEX idx_audit_logs_user_id ON audit_logs(user_id);
CREATE INDEX idx_audit_logs_action_type ON audit_logs(action_type);
CREATE INDEX idx_audit_logs_resource_type ON audit_logs(resource_type);
CREATE INDEX idx_audit_logs_status ON audit_logs(status);
```
#### 1.2 操作类型分类
| 操作类型 | 操作子类型 | 描述 | 示例 |
|---------|-----------|------|------|
| `auth` | `login`, `logout`, `token_refresh` | 认证相关操作 | 用户登录、登出 |
| `device` | `create`, `update`, `delete`, `status_check`, `import` | 设备管理操作 | 创建设备、更新设备信息 |
| `olt` | `create`, `update`, `delete`, `port_enable`, `port_disable` | OLT管理操作 | 启用/关闭OLT端口 |
| `user` | `create`, `update`, `delete`, `role_change` | 用户管理操作 | 创建用户、修改角色 |
| `system` | `config_update`, `task_trigger`, `cleanup` | 系统操作 | 触发状态检查、清理任务 |
| `inventory` | `stock_in`, `stock_out`, `transfer`, `count` | 库存管理操作 | 入库、出库、盘点 |
### 2. 文件存储设计
#### 2.1 目录结构
```
logs/
├── audit/ # 审计日志目录
│ ├── 2025-04-05/ # 按日期分目录
│ │ ├── auth/ # 按操作类型分子目录
│ │ │ ├── login_20250405193500_user123_abc123.json
│ │ │ └── logout_20250405194000_user456_def456.json
│ │ ├── device/
│ │ ├── olt/
│ │ └── ...
│ ├── 2025-04-06/
│ └── ...
├── app/ # 应用日志目录
│ └── app.log
└── celery/ # Celery任务日志目录
└── celery.log
```
#### 2.2 详细日志文件格式（JSON）
```json
{
"log_id": "abc123def456",
"audit_log_id": 12345,
"timestamp": "2025-04-05T19:35:00+08:00",
"user": {
"id": "user123",
"username": "张三",
"role": "admin",
"ip_address": "192.168.1.100"
},
"action": {
"type": "olt_port_enable",
"subtype": "port_operation",
"description": "启用OLT端口",
"resource": {
"type": "olt_port",
"id": "olt-1-port-2",
"name": "OLT-1端口2"
}
},
"request": {
"method": "POST",
"path": "/api/olt/1/port/2/enable",
"headers": {
"user-agent": "Mozilla/5.0...",
"content-type": "application/json"
},
"body": {
"reason": "设备上线",
"operator": "张三"
},
"query_params": {}
},
"response": {
"status_code": 200,
"body": {
"success": true,
"message": "端口启用成功",
"data": {
"port_id": "olt-1-port-2",
"status": "enabled",
"enabled_at": "2025-04-05T19:35:00+08:00"
}
}
},
"execution": {
"duration_ms": 1250,
"start_time": "2025-04-05T19:34:58.750+08:00",
"end_time": "2025-04-05T19:35:00.000+08:00"
},
"system": {
"service": "backend",
"version": "v0.7.0",
"environment": "production"
}
}
```
### 3. 组件设计
#### 3.1 审计日志中间件 (`audit_middleware.py`)
**功能**：
- 拦截所有API请求（排除健康检查、文档等）
- 提取请求和响应信息
- 异步发送日志到任务队列
**关键特性**：
- 支持请求体读取（JSON格式）
- 支持响应体捕获
- 异常处理，不影响主流程
- 性能监控（记录执行时间）
#### 3.2 审计日志服务 (`audit_service.py`)
**功能**：
- 解析日志数据，确定操作类型
- 创建数据库记录
- 保存详细日志到文件系统
- 提供查询接口
**关键方法**：
- `create_audit_log()`: 创建日志记录
- `query_logs()`: 查询日志（支持多条件筛选）
- `cleanup_old_logs()`: 清理90天前的日志
- `export_logs()`: 导出日志
#### 3.3 Celery任务 (`audit_tasks.py`)
**功能**：
- 异步处理日志记录
- 定期清理任务
- 日志归档任务
**任务列表**：
- `create_audit_log_task`: 创建审计日志
- `cleanup_audit_logs_task`: 清理旧日志（每天执行）
- `archive_audit_logs_task`: 归档日志（每月执行）
#### 3.4 API接口 (`audit_api.py`)
**端点设计**：
| 端点 | 方法 | 描述 | 权限 |
|------|------|------|------|
| `/api/audit/logs` | GET | 查询审计日志 | 超级管理员 |
| `/api/audit/logs/{id}` | GET | 获取单条日志详情 | 超级管理员 |
| `/api/audit/logs/export` | POST | 导出日志 | 超级管理员 |
| `/api/audit/stats` | GET | 获取日志统计 | 超级管理员 |
**查询参数**：
- `start_time`: 开始时间
- `end_time`: 结束时间
- `user_id`: 用户ID
- `action_type`: 操作类型
- `resource_type`: 资源类型
- `status`: 状态（success/failed/error）
- `page`: 页码
- `page_size`: 每页数量
### 4. 前端界面设计
#### 4.1 日志查询页面
**功能**：
- 时间范围选择器
- 多条件筛选（用户、操作类型、状态等）
- 分页显示
- 导出功能
**界面元素**：
- 查询条件表单
- 日志列表表格
- 分页控件
- 导出按钮
#### 4.2 日志详情页面
**功能**：
- 显示日志详细信息
- 查看详细日志文件内容
- 操作回放（显示请求和响应）
## 实施步骤
### 阶段一：基础框架搭建（1-2天）
1. **创建数据库模型**
- 创建 `audit_logs` 表
- 添加数据库迁移
2. **实现基础服务**
- 创建 `AuditService` 类
- 实现日志创建和存储逻辑
3. **配置Docker**
- 更新 `docker-compose.yml` 日志映射
- 确保目录权限正确
### 阶段二：中间件和异步处理（2-3天）
1. **实现审计中间件**
- 创建 `AuditMiddleware`
- 集成到FastAPI应用
2. **实现Celery任务**
- 创建审计日志任务
- 配置任务队列
3. **测试异步流程**
- 验证日志记录不阻塞主流程
- 测试异常处理
### 阶段三：查询接口和界面（2-3天）
1. **实现API接口**
- 创建审计日志查询端点
- 实现多条件筛选
2. **开发前端界面**
- 创建日志查询页面
- 实现筛选和分页功能
3. **实现导出功能**
- 支持JSON/CSV格式导出
- 批量导出功能
### 阶段四：清理和优化（1-2天）
1. **实现自动清理**
- 创建清理任务
- 测试清理逻辑
2. **性能优化**
- 数据库查询优化
- 文件IO优化
3. **监控和告警**
- 添加日志记录监控
- 设置磁盘空间告警
## 配置要求
### 环境变量
```bash
# 审计日志配置
AUDIT_LOG_ENABLED=true
AUDIT_LOG_RETENTION_DAYS=90
AUDIT_LOG_DIR=/app/logs/audit
AUDIT_LOG_LEVEL=INFO
# Celery配置
CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/0
```
### Docker配置更新
```yaml
services:
backend:
build: ./backend
volumes:
- ./backend/logs:/app/logs # 应用日志
- ./logs/audit:/app/logs/audit # 审计日志专用目录
environment:
- AUDIT_LOG_ENABLED=true
- AUDIT_LOG_DIR=/app/logs/audit
```
## 测试方案
### 单元测试
1. **服务层测试**
- 测试 `AuditService.create_audit_log()`
- 测试 `AuditService.query_logs()`
- 测试 `AuditService.cleanup_old_logs()`
2. **中间件测试**
- 测试请求拦截
- 测试异常处理
- 测试性能影响
### 集成测试
1. **端到端测试**
- 模拟用户操作，验证日志记录
- 测试查询接口
- 测试导出功能
2. **性能测试**
- 高并发下的日志记录性能
- 大数据量下的查询性能
### 验收测试
1. **功能验收**
- 验证所有操作类型都被记录
- 验证查询功能正常工作
- 验证清理功能按预期工作
2. **非功能验收**
- 性能：日志记录不影响API响应时间（<50ms）
- 可靠性：日志不丢失，可追溯
- 安全性：只有超级管理员可访问
## 维护和监控
### 日常维护
1. **磁盘空间监控**
- 监控日志目录大小
- 设置磁盘使用率告警（>80%）
2. **性能监控**
- 监控日志记录延迟
- 监控数据库查询性能
3. **定期检查**
- 每周检查清理任务执行情况
- 每月检查日志完整性
### 故障处理
1. **日志记录失败**
- 检查Celery worker状态
- 检查磁盘空间
- 检查文件权限
2. **查询性能下降**
- 优化数据库索引
- 增加查询缓存
- 考虑分表策略
## 扩展性考虑
### 未来扩展
1. **实时告警**
- 敏感操作实时通知
- 异常模式检测
2. **日志分析**
- 操作趋势分析
- 用户行为分析
3. **审计报告**
- 定期生成审计报告
- 合规性报告
### 性能优化
1. **数据库优化**
- 分区表（按时间分区）
- 读写分离
2. **存储优化**
- 压缩旧日志
- 冷热数据分离
## 风险评估和缓解措施
| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|----------|
| 磁盘空间不足 | 日志记录失败 | 中 | 1. 设置磁盘监控告警<br>2. 实现自动清理<br>3. 使用日志轮转 |
| 性能影响 | API响应变慢 | 低 | 1. 异步处理<br>2. 批量写入<br>3. 性能测试 |
| 数据丢失 | 审计追溯失败 | 低 | 1. 双重存储（DB+文件）<br>2. 定期备份<br>3. 监控告警 |
| 安全风险 | 日志泄露 | 中 | 1. 严格权限控制<br>2. 日志加密存储<br>3. 访问审计 |
## 成功标准
1. **功能完整性**
- 所有用户操作都被记录
- 支持多条件查询
- 支持日志导出
2. **性能指标**
- 日志记录延迟 < 100ms
- 查询响应时间 < 2s（1000条记录）
- 系统资源占用 < 5%
3. **可靠性**
- 日志不丢失率 > 99.9%
- 自动清理任务成功率 100%
- 系统可用性 > 99.5%
## 附录
### A. 文件清单
```
backend/
├── app/
│ ├── models/
│ │ └── audit_log.py # 审计日志模型
│ ├── middleware/
│ │ └── audit_middleware.py # 审计中间件
│ ├── services/
│ │ └── audit_service.py # 审计服务
│ ├── tasks/
│ │ └── audit_tasks.py # Celery任务
│ ├── api/
│ │ └── v1/
│ │ └── audit.py # 审计API
│ └── core/
│ └── config.py # 配置更新
├── alembic/
│ └── versions/ # 数据库迁移文件
└── tests/
└── test_audit.py # 测试文件
frontend/
└── src/
├── views/
│ └── AuditLogView.vue # 审计日志页面
├── api/
│ └── audit.js # 审计API调用
└── stores/
└── audit.js # 审计状态管理
```
### B. 依赖更新
**后端依赖**：
```txt
# requirements.txt 新增
python-json-logger==2.0.7
celery==5.3.4
redis==5.0.1
```
**前端依赖**：
```json
// package.json 新增
"date-fns": "^3.0.0",
"xlsx": "^0.18.5"
```
### C. 部署检查清单
- [ ] 数据库迁移已执行
- [ ] 环境变量已配置
- [ ] Docker卷映射已更新
- [ ] 目录权限已设置
- [ ] Celery worker已启动
- [ ] 清理任务已调度
-
库存管理功能设计方案.md
-532
View File
@@ -1,532 +0,0 @@
# H3C ONU设备管理系统 - 库存管理功能设计方案
## 项目背景
基于与项目负责人的详细讨论，为H3C ONU设备管理系统增加库存管理功能，用于管理项目中现有的实体设备（ONU、OLT、交换机、防火墙、上网行为管理等）的出入库台账。
## 设计讨论记录
**讨论时间**: 2026年4月5日
**参与人员**: 阿森、小柚（AI助手）
## 一、需求分析
### 1.1 核心需求
1. **设备全生命周期管理**：从采购入库 → 领用出库 → 安装使用 → 退库归还 → 报废处理
2. **物料分类管理**：支持ONU设备、OLT设备、交换机、防火墙、上网行为管理等
3. **库存台账管理**：记录基本信息、唯一标识、库存数量、位置信息、状态信息
4. **业务流程管理**：批量入库、领用出库、退库归还、报废/报修处理、盘点调整
5. **系统集成需求**：与现有设备监控系统深度集成，设备安装时更新位置信息，报废时从监控系统移除
### 1.2 用户场景
1. **仓库管理员**：管理物料入库、出库、盘点
2. **运维人员**：领用设备进行现场安装
3. **采购人员**：新设备采购入库
4. **管理人员**：查看库存报表，进行决策
### 1.3 功能范围
- 物料分类管理
- 库存台账管理
- 出入库流程管理
- 盘点管理
- 报表统计
- 与现有系统集成
## 二、整体架构设计
### 2.1 架构方案：集成扩展方案
**选择理由**：
1. **无缝集成**：与现有设备监控系统深度集成
2. **数据一致**：共享用户、权限、设备基础数据
3. **流程连贯**：设备完整生命周期管理
4. **技术复用**：复用现有的Excel导入、权限控制、UI组件
### 2.2 系统关系图
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 库存管理系统 │◄────►│ 设备监控系统 │◄────►│ 权限管理系统 │
│ │ │ │ │ (Casdoor) │
├─────────────────┤ ├─────────────────┤ └─────────────────┘
│ • 物料管理 │ │ • ONU状态监控 │
│ • 出入库台账 │ │ • OLT管理 │
│ • 库存统计 │ │ • 实时告警 │
│ • 领用审批 │ │ • 历史记录 │
└─────────────────┘ └─────────────────┘
│ │
└─────────────────────────┘
设备生命周期流转
```
### 2.3 技术架构
- **后端**：在现有FastAPI基础上扩展库存管理模块
- **前端**：在现有Vue 3基础上增加库存管理页面
- **数据库**：在现有PostgreSQL中新增库存相关表
- **权限**：集成现有权限系统，新增库存管理权限
- **导入导出**：复用现有Excel导入组件
## 三、详细功能设计
### 3.1 物料分类管理
#### 支持的设备类型：
1. ONU设备（与现有系统深度集成）
2. OLT设备（与现有OLT管理集成）
3. 交换机
4. 防火墙
5. 上网行为管理
6. 光模块等配件
#### 物料属性：
- **基本信息**：名称、型号、规格、品牌、单位
- **唯一标识**：
- ONU设备：MAC地址（与现有系统一致）
- OLT设备：IP地址 + 序列号
- 交换机：MAC地址 + 序列号
- 防火墙：序列号 + 资产编号
- 上网行为管理：序列号
- **库存信息**：当前数量、安全库存
- **位置信息**：仓库位置（项目专用仓库，无货架管理）
- **状态信息**：全新、已使用、待维修、报废
- **供应商信息**：供应商、采购日期、采购价格
### 3.2 库存管理方式
采用**混合管理模式**：
- **高价值设备**：序列号管理（每个设备单独跟踪）
- **低价值配件**：批次管理（按采购批次跟踪）
- **简单数量管理**：只记录总数（适用于消耗品）
### 3.3 出入库流程设计
#### A. 采购入库流程
```
Excel模板导入 → 批量入库 → 生成采购单 → 审核入库 → 更新库存
```
- 支持现有Excel导入方式
- 自动生成采购单编号
- 支持分批入库
#### B. 领用出库流程
```
选择物料 → 填写领用信息 → 登记安装信息 → 确认出库 → 同步到监控系统
```
- 管理员直接操作，无需审批流程
- 领用时预填安装信息（学校、楼宇、房间等）
- 自动创建监控设备记录
#### C. 退库归还流程
```
选择退库设备 → 选择退库类型 → 更新状态 → 退回库存
```
支持四种退库类型：
1. **简单退库**：状态变回库存，保留历史记录
2. **维修退库**：标记为待维修，进入维修流程
3. **报废退库**：进入报废流程，从监控系统移除
4. **带历史退库**：保留完整的安装和使用历史
### 3.4 库存管理功能
#### A. 库存总览
- 按设备类型统计数量
- 库存价值统计
- 库存状态分布（全新/已使用/待维修）
- 低库存预警
#### B. 定期盘点
- 每月/每季度全盘
- 盘点差异记录
- 盘点报告生成
- 库存数量调整
#### C. 报表统计
1. **库存总览报表**：各类物料数量和价值统计
2. **领用统计报表**：按人员、项目、时间统计
3. **库存预警报表**：低于安全库存的物料提醒
4. **设备生命周期报告**：设备从入库到报废的全过程
### 3.5 状态流转设计
```
库存中 (in_stock)
↓ 领用
已分配 (allocated)
↓ 安装
已安装 (installed)
↓ 投入使用
使用中 (in_use)
├─→ 简单退库 → 库存中
├─→ 维修退库 → 维修中 (repairing) → 维修完成 → 库存中
└─→ 报废退库 → 已报废 (scrapped)
```
## 四、数据库设计
### 4.1 核心数据表
```sql
-- 物料分类表
CREATE TABLE material_categories (
id BIGSERIAL PRIMARY KEY,
name VARCHAR(100) NOT NULL, -- 分类名称：ONU、OLT、交换机等
code VARCHAR(50) UNIQUE NOT NULL, -- 分类代码
description TEXT,
created_at TIMESTAMP DEFAULT NOW()
);
-- 物料主数据表
CREATE TABLE materials (
id BIGSERIAL PRIMARY KEY,
category_id BIGINT REFERENCES material_categories(id),
name VARCHAR(200) NOT NULL, -- 物料名称
model VARCHAR(100), -- 型号
specification TEXT, -- 规格
brand VARCHAR(100), -- 品牌
unit VARCHAR(20) DEFAULT '个', -- 单位
safe_quantity INTEGER DEFAULT 0, -- 安全库存
notes TEXT, -- 备注
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
-- 库存批次表（批次管理）
CREATE TABLE inventory_batches (
id BIGSERIAL PRIMARY KEY,
material_id BIGINT REFERENCES materials(id),
batch_no VARCHAR(50) NOT NULL, -- 批次号
quantity INTEGER NOT NULL, -- 批次数量
supplier VARCHAR(200), -- 供应商
purchase_date DATE, -- 采购日期
purchase_price DECIMAL(10,2), -- 采购单价
expiry_date DATE, -- 有效期（如有）
location VARCHAR(100), -- 仓库位置
status VARCHAR(20) DEFAULT 'in_stock', -- 状态：in_stock, reserved, out_of_stock
created_at TIMESTAMP DEFAULT NOW()
);
-- 序列号设备表（高价值设备单独跟踪）
CREATE TABLE serial_devices (
id BIGSERIAL PRIMARY KEY,
material_id BIGINT REFERENCES materials(id),
batch_id BIGINT REFERENCES inventory_batches(id),
serial_no VARCHAR(100) NOT NULL UNIQUE, -- 序列号
mac_address VARCHAR(17), -- MAC地址（ONU设备）
asset_no VARCHAR(50), -- 资产编号
status VARCHAR(20) DEFAULT 'in_stock', -- 状态：in_stock, allocated, installed, in_use, returned, repairing, scrapped
current_location VARCHAR(200), -- 当前位置
installed_info JSONB, -- 安装信息：学校、楼宇、房间等
onu_device_id BIGINT REFERENCES onu_devices(id), -- 关联监控设备
notes TEXT,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
-- 出入库记录表
CREATE TABLE inventory_transactions (
id BIGSERIAL PRIMARY KEY,
transaction_no VARCHAR(50) UNIQUE NOT NULL, -- 单据编号
transaction_type VARCHAR(20) NOT NULL, -- 类型：purchase_in, allocate_out, return_in, scrap_out, adjust
material_id BIGINT REFERENCES materials(id),
batch_id BIGINT REFERENCES inventory_batches(id),
serial_device_id BIGINT REFERENCES serial_devices(id),
quantity INTEGER NOT NULL,
from_status VARCHAR(20), -- 操作前状态
to_status VARCHAR(20), -- 操作后状态
operator_id BIGINT REFERENCES users(id), -- 操作人
project_name VARCHAR(200), -- 项目名称
installation_info JSONB, -- 安装信息
notes TEXT,
created_at TIMESTAMP DEFAULT NOW()
);
-- 盘点记录表
CREATE TABLE inventory_checks (
id BIGSERIAL PRIMARY KEY,
check_no VARCHAR(50) UNIQUE NOT NULL, -- 盘点单号
check_date DATE NOT NULL, -- 盘点日期
checker_id BIGINT REFERENCES users(id), -- 盘点人
material_id BIGINT REFERENCES materials(id),
batch_id BIGINT REFERENCES inventory_batches(id),
book_quantity INTEGER, -- 账面数量
actual_quantity INTEGER, -- 实际数量
difference INTEGER, -- 差异数量
reason TEXT, -- 差异原因
adjusted BOOLEAN DEFAULT FALSE, -- 是否已调整
created_at TIMESTAMP DEFAULT NOW()
);
```
### 4.2 数据关系图
```
material_categories
↑
materials ─┬─ inventory_batches
│
└─ serial_devices ───── onu_devices (现有表)
↑
inventory_transactions
↑
inventory_checks
```
## 五、与现有系统集成设计
### 5.1 设备流转集成
```python
# 领用出库时自动创建监控设备
def allocate_device(serial_device_id, installation_info):
# 1. 更新库存设备状态为 allocated
# 2. 如果设备类型是ONU，自动创建onu_devices记录
# 3. 关联serial_devices.onu_device_id
# 4. 初始化设备状态检查任务
# 安装完成时同步到监控系统
def install_device(serial_device_id, onu_device_id):
# 1. 更新库存设备状态为 installed
# 2. 更新onu_devices的安装位置信息
# 3. 开始定期状态监控
# 退库时处理监控设备
def return_device(serial_device_id, return_type):
if return_type == 'scrap':
# 报废：从监控系统移除，保留历史记录
deactivate_monitoring(serial_device_id)
else:
# 其他退库：暂停监控，设备状态标记为退库
pause_monitoring(serial_device_id)
```
### 5.2 权限集成
- 复用现有Casdoor用户体系
- 新增库存管理相关权限：
- `inventory:view` - 查看库存
- `inventory:manage` - 管理物料
- `inventory:transaction` - 出入库操作
- `inventory:check` - 盘点操作
- `inventory:report` - 查看报表
### 5.3 数据导入集成
- 复用现有的Excel导入组件
- 新增库存导入模板
- 支持批量设备入库
## 六、用户界面设计
### 6.1 桌面端界面布局
```
┌─────────────────────────────────────┐
│ 库存管理 │
├─────────────────────────────────────┤
│ [物料管理] [入库管理] [出库管理] │
│ [退库管理] [盘点管理] [报表统计] │
├─────────────────────────────────────┤
│ 主工作区 │
│ • 库存总览仪表板 │
│ • 物料列表（表格/卡片） │
│ • 出入库流水 │
└─────────────────────────────────────┘
```
### 6.2 移动端适配
- 复用移动端设计思路中的底部导航
- 增加"库存"标签页
- 移动端聚焦功能：库存查询、扫码盘点、快速领用
### 6.3 关键页面设计
1. **库存总览页面**：卡片式数据可视化，关键指标一目了然
2. **物料管理页面**：支持表格和卡片视图，可按分类筛选
3. **领用出库页面**：向导式操作流程，简化用户操作
4. **盘点管理页面**：支持移动端扫码，提高盘点效率
## 七、API接口设计
### 7.1 物料管理接口
```
GET /api/inventory/materials # 获取物料列表
POST /api/inventory/materials # 创建物料
GET /api/inventory/materials/{id} # 获取物料详情
PUT /api/inventory/materials/{id} # 更新物料
DELETE /api/inventory/materials/{id} # 删除物料
POST /api/inventory/materials/import # Excel导入物料
GET /api/inventory/materials/export # 导出物料列表
```
### 7.2 出入库接口
```
POST /api/inventory/transactions/purchase # 采购入库
POST /api/inventory/transactions/allocate # 领用出库
POST /api/inventory/transactions/return # 退库归还
POST /api/inventory/transactions/scrap # 报废处理
GET /api/inventory/transactions # 查询出入库记录
GET /api/inventory/transactions/{id} # 获取单据详情
```
### 7.3 库存查询接口
```
GET /api/inventory/summary # 库存总览
GET /api/inventory/status # 库存状态统计
GET /api/inventory/warning # 库存预警列表
GET /api/inventory/history/{device_id} # 设备流转历史
```
### 7.4 盘点管理接口
```
POST /api/inventory/checks # 创建盘点单
PUT /api/inventory/checks/{id} # 更新盘点结果
POST /api/inventory/checks/{id}/adjust # 执行库存调整
GET /api/inventory/checks # 查询盘点记录
GET /api/inventory/checks/{id}/report # 生成盘点报告
```
## 八、实施计划
### 第一阶段：基础框架（1-2周）
1. 数据库表结构创建和迁移脚本
2. 后端API基础框架搭建
3. 权限系统扩展（新增库存管理权限）
4. 基础物料管理功能实现
**交付物**：
- 数据库迁移文件
- 后端基础API
- 权限配置更新
### 第二阶段：核心功能（2-3周）
1. 出入库流程完整实现
2. Excel导入导出功能
3. 库存统计报表
4. 与监控系统集成开发
**交付物**：
- 完整的出入库功能
- Excel导入模板
- 库存报表功能
- 设备流转集成
### 第三阶段：高级功能（1-2周）
1. 移动端盘点功能
2. 库存预警系统
3. 设备生命周期报告
4. 性能优化和测试
**交付物**：
- 移动端盘点支持
- 预警系统
- 完整测试报告
## 九、技术实现要点
### 9.1 后端实现
- 新增`inventory`模块，目录结构：
```
backend/app/
├── api/
│ └── inventory/ # 库存管理API
├── models/
│ └── inventory.py # 库存数据模型
├── schemas/
│ └── inventory.py # 库存Pydantic模式
├── services/
│ └── inventory_service.py # 库存业务逻辑
└── tasks/
└── inventory_tasks.py # 库存相关异步任务
```
### 9.2 前端实现
- 新增库存管理路由和页面
- 复用现有的Element Plus组件
- 开发专用的库存管理组件
### 9.3 数据一致性保证
- 使用数据库事务保证库存操作的原子性
- 定期数据一致性检查任务
- 完整的操作日志记录
## 十、测试策略
### 10.1 功能测试
1. **单元测试**：每个API接口的独立测试
2. **集成测试**：库存流程与监控系统集成测试
3. **业务流程测试**：完整的出入库流程测试
4. **数据一致性测试**：库存数量与交易记录一致性验证
### 10.2 性能测试
1. **并发测试**：多用户同时操作库存
2. **大数据量测试**：导入大量设备数据
3. **响应时间测试**：关键操作响应时间
### 10.3 兼容性测试
1. **浏览器兼容**：主流浏览器测试
2. **移动端兼容**：手机浏览器测试
3. **Excel兼容**：不同版本Excel导入测试
## 十一、风险与应对
### 11.1 技术风险
1. **数据一致性风险**：采用数据库事务和定期检查
2. **性能风险**：大数据量时使用分页和缓存
3. **集成风险**：分阶段集成，先读后写
### 11.2 业务风险
1. **流程变更风险**：设计灵活的流程配置
2. **用户接受度风险**：提供培训和使用文档
3. **数据迁移风险**：制定详细的数据迁移计划
## 十二、维护与支持
### 12.1 监控指标
1. **库存操作成功率**：出入库操作成功比例
2. **数据一致性指标**：库存数量与实际数量差异
3. **用户使用指标**：各功能使用频率
### 12.2 运维支持
1. **日志记录**：详细的操作日志
2. **数据备份**：定期库存数据备份
3. **故障恢复**：数据不一致时的恢复流程
## 十三、预期效益
### 13.1 业务效益
1. **流程规范化**：设备从采购到报废的全生命周期管理
2. **库存可视化**：实时掌握库存状态，避免缺料和积压
3. **成本控制**：精确的设备资产管理和成本核算
4. **效率提升**：减少人工盘点时间，提高领用效率
### 13.2 管理效益
1. **决策支持**：基于数据的采购和库存优化决策
2. **责任追溯**：完整的设备流转历史记录
3. **合规管理**：符合资产管理规范要求
## 十四、后续扩展考虑
### 14.1 功能扩展
1. **供应商管理**：完整的供应商信息管理
2. **采购管理**：采购申请、比价、合同管理
3. **维修管理**：设备维修流程管理
4. **租赁管理**：设备租赁和归还管理
### 14.2 技术扩展
1. **条码/RFID支持**：自动化库存管理
2. **移动APP**：独立的库存管理APP
3. **API开放**：对外提供库存查询API
4. **数据分析**：基于AI的库存预测
## 十五、总结
本设计方案为H3C ONU设备管理系统增加了完整的库存管理功能，实现了设备从采购入库到报废退库的全生命周期管理。方案具有以下特点：
1. **深度集成**：与现有设备监控系统无缝集成
2. **流程完整**：覆盖采购、领用、安装、退库、报废全流程
3. **灵活配置**：支持不同设备类型的差异化管理
4. **用户友好**：简洁的界面和操作流程
5. **可扩展性强**：为后续功能扩展预留接口
该方案的实施将显著提升项目的设备管理水平和运营效率，为项目的长期发展奠定坚实基础。
---
**文档信息**：
- 创建时间：2026年4月5日
- 文档版本：v1.0
- 适用对象：开发团队、测试团队、运维团队
- 保密级别：内部使用
**备注**：
1. 本方案基于与项目负责人的详细讨论结果整理
2. 实施过程中可根据实际情况进行调整
3. 建议分阶段实施，降低风险
4. 重要变更需更新本文档并通知相关人员
开发总结.md
-128
View File
@@ -1,128 +0,0 @@
# H3C ONU设备管理系统 - 开发总结
## 项目完成情况
### 已完成阶段
**第一阶段（2周）** - ✅ 完成
- 后端 FastAPI 框架搭建
- 前端 Vue 3 + Element Plus 框架
- Casdoor 统一认证集成
- JWT 令牌管理
- Docker 部署配置
**第二阶段（4周）** - ✅ 完成
- 数据库模型设计（OLT、ONU、用户、历史）
- SSH 连接服务（支持 More 分页）
- ONU 状态解析逻辑
- 设备管理 API（列表、详情、筛选）
- Celery 异步任务系统
- 定时状态检查（每30分钟）
- Excel 批量导入功能
- 权限管理基础框架
## 核心功能实现
### 1. SSH 连接和状态检查
- ✅ Paramiko SSH 连接
- ✅ 自动处理 "More" 分页
- ✅ 解析 ONU 在线/离线状态
- ✅ 支持多 OLT 设备
### 2. 认证和权限
- ✅ Casdoor OAuth 2.0 登录
- ✅ JWT 令牌管理
- ✅ 基于角色的权限控制（RBAC）
- ✅ 用户信息同步
### 3. 设备管理
- ✅ 设备列表（分页、筛选）
- ✅ 设备详情查看
- ✅ 按区域/学校筛选
- ✅ Excel 批量导入
### 4. 异步任务
- ✅ Celery Worker 配置
- ✅ Celery Beat 定时任务
- ✅ 手动触发状态检查
- ✅ 自动定时检查（30分钟）
## 技术栈
**后端**：
- Python 3.11
- FastAPI
- SQLAlchemy
- Celery + Redis
- Paramiko
- Pandas
**前端**：
- Vue 3
- Element Plus
- Pinia
- Axios
- Vite
**部署**：
- Docker
- Docker Compose
- PostgreSQL（外部）
- Redis（外部）
## 项目结构
```
H3ConuMS2/
├── backend/
│ ├── app/
│ │ ├── api/v1/ # API 路由
│ │ ├── core/ # 核心配置
│ │ ├── models/ # 数据模型
│ │ ├── schemas/ # Pydantic Schema
│ │ ├── services/ # 业务逻辑
│ │ ├── tasks/ # Celery 任务
│ │ └── middleware/ # 中间件
│ ├── alembic/ # 数据库迁移
│ └── requirements.txt
├── frontend/
│ └── src/
│ ├── api/ # API 调用
│ ├── views/ # 页面组件
│ ├── stores/ # 状态管理
│ └── router/ # 路由配置
├── .claude/rules/ # Claude 开发规则
├── CLAUDE.md # 开发指南
└── docker-compose.yml
```
## 下一步开发建议
### 短期（1-2周）
1. 完善权限管理系统
2. 添加统计图表和仪表板
3. 实现设备变更审核流程
4. 优化性能和缓存
### 中期（1个月）
1. 库存管理模块
2. 告警通知系统
3. 报表导出功能
4. 移动端适配
### 长期
1. 系统监控和日志分析
2. 数据备份和恢复
3. 多租户支持
4. API 版本管理
## 启动指南
1. 配置环境变量：`cp backend/.env.example backend/.env`
2. 启动服务：`docker-compose up -d`
3. 访问系统：http://localhost:5173
---
**开发完成日期**：2026年4月1日
**当前版本**：v0.5.0
开发计划.md
-395
View File
@@ -1,395 +0,0 @@
# H3C ONU设备管理系统 - 开发计划
## 项目概述
基于Python FastAPI + Vue 3的H3C OLT设备监控管理系统，用于监控4000+ ONU设备的在线状态。
## 开发周期
**总周期**: 8-12周
**开始日期**: 2026年4月
**预计完成**: 2026年6月
## 第一阶段：项目基础搭建 (2周)
### 第1周：环境搭建和基础框架
**目标**: 完成开发环境搭建和基础项目结构
#### 后端任务
- [ ] 创建FastAPI项目结构
- [ ] 配置数据库连接（PostgreSQL + SQLAlchemy）
- [ ] 设置Alembic数据库迁移
- [ ] 配置日志系统
- [ ] 创建基础配置管理
- [ ] 设置单元测试框架
#### 前端任务
- [ ] 创建Vue 3项目（Vite）
- [ ] 集成Element Plus UI库
- [ ] 配置路由系统（Vue Router）
- [ ] 设置状态管理（Pinia）
- [ ] 配置API请求封装（Axios）
- [ ] 设置开发环境配置
#### 部署任务
- [ ] 创建Dockerfile（前后端）
- [ ] 编写docker-compose.yml
- [ ] 配置Nginx反向代理
- [ ] 设置环境变量管理
### 第2周：认证系统和基础API
**目标**: 实现Casdoor集成和基础API
#### 后端任务
- [ ] 集成Casdoor SDK
- [ ] 实现OAuth 2.0登录流程
- [ ] 创建JWT令牌管理
- [ ] 实现用户信息同步
- [ ] 创建基础CRUD API框架
- [ ] 实现API文档（Swagger/ReDoc）
#### 前端任务
- [ ] 实现Casdoor登录页面
- [ ] 创建登录状态管理
- [ ] 实现路由守卫（权限控制）
- [ ] 创建基础布局组件
- [ ] 实现API调用封装
- [ ] 创建错误处理机制
#### 测试任务
- [ ] 编写认证相关测试
- [ ] 测试API端点
- [ ] 测试前端组件
## 第二阶段：核心功能开发 (4周)
### 第3周：数据库设计和设备模型
**目标**: 完成数据库设计和设备管理基础功能
#### 后端任务
- [ ] 设计并创建数据库表结构
- [ ] olt_devices表
- [ ] onu_devices表
- [ ] device_status_history表
- [ ] 用户和权限相关表
- [ ] 创建SQLAlchemy模型
- [ ] 实现数据库迁移脚本
- [ ] 创建设备管理API
- [ ] 实现数据验证（Pydantic）
#### 前端任务
- [ ] 创建设备列表页面
- [ ] 实现表格组件
- [ ] 创建分页组件
- [ ] 实现搜索和筛选功能
- [ ] 创建设备详情页面
#### 数据库任务
- [ ] 初始化数据库
- [ ] 创建测试数据
- [ ] 配置数据库备份脚本
### 第4周：SSH连接和状态检查
**目标**: 实现SSH连接和设备状态检查功能
#### 后端任务
- [ ] 集成Paramiko SSH库
- [ ] 实现SSH连接池管理
- [ ] 创建命令执行和结果解析
- [ ] 实现设备状态检查服务
- [ ] 集成Celery异步任务
- [ ] 配置Redis消息队列
#### 前端任务
- [ ] 创建状态检查控制面板
- [ ] 实现手动刷新功能
- [ ] 创建检查进度显示
- [ ] 实现状态颜色标识
- [ ] 创建检查历史页面
#### 测试任务
- [ ] 测试SSH连接功能
- [ ] 测试命令解析逻辑
- [ ] 测试异步任务处理
### 第5周：Excel导入和数据管理
**目标**: 实现Excel数据导入和批量管理功能
#### 后端任务
- [ ] 集成Pandas库
- [ ] 实现Excel文件解析
- [ ] 创建数据导入服务
- [ ] 实现数据验证和清洗
- [ ] 创建批量导入API
- [ ] 实现导入历史记录
#### 前端任务
- [ ] 创建数据导入页面
- [ ] 实现文件上传组件
- [ ] 创建导入预览功能
- [ ] 实现导入进度显示
- [ ] 创建导入历史列表
#### 数据处理任务
- [ ] 编写数据转换脚本
- [ ] 创建数据验证规则
- [ ] 实现错误数据处理
### 第6周：权限管理系统
**目标**: 实现完整的RBAC权限管理系统
#### 后端任务
- [ ] 设计权限模型（RBAC）
- [ ] 实现角色和权限管理
- [ ] 创建权限检查中间件
- [ ] 实现数据级权限过滤
- [ ] 集成Casdoor权限同步
- [ ] 创建权限管理API
#### 前端任务
- [ ] 创建用户管理页面
- [ ] 实现角色管理界面
- [ ] 创建权限分配组件
- [ ] 实现权限指令（v-permission）
- [ ] 创建用户资料页面
#### 安全任务
- [ ] 实现密码加密存储
- [ ] 配置安全中间件
- [ ] 实现登录尝试限制
## 第三阶段：高级功能开发 (3周)
### 第7周：统计图表和仪表板
**目标**: 实现数据统计和可视化功能
#### 后端任务
- [ ] 创建统计计算服务
- [ ] 实现数据聚合查询
- [ ] 创建统计API端点
- [ ] 实现趋势分析功能
- [ ] 创建区域/学校统计
#### 前端任务
- [ ] 集成ECharts图表库
- [ ] 创建仪表板页面
- [ ] 实现统计卡片组件
- [ ] 创建图表组件
- [ ] 实现数据筛选联动
#### 数据任务
- [ ] 优化统计查询性能
- [ ] 实现数据缓存
- [ ] 创建统计数据导出
### 第8周：系统设置和审核流程
**目标**: 实现系统配置和设备变更审核
#### 后端任务
- [ ] 创建系统配置管理
- [ ] 实现OLT设备配置
- [ ] 创建定时任务配置
- [ ] 实现设备变更审核流程
- [ ] 创建审核通知机制
#### 前端任务
- [ ] 创建系统设置页面
- [ ] 实现OLT配置管理
- [ ] 创建任务配置界面
- [ ] 实现审核中心页面
- [ ] 创建变更请求表单
#### 工作流任务
- [ ] 设计审核流程状态机
- [ ] 实现通知系统
- [ ] 创建审核日志
### 第9周：性能优化和测试
**目标**: 优化系统性能和完善测试
#### 性能优化
- [ ] 数据库查询优化
- [ ] 实现缓存策略
- [ ] 优化SSH连接池
- [ ] 前端资源优化
- [ ] 实现懒加载
#### 测试完善
- [ ] 编写集成测试
- [ ] 进行性能测试
- [ ] 安全漏洞扫描
- [ ] 兼容性测试
#### 文档完善
- [ ] 完善API文档
- [ ] 编写用户手册
- [ ] 创建部署文档
- [ ] 编写维护指南
## 第四阶段：部署和上线 (1-2周)
### 第10周：生产环境部署
**目标**: 完成生产环境部署和配置
#### 部署任务
- [ ] 配置生产环境变量
- [ ] 设置SSL证书
- [ ] 配置域名和DNS
- [ ] 设置防火墙规则
- [ ] 配置监控告警
#### 数据迁移
- [ ] 准备生产数据库
- [ ] 迁移现有数据
- [ ] 配置数据库备份
- [ ] 设置数据恢复流程
#### 上线准备
- [ ] 进行最终测试
- [ ] 准备上线检查清单
- [ ] 制定回滚计划
- [ ] 准备用户培训材料
### 第11周：上线和监控
**目标**: 系统正式上线和运行监控
#### 上线任务
- [ ] 执行上线部署
- [ ] 验证系统功能
- [ ] 监控系统运行状态
- [ ] 处理上线问题
#### 监控任务
- [ ] 配置系统监控
- [ ] 设置性能监控
- [ ] 配置日志收集
- [ ] 设置告警规则
#### 用户支持
- [ ] 提供用户培训
- [ ] 收集用户反馈
- [ ] 处理用户问题
- [ ] 收集使用数据
## 后续功能规划
### 第12周及以后：功能扩展
#### 库存管理模块 (2-3周)
- [ ] 库存物品管理
- [ ] 出入库记录
- [ ] 库存预警系统
- [ ] 供应商管理
#### 告警通知模块 (1-2周)
- [ ] 设备离线告警
- [ ] 库存预警通知
- [ ] 多通道通知（邮件、微信、钉钉）
- [ ] 告警规则配置
#### 报表导出模块 (1周)
- [ ] 设备状态报表
- [ ] 历史记录报表
- [ ] 统计图表导出
- [ ] 自定义报表模板
#### 移动端适配 (2-3周)
- [ ] 响应式移动端界面
- [ ] PWA支持
- [ ] 移动端专属功能
- [ ] 离线数据支持
## 风险管理
### 技术风险
1. **SSH连接稳定性**
- 影响：设备状态检查失败
- 缓解：连接池、重试机制、备用方案
2. **性能问题**
- 影响：系统响应缓慢
- 缓解：异步处理、缓存优化、分批查询
3. **安全性**
- 影响：数据泄露或系统被攻击
- 缓解：加密存储、访问控制、安全审计
### 项目风险
1. **需求变更**
- 影响：开发进度延迟
- 缓解：敏捷开发、定期沟通、优先级管理
2. **资源不足**
- 影响：开发质量下降
- 缓解：合理规划、外部支持、功能裁剪
3. **集成问题**
- 影响：系统功能不完整
- 缓解：早期集成测试、备用方案、分阶段集成
## 质量保证
### 代码质量
- 代码审查流程
- 自动化测试覆盖
- 代码规范检查
- 性能基准测试
### 测试策略
- 单元测试：核心逻辑
- 集成测试：模块间交互
- 系统测试：端到端流程
- 性能测试：负载和压力
### 文档质量
- 技术文档完整
- API文档准确
- 用户手册易懂
- 部署文档详细
## 团队协作
### 开发团队角色
- 后端开发工程师（2人）
- 前端开发工程师（1人）
- 测试工程师（1人）
- DevOps工程师（1人）
### 沟通机制
- 每日站会（15分钟）
- 每周迭代评审
- 每月项目回顾
- 即时通讯工具支持
### 工具支持
- 代码仓库：Git + GitHub/GitLab
- 项目管理：Jira/Trello
- 文档协作：Confluence/Notion
- 持续集成：Jenkins/GitHub Actions
## 成功标准
### 功能完成度
- [ ] 核心功能100%完成
- [ ] 高级功能80%完成
- [ ] 用户体验满意度≥90%
### 性能指标
- [ ] 页面加载时间<3秒
- [ ] API响应时间<500ms
- [ ] 系统可用性≥99.5%
### 质量指标
- [ ] 测试覆盖率≥80%
- [ ] 缺陷密度<0.5/千行代码
- [ ] 用户反馈满意度≥85%
### 项目指标
- [ ] 按时交付率≥90%
- [ ] 预算控制率≥95%
- [ ] 团队满意度≥85%
---
**计划版本**: v1.0
**制定日期**: 2026年4月1日
**下次评审**: 2026年4月15日
**负责人**: 项目经理
开发进度.md
-296
View File
@@ -1,296 +0,0 @@
# H3C ONU设备管理系统 - 开发进度
## 项目状态
**当前版本**: v0.6.0
**开发日期**: 2026年4月3日
**状态**: 核心功能已完成，持续迭代优化
---
## ✅ 已完成功能
### 第一阶段：项目基础搭建 (2周) - 100%
#### 第1周：环境搭建和基础框架 ✅
- ✅ 创建FastAPI项目结构
- ✅ 配置数据库连接（PostgreSQL + SQLAlchemy）
- ✅ 设置Alembic数据库迁移
- ✅ 创建基础配置管理
- ✅ 创建Vue 3项目（Vite）
- ✅ 集成Element Plus UI库
- ✅ 配置路由系统（Vue Router）
- ✅ 设置状态管理（Pinia）
- ✅ 配置API请求封装（Axios）
- ✅ 创建Dockerfile（前后端）
- ✅ 编写docker-compose.yml
- ✅ 设置环境变量管理
#### 第2周：认证系统和基础API ✅
- ✅ 集成Casdoor SDK
- ✅ 实现OAuth 2.0登录流程
- ✅ 创建JWT令牌管理
- ✅ 实现用户信息同步
- ✅ 创建基础CRUD API框架
- ✅ 实现API文档（Swagger/ReDoc）
- ✅ 创建登录状态管理
- ✅ 创建基础布局组件
- ✅ 实现API调用封装
---
### 第二阶段：核心功能开发 (4周) - 100%
#### 第3周：数据库设计和设备模型 ✅
- ✅ 设计并创建数据库表结构
- ✅ olt_devices表
- ✅ onu_devices表
- ✅ device_status_history表
- ✅ users表
- ✅ permissions表
- ✅ 创建SQLAlchemy模型
- ✅ 创建设备管理API
- ✅ 实现数据验证（Pydantic）
- ✅ 创建设备列表页面
- ✅ 实现表格组件
- ✅ 创建分页组件
- ✅ 实现搜索和筛选功能
- ✅ 初始化数据库脚本
#### 第4周：SSH连接和状态检查 ✅
- ✅ 集成Paramiko SSH库
- ✅ 创建命令执行和结果解析
- ✅ 实现设备状态检查服务
- ✅ 集成Celery异步任务
- ✅ 配置Redis消息队列
- ✅ 创建状态检查控制面板
- ✅ 实现手动刷新功能
- ✅ 支持"More"分页处理
#### 第5周：Excel导入和数据管理 ✅
- ✅ 集成Pandas库
- ✅ 实现Excel文件解析
- ✅ 创建数据导入服务
- ✅ 实现数据验证和清洗
- ✅ 创建批量导入API
- ✅ 创建数据导入页面
- ✅ 实现文件上传组件
- ✅ 实现导入进度显示
#### 第6周：权限管理和统计 ✅
- ✅ 设计权限模型（RBAC）
- ✅ 创建权限检查中间件
- ✅ 创建统计API
- ✅ 实现仪表板统计卡片
- ✅ 创建布局和导航组件
- ✅ Celery Beat定时任务（每30分钟）
---
### 第三阶段：高级功能迭代 - 进行中
#### 统计图表和可视化 ✅
- ✅ ECharts图表集成
- ✅ 设备状态趋势图
- ✅ 区域/学校统计图表
- [ ] 历史数据可视化
#### OLT设备管理增强 ✅
- ✅ OLT设备配置管理（增删改查）
- ✅ OLT批量导入（Excel）
- ✅ 重复MAC地址检测与管理
- ✅ 离线端口清除功能（SSH执行 `default` 命令）
- ✅ 新发现设备入库管理（区域/学校信息补全）
- ✅ 环路检测功能（`display mac-address` 分析）
- ✅ 快速扫描（多线程并发扫描所有OLT）
- ✅ 扫描并入库（自动发现新设备）
#### OLT端口管理 ✅（2026-04-03 新增）
- ✅ 获取OLT所有端口状态（`display interface brief` 解析）
- ✅ 交换机面板样式可视化（UP/DOWN/ADM状态色彩区分）
- ✅ 点击端口开启/关闭（SSH执行 `shutdown`/`undo shutdown`）
- ✅ OLT详情页新增"OLT端口管理"入口按钮
#### 单设备状态检查优化 ✅（2026-04-03 修复）
- ✅ 修复"更新"按钮始终返回离线的问题（slot_command参数拼接错误）
- ✅ 设备详情"型号"字段实时回写数据库并展示
- ✅ 全部更新/快速扫描同步写入解析到的型号信息
- ✅ 修复多线程扫描连接池耗尽问题（轻量化查询优化）
#### 系统设置和审核
- [ ] 定时任务配置界面
- [ ] 设备变更审核流程
- [ ] 审核中心页面
#### 性能优化
- [ ] 数据库查询优化
- [ ] Redis缓存策略
- [ ] 前端资源优化
- [ ] 懒加载实现
---
## 🎯 核心功能清单
| 功能模块 | 状态 | 完成度 |
|---------|------|--------|
| 项目框架 | ✅ | 100% |
| 认证系统 | ✅ | 100% |
| 设备管理 | ✅ | 100% |
| SSH连接 | ✅ | 100% |
| 状态检查 | ✅ | 100% |
| Excel导入 | ✅ | 100% |
| 权限管理 | ✅ | 80% |
| 统计功能 | ✅ | 85% |
| 图表可视化 | ✅ | 75% |
| OLT端口管理 | ✅ | 100% |
| 环路检测 | ✅ | 100% |
| 审核流程 | ⏳ | 0% |
---
## 📊 开发统计
- **总任务数**: 80+
- **已完成**: 72+
- **完成率**: 90%
- **代码行数**: 约5000+行
- **文件数**: 55+个
---
**更新日期**: 2026年4月3日
---
## ✅ 已完成功能
### 第一阶段：项目基础搭建 (2周) - 100%
#### 第1周：环境搭建和基础框架 ✅
- ✅ 创建FastAPI项目结构
- ✅ 配置数据库连接（PostgreSQL + SQLAlchemy）
- ✅ 设置Alembic数据库迁移
- ✅ 创建基础配置管理
- ✅ 创建Vue 3项目（Vite）
- ✅ 集成Element Plus UI库
- ✅ 配置路由系统（Vue Router）
- ✅ 设置状态管理（Pinia）
- ✅ 配置API请求封装（Axios）
- ✅ 创建Dockerfile（前后端）
- ✅ 编写docker-compose.yml
- ✅ 设置环境变量管理
#### 第2周：认证系统和基础API ✅
- ✅ 集成Casdoor SDK
- ✅ 实现OAuth 2.0登录流程
- ✅ 创建JWT令牌管理
- ✅ 实现用户信息同步
- ✅ 创建基础CRUD API框架
- ✅ 实现API文档（Swagger/ReDoc）
- ✅ 创建登录状态管理
- ✅ 创建基础布局组件
- ✅ 实现API调用封装
---
### 第二阶段：核心功能开发 (4周) - 100%
#### 第3周：数据库设计和设备模型 ✅
- ✅ 设计并创建数据库表结构
- ✅ olt_devices表
- ✅ onu_devices表
- ✅ device_status_history表
- ✅ users表
- ✅ permissions表
- ✅ 创建SQLAlchemy模型
- ✅ 创建设备管理API
- ✅ 实现数据验证（Pydantic）
- ✅ 创建设备列表页面
- ✅ 实现表格组件
- ✅ 创建分页组件
- ✅ 实现搜索和筛选功能
- ✅ 初始化数据库脚本
#### 第4周：SSH连接和状态检查 ✅
- ✅ 集成Paramiko SSH库
- ✅ 创建命令执行和结果解析
- ✅ 实现设备状态检查服务
- ✅ 集成Celery异步任务
- ✅ 配置Redis消息队列
- ✅ 创建状态检查控制面板
- ✅ 实现手动刷新功能
- ✅ 支持"More"分页处理
#### 第5周：Excel导入和数据管理 ✅
- ✅ 集成Pandas库
- ✅ 实现Excel文件解析
- ✅ 创建数据导入服务
- ✅ 实现数据验证和清洗
- ✅ 创建批量导入API
- ✅ 创建数据导入页面
- ✅ 实现文件上传组件
- ✅ 实现导入进度显示
#### 第6周：权限管理和统计 ✅
- ✅ 设计权限模型（RBAC）
- ✅ 创建权限检查中间件
- ✅ 创建统计API
- ✅ 实现仪表板统计卡片
- ✅ 创建布局和导航组件
- ✅ Celery Beat定时任务（每30分钟）
---
## 📋 待开发功能
### 第三阶段：高级功能 (预计2-3周)
#### 统计图表和可视化
- ✅ ECharts图表集成
- ✅ 设备状态趋势图
- ✅ 区域/学校统计图表
- [ ] 历史数据可视化
#### 系统设置和审核
- ✅ OLT设备配置管理
- [ ] 定时任务配置界面
- [ ] 设备变更审核流程
- [ ] 审核中心页面
#### 性能优化
- [ ] 数据库查询优化
- [ ] Redis缓存策略
- [ ] 前端资源优化
- [ ] 懒加载实现
---
## 🎯 核心功能清单
| 功能模块 | 状态 | 完成度 |
|---------|------|--------|
| 项目框架 | ✅ | 100% |
| 认证系统 | ✅ | 100% |
| 设备管理 | ✅ | 100% |
| SSH连接 | ✅ | 100% |
| 状态检查 | ✅ | 100% |
| Excel导入 | ✅ | 100% |
| 权限管理 | ✅ | 80% |
| 统计功能 | ✅ | 80% |
| 图表可视化 | ⏳ | 0% |
| 审核流程 | ⏳ | 0% |
---
## 📊 开发统计
- **总任务数**: 60+
- **已完成**: 50+
- **完成率**: 83%
- **代码行数**: 约3000+行
- **文件数**: 40+个
---
**更新日期**: 2026年4月1日
环路检测方法.md
-34
View File
@@ -1,34 +0,0 @@
在“OLT管理”页面新增“环路检测”按钮，点击后可以检测所有OLT设备是否有环路，并在列表新增一列环路检测列，如果设备有环路，则显示环路的详细信息。环路检测的逻辑如下。
1. 连接OLT并使用命令 `display loopback-detection` 查看
2. OLT返回结果表明loopback-detection已启用环路检测功能
3. 返回 `No loop is detected.`则说明设备正常，没有环路。如果返回“Loop is detected on following interfaces”，就说明有环路了。（可以参考下面返回的结果）
4. 如果是有环路的情况，通过查找当前OLT的端口来确认MAC地址，比如OLT返回“Onu3/0/7:10 ”，就查找这个端口的MAC地址然后列出这个MAC的区域、学校、楼宇、房间号等信息。
```
# 有环路的情况OLT返回的结果
<7503OLT>display loopback-detection
Loop detection is enabled.
Global loop detection interval is 35 second(s).
Loop is detected on following interfaces:
* indicates the loop protection action was not triggered.
Interface Action mode VLANs/VSI
Onu3/0/7:10 Shutdown 3000
```
```
# 没有环路的情况OLT返回的结果
<8OLT>display loopback-detection
Loop detection is enabled.
Global loop detection interval is 35 second(s).
No loop is detected.
```
在设备列表页面的设备详情页面中新增一个“更新”按钮，点击后可以单独更新这个MAC的设备状态，流程如下：
1. 通过SSH连接这个MAC所属的OLT
2. 执行命令 `display onu slot 1 | include 1484-778e-a860`，也就是 `display onu slot {槽位} | include {MAC}`
3. OLT返回内容`1484-778e-a860 4 12414 Onu1/0/2:4 WA6520H-EGPON/A 106/ Up N/A`,分析返回的内容来更新设备状态和距离。
设备管理页面的“全部更新”按钮和OLT管理页面的“快速扫描”按钮现在都无法正常使用了，全部更新按钮点击后所有OLT设备都是失败的，快速扫描按钮报错'CheckService' object has no attribute 'scan_and_discover'。
设备管理页面的设备详情中的“更新”按钮有点问题，点击后他获取的设备信息都是离线的，但是点击“全部更新”后，设备是在线的，说明这个更新按钮有点问题。
移动端设计思路.md
-317
View File
@@ -1,317 +0,0 @@
# H3C ONU设备管理系统 - 移动端适配设计思路
## 项目背景
当前H3C ONU设备管理系统主要针对桌面端设计，在移动设备上存在以下问题：
1. 布局在小屏幕上显示不全，需要左右滚动
2. 按钮和交互元素太小，难以点击
3. 表格数据在小屏幕上难以阅读
4. 导航菜单在手机上使用不便
5. 响应式断点设置不合理
## 设计目标
为移动端用户提供专用的小屏幕优化布局，聚焦核心功能，提升现场维护、外出监控和应急处理场景下的使用体验。
## 用户场景分析
移动端用户主要使用场景：
1. **现场维护**：快速查看设备状态，执行简单操作
2. **外出监控**：随时了解整体运行情况
3. **应急处理**：进行紧急操作和故障排查
## 核心功能范围
移动端聚焦以下三个核心功能：
1. **统计预览** - 了解整体运行状态
2. **设备列表** - 查找和管理具体设备
3. **OLT管理** - 管理OLT设备和端口
**功能精简**：移动端暂不需要新增、删除设备等复杂管理功能。
## 整体设计方案
### 一、架构方案：混合响应式设计
- **独立移动端布局**：为小屏幕（<768px）设计专用布局
- **组件复用**：复用现有Vue组件和业务逻辑
- **渐进增强**：桌面端功能完整，移动端聚焦核心
- **主题继承**：完全支持现有的深色/浅色主题切换
### 二、技术实现方案
推荐使用**方案A：响应式断点 + 条件渲染**
```vue
<template>
<div class="mobile-layout" v-if="isMobile">
<!-- 移动端专用布局 -->
<BottomNavigation />
<DeviceCards v-if="currentTab === 'devices'" />
</div>
<div class="desktop-layout" v-else>
<!-- 现有桌面布局 -->
<Sidebar />
<DeviceTable />
</div>
</template>
<script>
// 使用CSS媒体查询检测屏幕尺寸
const isMobile = window.matchMedia('(max-width: 768px)').matches
</script>
```
## 详细设计说明
### 1. 导航系统 - 底部导航栏
```
[统计] [设备] [OLT] [我的]
```
**设计要点：**
- 固定底部，符合移动端使用习惯
- 图标+文字，清晰易懂
- 当前选中项高亮显示
- 支持徽章提示（如设备告警数量）
### 2. 设备列表 - 卡片式设计
#### 卡片内容（折叠状态）：
```
┌─────────────────────────┐
│ MAC: aabb-ccdd-eeee ● 在线 │
│ 学校: 第一中学 │
│ 楼宇: 教学楼A-301 │
│ 场所：计算机教室 │
│ 房间号：201 │
└─────────────────────────┘
```
#### 点击展开后拓展显示：
```
┌─────────────────────────┐
│ MAC: aabb-ccdd-eeee ● 在线 │
│ 学校: 第一中学 │
│ 楼宇: 教学楼A-301 │
│ 场所：计算机教室 │
│ 房间号：201 │
├─────────────────────────┤
│ [更新] [编辑] [业务下发] │
├─────────────────────────┤
│ 距离: 1235M │
│ 端口: Onu2/0/2:15 │
│ 型号：WA6520H-EGPON/A │
│ 所属 OLT：七百弄乡中心机房 │
│ 备注：由于是微机室，需配置 │
│ 设备1000M带宽限速 │
└─────────────────────────┘
```
**设计优势：**
- 信息层次清晰，重点突出（MAC、在线状态、学校名称、楼宇、场所、房间号）
- 节省屏幕空间
- 操作按钮在展开后显示，避免误触
### 3. 统计预览 - 可折叠面板
```
┌─────────────────────────┐
│ 📊 统计概览 │
│ ▼ 总体状态 │
│ 在线: 3852/4000 (96%) │
│ 城区: 95% 城郊: 92% │
│ 乡镇: 88% │
├─────────────────────────┤
│ ▶ 详细统计（点击展开） │
├─────────────────────────┤
│ ▶ 告警统计（点击展开） │
└─────────────────────────┘
```
**功能特点：**
- 默认显示关键指标
- 详细内容可折叠，按需展开
- 支持按区域/学校筛选
- 支持时间范围选择
### 4. OLT管理 - 卡片+展开式
#### 卡片内容：
```
┌─────────────────────────┐
│ 192.168.1.100 ● 正常 │
│ 安装位置： 岩滩接入网机房 │
│ 环路: 0个 [检测] │
├─────────────────────────┤
│ [快速扫描] [端口管理] [编辑] │
└─────────────────────────┘
```
**功能分层：**
- 卡片显示：IP地址、环路检测状态、快速扫描按钮、端口管理按钮、编辑按钮
## 视觉设计规范
### 1. 主题继承
- 完全支持现有的深色/浅色两种主题风格
- 用户可自由切换主题
- 保持一致的品牌视觉语言
### 2. 设计原则
- **触摸友好**：最小点击区域44×44px
- **信息密度**：适当减少信息密度，避免拥挤
- **操作简化**：复杂操作分步骤引导
- **反馈及时**：操作后提供明确反馈
### 3. 响应式断点
- **移动端**：< 768px
- **平板端**：768px - 1024px（可考虑适配）
- **桌面端**：> 1024px（现有布局）
## 技术实施方案
### 第一阶段：基础框架（1-2天）
1. 添加移动端检测逻辑
2. 创建底部导航组件
3. 设置移动端专用路由
4. 适配现有主题系统
### 第二阶段：核心页面（3-5天）
1. 设备卡片组件开发
2. 统计折叠面板
3. OLT管理卡片
4. 响应式表格重构
### 第三阶段：交互优化（2-3天）
1. 触摸手势支持
2. 加载状态优化
3. 离线能力增强
4. 性能优化
## 组件设计规范
### 1. 设备卡片组件 (DeviceCard.vue)
```vue
<template>
<div class="device-card" @click="toggleExpand">
<div class="card-header">
<span class="device-name">{{ device.name }}</span>
<span class="status-badge" :class="device.status">
{{ device.status === 'online' ? '● 在线' : '○ 离线' }}
</span>
</div>
<div class="card-content">
<div class="info-row">
<span class="label">MAC:</span>
<span class="value">{{ device.mac }}</span>
</div>
<div class="info-row">
<span class="label">学校:</span>
<span class="value">{{ device.school }}</span>
</div>
<!-- 更多信息... -->
</div>
<div v-if="expanded" class="card-expanded">
<!-- 展开后的详细信息和操作按钮 -->
</div>
</div>
</template>
```
### 2. 底部导航组件 (BottomNavigation.vue)
```vue
<template>
<nav class="bottom-nav">
<router-link
v-for="item in navItems"
:key="item.path"
:to="item.path"
class="nav-item"
:class="{ active: $route.path.startsWith(item.path) }"
>
<span class="nav-icon">{{ item.icon }}</span>
<span class="nav-label">{{ item.label }}</span>
</router-link>
</nav>
</template>
```
## 性能优化策略
### 1. 数据加载优化
- 分页加载设备列表
- 虚拟滚动长列表
- 图片和图标懒加载
### 2. 网络优化
- API请求合并
- 数据缓存策略
- 离线模式支持
### 3. 渲染优化
- 组件懒加载
- 避免不必要的重渲染
- 使用CSS动画代替JS动画
## 测试策略
### 1. 设备兼容性测试
- iOS Safari
- Android Chrome
- 微信内置浏览器
- 不同屏幕尺寸
### 2. 功能测试
- 触摸操作测试
- 手势支持测试
- 网络切换测试
- 主题切换测试
### 3. 性能测试
- 页面加载时间
- 内存使用情况
- 滚动流畅度
- 电池消耗
## 后续扩展考虑
### 1. 功能扩展
- 推送通知（设备离线告警）
- 扫码快速定位设备
- 语音搜索和操作
- 离线数据同步
### 2. 体验优化
- PWA支持（添加到主屏幕）
- 深色模式自动切换
- 手势快捷操作
- 自定义快捷功能
### 3. 平台扩展
- 微信小程序版本
- 企业微信集成
- 钉钉工作台集成
- 移动端APP
## 总结
本设计方案通过重新规划移动端专用布局，采用卡片式设计、底部导航、可折叠面板等移动端友好模式，解决了当前系统在移动设备上的可用性问题。方案既保持了与现有系统的功能一致性，又针对移动端使用场景进行了优化，能够显著提升移动端用户体验。
**核心价值：**
1. **专注核心功能**：聚焦统计、设备、OLT三大核心场景
2. **优化交互体验**：卡片式设计更适合触摸操作
3. **保持系统一致性**：复用现有组件和主题
4. **可扩展性强**：为后续功能扩展预留空间
---
*文档创建时间：2026年4月4日*
*基于与项目负责人的详细讨论结果整理*
1. 删除物料报错 inventory.js:12 DELETE http://10.10.10.14:5173/api/inventory/materials/1 400 (Bad Request)
2. 出入库记录点击单据编号应该可以看到出库或者入库单填写时的详细信息
1. 因为“数据导入”功能只导入了设备数据，所以不需要单独做一个页面了，改为在设备列表页面添加一个“数据导入”按钮，点击按钮后打开一个文件选择框，选择文件后进行数据导入（提供导入文件模板）。
2. 给现有的OLT列表也添加一个区域（和设备列表的区域内容同步，默认先选择城区，后续我再自己修改），并且设置区域权限，区域管理员只能管理对应区域的OLT。
1. 我发现现在的30分钟定时检查好像有点问题，还不是触发完了之后所有设备都显示离线，请帮我排查一下
2. 新增一个设置，超级管理员可以设置定时检查时间，默认是30分钟，用户可以自己设置，但是不能小于5分钟。
OLT管理页面的“区域”是需要跟用户管理页面中，区域管理员的“分配区域”是同步的，因为区域管理员应该只能查看到自己区域内的OLT，现在OLT管理页面的区域只有三个选项，这是不对的。
系统设计文档.md
-441
View File
@@ -1,441 +0,0 @@
# 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日
项目总结.md
-318
View File
@@ -1,318 +0,0 @@
# H3C ONU设备管理系统 - 项目总结
## 项目概述
基于Python FastAPI + Vue 3的H3C OLT设备监控管理系统，用于监控和管理4000+ ONU设备的在线状态。系统通过SSH连接H3C OLT设备，查询ONU设备状态，提供Web界面进行设备管理、状态监控、数据导入和权限管理。
## 设计讨论要点总结
### 1. 核心需求确认
- **设备状态监控**: 通过SSH连接H3C OLT设备，使用`display onu slot`命令查询ONU状态
- **数据规模**: 4000+设备MAC地址和物理位置信息管理
- **数据源**: Excel表格导入，PostgreSQL数据库存储
- **更新频率**: 自动每30分钟更新，手动刷新5分钟冷却限制
- **历史记录**: 保存90天状态历史
- **权限管理**: Casdoor统一认证，RBAC权限控制，区域/学校级别数据隔离
- **部署要求**: Docker Compose编排，外部数据库支持，环境变量配置
### 2. 技术架构决策
- **后端**: Python FastAPI + PostgreSQL + Celery + Redis
- **前端**: Vue 3 + Element Plus + Pinia
- **认证**: Casdoor统一认证集成
- **部署**: Docker容器化，Nginx反向代理
- **监控**: 健康检查，性能监控，日志收集
### 3. 权限系统设计
- **角色层级**: 超级管理员 → 管理员 → 区域管理员 → 学校管理员 → 操作员 → 查看员
- **权限控制**: 基于RBAC，支持数据级权限过滤
- **变更审核**: 设备信息变更需要管理员审核
- **Casdoor集成**: 统一认证，用户信息同步
### 4. 功能模块规划
1. **基础框架**: 项目结构，环境配置，Docker化
2. **认证系统**: Casdoor集成，JWT管理，权限中间件
3. **设备管理**: Excel导入，设备CRUD，状态检查
4. **SSH连接**: 连接池管理，命令执行，结果解析
5. **任务调度**: 定时检查，手动刷新，异步处理
6. **权限系统**: 角色管理，权限分配，数据过滤
7. **统计图表**: 仪表板，趋势分析，报表导出
8. **系统设置**: OLT配置，任务配置，审核流程
## 系统架构设计
### 整体架构
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 用户浏览器 │ │ Nginx反向代理 │ │ FastAPI后端 │
│ │◄──►│ │◄──►│ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Vue前端应用 │ │ Celery Worker │
│ │ │ │
└─────────────────┘ └─────────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ PostgreSQL数据库 │ │ Redis │
│ (外部) │ │ (外部) │
└─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ Casdoor │
│ 认证服务器 │
└─────────────────┘
```
### 数据库设计核心表
1. **olt_devices**: OLT设备信息（IP、SSH凭证、插槽命令）
2. **onu_devices**: ONU设备信息（MAC、位置、关联OLT）
3. **device_status_history**: 设备状态历史记录
4. **users**: 用户信息（Casdoor集成）
5. **roles/permissions**: 角色和权限管理
6. **device_change_requests**: 设备变更审核记录
### API设计原则
- RESTful风格，版本控制（/api/v1/）
- JWT认证，权限中间件
- 数据验证（Pydantic）
- 异步处理耗时操作
- 完善的错误处理和日志
## 关键技术实现
### 1. SSH连接管理
- **连接池**: 复用SSH连接，提高性能
- **超时重试**: 网络波动容错
- **命令解析**: 解析`display onu slot`命令输出
- **批量处理**: 分批查询，避免阻塞
### 2. 异步任务处理
- **Celery**: 异步任务队列
- **Redis**: 消息代理和结果存储
- **定时任务**: Celery Beat调度
- **进度跟踪**: 任务状态监控
### 3. 数据导入处理
- **Pandas**: Excel文件解析
- **数据验证**: 格式检查，重复检测
- **批量插入**: 性能优化
- **进度反馈**: 实时导入进度
### 4. 权限系统实现
- **RBAC模型**: 角色-权限关联
- **数据过滤**: SQL级别权限控制
- **中间件**: 请求级别权限检查
- **Casdoor同步**: 用户信息自动同步
### 5. 前端架构
- **组件化**: 可复用组件设计
- **状态管理**: Pinia集中状态
- **路由守卫**: 页面访问控制
- **响应式设计**: 移动端适配
## 部署方案
### 环境要求
- Docker 20.10+
- Docker Compose 2.0+
- 外部PostgreSQL数据库
- 外部Redis服务
- Casdoor认证服务器
### 配置文件
- **.env**: 环境变量配置
- **docker-compose.yml**: 服务编排
- **nginx.conf**: 反向代理配置
- **部署脚本**: 自动化部署和监控
### 监控和运维
- **健康检查**: /health端点
- **性能监控**: /metrics端点（Prometheus格式）
- **日志收集**: 结构化日志，日志轮转
- **备份策略**: 数据库定期备份
## 开发计划
### 第一阶段（2周）：项目基础
- 环境搭建，基础框架
- Casdoor集成，基础API
- 前端框架搭建
### 第二阶段（4周）：核心功能
- 数据库设计，设备管理
- SSH连接，状态检查
- Excel导入，数据管理
- 权限系统实现
### 第三阶段（3周）：高级功能
- 统计图表，仪表板
- 系统设置，审核流程
- 性能优化，测试完善
### 第四阶段（1-2周）：部署上线
- 生产环境部署
- 监控配置
- 用户培训
## 风险评估和应对
### 技术风险
1. **SSH连接稳定性**
- 风险：网络问题导致连接失败
- 应对：连接池、重试机制、超时设置
2. **性能问题**
- 风险：4000+设备查询性能
- 应对：异步处理、缓存优化、分批查询
3. **安全性**
- 风险：SSH凭证存储安全
- 应对：加密存储、访问控制、审计日志
### 项目风险
1. **需求变更**
- 风险：开发进度延迟
- 应对：敏捷开发、定期沟通
2. **集成问题**
- 风险：Casdoor集成问题
- 应对：早期测试、备用方案
## 扩展性考虑
### 水平扩展
- 无状态API服务，支持多实例
- 数据库读写分离
- Redis集群支持
- 负载均衡配置
### 功能扩展
1. **库存管理模块**（计划中）
- 设备库存管理
- 出入库记录
- 库存预警
2. **告警通知模块**（计划中）
- 设备离线告警
- 多通道通知
- 告警规则配置
3. **报表导出模块**（计划中）
- 自定义报表
- 数据导出
- 统计图表
4. **移动端适配**（计划中）
- 响应式移动端
- PWA支持
- 离线功能
## 成功标准
### 功能完成度
- 核心功能100%实现
- 高级功能80%实现
- 用户体验满意度≥90%
### 性能指标
- 页面加载时间<3秒
- API响应时间<500ms
- 系统可用性≥99.5%
### 质量指标
- 测试覆盖率≥80%
- 缺陷密度<0.5/千行代码
- 用户反馈满意度≥85%
### 项目指标
- 按时交付率≥90%
- 预算控制率≥95%
- 团队满意度≥85%
## 项目文档清单
### 已创建文档
1. **系统设计文档.md** - 详细系统设计说明
2. **README.md** - 项目概述和快速开始
3. **PROJECT_STRUCTURE.md** - 项目结构说明
4. **开发计划.md** - 详细开发计划
5. **项目总结.md** - 本项目总结文档
### 部署配置
1. **deploy/docker-compose.yml** - Docker编排配置
2. **deploy/.env.example** - 环境变量示例
3. **deploy/nginx/** - Nginx配置
4. **deploy/scripts/** - 部署和运维脚本
### 待创建文档
1. **API文档** - 详细API接口说明
2. **用户手册** - 最终用户使用指南
3. **部署指南** - 生产环境部署步骤
4. **开发指南** - 开发者贡献指南
## 后续步骤建议
### 短期（1-2周）
1. 搭建开发环境
2. 创建基础项目结构
3. 配置Casdoor集成
4. 实现基础认证功能
### 中期（1-2月）
1. 完成核心功能开发
2. 进行系统测试
3. 准备生产环境部署
4. 用户培训材料准备
### 长期（2-3月）
1. 系统上线运行
2. 收集用户反馈
3. 优化系统性能
4. 规划扩展功能开发
## 技术选型理由
### 后端技术选型
- **FastAPI**: 高性能，异步支持好，自动API文档
- **PostgreSQL**: 关系型数据库，事务支持，JSONB扩展
- **Celery**: 成熟的异步任务框架，社区支持好
- **Paramiko**: Python SSH库，功能完善，文档齐全
### 前端技术选型
- **Vue 3**: 渐进式框架，学习曲线平缓，生态丰富
- **Element Plus**: 企业级UI组件，设计规范，功能全面
- **Pinia**: Vue 3官方推荐状态管理，TypeScript支持好
### 部署技术选型
- **Docker**: 容器化标准，环境一致性，易于部署
- **Nginx**: 高性能Web服务器，反向代理成熟方案
- **Casdoor**: 开源统一认证，支持OAuth 2.0，易于集成
## 项目价值
### 业务价值
1. **效率提升**: 自动化设备状态监控，减少人工检查
2. **数据集中**: 统一管理4000+设备信息，便于查询统计
3. **实时监控**: 及时发现设备离线，快速响应
4. **权限控制**: 多级权限管理，数据安全有保障
### 技术价值
1. **现代化架构**: 采用最新技术栈，易于维护扩展
2. **容器化部署**: 环境一致，部署简单，易于运维
3. **开源集成**: 利用成熟开源方案，降低开发成本
4. **良好扩展性**: 模块化设计，便于功能扩展
## 总结
本项目是一个完整的设备监控管理系统，从需求分析、架构设计到部署方案都进行了详细规划。系统采用现代化的技术栈，具备良好的扩展性和维护性。通过分阶段实施，可以确保项目稳步推进，最终交付一个稳定、高效、易用的系统。
项目已经完成了详细的设计和规划，具备了开始实施的所有必要条件。建议按照开发计划分阶段实施，定期进行进度评审和调整，确保项目成功交付。
---
**文档版本**: v1.0
**创建日期**: 2026年4月1日
**最后更新**: 2026年4月1日
**项目状态**: 设计完成，准备实施