电子元件库存管理系统 v1.0

一个基于 Flask + SQLite 的轻量库存系统，适合先本地开发，后续部署到宝塔服务器。

当前支持三类容器：

• 28格小盒大盒：常见 4 连排小盒（竖向 7 排）。
• 14格中盒大盒：中等盒子，无固定摆放图。
• 袋装清单：防静电袋列表模式（每行一个袋位，支持批量新增）。
• 袋装清单 为固定容器（系统内置一个大盒），不需要新增/删除盒子。

v1.1 新增能力：

• 支持盒子改名和删除。
• 新增盒子时可设置 前缀 + 起始序号，内部编号自动递增。
• 盒子名称自动生成：基础名称 + 编号范围，重名自动加 #2/#3。
• 首页可直接看到每个盒子的编号范围（如 A1-A28）。
• 首页新增概览按钮：快速查看已启用的编号与名称。
• 编辑页支持 启用/停用。

1. 项目结构

inventory/
├── app.py
├── requirements.txt
├── init_db.py
├── data/
│   └── inventory.db          # 首次初始化后生成
├── templates/
│   ├── index.html
│   ├── box.html
│   ├── edit.html
│   └── stats.html
└── static/
	├── css/
	│   └── style.css

2. 本地运行

2.1 安装依赖

pip install -r requirements.txt

2.2 初始化数据库

python init_db.py

初始化后会生成：data/inventory.db

2.3 启动服务

python app.py

默认访问：http://127.0.0.1:5000

2.4 登录认证（默认开启）

系统启动后会自动启用登录保护，未登录用户会被重定向到登录页。

• 默认管理员用户名：admin
• 默认管理员密码：admin123456

可通过环境变量覆盖默认账号：

$env:INVENTORY_ADMIN_USERNAME="你的管理员用户名"
$env:INVENTORY_ADMIN_PASSWORD="你的管理员密码"

首次登录后，建议立即在页面右上角进入“修改密码”完成改密。

2.4.1 忘记密码救砖

如果还能登录：

• 右上角 账号 -> 修改密码

如果已经无法登录，可在项目根目录执行下面命令重置 admin 密码（将示例密码替换为你自己的强密码）：

c:/Users/BeihongWang/Desktop/inventory/.venv/Scripts/python.exe -c "from app import app,db,User,generate_password_hash; ctx=app.app_context(); ctx.push(); u=User.query.filter_by(username='admin').first(); u.password_hash=generate_password_hash('NewPass123!'); db.session.commit(); print('admin password reset ok'); ctx.pop();"

执行完成后，用新密码重新登录。

如果要重置非 admin 账号，可用通用模板（把 target_username 和 NewPass123! 改成你的值）：

c:/Users/BeihongWang/Desktop/inventory/.venv/Scripts/python.exe -c "from app import app,db,User,generate_password_hash; target_username='your_username'; new_password='NewPass123!'; ctx=app.app_context(); ctx.push(); u=User.query.filter_by(username=target_username).first(); print('user found:', bool(u)); (setattr(u, 'password_hash', generate_password_hash(new_password)), db.session.commit(), print('password reset ok')) if u else print('skip reset'); ctx.pop();"

注意：

• INVENTORY_ADMIN_PASSWORD 仅在“系统中还没有任何用户”时用于创建默认管理员。
• 如果数据库里已经有用户，修改该环境变量不会自动改已有账号密码。

2.5 可选：启用 AI 补货建议（硅基流动）

在启动前设置环境变量：

$env:SILICONFLOW_API_KEY="你的APIKey"
$env:SILICONFLOW_MODEL="Qwen/Qwen2.5-7B-Instruct"

可选变量：

• SILICONFLOW_API_URL（默认：https://api.siliconflow.cn/v1/chat/completions）
• SILICONFLOW_TIMEOUT（默认：30 秒）

仓库概览页点击 AI补货建议 按钮即可调用接口。

也可在页面中直接配置参数：

• 入口：仓库概览 -> AI参数
• 页面：/ai/settings
• 保存文件：data/ai_settings.json

2.6 系统日志

为便于定位 AI 请求失败、配置错误、未处理异常，系统提供日志查看页面：

• 页面入口：右上角 账号 -> 系统日志
• 快速入口：仓库概览 页面 AI 补货建议卡片中的 日志
• 日志文件：data/app.log

当 AI 补货建议出现“请求失败，请稍后重试”时，优先打开系统日志查看最近的 ERROR 或 WARNING 记录。

