# 零件库存管理系统实现文档

## 📋 项目概述

零件库存管理系统是一个完整的库存管理解决方案，支持零件信息管理、库存出入库、标签打印、二维码扫描、告警管理等核心功能。

## ✅ 已完成功能

### 1. 数据库设计 ✓

#### 核心表结构

**parts_parts** - 零件主表
- 零件基本信息（零件号、名称、描述、规格）
- 工位与仓位信息
- 库存信息（当前库存、最小/最大库存、单位）
- 供应商信息
- 成本信息
- QR Code 和 Barcode

**parts_labels** - 标签表
- 标签代码
- 二维码数据
- 打印历史记录
- 模板和尺寸配置

**parts_inventory_log** - 库存日志表
- 操作类型（入库、出库、调整、转移等）
- 数量变化记录
- 操作人信息
- 扫码信息
- 设备信息

**parts_stock_alerts** - 库存告警表
- 告警类型（低库存、零库存、超库存）
- 严重程度
- 告警状态（待处理、已确认、已解决）
- 处理记录

**parts_import_log** - 导入日志表
- 文件信息
- 导入结果统计
- 错误详情

### 2. 后端 API ✓

#### Parts API (`/parts`)
- `POST /` - 创建零件
- `GET /` - 查询零件列表（分页、搜索、筛选）
- `GET /:id` - 获取零件详情
- `GET /by-number/:partNumber` - 通过零件号查询
- `GET /by-code/:code` - 通过扫码查询
- `PUT /:id` - 更新零件
- `DELETE /:id` - 删除零件（软删除）
- `POST /bulk-import` - 批量导入
- `GET /stats/inventory` - 库存统计
- `GET /meta/categories` - 获取所有分类
- `GET /meta/stations` - 获取所有工位
- `GET /meta/warehouse-locations` - 获取所有仓位

#### Inventory API (`/inventory`)
- `POST /check-in` - 扫码入库
- `POST /check-out` - 扫码出库
- `POST /adjust` - 库存调整（需要 Admin 权限）
- `POST /transfer` - 库存转移
- `GET /logs` - 查询库存日志
- `GET /history/:partId` - 获取零件库存历史
- `GET /stats` - 获取库存统计
- `POST /bulk-operation` - 批量操作

#### Labels API (`/labels`)
- `POST /generate` - 生成标签
- `POST /generate/bulk` - 批量生成标签
- `POST /print` - 打印标签
- `POST /print/bulk` - 批量打印标签
- `GET /:id` - 获取标签详情
- `GET /by-code/:labelCode` - 通过标签代码查询
- `GET /by-part/:partId` - 获取零件的所有标签
- `DELETE /:id` - 作废标签
- `GET /stats/print` - 获取打印统计

#### Alerts API (`/alerts`)
- `GET /` - 查询库存告警
- `GET /:id` - 获取告警详情
- `POST /acknowledge` - 确认告警
- `POST /resolve` - 解决告警
- `POST /bulk-acknowledge` - 批量确认
- `POST /bulk-resolve` - 批量解决
- `GET /stats/summary` - 获取告警统计
- `POST /auto-resolve` - 自动解决已修复的告警

#### Excel API (`/parts/excel`)
- `POST /import` - 导入 Excel
- `GET /export` - 导出 Excel
- `GET /template` - 下载模板
- `POST /validate` - 验证数据
- `GET /import-history` - 获取导入历史
- `GET /import-log/:id` - 获取导入日志详情

### 3. 核心服务实现 ✓

#### PartsService
- 零件 CRUD 操作
- 批量导入
- 库存统计
- 自动生成唯一 QR Code
- 自动库存告警检查

#### InventoryService
- 扫码入库/出库
- 库存调整
- 库存转移
- 日志记录
- 库存历史查询
- 批量操作

#### LabelService
- 标签生成
- 批量生成
- 打印标签（支持 Zebra/Brother 打印机）
- 打印历史
- QR Code 数据生成
- ZPL 格式输出

#### AlertService
- 告警查询
- 告警确认和解决
- 批量操作
- 告警统计
- 自动解决机制

