# cangkuwms

**Repository Path**: husiwen/cangkuwms

## Basic Information

- **Project Name**: cangkuwms
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-15
- **Last Updated**: 2026-10-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 仓擎 WMS — 多租户 SaaS 仓储管理系统

多租户 SaaS 仓储管理平台，包含完整的入库/出库/盘点流程、RBAC 权限、ECharts 数据看板，以及 AI 辅助功能（异常检测、补货预测、智能助手等）。

## 界面预览

### 登录页

![登录页](./docs/screenshots/01-login.png)

### 工作台

数据看板：库存概览、出入库趋势、分类占比、热销商品。

![工作台](./docs/screenshots/02-dashboard.png)

### 商品管理

支持 SKU、条码、分类、图片上传。

![商品管理](./docs/screenshots/03-products.png)

### 入库 / 出库

完整的入库收货、出库拣货发货流程。

| 入库单 | 出库单 |
|--------|--------|
| ![入库单](./docs/screenshots/04-inbound.png) | ![出库单](./docs/screenshots/05-outbound.png) |

### 库存查询

按仓库、库位查看实时库存。

![库存查询](./docs/screenshots/06-inventory.png)

### AI 助手 & 告警中心

智能对话助手 + 低库存预警、AI 异常检测。

| AI 助手 | 告警中心 |
|---------|----------|
| ![AI 助手](./docs/screenshots/07-ai.png) | ![告警中心](./docs/screenshots/08-alerts.png) |

## 项目结构

```
wms-saas/
├── apps/
│   ├── api/              # Laravel 12 REST API（PHP 8.2+）
│   ├── admin-web/        # Vue 3 + Element Plus 管理后台
│   └── ai-service/       # FastAPI AI 微服务（Python 3.10+）
├── docker-compose.yml    # Docker 一键部署（MySQL + Redis + 三服务）
├── scripts/
│   └── start-local.ps1   # Windows 本地一键启动脚本
└── README.md
```

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 API | Laravel 12、Sanctum 认证、多租户 Global Scope |
| 管理后台 | Vue 3、Vite、Element Plus、Pinia、ECharts |
| AI 服务 | FastAPI、规则引擎 + 可选 OpenAI 兼容 LLM |
| 数据库 | MySQL 8 |
| 缓存/队列 | Redis（推荐） |

## 前置条件

本地开发需要安装：

- **PHP 8.2+** + Composer
- **Node.js 18+** + npm
- **Python 3.10+**
- **MySQL 8**（本地或 Docker）
- **Redis**（本地已启动，端口 6379）

> phpstudy 用户：确保 MySQL 和 Redis 服务已启动。

## 快速启动（本地开发 — 推荐）

### 方式一：一键启动

```powershell
.\scripts\start-local.ps1
```

脚本会自动执行数据库迁移与种子数据填充，并打开 3 个终端窗口分别运行 API、管理后台、AI 服务。

### 方式二：手动启动

```powershell
# 1. 配置并初始化 API
cd apps/api
composer install
copy .env.example .env
php artisan key:generate
# 编辑 .env，配置 MySQL 连接（见下方环境变量说明）
php artisan migrate:fresh --seed
php artisan storage:link
php artisan serve --host=127.0.0.1 --port=8000

# 2. 管理后台
cd apps/admin-web
npm install
npm run dev -- --host 127.0.0.1 --port 5173

# 3. AI 服务
cd apps/ai-service
pip install -r requirements.txt
python -m uvicorn main:app --host 127.0.0.1 --port 8001 --reload
```

### 服务地址

| 服务 | 地址 |
|------|------|
| 管理后台 | http://127.0.0.1:5173 |
| API | http://127.0.0.1:8000 |
| AI 服务 | http://127.0.0.1:8001 |
| MySQL | 127.0.0.1:3306 |
| Redis | 127.0.0.1:6379 |

## Docker 部署（可选）

```bash
docker compose up --build
```

Docker 会自动创建 MySQL 数据库、执行迁移和种子数据。默认 MySQL 账号：

- 数据库：`wms_saas`
- 用户名：`wms`
- 密码：`wms_secret`

## 演示账号

所有账号密码均为 **`password`**，支持邮箱或手机号登录。

