# material-dashboard **Repository Path**: jimonik/material-dashboard ## Basic Information - **Project Name**: material-dashboard - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-06-01 - **Last Updated**: 2026-06-01 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Vertu 物控仪表盘使用说明 本项目用于生成 Vertu 关键物料监控数据，并在本地仪表盘展示。 - 数据输出文件：`data/data.json` - 页面入口：`http://localhost:8080/dashboard.html` - 核心刷新脚本：`src/update-data.js` --- ## 1. 项目目标与原则 - 监控范围只针对 `excel/物料明细.xlsx` 中的物料编码（不是全公司全量物料）。 - BOM 结构以本地 Excel 为准（`excel/mrp.bom.xlsx` / `excel/mrp.bom.with-types.xlsx`）。 - 库存、采购、销售等数量数据来自 VPS（`https://admin.vertu.cn`）。 - 日常建议“仅库存”刷新；全量刷新用于定期更新采购/销售/BOM 结果。 --- ## 2. 目录结构（核心文件） ```text material-dashboard/ ├── package.json ├── README.MD ├── start.sh # 一键启动（macOS / Linux） ├── start.bat # 一键启动（Windows） ├── public/ # 前端静态页 │ ├── dashboard.html │ └── dashboard-app.js ├── data/ │ └── data.json # 刷新输出 ├── excel/ # 配置与源 Excel │ ├── 物料明细.xlsx │ ├── mrp.bom.xlsx │ ├── mrp.bom.with-types.xlsx │ └── ... ├── cache/ # 刷新断点与快照 ├── src/ │ ├── server.js # 本地服务 + 刷新 API │ ├── update-data.js # 全量刷新 │ ├── paths.js # 统一路径配置（代码内引用） │ └── lib/ # 公共逻辑 └── scripts/ # 局部刷新与工具脚本 ``` 路径约定（由 `src/paths.js` 维护，一般无需手改）： | 用途 | 路径 | |------|------| | 前端页面 | `public/` | | 数据输出 | `data/data.json` | | Excel 配置 | `excel/` | | 刷新缓存 | `cache/` | | 服务端入口 | `src/server.js`、`src/update-data.js` | --- ## 3. 环境准备 ### 3.1 依赖安装 ```powershell cd material-dashboard npm install ``` ### 3.2 VPS 登录 ```powershell vertu login --base-url https://admin.vertu.cn ``` --- ## 4. 快速开始（推荐） ### 4.1 一键启动仪表盘（推荐） 默认端口 **8080**。启动前若该端口已被占用，脚本会**强制结束占用进程**后再启动，并自动打开浏览器。 **macOS / Linux：** ```bash cd material-dashboard ./start.sh ``` **Windows：** 双击 `start.bat`，或在 cmd 中执行： ```bat start.bat ``` 等价于 `npm run serve`，但更适合日常双击/一键使用。 ### 4.2 手动启动服务 ```powershell npm run serve ``` 或： ```powershell node src/server.js ``` 浏览器访问： ### 4.3 全量刷新 ```powershell npm run update ``` 或： ```powershell node src/update-data.js ``` 成功标志： ```text [update-data] 已写入 data/data.json（... 条） ``` ### 4.4 日常仅库存刷新（推荐） ```powershell node scripts/repair-inventory.js ``` 或在仪表盘顶部刷新类型选「仅库存」并开始刷新。 --- ## 5. 刷新模式说明 `src/server.js` 支持这些刷新模式： - `full`：全量刷新（`src/update-data.js`） - `materials`：局部刷新-物料明细 - `bom`：局部刷新-BOM - `inventory`：局部刷新-库存 - `purchase`：局部刷新-采购 - `sales`：局部刷新-销售明细 接口： - `POST /api/refresh` - `GET /api/refresh/status` --- ## 6. 库存刷新机制（已优化） 库存来源模型：`inventory.merge.report` ### 6.1 查询编码范围 只查询会参与汇总的编码： - 监控物料编码 - 关联半成品编码 - 按“产品”列过滤后参与汇总的成品编码 不再查询无关成品候选编码，减少请求量。 ### 6.2 分批 + 重试 + 自动拆批 库存查询默认行为： - 每批 30 个编码 - 批间等待（默认 4000ms） - 单批失败自动重试 - 重试仍失败会自动拆成更小子批继续查 ### 6.3 同次任务断点续跑 中断时保存：`cache/inventory-fetch-progress.json` - 12 小时内同编码集可自动续跑 - 也可显式设置 `INVENTORY_RESUME=1` - 成功结束后自动删除进度文件 ### 6.4 库存快照复用（避免重复打 VPS） 完成后保存：`cache/inventory-stock-snapshot.json` - 默认 6 小时内同指纹可复用快照，跳过库存 VPS 查询 - 强制全新重查：`INVENTORY_FORCE_FRESH=1` --- ## 7. 销售刷新机制（已优化） 销售来源模型：`sale.order.line.report` - 改为小批串行拉取（默认每批 8） - 批间等待 + 批内重试 - 避免长编码批量请求过重导致 503 或命令失败 --- ## 8. 常用命令清单 ```powershell # 一键启动（macOS / Linux） ./start.sh # 一键启动（Windows） start.bat # 全量 npm run update # 全量离线（仅本地推导，不查 VPS） npm run update:offline # 启服务 npm run serve # 仅库存 node scripts/repair-inventory.js # 仅采购 node scripts/repair-purchase.js # 仅销售明细 node scripts/repair-salesbreakdown.js # 局部 BOM 修复（含库存相关重算） node scripts/repair-bom.js # 物料表重载 node scripts/repair-materials-excel.js ``` --- ## 9. 常用环境变量 ### 9.1 库存相关 - `INVENTORY_BATCH`：库存批大小（默认 30） - `INVENTORY_DELAY_MS`：批间延迟（默认 4000） - `INVENTORY_BATCH_RETRY`：单批重试次数（默认 8） - `INVENTORY_BATCH_RETRY_MS`：重试基础等待毫秒（默认 15000） - `INVENTORY_MIN_SUB_BATCH`：自动拆批最小子批（默认 5） - `INVENTORY_SUB_DELAY_MS`：子批间延迟（默认 1500） - `INVENTORY_RESUME=1`：显式续跑 - `INVENTORY_FORCE_FRESH=1`：强制全新重查 - `INVENTORY_AUTO_RESUME_HOURS`：自动续跑窗口小时（默认 12） - `INVENTORY_SNAPSHOT_TTL_HOURS`：快照有效小时（默认 6） - `INVENTORY_REUSE_SNAPSHOT=1`：显式复用快照 ### 9.2 销售相关 - `SALE_BATCH`：销售批大小（默认 8） - `SALE_DELAY_MS`：销售批间延迟（默认 2500） - `SALE_BATCH_RETRY`：销售批重试（默认 6） ### 9.3 服务端口 - 默认端口：`8080`（`src/server.js` 读取环境变量 `PORT`） - `start.sh` / `start.bat` 启动前会强制释放 `8080` 端口占用 - 手动改端口示例：`PORT=9000 npm run serve`（一键脚本同样支持 `PORT` 环境变量） --- ## 10. 故障排查 ### 10.1 HTTP 503 / Unexpected token '<' 含义：VPS 返回 HTML 错误页（服务忙/网关异常），不是本地 JSON。 处理建议： 1. 直接重跑（可续跑） 2. 增大延迟、减小批量 3. 错峰（夜间）执行 示例： ```powershell $env:INVENTORY_DELAY_MS='6000' $env:INVENTORY_BATCH_RETRY='10' npm run update ``` ### 10.2 `getaddrinfo ENOTFOUND admin.vertu.cn` 含义：DNS/网络问题，域名无法解析。 先排查： ```powershell nslookup admin.vertu.cn ``` 检查 VPN、网络、DNS 后再续跑。 ### 10.3 `Command failed`（长编码批） 通常是请求过重或命令参数过长。当前脚本已支持自动拆批；如仍出现，可调小批量： ```powershell $env:INVENTORY_BATCH='20' $env:SALE_BATCH='6' npm run update ``` > 若已有库存进度文件，不建议中途改 `INVENTORY_BATCH`，会导致批次指纹变化，可能无法接续原进度。 ### 10.4 端口 8080 被占用（`EADDRINUSE`） 含义：已有进程监听 8080，无法启动服务。 处理建议： 1. **推荐**：直接运行 `./start.sh` 或 `start.bat`（会自动 kill 占用进程后再启动） 2. 手动排查（macOS）： ```bash lsof -iTCP:8080 -sTCP:LISTEN kill -9 ``` 3. 或改用其他端口：`PORT=9000 npm run serve` ### 10.5 登录相关 ```powershell vertu login --base-url https://admin.vertu.cn ``` --- ## 11. 日常运维建议 - 白天优先“仅库存”刷新；全量放夜间。 - BOM 或“产品”列变更后，先做 BOM/物料修复，再做库存或全量。 - 遇到中断，优先续跑，不要轻易 `INVENTORY_FORCE_FRESH=1`（会重查已完成批次）。 - 大规模调整前先备份 `data/data.json` 与 `excel/` 下关键表格。 --- ## 12. 近期变更（2026-06） - **目录规范化**：项目根目录为 `material-dashboard`；前端、数据、Excel、服务端代码分目录存放（见第 2 节）。 - **路径集中管理**：新增 `src/paths.js`，脚本与库统一引用，避免硬编码散落。 - **移除旧批处理**：已删除原先各 `run-repair-*.bat`、`run-view-dashboard.bat` 等 Windows 修复/启动脚本，统一改用 Node 命令或一键脚本。 - **一键启动**：新增根目录 `start.sh`（macOS / Linux）与 `start.bat`（Windows）；固定使用 8080，启动前强制结束端口占用，并自动打开浏览器。 --- ## 13. 版本提示 本文档对应当前代码行为（含目录结构、一键启动、库存续跑、库存快照、销售小批重试）。 若后续改动 `src/update-data.js`、`src/lib/inventory-fetch.js`、`src/server.js`、`src/paths.js`，请同步更新本文件。