PartShelf V2 - 电子元器件库存管理系统

一个现代化的电子元器件库存管理系统，具有智能批量导入、一键出库、库存历史记录等功能，采用模块化架构设计，易于维护和扩展。

✨ 功能特性

📦 库存管理

✅ 添加、编辑和删除电子元件
✅ 实时库存数量跟踪
✅ 按类型、封装、制造商分类管理
✅ 库存预警（低库存提示）
✅ 单件入库/出库操作
✅ 器件详情弹窗（无需跳转页面）
✅ 器件参数显示（JSON 格式）

📊 批量操作

✅ CSV/Excel 批量导入
✅ 一键批量出库（智能匹配）
✅ 批量入库功能
✅ 数据导出（CSV/Excel）
✅ 智能零件匹配算法

📝 历史记录

✅ 完整的库存操作历史
✅ 操作类型追踪（入库/出库/调整）
✅ 数量变化记录
✅ 操作备注支持
✅ 历史数据分页查询

🔍 高级筛选

✅ 多条件组合搜索
✅ 可筛选字段搜索（制造商/封装/类型）
✅ 表头排序功能
✅ 分页显示
✅ 快速搜索

🎨 用户界面

✅ 响应式设计
✅ 现代化 UI（Bootstrap 5）
✅ 流畅动画效果
✅ 实时操作反馈
✅ 模块化前端架构

⚙️ 可配置化

✅ 自定义类别管理
✅ 自定义子类别管理
✅ 参数模板配置
✅ 位号前缀自动分配
✅ 设置页面管理

📡 IoT 集成（可选）

✅ MQTT 消息推送
✅ 库存变更事件发布
✅ 可配置的 MQTT 代理
✅ 断线重连机制

🛠️ 技术栈

后端

Python 3.8+ - 编程语言
FastAPI - 高性能 Web 框架
SQLAlchemy - ORM 数据库操作
SQLite - 轻量级数据库
Pydantic - 数据验证

前端

HTML5/CSS3 - 页面结构和样式
JavaScript (ES6+) - 交互逻辑
Bootstrap 5 - UI 框架
Font Awesome - 图标库
模块化架构 - 8个功能模块

数据处理

pandas - 数据处理和分析
openpyxl - Excel 文件处理
python-multipart - 文件上传支持

IoT 集成（可选）

paho-mqtt - MQTT 客户端库

📁 项目结构

PartShelf-V2/
├── app/                      # 应用主目录
│   ├── api/                  # API 路由
│   │   ├── inventory_api_routes.py   # 库存管理API
│   │   ├── project_api_routes.py     # 项目管理API
│   │   ├── config_api_routes.py      # 配置管理API
│   │   └── web_routes.py             # Web页面路由
│   ├── crud/                 # 数据库操作层
│   ├── models/               # 数据模型
│   │   ├── part.py                   # 零件模型
│   │   ├── config.py                 # 配置模型（类别/子类别/参数模板）
│   │   └── ...
│   ├── schemas/              # Pydantic 数据验证
│   │   ├── inventory.py              # 库存数据验证
│   │   ├── config.py                 # 配置数据验证
│   │   └── ...
│   ├── services/             # 业务逻辑层
│   │   ├── inventory_service.py      # 库存服务
│   │   ├── config_service.py         # 配置服务
│   │   ├── mqtt_service.py           # MQTT 服务（可选）
│   │   ├── part_id_service.py        # 零件ID生成服务
│   │   └── ...
│   └── main.py               # 应用入口
├── db/                       # 数据库
│   ├── database.py           # 数据库配置
│   └── partshelf.db          # SQLite 数据库文件
├── static/                   # 静态资源
│   ├── css/                  # 样式文件
│   │   ├── bootstrap.css     # Bootstrap 样式
│   │   └── custom.css        # 自定义样式
│   ├── js/                   # JavaScript 文件
│   │   ├── inventory/        # 库存管理模块（10个模块）
│   │   │   ├── utils.js              # 工具函数
│   │   │   ├── cache.js              # 数据缓存
│   │   │   ├── filter.js             # 筛选搜索
│   │   │   ├── table.js              # 表格排序和器件详情弹窗
│   │   │   ├── stock-operations.js   # 库存操作
│   │   │   ├── batch-operations.js   # 批量操作
│   │   │   ├── history.js            # 历史记录
│   │   │   ├── sidebar.js            # 侧栏筛选
│   │   │   ├── form-cascade.js       # 表单级联
│   │   │   ├── config-loader.js      # 配置加载
│   │   │   └── main.js               # 主入口
│   │   ├── bootstrap.bundle.js
│   │   ├── projects.js
│   │   └── project_details.js
│   └── favicon.ico
├── templates/                # HTML 模板
│   ├── inventory.html        # 库存管理页面（含器件详情弹窗）
│   ├── projects.html         # 项目管理页面
│   ├── project_details.html  # 项目详情页面
│   ├── component_details.html # 元件详情页面（独立页面）
│   ├── settings.html         # 设置页面
│   └── _navbar.html          # 导航栏模板
├── Dockerfile                # Docker 构建文件
├── docker-compose.yml        # Docker 编排
├── requirements.txt          # Python 依赖
└── .env                      # 环境变量配置