2.7 AI 数据库聊天

系统提供数据库聊天页，支持自然语言提问并自动生成只读 SQL 查询库存数据：

• 页面：/ai/chat
• 入口：仓库概览 右侧 AI 卡片中的 聊天

安全边界：

• 只允许 SELECT/CTE 查询
• 禁止写操作（INSERT/UPDATE/DELETE/DDL 等）
• 禁止访问 users 表
• 默认自动补 LIMIT，避免一次性返回过多数据

若提问失败，可在系统日志中查看 ai_chat_* 相关记录。

联网补充（可选）：

• 聊天页可勾选 允许联网补充
• 开启后会在数据库查询结果基础上补充公开来源线索
• 回答会区分“数据库结论”和“联网参考”，并展示来源可信度与链接

本地记忆：

• AI 聊天会为当前登录用户保存本地记忆（最近对话与“记住 ...”条目）
• 记忆文件：data/ai_chat_memory.json
• 聊天页可点击 清空本地记忆 按钮重置

3. 页面说明

3.1 首页 /

• 首页已改为入口跳转到 仓库概览 页面。

3.1.1 仓库概览 /types

• 展示三类独立界面入口：28格小盒大盒、14格中盒大盒、袋装清单。
• 每类入口显示当前容器数量，点击进入单独分类页面。

3.1.2 分类独立页 /type/<box_type>

• 每个分类使用独立页面，避免容器变多后的长页翻找。
• 页面内支持新增、设置、删除，并在操作后停留在当前分类页。

3.2 盒子详情 /box/<box_id>

• 28格/14格：格子视图，点格子进入编辑。
• 袋装清单：表格视图，支持单条新增和批量新增。
• 袋装清单 仅使用编号前缀（如 BAG），不设置编号范围。
• 28格/14格 支持快速入库：多行粘贴后自动分配空位。
• 28格/14格/自定义容器 支持立创编号入库：进入对应格位编辑页后输入编号，自动拉取商品基础信息并写入当前格位。
• 支持按当前盒子导出打标 CSV（仅导出启用记录），可用于热敏打标机导入。
• 打标 CSV 列名为中英双语格式（如 料号(part_no)、备注(note)），便于直接识别。
• 打标 CSV 新增 短标签(short_label) 与 搜索关键词(search_keywords) 列，便于打标和后续检索。

3.3 编辑页 /edit/<box_id>/<slot>

• 编辑料号、名称、规格、数量、备注。
• 新增 AI 标签与备注标准化：可生成更适合标签打印的短标签、建议名称、建议备注和搜索关键词，确认后再回填表单。
• 通过按钮启用/停用。
• 可删除当前格子记录。

3.4 统计页 /stats

• 独立统计页，仅展示核心指标：库存总量 / 分类占比 / 变动趋势。
• 支持 7天 与 30天 视图切换：/stats?days=7、/stats?days=30。
• 支持分类筛选：/stats?days=30&box_type=small_28（可选值：small_28、medium_14、custom、bag、all）。
• 趋势图基于库存变动日志实时计算，来源包括：新增、快速入库、启用/停用、删除。
• 说明：升级前的历史操作不会自动回溯写入日志，趋势从启用该版本后开始逐步真实化。
• 新增最近操作时间线（最新 20 条），便于追踪库存变化来源。
• 筛选到单一分类后，指标会切换为更有意义的数据：分类库存占比 / 周期操作次数 / 活跃天数 / 分类内元件Top。
• 支持趋势数据导出 CSV：/stats/export?days=7&box_type=all（包含 daily_delta 日增减列）。
• 支持清除统计日志（当前筛选或全部），仅影响统计与趋势，不影响库存数据本体。

3.5 快速搜索与出库 /search

• 支持自然语言搜索，例如 3.3V 稳压芯片、0805 常用电阻、USB 相关器件。
• 会自动把搜索词映射到 料号 / 名称 / 规格 / 备注 组合搜索，并显示解析结果。
• 搜索结果可一键跳转到对应盒位编辑页。
• 支持快速出库：只填写数量即可扣减库存，并写入统计日志。

3.6 AI 补货建议 /ai/restock-plan

• 基于低库存清单和最近 30 天出库数据生成补货建议。
• 未配置 SILICONFLOW_API_KEY 时会返回明确错误提示。

3.7 AI 参数设置 /ai/settings