| 角色 | 邮箱 | 手机号 | 说明 |
|------|------|--------|------|
| 平台管理员 | admin@platform.com | 13800000001 | 可管理全平台用户、租户、AI 配置 |
| 租户管理员 | admin@demo.com | 13800000002 | Demo 租户（tenant_id=1）全部权限 |
| 仓库员工 | staff@demo.com | 13800000003 | 仅仓储操作权限（入库/出库/盘点/库存） |

### 演示数据

种子数据包含：

- 1 个演示租户「Demo Warehouse Co」
- 1 个仓库、5 个库位
- 5 个商品（中文名称，含 SKU/条码/分类）
- 随机库存数量
- 1 张待收货入库单（IN-DEMO001）
- 3 个订阅套餐（Starter / Professional / Enterprise）

## 功能清单

### 已实现（含管理后台 UI）

| 模块 | 功能 |
|------|------|
| 认证 | 邮箱/手机号登录、注册租户、退出、个人资料与密码修改 |
| 工作台 | ECharts 图表（出入库趋势、分类库存、热销商品、单据状态） |
| 商品管理 | CRUD、图片上传 |
| 仓库/库位 | CRUD |
| 库存 | 查询、汇总、低库存告警、库存调整、流水记录 |
| 入库 | 创建入库单、收货确认、详情查看 |
| 出库 | 创建出库单、拣货、发货、详情查看 |
| 盘点 | 创建盘点单、录入实盘数、完成盘点 |
| 报表 | 库存流水、单据统计 |
| 告警中心 | 低库存预警 + AI 异常检测 |
| AI 助手 | 对话式仓储助手 |
| 用户/角色 | 租户内用户 CRUD、角色 CRUD、权限分配 |
| 平台管理 | 全平台用户管理、租户列表、AI 模型配置 |
| 租户切换 | 平台管理员可切换租户上下文，代管租户业务 |

### 仅 API（暂无管理后台 UI）

| 模块 | 说明 |
|------|------|
| 订阅计费 | 套餐、订阅、用量 API（`/platform/plans` 等） |
| PDA 扫码 | 商品/库位查询、扫码入库/出库（`/scan/*`） |
| AI 高级 | OCR 识别、拣货路径、库位推荐（API 可用，UI 未接入） |

### AI 能力说明

| 功能 | 实现方式 |
|------|----------|
| 异常检测 | 规则阈值（库存异常、周转异常） |
| 补货预测 | 基于安全库存的简单预测 |
| 智能助手 | 内置规则回复；可在平台后台配置 OpenAI 兼容 LLM |
| OCR 入库 | 演示模式（返回模拟数据，非真实图片识别） |
| 库位推荐 | 按商品分类匹配库区（支持中文分类） |

## 环境变量

### API（`apps/api/.env`）

```env
APP_URL=http://127.0.0.1:8000

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=wms_saas
DB_USERNAME=root
DB_PASSWORD=root

REDIS_HOST=127.0.0.1
REDIS_PORT=6379

CACHE_STORE=redis
QUEUE_CONNECTION=redis

AI_SERVICE_URL=http://127.0.0.1:8001
SANCTUM_STATEFUL_DOMAINS=localhost,localhost:5173,127.0.0.1,127.0.0.1:5173
```

### 管理后台（`apps/admin-web/.env.local`）

```env
VITE_API_URL=http://127.0.0.1:8000
```

## API 概览

- **Base URL：** `http://127.0.0.1:8000/api/v1`
- **认证：** `Authorization: Bearer {token}`
- **租户上下文：** `X-Tenant-Id: {tenant_id}`（平台管理员切换租户时使用）

### 主要接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/auth/login` | 登录（`account` 支持邮箱或手机号） |
| POST | `/auth/register` | 注册新租户 |
| GET | `/auth/me` | 当前用户信息 |
| PUT | `/auth/profile` | 更新资料/密码 |
| GET | `/dashboard` | 工作台数据 |
| CRUD | `/products` | 商品管理 |
| POST | `/upload/product-image` | 商品图片上传 |
| CRUD | `/warehouses`, `/locations` | 仓库/库位 |
| GET | `/inventory` | 库存查询 |
| POST | `/inventory/adjust` | 库存调整 |
| GET/POST | `/inbound`, `/inbound/receive` | 入库单 |
| GET/POST | `/outbound`, `/outbound/pick`, `/outbound/{id}/ship` | 出库单 |
| GET/POST | `/stocktakes`, `/stocktakes/count`, `/stocktakes/{id}/complete` | 盘点 |
| GET | `/reports/movements`, `/reports/orders` | 报表 |
| POST | `/ai/assistant` | AI 助手对话 |
| GET | `/ai/anomalies`, `/ai/forecast` | AI 分析 |
| CRUD | `/users`, `/roles` | 租户用户/角色 |
| CRUD | `/platform/users` | 平台用户管理 |
| GET/PUT | `/platform/ai-settings` | AI 模型配置 |
| GET | `/platform/tenants` | 租户列表 |
| POST | `/scan/inbound` | PDA 扫码入库 |

## 管理后台页面

| 路由 | 页面 | 权限 |
|------|------|------|
| `/login` | 登录 | — |
| `/` | 工作台 | 全部 |
| `/products` | 商品管理 | products.view |
| `/warehouses` | 仓库 | products.view |
| `/locations` | 库位 | products.view |
| `/inventory` | 库存查询 | inventory.view |
| `/inbound` | 入库单 | inbound.view |
| `/outbound` | 出库单 | outbound.view |
| `/stocktake` | 盘点 | stocktake.view |
| `/reports` | 报表 | reports.view |
| `/alerts` | 告警中心 | inventory.view |
| `/ai` | AI 助手 | ai.use |
| `/users` | 用户管理 | users.view |
| `/roles` | 角色管理 | roles.view |
| `/settings` | 个人设置 | 全部 |
| `/platform/users` | 平台用户 | 平台管理员 |
| `/platform/tenants` | 租户管理 | 平台管理员 |
| `/platform/ai-settings` | AI 配置 | 平台管理员 |

## 权限与角色

系统内置 17 个权限点，覆盖商品、库存、入库、出库、盘点、报表、AI、用户、角色等模块。

- **Admin 角色：** 租户内全部权限
- **Staff 角色：** 仓储操作权限（入库/出库/盘点/库存），不含商品管理、报表、AI、用户管理

菜单根据用户权限动态显示；写操作 API 有权限中间件保护。

## 数据库初始化

```powershell
cd apps/api

# 首次安装或重置全部数据
php artisan migrate:fresh --seed

# 仅追加种子数据（已有表结构时）
php artisan db:seed --force
```

种子执行顺序：`PermissionSeeder` → `PlanSeeder` → `AiSettingsSeeder` → `DemoSeeder`

## 已知限制

以下为当前版本的已知限制，不影响核心仓储流程使用：

1. **订阅计费** — 数据模型和 API 已就绪，管理后台暂无套餐/订阅管理 UI
2. **PDA 扫码** — 后端 API 完整，暂无移动端/PDA 前端
3. **OCR** — AI 服务返回演示数据，未接入真实 OCR 引擎
4. **套餐限额** — 用户数/仓库数/商品数上限尚未在业务层强制校验
5. **部分读接口** — 商品/库存等 GET 接口未加细粒度读权限（写操作已保护）
6. **Staff 角色** — 菜单隐藏商品/报表/AI，但直接调 API 可读（待加强）

## 开发说明

```powershell
# 前端生产构建
cd apps/admin-web && npm run build

# 查看 API 路由
cd apps/api && php artisan route:list

# 清除缓存
cd apps/api && php artisan cache:clear && php artisan config:clear
```

## 许可协议

本项目采用**自定义许可协议**（非 MIT），详见 [LICENSE](./LICENSE)。

| 用途 | 是否允许 |
|------|----------|
| 个人学习、研究、非商业开发 | ✅ 免费 |
| 本地 / 私有环境部署测试 | ✅ 免费 |
| 商业使用（SaaS 收费、对外提供服务、集成到商业产品等） | ❌ 须事先获得**书面授权** |

如需商业授权，请通过下方联系方式申请。

## 联系方式

- **邮箱：** [907262317@qq.com](mailto:907262317@qq.com)
- **微信：** `vipzhang123aa`

如有问题反馈、功能建议或商业合作，欢迎邮件或微信联系。