# 垛位管理
**Repository Path**: webvip/stack-management
## Basic Information
- **Project Name**: 垛位管理
- **Description**: 仓储垛位管理系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-11-10
- **Last Updated**: 2026-11-10
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 垛序仓储 · 生产厂家码垛仓储管理系统
面向生产厂家成品库的 B/S 仓储管理系统。以“垛位”为核心管理单元,提供可编辑的厂区平面图、动态仓位布局、生产入库、发货出库、客户车辆登记、语音录入、收发存流水、日报/月报和只读分享能力,适配电脑和手机浏览器。
## 在线系统
| 系统 | 访问地址 | 说明 |
| --- | --- | --- |
| 系统导航 | | ERPNext、垛序仓储及后续系统的统一入口 |
| 垛序仓储 | | 本系统的生产工作台 |
| 系统管理台 | | 使用独立管理密码登录,不占用普通用户入口 |
| ERPNext | | 原 ERPNext,根路径保持不变 |
ERPNext 已占用根路径,因此仓储系统部署在 `/warehouse/`,统一导航部署在 `/portal/`;ERPNext 登录页右上角也提供“垛序仓储 / 系统导航”入口。生产账号和密码不在 Git 中保存,请从服务器 `/root/wms-credentials.txt`(仅 root 可读)获取。
## 已实现功能
- **厂区平面图**:展示厂区大门、主通道、横向通道、道路节点和库区,明确从大门到各垛位的行车路线;支持设置多个厂区大门和多个固定装车区。演示布局为 A、B、C 三个库区、每区 3 个垛位,实际垛位数量不限,可按真实位置分布并支持缩放和横向滑动查看。
- **垛位区归组查看**:同一库区代码下的多个垛位会自动归为一个垛位区;点击平面图中的垛位区名称或空白区域,可查看区内全部垛位、库存、货品和日期,再点击单个垛位进入详情。
- **已有示意图导入**:可以把现成厂区图上传为底图,按底图摆放垛位、装卸位和道路节点,无需重新绘制整张图;AI 识别为可选项。
- **大字体与全屏查看**:平面图垛位编码、货品、数量、库区名称、道路标识和总览控件均已放大,垛位文字关闭字体合成加粗以避免重影;支持缩放、全屏查看和手机横向滑动。
- **垛前装卸位**:每个垛位前方在靠近通道的位置显示小车标识,表示该垛位的固定装卸位置;点击垛位即可查看货品和库存。
- **固定装车停靠区**:平面图标出装车车位、状态和当前占用车辆;可在设计器中新增多个固定装车区,装车作业只对应这些停靠区,其他垛位区域不设车辆停靠点。
- **可视化布局设计器**:仓管员可拖动库区、垛位、垛前装卸位、道路节点、大门和固定装车区;库区和垛位均支持八向边框缩放及精确宽高输入,库区缩放时区内垛位与装卸位同步缩放;可新增道路、大门和装车区,修改图纸名称并保存,所有终端和只读分享页同步更新。
- **底图自由变换**:上传 PNG / JPG / WebP 厂区平面图后,可在“底图位置”模式中拖动整张底图、拖四角或四边手柄任意拉伸缩放,长图允许变形;一键“恢复底图比例”可按原始宽高比居中适配。配置视觉大模型后,还可自动识别大门、道路、装载区、垛位和装卸位,生成可继续编辑的布局草稿。
- **垛位标准规格**:每个仓位预置长 × 宽 × 高与标准容量,编码格式为 `3位序号-产品规格-包装规格-垛位规格`,例如 `008-粉-大包-201003`。
- **货品档案与动态库存**:垛位和详情显示货品名称、规格型号、生产日期、码垛日期、现有数量、本日入库、本日出库、垛位标准参考数量。
- **完整收发存记录**:点击垛位可打开期初录入、累计入库、累计出库、结存和全部库存流水,记录生产/码垛日期、客户、目的地、车辆、操作人及语音来源。
- **库存作业**:支持期初库存、生产入库、发货出库;入库增加库存,出库扣减库存,并校验垛位容量、库存下限和重复提交。
- **出库登记**:出库时登记客户、目的地、运输车辆;可选填司机、电话、承运商和备注,发货记录可追溯。
- **权限隔离**:仓管员登录后可维护库存;访客通过只读分享链接只能查看布局、仓位和货品信息,无法编辑,也看不到客户、车辆和报表等敏感数据。
- **只读分享二维码**:生成只读分享链接时同步生成对应二维码,可下载 PNG 后发给客户或管理人员;手机相机、飞书或微信扫码即可打开只读平面图和库存视图,无需登录。链接和二维码仅在创建时完整展示一次。
- **多企业管理**:可建立多个企业,每个企业拥有独立的垛位、库存、流水、报表、平面图和分享链接;系统内置独立的“演示企业”,演示数据不影响真实业务。
- **独立系统管理台**:通过专用地址 `/admin` 和独立管理密码进入,不向普通用户显示;管理共享大模型、模型优先级、注册用户和账号角色。
- **注册用户与角色权限**:用户可自行注册,默认是只读查询用户;管理员可将账号设为仓管员。只有仓管员能新增/修改垛位、录入库存和登记出库,查询用户可看平面图、垛位和报表。
- **共享与自定义大模型**:内置 ZMRPA、Agnes AI、SenseNova 三家 OpenAI 兼容接口,可设置是否开启共享;开启后按优先级自动选择并故障切换。用户也可在“个人设置”中配置自己的模型和 API Key。
- **飞书 / 企业微信通知**:每位用户可在“个人设置”中绑定自己的飞书群机器人或企业微信群机器人,选择期初录入、生产入库、发货出库事件后自动推送库存变动;网页工作台、网页语音和飞书机器人确认后的库存操作都会触发通知。Webhook 与飞书签名密钥加密保存,支持发送测试消息。
- **垛位台账维护**:在“企业与垛位”页面新增、编辑、停用或删除垛位;设定 3 位序号、库区、产品/包装规格和长宽高,标准容量与仓位编码自动生成。
- **垛位二维码**:每个垛位可生成并打印免登录二维码;扫码后可查看仓位、货品、规格型号、现有数量,并按期间查询期初库存、入库、出库、期末库存和流水,自动隐藏客户、车辆、司机和操作员等敏感信息。
- **语音录入**:浏览器语音转文字后,由大模型识别业务类型和货品字段;未配置大模型或调用失败时自动降级为内置中文规则解析。解析结果必须人工确认后才会提交。
- **日报 / 月报**:按日期范围查询出入库汇总、仓位结存和流水,并导出 Excel。
- **响应式界面**:电脑端双栏布局,手机端单栏布局,支持多终端查询。
- **一键启动**:Windows 双击 `start.cmd` 自动创建虚拟环境、安装依赖并打开浏览器;Linux/macOS 使用 `start.sh`。
## 技术栈
- 后端:FastAPI + SQLAlchemy 2 + SQLite
- 前端:原生 HTML / CSS / JavaScript,无构建链
- 报表:openpyxl 生成 Excel
- 鉴权:PBKDF2 密码哈希 + 签名会话 Cookie + 登录限流
## 快速启动
环境要求:Python 3.11 及以上。
Windows 直接双击 `start.cmd`,或在命令行执行:
```powershell
.\start.ps1
```
脚本会自动创建 `.venv`、安装依赖、复制 `.env`、打印局域网地址并打开浏览器。Linux/macOS 使用:
```bash
chmod +x start.sh
./start.sh
```
也可以手工启动:
```powershell
python -m pip install -r requirements.txt
Copy-Item .env.example .env
python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000
```
指定端口:
```powershell
.\start.ps1 -Port 8080
```
默认仓管员账号:
```text
账号:keeper
密码:Warehouse@2026
```
系统管理台:`http://127.0.0.1:8000/admin`
```text
初始管理密码:Admin@2026(由 WMS_ADMIN_PASSWORD 控制)
```
管理台入口不出现在普通业务页面中。首次登录管理台后,请立即在“安全设置”中修改独立管理密码。
首次登录后请在“个人设置”中修改密码。若数据库为空,系统会自动创建“演示企业”、A/B/C 三个库区共 9 个演示垛位、库存和近 30 天流水,便于直接验收。正式使用时不需要修改代码或重建数据库:在“企业与垛位”中新建企业,按实际仓库新增垛位,再通过“库存作业 → 期初录入”录入真实库存即可。
## 企业、真实数据与演示数据
- 演示企业编码为 `DEMO`,名称显示为“演示企业”,不能删除,其数据与真实企业完全隔离。
- 新建企业后会自动切换到该企业工作区。此时平面图、仓位、库存、流水、报表和分享链接均为空,需要先建立垛位,再录入期初库存。
- 每个企业可以使用相同的 3 位仓位序号(例如都有自己的 `008`),系统按企业隔离校验。
- 删除有历史流水的垛位时采用停用方式,保留历史报表记录;仍有库存的垛位必须先出库才能停用或删除。
- 企业可在同一工作区中随时切换,切换后所有页面只显示当前企业的数据。
## 配置说明
复制 `.env.example` 为 `.env` 后按需修改:
| 配置项 | 说明 | 默认值 |
| --- | --- | --- |
| `WMS_HOST` | 监听地址 | `0.0.0.0` |
| `WMS_PORT` | 服务端口 | `8000` |
| `WMS_DATA_DIR` | 数据目录 | `./data` |
| `WMS_DATABASE_URL` | 数据库连接串 | `sqlite:///data/wms.db` |
| `WMS_BASE_PATH` | 子路径部署前缀,例如 `/warehouse`;根路径留空 | 空 |
| `WMS_PUBLIC_BASE_URL` | 对外访问地址,用于生成完整分享链接 | 空 |
| `WMS_COOKIE_SECURE` | HTTPS 部署时设为 `true` | `false` |
| `WMS_INITIAL_USERNAME` | 首次初始化仓管员账号 | `keeper` |
| `WMS_INITIAL_PASSWORD` | 首次初始化密码 | `Warehouse@2026` |
| `WMS_INITIAL_DISPLAY_NAME` | 仓管员显示名称 | `仓库管理员` |
| `WMS_SHOW_DEFAULT_LOGIN_HINT` | 登录页是否显示默认账号密码提示;公开部署设为 `false` | `true` |
| `WMS_ADMIN_PASSWORD` | 独立管理台首次初始化密码,登录后可在管理台修改 | `Admin@2026` |
| `ZMRPA_LLM_API_KEY` | ZMRPA 共享模型 Key;免费接口可留空 | 空 |
| `AGNES_LLM_API_KEY` | Agnes AI 共享模型 Key | 空 |
| `SENSENOVA_LLM_API_KEY` | SenseNova 共享模型 Key | 空 |
| `LLM_API_KEY` | 兼容旧版单模型配置的密钥 | 空 |
| `LLM_BASE_URL` | 大模型接口地址 | `https://api.openai.com/v1` |
| `LLM_MODEL` | 模型名称 | `gpt-4.1-mini` |
| `LLM_VISION_MODEL` | 平面图识别的视觉模型;留空时与 `LLM_MODEL` 相同 | 空 |
| `LLM_TIMEOUT_SECONDS` | 大模型调用超时 | `25` |
| `FEISHU_BOT_ENABLED` | 是否启用飞书自建应用机器人;管理台页面配置优先 | `false` |
| `FEISHU_CONNECTION_MODE` | 事件接收方式:`long` 长连接(推荐)或 `callback` HTTP 回调 | `long` |
| `FEISHU_APP_ID` | 飞书自建应用 App ID | 空 |
| `FEISHU_APP_SECRET` | 飞书自建应用 App Secret,建议只在管理台填写 | 空 |
| `FEISHU_VERIFICATION_TOKEN` | HTTP 回调模式的 Verification Token;长连接模式不需要 | 空 |
| `FEISHU_ENCRYPT_KEY` | HTTP 回调模式的 Encrypt Key;长连接模式不需要 | 空 |
安装依赖时请保留 `python-multipart`,平面图底图和 AI 识别均依赖其接收文件上传。
### 接入大模型语音解析
推荐登录 `/admin`,在“共享大模型”中配置并开启共享开关。系统内置以下三家 OpenAI 兼容供应商:
- ZMRPA:`https://www.zmrpa.cn/freellmapi/v1`
- Agnes AI:`https://apihub.agnes-ai.com/v1`
- SenseNova 商汤:`https://token.sensenova.cn/v1`
每个供应商可配置接口地址、对话模型、视觉模型、API Key、优先级和启停状态。共享开关开启后,系统按优先级自动选择第一个可用模型;某个模型连接失败时会自动切换下一个可用模型。管理员还可以继续新增自定义共享供应商。
如果关闭共享模型,用户仍可在“个人设置 → 大模型设置”中填写自己的 OpenAI 兼容接口、模型和 Key,并点击“测试连通性”验证。API Key 使用系统密钥加密后存入数据库,接口只返回脱敏值,不会回传明文。
只要接口兼容 OpenAI Chat Completions,也可以指向其他厂商网关。后端仅让模型抽取业务字段,不会直接执行模型返回的指令;前端会先展示识别结果,确认后才写入库存。
浏览器语音识别依赖 Web Speech API,建议使用最新版 Chrome 或 Edge。语音转文字本身由浏览器完成,不依赖大模型;业务类型(入库/出库)和字段抽取会优先调用大模型,未配置或调用失败时自动降级为内置中文规则解析。因此没有大模型也可以使用“手工输入文字 + 规则解析”。
手机端可以正常访问和语音录入。除 `localhost` / `127.0.0.1` 外,手机麦克风通常要求 HTTPS;通过局域网 HTTP 访问时,部分浏览器会禁用语音识别,可改用文字输入。正式部署建议为域名配置 HTTPS。
### 接入飞书 / 企业微信群机器人(Webhook 通知)
这里的 Webhook 对接的是**群机器人单向消息通知**,用于网页工作台、网页语音或飞书机器人确认后的期初录入、生产入库、发货出库库存提醒;它不是飞书/企业微信扫码登录,也不能在群里查询或修改库存。若要在飞书中直接办理业务,请继续看下一节“接入飞书自建应用机器人”。
| 对接方式 | 配置位置 | 能力 |
| --- | --- | --- |
| 飞书 / 企业微信群机器人 Webhook | 个人设置 → 飞书 / 企业微信通知 | 库存变动单向提醒 |
| 飞书企业自建应用机器人 | 管理台 → 飞书集成 | 查询库存、入库、出库、期初、垛位维护;写操作需回复“确认” |
每个登录账号独立保存自己的通知配置。网页端、网页语音或飞书机器人以 A 账号办理的库存操作只会推送 A 账号配置的机器人,不会自动通知其他账号;飞书机器人操作使用该飞书账号绑定的仓管员账号的通知设置。
#### 飞书群机器人 Webhook
1. 在飞书中打开接收通知的群,进入“群设置 → 群机器人 → 添加机器人 → 自定义机器人”。
2. 复制 Webhook,格式必须是 `https://open.feishu.cn/open-apis/bot/v2/hook/...`。
3. 设置机器人安全方式,推荐“签名校验”,并复制签名密钥;系统发送时会自动计算 `timestamp` 和 `sign`,不需要手工填写。
4. 如使用“自定义关键词”,填写 `垛序仓储`。系统推送文案固定以“【垛序仓储 · …】”开头,可匹配该关键词。
5. 如使用 IP 白名单,把服务器公网出口 IP 加入白名单;当前腾讯云部署通常为 `119.28.151.34`,以服务器实际出口 IP 为准。
6. 登录仓储系统,进入“个人设置 → 飞书 / 企业微信通知 → 飞书群机器人”,粘贴 Webhook 和可选签名密钥,先保存。
7. 点击“发送飞书测试消息”,确认群内收到测试消息后,再勾选“启用”和需要推送的库存事件并保存。
#### 企业微信群机器人 Webhook
1. 在企业微信中打开接收通知的群,进入“群设置 → 群机器人 → 添加机器人”。
2. 复制 Webhook,格式必须是 `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=...`。
3. 如群机器人设置了 IP 白名单,把服务器公网出口 IP 加入白名单。
4. 登录仓储系统,进入“个人设置 → 飞书 / 企业微信通知 → 企业微信群机器人”,粘贴 Webhook 并保存。
5. 点击“发送企业微信测试消息”,确认收到后,再勾选“启用”和需要推送的事件并保存。
企业微信群机器人不支持飞书那种签名校验,系统直接向官方 Webhook 发送文本消息。
#### 推送事件与开关
- “期初录入”“生产入库”“发货出库”三个事件默认全部勾选,可分别关闭;未勾选的事件不会推送。
- 网页工作台、网页语音和飞书机器人回复“确认”后执行的库存操作都会触发通知;飞书机器人使用绑定的仓管员账号及其 Webhook 设置。
- 飞书和企业微信可以同时启用,系统会分别发送;任一渠道失败不会影响另一渠道,也不会回滚已经提交的库存事务。
- 测试消息只验证 Webhook 是否可用,不需要先勾选“启用”,但必须先保存 Webhook;正式推送仍需启用对应渠道和事件。
- 通知内容包含企业、仓位、货品/规格、数量、结存、操作员和时间;出库通知还会包含客户、目的地和车辆。
- 修改 Webhook 或签名密钥时直接粘贴新值并保存;输入框留空表示保持原值,不会清空已保存内容。清除凭据前先取消“启用”,再勾选“清除 Webhook/签名密钥”。
#### 地址校验、安全与排查
- 后端只接受 `https://open.feishu.cn/open-apis/bot/v2/hook/...` 和 `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=...` 两种官方 HTTPS 地址;拒绝内网地址、其他域名、账号密码、自定义端口和 URL 片段,避免 SSRF。
- Webhook 与飞书签名密钥使用 `WMS_SECRET_KEY` 派生的服务端密钥加密存储,页面只显示脱敏值。更换 `WMS_SECRET_KEY` 会导致已保存的 Webhook、签名密钥和大模型 Key 无法解密,需要重新填写。
- 服务器必须能通过 HTTPS 访问 `open.feishu.cn` 和 `qyapi.weixin.qq.com`;企业网络限制出站访问时,Webhook 会发送失败。
- 飞书提示签名不匹配时,检查签名密钥是否与当前机器人一一对应;企业微信提示 Key 无效时,重新复制完整 Webhook,避免复制到过期或已删除机器人的地址。
- 群内没有收到消息时,依次检查:账号是否启用对应渠道、库存事件是否勾选、Webhook 是否保存、服务器出站网络是否正常、机器人是否被移出群聊。
- 发送失败只记录在 `sudo journalctl -u wms -f` 日志中,不会影响网页端已经完成的入库、出库或期初录入。
- 消息会发送到机器人所在群,群成员均可见。Webhook 等同于群机器人凭据,请只在可信业务群使用,不要转发或写入代码仓库。
### 接入飞书自建应用机器人(可查询与修改)
群机器人 Webhook 只能让系统单向发送通知;如果要在飞书里直接查询库存、入库、出库、录入期初或增删垛位,必须使用**飞书企业自建应用 + 机器人能力 + 事件订阅**。应用凭据只保存在服务端数据库,读取接口只返回脱敏值。
飞书开放平台配置:
1. 创建“企业自建应用”,在“添加应用能力”中启用**机器人**。
2. 在“权限管理”中开通 `im:message`(接收消息)和 `im:message:send_as_bot`(以机器人身份发消息)。
3. 在“事件与回调 → 事件配置”中选择**使用长连接接收事件**(推荐),订阅事件 `im.message.receive_v1`。
4. 在“凭证与基础信息”中取得 App ID 和 App Secret。长连接模式不需要回调地址、Verification Token,也不会触发 Challenge 验证。
5. 发布应用版本,并把需要使用机器人的成员加入应用可用范围。
如你的飞书应用或网络策略要求由飞书主动推送事件,也可在第 3 步选择“将事件发送至开发者服务器”使用 HTTP 回调。此时需要填写 Verification Token,并把管理台显示的回调地址填入飞书开放平台;子路径部署时通常为 `https://你的域名/warehouse/api/feishu/events`。
系统管理台配置:
1. 登录 `/admin`,进入“飞书集成”,事件接收方式选择“使用长连接接收事件(推荐)”,填写 App ID 和 App Secret,然后启用并保存。
2. 保存后点击“测试应用凭据”,系统会向飞书申请 `tenant_access_token` 验证凭据。
3. 页面显示“已连接”即表示长连接正常;保存后最多等待 5 秒。修改 App ID、App Secret 或连接方式后需要重启 `wms` 服务才能替换旧连接。
4. 让用户在飞书中给机器人发送任意消息;未绑定时机器人会返回该用户的 `open_id`。
5. 管理员在“飞书集成 → 用户绑定”中填写 `open_id`,选择 WMS 用户和所属企业。一个 WMS 用户只能绑定一个飞书账号。
6. 绑定为“查询用户”的账号只能查看;绑定为“仓管员”的账号才能执行库存和垛位写操作。
支持的文本指令与自然语言:
```text
帮助
总览
查询 008
查询 A区
入库 008 120包,货品氯化钙,规格 CL-01
A-01 | 001号 | 食品级碳酸钙 新增入库11包
出库 008 80包,客户华东公司,目的地苏州,车牌苏E8F236
A-01 001号 客户华东公司来提货 5包,目的地苏州,车牌苏E8F236
期初 008 100包,货品氯化钙,规格 CL-01
新增垛位 A 010 粉 大包 20 10 3
删除垛位 009
确认
取消
```
写操作会先返回仓位、数量、货品或客户车辆摘要,只有回复“确认”才执行;回复“取消”放弃。待确认操作 5 分钟有效,并继续复用网页端的库存容量、货品一致性、出库车辆信息、权限和历史流水校验。删除仍有库存的垛位会被拒绝;有历史流水的空垛位停用而不是物理删除。
飞书自然语言识别规则:
- 必须同时识别到仓位、数量和明确的业务意图,才会生成待确认操作。仓位可写成 `001`、`001号` 或 `A-01`,数量需带单位,例如 `11包`、`5件`、`3袋`、`2箱`、`1托`。
- 入库意图包括“入库、进库、到货、收货、卸货、进仓、进货、补货、增加库存、库存增加、加库存”等词;出库意图包括“出库、发货、出货、提货、装车、发运、拉走、减少库存、库存减少、减库存、消耗”等词。
- 带“查询、查看、多少、几包、记录、明细、流水、统计、报表、吗、呢、?”等查询词的消息始终按只读查询处理,即使同时出现“入库/出库”字样也不会写库存。
- 只识别到仓位和数量、但看不出入库还是出库时:未配置大模型会提示补充“入库”或“出库”;已配置大模型时可推断业务类型,但仍只生成待确认摘要,回复“确认”后才会写入。
- 发送“帮助”会返回分栏说明,包含查询、入库/出库、期初、垛位维护、权限和大模型识别范围。
长连接由服务器主动连接飞书,无需公网回调地址;同一 `event_id` 只处理一次。HTTP 回调模式仍会校验 Verification Token、App ID 和可选事件加密。待确认操作和事件去重缓存当前保存在应用进程内,因此生产环境请使用**单进程 Uvicorn** 运行;如改为多进程或多节点,需要把这两类缓存迁移到 Redis 或数据库。长连接依赖 `lark-oapi`,部署时请执行 `pip install -r requirements.txt`;该依赖要求 `websockets<16`。企业微信后续可采用“自建应用消息回调”实现同样的指令能力,群机器人 Webhook 仍只用于通知。
#### 飞书长连接排查
- 管理台显示“正在连接…”:确认 App ID、App Secret 正确,飞书应用已发布,且事件接收方式选择的是“使用长连接接收事件”。
- 管理台显示“缺少依赖”:在服务器执行 `/opt/wms/.venv/bin/python -m pip install -r /opt/wms/requirements.txt`,然后重启 `wms`。
- 管理台显示“配置已变更,需重启”:修改 App ID、App Secret 或连接方式后执行 `sudo systemctl restart wms`,旧连接不会热替换。
- 收不到消息:在飞书开放平台确认已订阅 `im.message.receive_v1`、权限 `im:message` 与 `im:message:send_as_bot` 已生效,并用 `sudo journalctl -u wms -f` 查看连接日志。
- 长连接正常但用户未绑定:机器人会回复该用户的 `open_id`,管理员在“飞书集成 → 用户绑定”中完成绑定。
### 厂区平面图设计与 AI 识别
1. 登录后进入“仓位总览”,点击“设计平面图”。
2. 在“库区 / 垛位”模式中点击库区空白处选中 A、B 等库区:拖动库区内部可整体移动,拖动四边或四角控制点可缩放,区内所有垛位和装卸位按比例同步调整;也可在工具栏输入“库区宽度 / 库区高度”精确调整。
3. 点击任一垛位选中后,可拖动本体移动,拖动八个控制点自由缩放,或在工具栏输入“垛位宽度 / 垛位高度”精确适配背景图。垛位最小尺寸为 20 × 14 px,卡片文字会随尺寸自动调整,避免重叠。
4. 选择“调整装卸位”单独移动垛前小车;选择“道路节点”调整道路走向、宽度或新增通道;选择“大门 / 装车区”新增、改名、删除、拖动或调整多个车辆出入口和固定停靠区。
5. 点击“保存平面图”后,仓管员工作台、其他终端和已生成的只读分享链接同时使用新布局。未保存的调整只在当前编辑器中保留;点击“恢复默认”可恢复系统初始布局。
6. 上传真实平面图时可先选择“上传为底图”,再切到“底图位置”自由拖动和拉伸,调整透明度后手工对齐;长图可点“恢复底图比例”。也可以选择“AI 识别并生成”,让视觉模型自动生成布局草稿。
AI 平面图识别使用 OpenAI 兼容的 Chat Completions 视觉接口。请在 `/admin` 的共享模型中填写可用的视觉模型,或在个人设置中填写自定义视觉模型。未配置视觉模型时,接口返回 `503`,仍可手工设计或直接上传底图。
- 支持 PNG、JPG、WebP,单张图片最大 12 MB。
- 没有可用共享或自定义模型时,AI 识别接口返回 `503`,仍可使用手工设计器或直接上传底图。
- AI 结果只作为草稿,必须人工核对大门、道路、垛位和装卸位后点击保存;识别失败或图中垛位过少时会提示改用手工布局。
- 布局保存在数据库 `warehouse_layouts` 表中,底图文件保存在 `data/layouts/`,不需要为已有数据库重建表。
- 库区矩形保存在布局的 `zones` 字段中;旧布局没有该字段时,系统会按区内垛位自动推导库区范围,不影响已有数据。
## 使用流程
1. 仓管员登录,在“仓位总览”查看厂区平面图;点击任一垛位查看货品、规格、库存和装卸位置,点击“查看全部”打开完整收发存记录。
2. 首次正式使用时,进入“企业与垛位”新建企业,新增实际垛位并设置规格;系统自动生成仓位编码和标准容量。
3. 在“库存作业”中选择新垛位,使用“期初录入”建立真实库存;后续生产入库和发货出库均在此基础上增减。
4. 如需调整实际厂区布局,点击“设计平面图”拖动或缩放库区、垛位、装卸小车、道路和固定装车区,保存后自动同步。
5. 发货时执行发货出库,填写客户、目的地和运输车辆;系统校验库存并生成流水。
6. 在“报表中心”按日或按月查询,导出 Excel。
7. 在“只读分享”生成带有效期的链接和二维码,发给客户或管理人员查看实时厂区平面图、垛位位置和只读收发存记录;二维码可下载后打印或转发。
8. 在垛位详情或“企业与垛位”台账中生成垛位二维码,打印张贴;扫码即可免登录按期间查询该垛位信息。
9. 如需消息提醒,在“个人设置 → 飞书 / 企业微信通知”中填写群机器人 Webhook,选择事件开关并发送测试消息。
10. 如需在飞书中直接查询和办理业务,在 `/admin → 飞书集成` 配置企业自建应用并绑定用户,详见“接入飞书自建应用机器人”。
## 把现有厂区示意图转成平面图
1. 在“企业与垛位”中按图中的垛位区建立垛位。同一个垛位区使用相同的库区代码,例如 `1`、`2` … `7`,库区名称填写“垛位区1”“垛位区2”;区内每个垛使用不同的三位序号。
2. 进入“仓位总览”,点击“设计平面图”,选择现有 PNG / JPG / WebP 示意图,点击“上传为底图”。
3. 调整底图透明度,在“库区 / 垛位”模式中先选中库区,拖动或缩放库区范围以贴合底图上的垛位区;再逐个选中垛位,拖动或缩放至对应位置和大小。
4. 需要交互道路时,在“道路节点”模式中拖节点、调整宽度或添加道路;在“大门 / 装车区”模式中按底图补充大门和固定装卸车位。
5. 保存后,同一库区的垛位会按已保存的库区范围形成可点击的垛位区。点击库区可查看区内全部垛位,点击具体垛位可查看库存和收发存记录。
6. 正式环境如需 AI 自动识别,需配置 `LLM_API_KEY` 和视觉模型;未配置时上传底图加手工对齐即可完成转换。
## 只读分享与权限
- 普通用户可自行注册,注册后默认为“查询用户”,只能查看平面图、垛位、库存和报表;管理员可在 `/admin → 用户管理` 中将其改为“仓管员”或停用账号。
- 只有仓管员可以新增/编辑/删除垛位、录入期初/入库/出库、生成分享链接和导出 Excel。
- 分享链接使用随机令牌,数据库中只保存令牌哈希,可设置有效期并随时停用。
- 创建分享时弹窗会显示完整链接和二维码;两者只在创建时返回一次,可复制链接或下载二维码 PNG 后发送。二维码与链接使用同一令牌,停用分享后同时失效。
- 分享页只开放厂区平面图、仓位位置、仓位编码、货品档案、库存状态和脱敏后的收发存记录,不提供任何写入接口。
- 分享页的收发存记录会隐藏客户、运输车辆和操作人,也不提供布局设计器、库存作业或报表。
- 库存写接口都要求有效的仓管员会话;未登录、查询用户或只读分享令牌无法调用。
## 数据与备份
运行数据位于 `data/wms.db`,加密签名密钥位于 `data/secret.key`。SQLite 已启用 WAL 模式。
- 建议每天备份 `data/wms.db` 和 `data/secret.key`。
- 在线备份时可先停止服务,或使用 SQLite 的 `.backup` 命令,避免直接复制正在写入的数据库。
- 恢复时停止服务,替换两个文件后重新启动。
- 生产环境如需多实例或更高并发,可设置 `WMS_DATABASE_URL` 切换到 PostgreSQL,并使用单个数据库服务。
## 局域网与正式部署
同一局域网内访问时,用 `--host 0.0.0.0` 启动,并在服务器防火墙放行对应端口,例如 Windows 防火墙放行 TCP 8000。其他电脑访问 `http://服务器IP:8000`。
手机与电脑连接同一局域网后,可直接打开 `http://服务器IP:8000`。页面已做响应式适配,手机可查询仓位、查看垛位详情、点击平面图、进行语音录入(需浏览器支持且通常要求 HTTPS)以及查看报表。管理台同样支持手机访问 `/admin`。
打印垛位二维码或分享二维码前,请先从手机可访问的局域网地址或正式域名登录系统再生成;也可以设置 `WMS_PUBLIC_BASE_URL` 固定二维码中的访问地址,避免二维码指向 `127.0.0.1` 导致手机无法打开。子路径部署时系统会自动补全 `WMS_BASE_PATH`,不会生成重复的 `/warehouse` 前缀。
正式环境建议:
- 使用 Nginx / Caddy 配置 HTTPS 反向代理;
- 设置 `WMS_PUBLIC_BASE_URL=https://你的域名`;
- 设置 `WMS_COOKIE_SECURE=true`;
- 修改默认密码和 `WMS_SECRET_KEY`,并定期备份数据;
- 只开放应用端口,不直接暴露数据库文件。
如果与其他系统共用同一个域名或 IP,可把本系统部署在子路径,例如
`https://example.com/warehouse/`。此时设置 `WMS_BASE_PATH=/warehouse`,
并把 `WMS_PUBLIC_BASE_URL` 设为包含该子路径的完整地址;Nginx 反向代理
`proxy_pass` 不要加结尾斜杠,应用会通过 FastAPI `root_path` 自动去掉前缀。
## 测试
```powershell
python -m pytest -q
```
当前测试覆盖登录鉴权、库存权限、容量校验、出入库、厂区布局保存与重置、库区矩形持久化与旧布局自动推导、垛位完整流水、飞书/企业微信通知加密与触发、飞书机器人操作触发 Webhook 通知、飞书回调验签与去重、飞书查询/入库确认/权限/垛位维护、飞书自然语言入库/出库识别、帮助菜单、分享脱敏、分享二维码生成、企业隔离、同序号跨企业、垛位增删改、二维码公开查询、期间筛选、图片上传校验、AI 未配置回退、报表和语音解析等核心流程。
## 目录结构
```text
backend/
main.py API 路由与页面入口
models.py 数据模型
seed.py 仓库、货品、演示流水初始化
services/ 库存、厂区布局、视觉识别、报表、语音解析
static/
index.html 仓管员工作台
admin.html 独立系统管理台
bin.html 垛位二维码免登录查询页
share.html 只读分享页
css/ 响应式样式与管理台样式
js/ 页面逻辑、管理台与语音交互
docs/
使用说明.md 完整角色、管理台、模型、手机与发布说明
deploy/ 腾讯云子路径部署配置与维护说明
portal/ 可配置的系统导航页
tests/ 接口测试
tools/ 本地验收与补丁工具
data/ SQLite 数据、密钥与验收截图
```
## 已知边界
- 用户注册后立即生效,默认只读;当前未提供邮件验证码或邀请制审批,管理员可在管理台停用账号。
- 首次启动的 9 个演示垛位(A/B/C 三个库区、每区 3 个)及默认厂区布局来自 `backend/seed.py`,统一归入“演示企业”;已有演示数据会在服务启动时自动清理为 A/B/C 三区,仅作用于“演示企业”,不影响真实企业;实际业务请新建企业并录入自己的垛位和库存。
- AI 平面图识别依赖源图清晰度和视觉模型能力,生成结果必须人工核对;复杂图纸建议上传底图后手工对齐。
- SQLite 适合单机或小规模团队,高并发多节点部署建议迁移 PostgreSQL。
## 代码仓库
Gitee: