# WMS SaaS

商业化、多租户的仓储管理系统（Warehouse Management System）。面向电商卖家、海外仓、第三方仓与 3PL，支持多租户、多仓库、多客户、多 SKU，以及入库、出库、库存与电商订单接入。

当前处于 **Phase 1：架构与数据模型设计**。设计文档在 [`docs/`](./docs/README.md)，代码目录（`backend/`、`frontend/`、`py-service/`）尚未创建。开发顺序见 [`docs/16-roadmap.md`](./docs/16-roadmap.md)。

## 架构

```
Vue 3 Admin
    │
    ▼
Laravel REST API          ← 唯一的核心业务系统
    │
    ├── MySQL 8             ← 业务事实数据源
    ├── Redis 7             ← Cache / Queue / Lock / Rate Limit
    └── Queue / Scheduler
            │
            ├── 第三方平台 Adapter（Amazon、Shopify、TikTok Shop 等）
            └── Python FastAPI（AI / 数据分析，只读分析，不写核心库）
```

| 组件 | 职责 |
| --- | --- |
| `frontend/` | Vue 3 Admin：界面、交互、前端权限展示 |
| `backend/` | Laravel：租户、用户、SKU、仓库、库存、入库、出库、订单、物流、权限、审计 |
| `py-service/` | FastAPI：分析、预测、补货建议、异常检测。只通过 `/internal/v1/` 与 Laravel 交互 |

## 技术栈

| 层 | 选型 |
| --- | --- |
| 前端 | Vue 3、TypeScript、Vite、Element Plus、Pinia、Vue Router（基于 [pure-admin-thin i18n](https://github.com/pure-admin/pure-admin-thin/tree/i18n)） |
| 后端 | Laravel 13、PHP 8.4、Sanctum、Queue、Scheduler |
| 数据 | MySQL 8、Redis 7 |
| 分析 | Python 3、FastAPI、Pydantic |
| 运行 | 根目录一个 `docker-compose.yml`（Phase 17 落地；开发环境见 [`docs/13-docker.md`](./docs/13-docker.md)） |

API 前缀：`/api/v1/...`。

## 仓库结构

```
wms-saas/
├── backend/          Laravel 核心业务（待建）
├── frontend/         Vue 3 Admin（待建）
├── py-service/       Python AI / Data Service（待建）
├── docs/             设计文档与表结构
├── docker-compose.yml   统一开发环境（待建，见 docs/13-docker.md）
└── README.md
```

## 不可违背的约束

1. **多租户**：单库 + `tenant_code`，由 TenantContext 自动隔离，禁止跨租户读写。
2. **库存**：余额是结果，流水（`wms_stock_log`）是事实。库存变化必须同事务写流水，且并发安全。
3. **Laravel 是唯一核心业务系统**：Python 不直接写核心库。
4. **平台解耦**：订单是统一模型，第三方平台走 Connector / Adapter，核心表不写死平台逻辑。
5. **状态机**：状态用 Enum，合法转换集中定义。
6. **业务编码优先**：关联使用 `sku_code`、`outbound_no` 等，自增 ID 只作内部主键。
7. **分阶段**：按 Phase 1～17 推进，每个阶段先说明方案、再实施、再验证。

原则：**简单、清晰、可维护、可扩展、业务优先。**

## 文档

完整设计见 [`docs/README.md`](./docs/README.md)。日常开发先读这些：

| 文档 | 内容 |
| --- | --- |
| [00 概述](./docs/00-overview.md) | 项目定位与目标 |
| [02 架构](./docs/02-architecture.md) | 分层与职责边界 |
| [03 多租户](./docs/03-multi-tenancy.md) | `tenant_code` 与 TenantContext |
| [05 库存](./docs/05-inventory.md) | 余额、流水、并发 |
| [09 数据库](./docs/09-database.md) | 表设计规范 |
| [database/](./docs/database/README.md) | 按领域的表结构 |
| [16 路线图](./docs/16-roadmap.md) | Phase 顺序与当前阶段 |

## 本地开发

环境与业务代码尚未初始化。进入对应 Phase 后：

```bash
docker compose up -d
```

敏感配置通过 `.env` 注入，不提交到 Git。