#### ExcelService
- Excel 数据导入
- Excel 数据导出
- 数据验证
- 模板生成
- 导入历史管理

### 4. 国际化支持 ✓

已完成中英文翻译：
- 零件管理模块（parts）
- 库存管理模块（inventory）
- 标签管理模块（labels）
- 告警管理模块（alerts）
- Excel 导入导出模块（excel）
- 扫码模块（scan）

## 🚧 待实现功能

### 5. 前端页面

#### 零件管理页面
1. **零件列表页面** (`/parts/list`)
   - 搜索和筛选
   - 分页表格
   - 快速操作按钮
   - 库存状态标识

2. **零件详情页面** (`/parts/detail/[id]`)
   - 基本信息展示
   - 库存历史图表
   - 标签管理
   - 操作日志

3. **创建/编辑零件** (`/parts/create`, `/parts/edit/[id]`)
   - 表单验证
   - 图片上传
   - 自动生成 QR Code

#### Excel 导入导出
4. **Excel 导入界面** (`/parts/import`)
   - 文件上传
   - 数据预览和验证
   - 错误提示
   - 导入结果展示
   - 导入历史

#### 标签管理
5. **标签打印界面** (`/parts/labels`)
   - 选择零件
   - 批量生成标签
   - 预览标签
   - 打印机配置
   - 打印历史

#### 扫码功能
6. **iPad 扫码界面** (`/parts/scan`)
   - 摄像头扫码
   - 入库/出库切换
   - 大按钮设计（适配 iPad）
   - 快速模式
   - 实时库存显示

#### 库存管理
7. **库存查询与可视化** (`/parts/inventory`)
   - 库存统计卡片
   - 库存历史图表
   - 按工位/仓位查询
   - 库存告警展示
   - 操作日志查询

### 6. 权限配置

需要在权限系统中添加以下权限：

```typescript
const partsPermissions = [
  // Parts
  { resource: 'parts', action: 'read', description: '查看零件' },
  { resource: 'parts', action: 'create', description: '创建零件' },
  { resource: 'parts', action: 'update', description: '更新零件' },
  { resource: 'parts', action: 'delete', description: '删除零件' },
  { resource: 'parts', action: 'import', description: '导入零件' },
  { resource: 'parts', action: 'export', description: '导出零件' },
  
  // Inventory
  { resource: 'inventory', action: 'read', description: '查看库存' },
  { resource: 'inventory', action: 'checkin', description: '入库' },
  { resource: 'inventory', action: 'checkout', description: '出库' },
  { resource: 'inventory', action: 'adjust', description: '调整库存（管理员）' },
  { resource: 'inventory', action: 'transfer', description: '转移库存' },
  { resource: 'inventory', action: 'bulk', description: '批量操作' },
  
  // Labels
  { resource: 'labels', action: 'read', description: '查看标签' },
  { resource: 'labels', action: 'create', description: '生成标签' },
  { resource: 'labels', action: 'print', description: '打印标签' },
  { resource: 'labels', action: 'delete', description: '作废标签' },
  
  // Alerts
  { resource: 'alerts', action: 'read', description: '查看告警' },
  { resource: 'alerts', action: 'acknowledge', description: '确认告警' },
  { resource: 'alerts', action: 'resolve', description: '解决告警' },
];
```

### 7. 角色配置

建议的角色权限：

**Admin（管理员）**
- 所有权限

**Operator（操作员）**
- parts:read
- inventory:read/checkin/checkout/transfer
- labels:read/create/print
- alerts:read/acknowledge

**Viewer（查看者）**
- parts:read
- inventory:read
- labels:read
- alerts:read

## 📦 数据库迁移

运行以下命令创建数据库表：

```bash
cd backend
npm run prisma:generate
npm run prisma:migrate:create
npm run prisma:migrate:deploy
```

## 🔧 开发指南

### 后端开发

1. **添加新的 API 端点**
   - 在对应的 Controller 中添加路由
   - 在 Service 中实现业务逻辑
   - 使用 DTO 进行参数验证
   - 添加权限控制装饰器

