# 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. 重要变更需更新本文档并通知相关人员