feat(auth): 添加用户权限获取接口并完善JWT令牌角色信息

- 在JWT令牌中添加用户角色信息
- 新增get_my_permissions接口用于获取当前用户权限码列表
- 重构认证回调逻辑,增加错误日志记录
- 更新用户信息获取接口使用Authorization头验证
```
This commit is contained in:
2026-04-06 00:40:08 +08:00
parent dfa8fa62a8
commit f1f8518985
71 changed files with 9402 additions and 191 deletions
+532
View File
@@ -0,0 +1,532 @@
# 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. 重要变更需更新本文档并通知相关人员