H3ConuMS-v2/库存管理功能设计方案.md

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