2. **数据库操作**
   - 使用 Prisma Client
   - 使用事务保证数据一致性
   - 添加适当的索引优化查询

3. **错误处理**
   - 使用 NestJS 内置异常
   - 提供清晰的错误消息
   - 记录错误日志

### 前端开发

1. **创建新页面**
   - 使用 Next.js App Router
   - 服务器组件优先
   - 使用 React Query 进行数据获取

2. **API 调用**
   - 创建 API 客户端函数
   - 使用类型安全的接口
   - 处理加载和错误状态

3. **国际化**
   - 所有文本使用 i18n keys
   - 在 `en.ts` 和 `zh.ts` 中添加翻译

4. **UI 组件**
   - 使用 Radix UI 组件
   - 使用 Tailwind CSS 样式
   - 遵循飞书设计规范

## 🎯 功能特性

### 智能告警
- 自动检测低库存
- 多级告警（临界、严重、警告）
- 自动解决机制
- 告警统计和分析

### 标签打印
- 支持多种打印机（Zebra、Brother）
- 自定义标签模板
- 批量生成和打印
- 打印历史追踪

### Excel 导入导出
- 数据验证
- 批量导入
- 错误处理
- 导入历史
- 下载模板

### 扫码功能
- QR Code 和 Barcode 支持
- iPad 优化界面
- 实时库存更新
- 设备信息记录

### 库存追踪
- 完整的操作日志
- 库存历史图表
- 按工位/仓位统计
- 多种操作类型支持

## 📊 API 响应格式

所有 API 遵循统一的响应格式：

```typescript
{
  success: true,
  data: { ... },
  message: "操作成功",
  timestamp: "2025-11-17T..."
}
```

## 🔐 安全性

- JWT 认证
- 基于角色的权限控制（RBAC）
- API 权限验证
- 操作审计日志
- 软删除机制

## 🧪 测试

建议的测试场景：

1. **零件管理**
   - 创建、更新、删除零件
   - 搜索和筛选
   - 批量导入

2. **库存操作**
   - 扫码入库/出库
   - 库存不足校验
   - 并发操作

3. **告警系统**
   - 自动告警触发
   - 告警确认和解决
   - 自动解决机制

4. **标签打印**
   - 生成标签
   - 打印格式输出
   - 批量操作

## 📝 后续优化建议

1. **性能优化**
   - 添加 Redis 缓存
   - 优化数据库查询
   - 实现分页优化

2. **功能增强**
   - 添加库存预测
   - 支持多仓库
   - 移动端 APP
   - 实时通知

3. **报表功能**
   - 库存报表
   - 操作报表
   - 告警报表
   - 数据导出

4. **集成功能**
   - ERP 系统集成
   - 采购系统集成
   - 生产系统集成

## 🚀 部署说明

### 环境要求
- Node.js 18+
- PostgreSQL 14+
- Redis（可选，用于缓存）

### 部署步骤

1. 克隆代码
2. 安装依赖
3. 配置数据库连接
4. 运行数据库迁移
5. 启动后端服务
6. 构建前端
7. 配置 Nginx 反向代理

## 📚 相关文档

- [Prisma Schema](./backend/prisma/schema.prisma)
- [API 文档](./backend/src/parts/)
- [国际化配置](./frontend/src/locales/)

## 🆘 常见问题

**Q: 如何添加新的操作类型？**
A: 在 Prisma schema 的 `InventoryOperationType` 枚举中添加新类型，然后运行迁移。

**Q: 如何自定义标签模板？**
A: 在 `LabelService` 中修改 `generatePrintData` 方法，添加新的模板格式。

**Q: 如何配置告警阈值？**
A: 在零件创建/编辑时设置 `minStock` 和 `maxStock`，系统会自动生成告警。

**Q: Excel 导入支持哪些字段？**
A: 查看 `ExcelService.getExcelTemplate()` 方法获取完整的字段列表和示例。

## 👥 开发团队

本系统遵循现有项目的架构和代码规范，保持与其他模块的一致性。

---

**最后更新**: 2025-11-17
**版本**: 1.0.0