# material-bank

**Repository Path**: iron-mam/material-bank

## Basic Information

- **Project Name**: material-bank
- **Description**: 工程概论课程项目：材智通智慧材料库数字化管理系统，基于 Spring Boot、React、MySQL 与 Docker 实现材料管理、入库、领用、库存预警和出入库记录等功能。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-05-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 材智通：智慧材料库数字化管理系统

面向工程概论课程交付的材料库数字化管理系统，覆盖“材料类别-入库-领用-归还-报废-预警-导出-采购预测”的全生命周期管理。

## 当前功能

- 类目管理：四级类目、父子级、默认单位、安全库存、树形展示、增删改查。
- 材料管理：材料编码、名称、类目、品牌、型号、规格、单位、单价、供应商、库存、安全库存、标签/二维码内容展示。
- 入库管理：入库校验、批次号、二维码内容、供应商、库存增加、IN 事务、操作前后库存。
- 领用管理：按材料、批次号或二维码内容领用，保存用途和项目号，库存不足拦截，OUT 事务。
- 归还/报废：支持部分归还关联原领用记录，报废支持原因和附件 URL，生成 RETURN/SCRAP 事务。
- 库存预警：安全库存预警记录、待处理/已处理/已恢复状态、采购员处理入口、通知配置预留。
- 供应商模块：供应商维护、报价记录、报价附件 URL、同材料报价对比。
- 报表导出：出入库记录、学期耗材汇总表、经费对应表、个人领用明细，支持 Excel/CSV/PDF。
- 仪表盘：材料总数、预警、本月入出库/报废、库存金额、TOP10、个人排行、资金占比。
- 移动端/PWA：manifest、service worker、移动端页面适配，扫码不可用时支持手动输入批次号/二维码内容。
- AI采购预测：不需要外部 AI Key，使用后端本地“移动平均 + 教学计划修正”算法，结果来自数据库。
- 权限：游客、学生、实验员、教师、采购员、管理员的菜单级权限，用户管理支持角色和启停字段。

## 技术栈

- 前端：React、Vite、Ant Design、Axios。
- 后端：Spring Boot 3、Spring Data JPA、Bean Validation、Apache POI、Apache PDFBox。
- 数据库：MySQL 8、utf8mb4。
- 部署：Docker Compose。

## 启动方式

```powershell
cd material-bank
copy .env.example .env
docker compose up -d --build
```

访问地址：

- 前端：`http://localhost:5173`
- 后端：`http://localhost:8080`
- MySQL：默认 `localhost:3307`

如果旧 Docker volume 中已有旧表结构，建议重置演示库：

```powershell
docker compose down -v
docker compose up -d --build
```

## 默认账号

本课程版采用模拟登录，登录页选择用户名和角色即可：

- `visitor01` / 游客
- `student01` / 学生
- `lab01` / 实验员
- `teacher01` / 教师
- `purchaser01` / 采购员
- `admin` / 管理员

## 演示流程

1. 管理员登录，查看类目树。
2. 新增材料并选择四级类目和供应商。
3. 实验员入库，查看批次号和二维码内容。
4. 学生按批次号/二维码内容领用，填写用途和项目号。
5. 实验员执行部分归还和报废。
6. 采购员处理库存预警。
7. 教师查看仪表盘和报表导出。
8. 采购员维护供应商报价并对比。
9. 新增教学计划，生成 AI 采购预测并导出 Excel。

## PDF 导出字体

PDF 导出使用后端 `backend/src/main/resources/fonts/` 中的中文字体并嵌入 PDF，当前包含 `NotoSansSC-VF.ttf`。如果替换字体，请放置 `NotoSansSC-Regular.otf`、`NotoSansSC-Regular.ttf`、`SourceHanSansSC-Regular.otf` 或 `SourceHanSansSC-Regular.ttf` 到该目录。

出入库记录页面顶部支持按当前筛选条件导出 Excel、CSV、PDF；页面下方“报表导出”区支持学期汇总、经费对应、个人明细的 Excel/PDF 导出。

## AI 预测说明

当前版本默认：

```yaml
ai.enabled: false
ai.provider: none
ai.api-key:
ai.model:
```

系统不调用 OpenAI、DeepSeek、通义千问等外部接口。预测公式：

`suggested_purchase_qty = ceil(max(avg_monthly_usage * predict_months * intensity_factor * student_factor + safe_stock - current_stock, 0))`

后续可在 `PredictionService` 基础上扩展 `PredictStrategy`，接入机器学习或大模型 API。

教学计划日期统一为 `YYYY-MM-DD`，例如 `2026-02-28`。前端日期选择器也兼容输入 `2026-2-28`，提交时会自动格式化。

## 常见问题

- Maven/Docker 构建下载依赖失败：通常是 Maven Central 或 Docker Hub 网络中断，重试 `docker compose build backend`。
- 中文乱码：确认终端和 MySQL 使用 UTF-8/utf8mb4，浏览器页面正常显示中文。
- PDF 中文显示：确认 `backend/src/main/resources/fonts/` 下存在支持中文的 Noto Sans SC 或 Source Han Sans SC 字体。