docs/00-overview.md

README.md

@@ -0,0 +1,87 @@
+# 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。