• 支持页面内编辑：API URL / 模型名称 / API Key / 超时 / 低库存阈值 / 建议条目上限。
• 同一套 AI 参数同时用于：入库预处理、自然语言搜索、重复巡检、补货建议、标签与备注标准化。
• 支持页面内编辑立创接口参数：Base URL / Path / API Key / Header / Prefix / 请求编号字段 / 超时。
• 保存后立即生效，无需改代码。

3.8 立创编号入库 /edit/<box_id>/<slot>/lcsc-import

• 请求方式：POST
• 表单字段：
  • lcsc_product_id：立创商品编号（默认按文档使用整数 productId）
  • quantity：写入数量
• 导入逻辑：
  • part_no <- productModel（兜底 productCode）
  • name <- productName
  • specification <- brandName / encapStandard / catalogName
  • note <- LCSC productCode + productId
• 鉴权支持：
  • JOP签名（推荐，示例中的 app_id/access_key/secret_key）
  • 简单Header API Key（兼容模式）

4. 袋装批量新增格式

在袋装清单页面的批量输入框里，每行一条，可用英文逗号或 Tab 分隔：

料号, 名称, 数量, 规格, 备注

示例：

10K-0603, 贴片电阻10K, 500, 0603, A袋, 常用
100nF-0603, 电容100nF, 300, 0603, B袋, X7R

说明：

• 料号、名称 必填。
• 数量 需为大于等于 0 的整数（留空按 0）。
• 无效行会跳过并提示。

5. 快速入库（28格/14格）

在盒子页面使用“快速入库”，每行一条：

料号, 名称, 数量, 规格, 位置备注, 备注

规则：

• 自动放入当前盒子的空位。
• 同料号已存在时自动累加数量（不重复占位）。
• 格子满了会跳过并提示具体行号。

6. 自动编号规则（新增）

新增盒子时只需填写：

• 前缀：如 A、B、C、BAG
• 起始序号：如 1

系统自动生成内部编号：

• 第 1 位：前缀 + 起始序号
• 第 N 位：前缀 + (起始序号 + N - 1)

示例：

• 前缀 A、起始 1、容量 28 -> A1-A28
• 前缀 B、起始 100、容量 14 -> B100-B113

盒子名生成示例：

• 基础名称 电阻盒 + 范围 A1-A28 -> 电阻盒 A1-A28
• 若发生重名会自动变为：电阻盒 A1-A28 #2

7. 元器件命名建议（简洁版）

为避免命名过长又保证可检索，建议：

• 料号(part_no)：优先写厂家/采购料号，保持唯一。
• 名称(name)：品类 + 关键值 + 封装，如 电阻10K 0603、电容100nF 0603。
• 规格(specification)：补充精度/耐压/温漂等必要信息，如 1%、50V X7R。

推荐格式：

名称: 电阻10K 0603
规格: 1%

名称: 电容100nF 0603
规格: 50V X7R

7.1 轻量入库规范（推荐）

目标：字段尽量少，但保证后续能搜索、能区分、能补货。

最少必填（3项）：

• 料号(part_no)：优先填厂家型号（如 STM32F103C8T6）。
• 名称(name)：品类 + 型号/关键值（如 MCU STM32F103C8T6）。
• 数量(quantity)：当前实际库存数量。

建议选填（2-3项）：

• 规格(specification)：只写 2-4 个关键参数（如 Cortex-M3 / 64KB Flash / LQFP-48）。
• 位置备注(location)：盒位或袋位（如 A12、BAG4）。
• 备注(note)：来源或追溯信息（如 LCSC item 9243 或商品链接）。

不建议录入（避免复杂且易过期）：

• 实时单价、促销价、交期、商城库存等动态信息。

推荐录入模板：

料号: <厂家型号>
名称: <品类 + 型号/关键值>
规格: <封装 + 关键参数>
数量: <整数>
位置备注: <盒位/袋位>
备注: <来源编号或链接>

示例：

料号: STM32F103C8T6
名称: MCU STM32F103C8T6
规格: Cortex-M3 / 64KB Flash / LQFP-48
数量: 10
位置备注: BAG4
备注: LCSC item 9243

8. 数据库说明

• 使用 SQLite，文件路径：data/inventory.db
• 库存变动日志表：inventory_events（用于统计页趋势计算）
• inventory_events 主要字段：box_type、part_no、event_type、delta、created_at
• 首次发布执行一次 python init_db.py
• 后续通常不需要重复初始化

9. 服务器部署（宝塔）

建议流程：