🚀 快速开始

方式一：Docker 部署（推荐）

详见下方 Docker 部署教程

方式二：本地开发环境

1. 环境要求

Python 3.8 或更高版本
pip 包管理器

2. 安装步骤

# 克隆项目
git clone <repository-url>
cd PartShelf-V2

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 启动应用
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

访问 http://localhost:8000 查看应用

访问 http://localhost:8000/settings 管理配置

🐳 Docker 部署教程

前置要求

安装 Docker
安装 Docker Compose（Docker Desktop 已包含）

方式一：使用 Docker Compose（推荐）

1. 拉取项目代码

# 克隆仓库
git clone https://github.com/FASUZO/PartShelf-V2.git

# 进入项目目录
cd PartShelf-V2

2. 配置环境变量

创建或编辑 .env 文件：

# 应用配置
APP_HOST=0.0.0.0
APP_PORT=8000

# 数据库配置
DATABASE_URL=sqlite:///./db/partshelf.db

# MQTT 配置（可选）
MQTT_ENABLED=false
MQTT_BROKER=127.0.0.1
MQTT_PORT=1883
MQTT_USERNAME=
MQTT_PASSWORD=
MQTT_TOPIC_PREFIX=partshelf

3. 构建并启动容器

# 构建并启动（后台运行）
docker-compose up -d

# 查看日志
docker-compose logs -f

# 查看运行状态
docker-compose ps

4. 配置 MQTT（可选）

如果需要 MQTT 功能，可以在设置页面（/settings）中配置，或通过环境变量配置：

# 在 .env 文件中添加
MQTT_ENABLED=true
MQTT_BROKER=your-mqtt-broker.com
MQTT_PORT=1883
MQTT_USERNAME=your-username
MQTT_PASSWORD=your-password
MQTT_TOPIC_PREFIX=partshelf

5. 访问应用

打开浏览器访问：http://localhost:8000

6. 常用命令

# 停止容器
docker-compose down

# 重启容器
docker-compose restart

# 查看日志
docker-compose logs -f

# 进入容器
docker-compose exec app bash

# 重新构建并启动
docker-compose up -d --build

# 停止并删除容器、网络
docker-compose down -v

方式二：使用 Dockerfile 手动构建

1. 拉取项目代码

# 克隆仓库
git clone https://github.com/FASUZO/PartShelf-V2.git

# 进入项目目录
cd PartShelf-V2

2. 构建镜像

# 构建 Docker 镜像
docker build -t partshelf-v2 .

# 查看镜像
docker images

3. 运行容器

# 创建数据持久化目录
mkdir -p ./data/db

# 运行容器
docker run -d \
  --name partshelf \
  -p 8000:8000 \
  -v $(pwd)/data/db:/app/db \
  -e DATABASE_URL=sqlite:///./db/partshelf.db \
  partshelf-v2

Windows PowerShell 版本：

# 创建数据持久化目录
New-Item -ItemType Directory -Force -Path .\data\db

# 运行容器
docker run -d `
  --name partshelf `
  -p 8000:8000 `
  -v ${PWD}\data\db:/app/db `
  -e DATABASE_URL=sqlite:///./db/partshelf.db `
  partshelf-v2

4. 管理容器

# 查看运行状态
docker ps

# 查看日志
docker logs -f partshelf

# 停止容器
docker stop partshelf

# 启动容器
docker start partshelf

# 删除容器
docker rm -f partshelf

# 进入容器
docker exec -it partshelf bash

数据持久化

数据持久化非常重要，否则容器删除后数据会丢失。

使用 Docker Compose（已配置）

docker-compose.yml 已配置数据卷：

volumes:
  - ./db:/app/db

数据库文件会保存在宿主机的 ./db 目录。

使用 Docker 命令

# 挂载数据库目录
docker run -d \
  -p 8000:8000 \
  -v $(pwd)/db:/app/db \
  partshelf-v2

生产环境部署

1. 使用 Nginx 反向代理

创建 nginx.conf：

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

更新 docker-compose.yml：

version: '3.8'

services:
  app:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - ./db:/app/db
    environment:
      - DATABASE_URL=sqlite:///./db/partshelf.db
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - app
    restart: unless-stopped

2. 使用 HTTPS（Let's Encrypt）

# 安装 certbot
sudo apt install certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d your-domain.com

# 自动续期
sudo certbot renew --dry-run

3. 性能优化

更新 docker-compose.yml：

services:
  app:
    build: .
    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
    # ... 其他配置

故障排查

1. 查看容器日志

docker-compose logs -f
docker logs partshelf

2. 数据库问题

