智能物料编码管理系统

基于 React + Vite + TypeScript + Supabase 的智能物料与文件编码管理系统，支持物料编码规则化管理、智能查重、数据导出及操作记录追溯。

✨ 主要功能

• 📦 物料编码发放：支持 12 种物料类型的自动化编码生成
• 🔍 智能查重：AI 驱动的相似度检测，防止重复编码
• 📊 数据管理：完整的物料记录管理和历史查询
• 🔐 权限管理：基于角色的用户权限控制
• 💾 数据持久化：Supabase 云端数据库存储
• 📈 动态配置：物料对照表从数据库动态加载

🚀 快速开始

前置要求

• Node.js (版本 18.x 或更高)

  • 下载地址：https://nodejs.org/
  • 安装后验证：node --version 和 npm --version

• Supabase 账号（用于数据库）

  • 注册地址：https://supabase.com/
  • 免费版即可使用

• Google Gemini API Key（可选，用于 AI 功能）

  • 获取地址：https://aistudio.google.com/apikey
  • 如果没有 API Key，AI 相似度检测功能将无法使用

安装步骤

1. 安装依赖

   npm install

2. 配置 Supabase 数据库

   a. 创建 Supabase 项目

   • 访问 https://supabase.com/ 并登录
   • 创建新项目，记录项目 URL 和 anon key

   b. 初始化数据库

   • 在 Supabase Dashboard > SQL Editor 中执行 supabase/schema.sql（创建表结构）
   • 执行 supabase/seed.sql（初始化物料对照表数据）

   c. 配置环境变量

   • 在项目根目录创建 .env.local 文件
   • 添加以下内容：

     VITE_SUPABASE_URL=https://你的项目ID.supabase.co
     VITE_SUPABASE_ANON_KEY=你的anon密钥
     GEMINI_API_KEY=你的API密钥（可选）
     

3. 启动开发服务器

   npm run dev

4. 访问应用

   • 浏览器会自动打开，或手动访问：http://localhost:3000
   • 默认登录账号：用户名 admin，密码 123456

📁 项目结构

项目根目录/
├── App.tsx                 # 主应用组件
├── index.tsx              # 入口文件
├── index.html             # HTML 模板
├── main.js                # Electron 主进程文件
├── vite.config.ts         # Vite 配置
├── tsconfig.json          # TypeScript 配置
├── package.json           # 项目依赖配置
├── components/           # 通用组件
│   ├── Button.tsx
│   └── Input.tsx
├── views/                # 页面组件
│   ├── Dashboard.tsx     # 仪表盘
│   ├── MaterialCoding.tsx # 物料编码发放
│   ├── MaterialRules.tsx  # 物料规则管理
│   ├── FileRules.tsx      # 文件规则管理
│   ├── Login.tsx         # 登录页
│   └── ...
├── services/             # 服务层
│   ├── supabase.ts       # Supabase 数据库服务
│   ├── gemini.ts         # Gemini AI 服务
│   └── storage.ts        # 本地存储服务
├── supabase/             # 数据库相关
│   ├── schema.sql        # 数据库表结构
│   ├── seed.sql          # 初始化数据
│   └── seed_from_csv.js  # CSV 数据导入脚本
└── doc/                  # 文档资料
    ├── 物料代码对照表.csv
    └── 部分细节.csv

🗄️ 数据库配置

数据库初始化

1. 执行表结构脚本

   • 在 Supabase Dashboard > SQL Editor 中打开 supabase/schema.sql
   • 复制全部内容并执行
   • 确认创建了以下表：
     • users - 用户表
     • login_logs - 登录日志表
     • code_sets - 代码集表
     • code_items - 代码项表

2. 导入初始化数据

   • 在 Supabase Dashboard > SQL Editor 中打开 supabase/seed.sql
   • 复制全部内容并执行
   • 确认数据已导入（可在 Table Editor 中查看）

数据更新

如果需要更新物料对照表数据：

1. 修改 doc/物料代码对照表.csv 或 doc/部分细节.csv
2. 运行脚本生成新的 SQL：

   node supabase/seed_from_csv.js > supabase/seed.sql

3. 在 Supabase SQL Editor 中执行新的 seed.sql

📝 物料编码规则

系统支持以下物料类型的编码生成：

• 成品类 (1) - 格式：1 + L2 + L3 + 语言 + 版本 + 序号
• 半成品类 (2) - 格式：2 + L2 + L3 + 分类 + 版本 + 序号
• 电子类 (3) - 支持 PCB、电阻、电容等细分类型
• 机械类 (4) - 支持金属、垫圈、螺丝等细分类型
• 塑胶类 (5) - 支持壳体、电池盖、按键等细分类型
• 光学类 (6) - 支持镜片类、光纤类等细分类型
• 包材类 (7) - 支持包装袋、标签等细分类型
• 辅料耗材类 (8) - 格式：8 + 分类 + 序号
• 管材工具类 (9) - 格式：9 + 分类 + 序号
• 工装类 (GZ) - 格式：GZ + 序号

详细编码规则请参考：doc/QI-08-006 物料编码规则管理规定V3.6 (5).pdf

🛠️ 开发命令

• 启动开发服务器：npm run dev
• 构建生产版本：npm run build
• 预览构建结果：npm run preview
• 打包 Electron 桌面应用：npm run dist

❓ 常见问题

1. 端口被占用

如果 3000 端口被占用，可以修改 vite.config.ts 中的端口号：

server: {
  port: 3001, // 改为其他端口
}

2. Supabase 连接失败

• 检查 .env.local 文件中的 VITE_SUPABASE_URL 和 VITE_SUPABASE_ANON_KEY 是否正确
• 确认 Supabase 项目已创建且运行正常
• 检查浏览器控制台是否有错误信息

3. 数据库数据未加载

• 确认已执行 supabase/schema.sql 和 supabase/seed.sql
• 在 Supabase Dashboard > Table Editor 中检查 code_sets 和 code_items 表是否有数据
• 检查浏览器控制台是否有加载警告

4. 依赖安装失败

• 尝试清除缓存：npm cache clean --force
• 删除 node_modules 和 package-lock.json，然后重新 npm install
• 如果使用国内网络，可以配置 npm 镜像：

  npm config set registry https://registry.npmmirror.com

5. Electron 打包失败

• 确保已安装所有依赖
• 检查是否有杀毒软件拦截
• 查看控制台错误信息

🔒 安全建议

1. 环境变量：不要将 .env.local 文件提交到代码仓库
2. 数据库密码：生产环境建议使用更复杂的数据库密码
3. API 密钥：妥善保管 Supabase 和 Gemini API 密钥
4. 数据备份：定期备份 Supabase 数据库
5. 权限控制：根据实际需求调整 Row Level Security (RLS) 策略

📊 技术栈

• 前端框架：React 19
• 构建工具：Vite 6
• 语言：TypeScript
• 数据库：Supabase (PostgreSQL)
• AI 服务：Google Gemini API
• 桌面应用：Electron

📄 许可证

本项目为内部使用项目。

📞 技术支持

如遇到问题，请检查：

1. Node.js 版本是否符合要求
2. 依赖是否正确安装
3. 环境变量是否正确配置
4. Supabase 数据库是否已初始化
5. 浏览器控制台是否有错误信息