v6ole
f1f8518985
feat(auth): 添加用户权限获取接口并完善JWT令牌角色信息 - 在JWT令牌中添加用户角色信息 - 新增get_my_permissions接口用于获取当前用户权限码列表 - 重构认证回调逻辑，增加错误日志记录 - 更新用户信息获取接口使用Authorization头验证 ```
19 KiB
19 KiB
H3C ONU设备管理系统 - 库存管理功能设计方案
项目背景
基于与项目负责人的详细讨论，为H3C ONU设备管理系统增加库存管理功能，用于管理项目中现有的实体设备（ONU、OLT、交换机、防火墙、上网行为管理等）的出入库台账。
设计讨论记录
讨论时间: 2026年4月5日
参与人员: 阿森、小柚（AI助手）
一、需求分析
1.1 核心需求
- 设备全生命周期管理：从采购入库 → 领用出库 → 安装使用 → 退库归还 → 报废处理
- 物料分类管理：支持ONU设备、OLT设备、交换机、防火墙、上网行为管理等
- 库存台账管理：记录基本信息、唯一标识、库存数量、位置信息、状态信息
- 业务流程管理：批量入库、领用出库、退库归还、报废/报修处理、盘点调整
- 系统集成需求：与现有设备监控系统深度集成，设备安装时更新位置信息，报废时从监控系统移除
1.2 用户场景
- 仓库管理员：管理物料入库、出库、盘点
- 运维人员：领用设备进行现场安装
- 采购人员：新设备采购入库
- 管理人员：查看库存报表，进行决策
1.3 功能范围
- 物料分类管理
- 库存台账管理
- 出入库流程管理
- 盘点管理
- 报表统计
- 与现有系统集成
二、整体架构设计
2.1 架构方案：集成扩展方案
选择理由：
- 无缝集成：与现有设备监控系统深度集成
- 数据一致：共享用户、权限、设备基础数据
- 流程连贯：设备完整生命周期管理
- 技术复用：复用现有的Excel导入、权限控制、UI组件
2.2 系统关系图
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 库存管理系统 │◄────►│ 设备监控系统 │◄────►│ 权限管理系统 │
│ │ │ │ │ (Casdoor) │
├─────────────────┤ ├─────────────────┤ └─────────────────┘
│ • 物料管理 │ │ • ONU状态监控 │
│ • 出入库台账 │ │ • OLT管理 │
│ • 库存统计 │ │ • 实时告警 │
│ • 领用审批 │ │ • 历史记录 │
└─────────────────┘ └─────────────────┘
│ │
└─────────────────────────┘
设备生命周期流转
2.3 技术架构
- 后端：在现有FastAPI基础上扩展库存管理模块
- 前端：在现有Vue 3基础上增加库存管理页面
- 数据库：在现有PostgreSQL中新增库存相关表
- 权限：集成现有权限系统，新增库存管理权限
- 导入导出：复用现有Excel导入组件
三、详细功能设计
3.1 物料分类管理
支持的设备类型：
- ONU设备（与现有系统深度集成）
- OLT设备（与现有OLT管理集成）
- 交换机
- 防火墙
- 上网行为管理
- 光模块等配件
物料属性：
- 基本信息：名称、型号、规格、品牌、单位
- 唯一标识：
- ONU设备：MAC地址（与现有系统一致）
- OLT设备：IP地址 + 序列号
- 交换机：MAC地址 + 序列号
- 防火墙：序列号 + 资产编号
- 上网行为管理：序列号
- 库存信息：当前数量、安全库存
- 位置信息：仓库位置（项目专用仓库，无货架管理）
- 状态信息：全新、已使用、待维修、报废
- 供应商信息：供应商、采购日期、采购价格
3.2 库存管理方式
采用混合管理模式：
- 高价值设备：序列号管理（每个设备单独跟踪）
- 低价值配件：批次管理（按采购批次跟踪）
- 简单数量管理：只记录总数（适用于消耗品）
3.3 出入库流程设计
A. 采购入库流程
Excel模板导入 → 批量入库 → 生成采购单 → 审核入库 → 更新库存
- 支持现有Excel导入方式
- 自动生成采购单编号
- 支持分批入库
B. 领用出库流程
选择物料 → 填写领用信息 → 登记安装信息 → 确认出库 → 同步到监控系统
- 管理员直接操作，无需审批流程
- 领用时预填安装信息（学校、楼宇、房间等）
- 自动创建监控设备记录
C. 退库归还流程
选择退库设备 → 选择退库类型 → 更新状态 → 退回库存
支持四种退库类型：
- 简单退库：状态变回库存，保留历史记录
- 维修退库：标记为待维修，进入维修流程
- 报废退库：进入报废流程，从监控系统移除
- 带历史退库：保留完整的安装和使用历史
3.4 库存管理功能
A. 库存总览
- 按设备类型统计数量
- 库存价值统计
- 库存状态分布（全新/已使用/待维修）
- 低库存预警
B. 定期盘点
- 每月/每季度全盘
- 盘点差异记录
- 盘点报告生成
- 库存数量调整
C. 报表统计
- 库存总览报表：各类物料数量和价值统计
- 领用统计报表：按人员、项目、时间统计
- 库存预警报表：低于安全库存的物料提醒
- 设备生命周期报告：设备从入库到报废的全过程
3.5 状态流转设计
库存中 (in_stock)
↓ 领用
已分配 (allocated)
↓ 安装
已安装 (installed)
↓ 投入使用
使用中 (in_use)
├─→ 简单退库 → 库存中
├─→ 维修退库 → 维修中 (repairing) → 维修完成 → 库存中
└─→ 报废退库 → 已报废 (scrapped)
四、数据库设计
4.1 核心数据表
-- 物料分类表
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 设备流转集成
# 领用出库时自动创建监控设备
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 关键页面设计
- 库存总览页面：卡片式数据可视化，关键指标一目了然
- 物料管理页面：支持表格和卡片视图，可按分类筛选
- 领用出库页面：向导式操作流程，简化用户操作
- 盘点管理页面：支持移动端扫码，提高盘点效率
七、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周）
- 数据库表结构创建和迁移脚本
- 后端API基础框架搭建
- 权限系统扩展（新增库存管理权限）
- 基础物料管理功能实现
交付物：
- 数据库迁移文件
- 后端基础API
- 权限配置更新
第二阶段：核心功能（2-3周）
- 出入库流程完整实现
- Excel导入导出功能
- 库存统计报表
- 与监控系统集成开发
交付物：
- 完整的出入库功能
- Excel导入模板
- 库存报表功能
- 设备流转集成
第三阶段：高级功能（1-2周）
- 移动端盘点功能
- 库存预警系统
- 设备生命周期报告
- 性能优化和测试
交付物：
- 移动端盘点支持
- 预警系统
- 完整测试报告
九、技术实现要点
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 功能测试
- 单元测试：每个API接口的独立测试
- 集成测试：库存流程与监控系统集成测试
- 业务流程测试：完整的出入库流程测试
- 数据一致性测试：库存数量与交易记录一致性验证
10.2 性能测试
- 并发测试：多用户同时操作库存
- 大数据量测试：导入大量设备数据
- 响应时间测试：关键操作响应时间
10.3 兼容性测试
- 浏览器兼容：主流浏览器测试
- 移动端兼容：手机浏览器测试
- Excel兼容：不同版本Excel导入测试
十一、风险与应对
11.1 技术风险
- 数据一致性风险：采用数据库事务和定期检查
- 性能风险：大数据量时使用分页和缓存
- 集成风险：分阶段集成，先读后写
11.2 业务风险
- 流程变更风险：设计灵活的流程配置
- 用户接受度风险：提供培训和使用文档
- 数据迁移风险：制定详细的数据迁移计划
十二、维护与支持
12.1 监控指标
- 库存操作成功率：出入库操作成功比例
- 数据一致性指标：库存数量与实际数量差异
- 用户使用指标：各功能使用频率
12.2 运维支持
- 日志记录：详细的操作日志
- 数据备份：定期库存数据备份
- 故障恢复：数据不一致时的恢复流程
十三、预期效益
13.1 业务效益
- 流程规范化：设备从采购到报废的全生命周期管理
- 库存可视化：实时掌握库存状态，避免缺料和积压
- 成本控制：精确的设备资产管理和成本核算
- 效率提升：减少人工盘点时间，提高领用效率
13.2 管理效益
- 决策支持：基于数据的采购和库存优化决策
- 责任追溯：完整的设备流转历史记录
- 合规管理：符合资产管理规范要求
十四、后续扩展考虑
14.1 功能扩展
- 供应商管理：完整的供应商信息管理
- 采购管理：采购申请、比价、合同管理
- 维修管理：设备维修流程管理
- 租赁管理：设备租赁和归还管理
14.2 技术扩展
- 条码/RFID支持：自动化库存管理
- 移动APP：独立的库存管理APP
- API开放：对外提供库存查询API
- 数据分析：基于AI的库存预测
十五、总结
本设计方案为H3C ONU设备管理系统增加了完整的库存管理功能，实现了设备从采购入库到报废退库的全生命周期管理。方案具有以下特点：
- 深度集成：与现有设备监控系统无缝集成
- 流程完整：覆盖采购、领用、安装、退库、报废全流程
- 灵活配置：支持不同设备类型的差异化管理
- 用户友好：简洁的界面和操作流程
- 可扩展性强：为后续功能扩展预留接口
该方案的实施将显著提升项目的设备管理水平和运营效率，为项目的长期发展奠定坚实基础。
文档信息：
- 创建时间：2026年4月5日
- 文档版本：v1.0
- 适用对象：开发团队、测试团队、运维团队
- 保密级别：内部使用
备注：
- 本方案基于与项目负责人的详细讨论结果整理
- 实施过程中可根据实际情况进行调整
- 建议分阶段实施，降低风险
- 重要变更需更新本文档并通知相关人员