1. 上传代码或 git clone 到服务器。
2. 创建并启用虚拟环境。
3. pip install -r requirements.txt
4. python init_db.py
5. 用 Gunicorn 启动：app:app
6. 宝塔/Nginx 反向代理到 Gunicorn 端口
7. 域名解析 + SSL

建议 Gunicorn 仅监听内网：127.0.0.1:5000

10. 日常发布流程

本地开发后：

git add .
git commit -m "feat: xxx"
git push origin main

服务器更新：

cd /www/wwwroot/inventory
git pull origin main
source venv/bin/activate
pip install -r requirements.txt

最后在宝塔里重启 Python 项目。

11. 备份建议

重点备份：data/inventory.db

可按天备份，例如：

cp /www/wwwroot/inventory/data/inventory.db /www/backup/inventory_$(date +%F).db

12. 常见问题

Q1: VS Code 提示无法解析 flask 导入

通常是编辑器没选到正确虚拟环境，不代表代码不能运行。切换解释器到项目 venv 即可。

Q2: 为什么线上不能用 python app.py 长期跑

python app.py 是开发模式。生产请使用 Gunicorn（或其他 WSGI）并由宝塔托管。

Q3: 本地和服务器数据库要实时同步吗

不建议 SQLite 双向实时同步。建议以服务器库为主，本地用于测试。

13. 后续 AI 代办清单

下面这份清单按“先容易落地、再逐步增强”的顺序排列，建议后续按阶段推进，不要一次铺太大。

第一阶段：先做能直接省时间的功能

• AI 入库预处理
• 支持粘贴采购清单、聊天记录、Excel 文本后，由 AI 自动拆分为 料号 / 名称 / 数量 / 规格 / 备注
• 自动识别脏数据，例如缺字段、数量格式异常、字段顺序混乱
• 输出结构化预览结果，用户确认后再正式写入库存
• 对接现有快速入库 / 袋装批量新增流程，不直接绕开人工确认

第二阶段：提升库存数据质量

• AI 重复物料巡检
• 定期扫描库存，找出“疑似同料号”“疑似同参数”“疑似同立创编号”的记录
• 输出“疑似重复物料清单”，由人工决定是否合并
• 给出重复原因说明，例如名称近似、规格一致、备注含相同 LCSC 编号
• 增加“建议统一名称/规格写法”的辅助提示

第三阶段：升级补货能力

• AI 缺货风险预测

• 不只看当前库存阈值，还结合最近 7 天 / 30 天出库趋势评估风险

• 给出“预计可支撑天数”“风险等级”“建议补货时机”

• 在现有 AI 补货建议基础上增加“为什么建议补货”的解释

• AI 采购建议优化

• 结合 最小包装量 给出更合理的采购数量

• 将补货建议分为 紧急 / 本周 / 可延后

• 支持把多个建议项整理成采购清单草稿

第四阶段：提升查找和录入体验

• AI 自然语言搜索

• 支持搜索“3.3V 稳压芯片”“0805 常用电阻”“USB 相关器件”这类自然语言

• 将自然语言自动映射到 名称 / 规格 / 备注 / 料号 的组合搜索

• AI 标签与备注标准化

• 自动生成更适合标签打印的短名称

• 自动补全更统一的备注格式和搜索关键词

• 让名称更短、备注更规范，方便后续检索和盘点

第五阶段：做更深层的数据分析

• AI 异常库存行为分析
• 分析哪些元件短时间频繁出库、频繁被修改、频繁被合并
• 标出值得人工复查的异常记录
• 为后续库存盘点提供风险提示

14. AI 开发顺序建议

建议按下面顺序做，避免功能做散：

1. 先做 AI 入库预处理
2. 再做 AI 重复物料巡检
3. 然后把 AI 补货建议 升级为 缺货风险预测 + 采购建议优化
4. 最后再补 自然语言搜索 / 标签标准化 / 异常分析

这样安排的原因：

• AI 入库预处理 最容易立刻省时间
• AI 重复物料巡检 能提升库存数据质量，为后续 AI 功能打基础
• 缺货预测 和 采购建议 依赖更干净、更稳定的历史数据
• 自然语言搜索 和 异常分析 更适合在系统稳定后增强体验

15. 当前最推荐优先做的一项

当前最推荐优先实现：AI 入库预处理

原因：

• 最贴近日常使用场景
• 改动风险低，不会破坏现有库存规则
• 可以复用现有快速入库、袋装批量、人工确认合并流程
• 做完后，后续 重复物料巡检、补货预测 的数据基础也会更好