# 进入容器
docker-compose exec app bash

# 检查数据库文件
ls -la db/

# 检查数据库权限
chmod 666 db/partshelf.db

3. 端口冲突

# 查看端口占用
# Windows:
netstat -ano | findstr :8000

# Linux/Mac:
lsof -i :8000

# 修改端口
docker-compose.yml 中修改 ports: "8001:8000"

4. 重新初始化数据库

# 停止容器
docker-compose down

# 备份数据库
cp db/partshelf.db db/partshelf.db.backup

# 删除数据库
cp db/partshelf.db db/partshelf.db.backup

# 重启容器
docker-compose up -d

📖 使用说明

基本操作

浏览库存 - 访问主页查看所有电子元件
添加元件 - 点击"添加零件"按钮录入新元件
批量导入 - 通过 CSV/Excel 文件批量导入
搜索筛选 - 使用搜索框和高级筛选查找元件
库存操作 - 点击入库/出库按钮调整库存
查看详情 - 点击眼睛图标查看器件详情弹窗
器件参数 - 在详情弹窗中查看器件参数（JSON 格式）

入库防重复机制

系统通过以下字段组合判断零件唯一性，防止重复录入：

校验字段	说明	示例
名称 (name)	零件型号名称	SS54、ESP-12F
制造商 (manufacturer)	生产厂商	TI、安信可
封装 (package)	物理封装类型	SOT-23、DIP-8

入库流程：

输入数据 (名称 + 制造商 + 封装 + 数量 + ...)
    ↓
查询库存中是否存在相同的 "名称 + 制造商 + 封装" 组合
    ↓
存在 → 直接增加该零件的库存数量
不存在 → 创建新零件记录 + 创建库存记录

注意事项：

同一零件使用不同名称（如 SS54 vs SS-54）会被视为不同零件
同一制造商使用不同写法（如 TI vs Texas Instruments）会被视为不同制造商
LC Number 不参与去重判断，仅作为参考信息存储

器件详情弹窗

点击器件列表中的眼睛图标
弹窗显示器件基本信息、描述、参数和操作选项
可以在弹窗中更新数量、查看历史、导出详情、删除零件
参数表格显示器件的自定义参数（如阻值、功率、精度等）

可配置化管理

访问设置页面（/settings）
管理类别和子类别
配置参数模板
设置位号前缀

批量出库流程

准备 CSV 文件（包含 Name 和 Quantity 列）
点击"一键出库"上传文件
系统自动匹配库存
确认匹配结果
执行批量出库

库存历史查询

点击"使用历史"菜单
可按操作类型筛选
查看所有库存变更记录

🤝 贡献指南

欢迎贡献代码、报告问题或提出建议！

贡献步骤

Fork 本仓库
创建功能分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
提交 Pull Request

代码规范

Python: 遵循 PEP 8 规范
JavaScript: 使用模块化架构
注释: 所有函数添加中文注释
提交: 使用清晰的提交信息
配置: 使用 JSON 格式存储参数模板

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

📮 联系方式

项目问题: GitHub Issues
邮件联系: fasuzo@qq.com

🙏 致谢

感谢以下开源项目：

⭐ 如果这个项目对您有帮助，请给个 Star！

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.mimocode/plans		.mimocode/plans
app		app
db		db
docs		docs
mosquitto/config		mosquitto/config
static		static
templates		templates
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
lcsc-playwright-scraper.mjs		lcsc-playwright-scraper.mjs
package-lock.json		package-lock.json
package.json		package.json
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

PartShelf V2 - 电子元器件库存管理系统

✨ 功能特性

📦 库存管理

📊 批量操作

📝 历史记录

🔍 高级筛选

🎨 用户界面

⚙️ 可配置化

📡 IoT 集成（可选）

🛠️ 技术栈

后端

前端

数据处理

IoT 集成（可选）

📁 项目结构

🚀 快速开始

方式一：Docker 部署（推荐）

方式二：本地开发环境

1. 环境要求

2. 安装步骤

🐳 Docker 部署教程

前置要求

方式一：使用 Docker Compose（推荐）

1. 拉取项目代码

2. 配置环境变量

3. 构建并启动容器

4. 配置 MQTT（可选）

5. 访问应用

6. 常用命令

方式二：使用 Dockerfile 手动构建

1. 拉取项目代码

2. 构建镜像

3. 运行容器

4. 管理容器

数据持久化

使用 Docker Compose（已配置）

使用 Docker 命令

生产环境部署

1. 使用 Nginx 反向代理

2. 使用 HTTPS（Let's Encrypt）

3. 性能优化

故障排查

1. 查看容器日志

2. 数据库问题

3. 端口冲突

4. 重新初始化数据库

📖 使用说明

基本操作

入库防重复机制

器件详情弹窗

可配置化管理

批量出库流程

库存历史查询

🤝 贡献指南

贡献步骤

代码规范

📄 许可证

📮 联系方式

🙏 致谢

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages