wms-saas/README.md

WMS SaaS

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

当前处于 Phase 2：backend/ 已初始化（统一响应、TenantContext、GET /api/v1/health）。业务表与前端尚未开始。开发顺序见 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）
后端	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）

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

仓库结构

wms-saas/
├── backend/          Laravel 核心业务（Phase 2 基础已在）
├── 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。日常开发先读这些：

文档	内容
00 概述	项目定位与目标
02 架构	分层与职责边界
03 多租户	tenant_code 与 TenantContext
05 库存	余额、流水、并发
09 数据库	表设计规范
database/	按领域的表结构
16 路线图	Phase 顺序与当前阶段

本地开发

backend/ 已可运行测试。本机需 PHP 8.4；当前仓库还没有根目录 docker-compose.yml（Phase 17）。

cd backend
php artisan test

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