# sample-wms

**Repository Path**: oamains/sample-wms

## Basic Information

- **Project Name**: sample-wms
- **Description**: 简易的仓储管理 （sample-wms）
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-13
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 出入库管理 微信小程序

基于[微信小程序框架](https://developers.weixin.qq.com/miniprogram/dev/framework/)与[云开发](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/basis/getting-started.html)构建的简易仓库管理系统，支持产品出入库、条码扫描、库存查询与记录追溯，数据存储于云数据库，支持多人协作。

## 功能说明

| 模块 | 说明 |
|------|------|
| 授权登录 | 员工微信授权登录；管理员支持账号密码登录 |
| 产品列表 | 主界面，从云数据库加载产品及库存 |
| 入库 | 扫描/手动输入条码，云函数写入库存与记录 |
| 出库 | 扫描条码出库，云函数校验库存并扣减 |
| 出入库记录 | 普通用户仅显示自己的操作记录；管理员可查看全部 |
| 数据导出 | 管理员可将出入库记录、产品库存导出为 Excel（CSV 格式） |
| 数据导入 | 管理员可从 Excel/CSV 批量导入或更新产品库存 |

### 产品基本信息

- 产品名称、产品条码、数量、备注

## 架构

```
小程序端                    云开发
─────────                  ────────
pages/*  ──callFunction──►  login    授权校验（authorized_users）
         ──callFunction──►  wms      出入库业务（products + records）
```

未配置 `envId` 时自动降级为本地存储模式（仅开发调试用）。

## 云开发部署（必做）

### 第一步：开通云开发

1. 微信开发者工具 → 顶部「云开发」→ 开通并创建环境
2. 复制环境 ID，填入 `config/cloud.js`：

```js
module.exports = {
  enabled: true,
  envId: '你的云环境ID'   // 例如 cloud1-xxx
}
```

### 第二步：创建数据库集合

在云开发控制台 → 数据库，创建 3 个集合，权限均设为 **仅管理端可读写**：

| 集合名 | 用途 |
|--------|------|
| `authorized_users` | 授权用户白名单 |
| `products` | 产品库存 |
| `records` | 出入库记录 |

字段说明见 [database/README.md](database/README.md)。

### 第三步：部署云函数

在开发者工具中，右键以下目录 → **上传并部署：云端安装依赖**：

- `cloudfunctions/login` — 授权校验
- `cloudfunctions/wms` — 出入库业务

### 第四步：添加授权用户

在 `authorized_users` 集合手动添加员工记录，或让员工首次微信登录后将其 openid 加入白名单。详见 [database/README.md](database/README.md)。

### 第五步：编译运行

## 授权流程

**员工**：登录页 → 微信授权登录 → 校验白名单 → 进入系统

**管理员**：登录页 → 点击「管理员登录」→ 输入账号密码 → 进入系统（可查看全部记录、导入导出）

```
微信授权登录 → 云函数校验授权用户 → 产品列表
                  ↓ 否
            显示 openid，联系管理员添加
```

### 管理员账号

**本地开发**（`config/admin.js`）：

| 账号 | 密码 |
|------|------|
| admin | admin123 |

**云开发**：在 `authorized_users` 集合添加管理员记录，需包含 `username`、`password`、`role: admin`：

```json
{
  "_id": "2b52cea36a2cf2db002613813c14a423",
  "username": "admin",
  "nickname": "管理员",
  "mobile": "",
  "wx_openid": "",
  "password": "0192023a7bbd73250516f069df18b500",
  "role": "admin",
  "enabled": true,
  "createdAt": 1718000000000
},
{
  "username": "wms",
  "nickname": "超级管理员",
  "mobile": "",
  "wx_openid": "",
  "password": "0192023a7bbd73250516f069df18b500",
  "enabled": true,
  "role": "super",
  "createdAt": 1718000000000,
  "updatedAt": 1718000000000
}
```

添加更多员工：在 `authorized_users` 集合新增记录，填入其 `openid` 和 `nickName`。

微信授权管理员：也可将 `role` 设为 `admin`，管理员用微信登录同样拥有管理权限。

管理员账号密码登录后，可在产品页底部 **修改密码**，新密码保存至云数据库 `authorized_users` 记录，修改成功后需重新登录。

### 产品导入格式

管理员在产品页点击「导入 Excel」，选择 `.xlsx`、`.xls` 或 `.csv` 文件。表头需包含：

| 产品名称 | 条码 | 库存数量 | 备注 |
|---------|------|---------|------|
| 示例产品 | 690001 | 100 | 可选 |

- 条码已存在：更新名称、库存数量、备注
- 条码不存在：新增产品
- 可先「导出 Excel」获取模板，修改后重新导入

## 项目结构

```
sample-wms/
├── app.js / app.json / app.wxss
├── config/
│   ├── cloud.js            # 云环境配置
│   ├── admin.js            # 本地管理员账号
│   └── whitelist.js        # 本地降级白名单
├── cloudfunctions/
│   ├── login/              # 授权校验
│   └── wms/                # 出入库业务
├── database/
│   └── README.md           # 数据库集合说明
├── pages/
│   ├── login/              # 授权登录
│   ├── products/           # 产品列表（主界面）
│   ├── inbound/            # 入库
│   ├── outbound/           # 出库
│   ├── records/            # 出入库记录
│   └── product-detail/     # 产品详情
└── utils/
    ├── auth.js             # 登录态管理
    ├── cloudApi.js         # 云函数调用封装
    ├── wmsService.js       # 统一数据层（云/本地自动切换）
    ├── export.js           # CSV 导出（Excel 可打开）
    ├── importUtil.js       # Excel/CSV 导入
    ├── storage.js          # 本地存储（降级用）
    └── util.js             # 工具函数
```

## 本地降级模式

若未配置 `envId`，系统自动使用本地存储 + 昵称白名单：

```js
// config/whitelist.js
authorizedNickNames: ['你的微信昵称'],
adminNickNames: ['管理员昵称']   // 本地管理员，需同时在 authorizedNickNames 中
```

## 业务规则

- **入库**：条码不存在则新建产品；已存在则累加库存，写入 `records`
- **出库**：库存 ≤ 0 禁止出库；出库量不能超过库存
- **记录**：每次操作记录操作人、结存数量；普通用户仅看自己的记录
- **管理员**：`role: admin` 可查看全部记录，导出/导入产品库存为 Excel

## 技术参考

- [小程序框架](https://developers.weixin.qq.com/miniprogram/dev/framework/)
- [云开发文档](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/basis/getting-started.html)
- [云数据库](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/guide/database.html)
- [云函数](https://developers.weixin.qq.com/miniprogram/dev/wxcloud/guide/functions.html)