wangbeihong
8e0bd4f995
- 更新了 AI 设置页面，统一了 AI 补充、自然语言搜索、入站预处理和标签标准化的配置。 - 在编辑页面新增了 AI 标签和笔记标准化板块，包括建议预览及应用功能。 - 改进的搜索页面，支持带有示例的自然语言查询和模糊选择下拉菜单。 - 增强的搜索结果显示，包含更多匹配信息和查看 AI 搜索过程的模态。 - 更新新组件样式，优化布局以提升用户体验。
428 lines
14 KiB
Markdown
428 lines
14 KiB
Markdown
# 电子元件库存管理系统 v1.0
|
||
|
||
一个基于 `Flask + SQLite` 的轻量库存系统，适合先本地开发，后续部署到宝塔服务器。
|
||
|
||
当前支持三类容器：
|
||
|
||
- `28格小盒大盒`：常见 4 连排小盒（竖向 7 排）。
|
||
- `14格中盒大盒`：中等盒子，无固定摆放图。
|
||
- `袋装清单`：防静电袋列表模式（每行一个袋位，支持批量新增）。
|
||
- `袋装清单` 为固定容器（系统内置一个大盒），不需要新增/删除盒子。
|
||
|
||
v1.1 新增能力：
|
||
|
||
- 支持盒子改名和删除。
|
||
- 新增盒子时可设置 `前缀 + 起始序号`，内部编号自动递增。
|
||
- 盒子名称自动生成：`基础名称 + 编号范围`，重名自动加 `#2/#3`。
|
||
- 首页可直接看到每个盒子的编号范围（如 `A1-A28`）。
|
||
- 首页新增概览按钮：快速查看已启用的编号与名称。
|
||
- 编辑页支持 `启用/停用`。
|
||
|
||
## 1. 项目结构
|
||
|
||
```text
|
||
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 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 2.2 初始化数据库
|
||
|
||
```bash
|
||
python init_db.py
|
||
```
|
||
|
||
初始化后会生成：`data/inventory.db`
|
||
|
||
### 2.3 启动服务
|
||
|
||
```bash
|
||
python app.py
|
||
```
|
||
|
||
默认访问：`http://127.0.0.1:5000`
|
||
|
||
### 2.4 可选：启用 AI 补货建议（硅基流动）
|
||
|
||
在启动前设置环境变量：
|
||
|
||
```powershell
|
||
$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`
|
||
|
||
## 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 分隔：
|
||
|
||
```text
|
||
料号, 名称, 数量, 规格, 备注
|
||
```
|
||
|
||
示例：
|
||
|
||
```text
|
||
10K-0603, 贴片电阻10K, 500, 0603, A袋, 常用
|
||
100nF-0603, 电容100nF, 300, 0603, B袋, X7R
|
||
```
|
||
|
||
说明：
|
||
|
||
- `料号`、`名称` 必填。
|
||
- `数量` 需为大于等于 0 的整数（留空按 0）。
|
||
- 无效行会跳过并提示。
|
||
|
||
## 5. 快速入库（28格/14格）
|
||
|
||
在盒子页面使用“快速入库”，每行一条：
|
||
|
||
```text
|
||
料号, 名称, 数量, 规格, 位置备注, 备注
|
||
```
|
||
|
||
规则：
|
||
|
||
- 自动放入当前盒子的空位。
|
||
- 同料号已存在时自动累加数量（不重复占位）。
|
||
- 格子满了会跳过并提示具体行号。
|
||
|
||
## 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`。
|
||
|
||
推荐格式：
|
||
|
||
```text
|
||
名称: 电阻10K 0603
|
||
规格: 1%
|
||
```
|
||
|
||
```text
|
||
名称: 电容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` 或商品链接）。
|
||
|
||
不建议录入（避免复杂且易过期）：
|
||
|
||
- 实时单价、促销价、交期、商城库存等动态信息。
|
||
|
||
推荐录入模板：
|
||
|
||
```text
|
||
料号: <厂家型号>
|
||
名称: <品类 + 型号/关键值>
|
||
规格: <封装 + 关键参数>
|
||
数量: <整数>
|
||
位置备注: <盒位/袋位>
|
||
备注: <来源编号或链接>
|
||
```
|
||
|
||
示例：
|
||
|
||
```text
|
||
料号: 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. 日常发布流程
|
||
|
||
本地开发后：
|
||
|
||
```bash
|
||
git add .
|
||
git commit -m "feat: xxx"
|
||
git push origin main
|
||
```
|
||
|
||
服务器更新：
|
||
|
||
```bash
|
||
cd /www/wwwroot/inventory
|
||
git pull origin main
|
||
source venv/bin/activate
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
最后在宝塔里重启 Python 项目。
|
||
|
||
## 11. 备份建议
|
||
|
||
重点备份：`data/inventory.db`
|
||
|
||
可按天备份，例如：
|
||
|
||
```bash
|
||
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 代办清单
|
||
|
||
下面这份清单按“先容易落地、再逐步增强”的顺序排列，建议后续按阶段推进，不要一次铺太大。
|
||
|
||
### 第一阶段：先做能直接省时间的功能
|
||
|
||
- [x] AI 入库预处理
|
||
- [x] 支持粘贴采购清单、聊天记录、Excel 文本后，由 AI 自动拆分为 `料号 / 名称 / 数量 / 规格 / 备注`
|
||
- [x] 自动识别脏数据，例如缺字段、数量格式异常、字段顺序混乱
|
||
- [x] 输出结构化预览结果，用户确认后再正式写入库存
|
||
- [x] 对接现有快速入库 / 袋装批量新增流程，不直接绕开人工确认
|
||
|
||
### 第二阶段：提升库存数据质量
|
||
|
||
- [x] AI 重复物料巡检
|
||
- [x] 定期扫描库存，找出“疑似同料号”“疑似同参数”“疑似同立创编号”的记录
|
||
- [x] 输出“疑似重复物料清单”，由人工决定是否合并
|
||
- [x] 给出重复原因说明，例如名称近似、规格一致、备注含相同 LCSC 编号
|
||
- [x] 增加“建议统一名称/规格写法”的辅助提示
|
||
|
||
### 第三阶段：升级补货能力
|
||
|
||
- [ ] AI 缺货风险预测
|
||
- [ ] 不只看当前库存阈值，还结合最近 7 天 / 30 天出库趋势评估风险
|
||
- [ ] 给出“预计可支撑天数”“风险等级”“建议补货时机”
|
||
- [ ] 在现有 AI 补货建议基础上增加“为什么建议补货”的解释
|
||
|
||
- [ ] AI 采购建议优化
|
||
- [ ] 结合 `最小包装量` 给出更合理的采购数量
|
||
- [ ] 将补货建议分为 `紧急 / 本周 / 可延后`
|
||
- [ ] 支持把多个建议项整理成采购清单草稿
|
||
|
||
### 第四阶段：提升查找和录入体验
|
||
|
||
- [x] AI 自然语言搜索
|
||
- [x] 支持搜索“3.3V 稳压芯片”“0805 常用电阻”“USB 相关器件”这类自然语言
|
||
- [x] 将自然语言自动映射到 `名称 / 规格 / 备注 / 料号` 的组合搜索
|
||
|
||
- [x] AI 标签与备注标准化
|
||
- [x] 自动生成更适合标签打印的短名称
|
||
- [x] 自动补全更统一的备注格式和搜索关键词
|
||
- [x] 让名称更短、备注更规范，方便后续检索和盘点
|
||
|
||
### 第五阶段：做更深层的数据分析
|
||
|
||
- [ ] AI 异常库存行为分析
|
||
- [ ] 分析哪些元件短时间频繁出库、频繁被修改、频繁被合并
|
||
- [ ] 标出值得人工复查的异常记录
|
||
- [ ] 为后续库存盘点提供风险提示
|
||
|
||
## 14. AI 开发顺序建议
|
||
|
||
建议按下面顺序做，避免功能做散：
|
||
|
||
1. 先做 `AI 入库预处理`
|
||
2. 再做 `AI 重复物料巡检`
|
||
3. 然后把 `AI 补货建议` 升级为 `缺货风险预测 + 采购建议优化`
|
||
4. 最后再补 `自然语言搜索 / 标签标准化 / 异常分析`
|
||
|
||
这样安排的原因：
|
||
|
||
- `AI 入库预处理` 最容易立刻省时间
|
||
- `AI 重复物料巡检` 能提升库存数据质量，为后续 AI 功能打基础
|
||
- `缺货预测` 和 `采购建议` 依赖更干净、更稳定的历史数据
|
||
- `自然语言搜索` 和 `异常分析` 更适合在系统稳定后增强体验
|
||
|
||
## 15. 当前最推荐优先做的一项
|
||
|
||
当前最推荐优先实现：`AI 入库预处理`
|
||
|
||
原因：
|
||
|
||
- 最贴近日常使用场景
|
||
- 改动风险低，不会破坏现有库存规则
|
||
- 可以复用现有快速入库、袋装批量、人工确认合并流程
|
||
- 做完后，后续 `重复物料巡检`、`补货预测` 的数据基础也会更好
|