---
description: WMS SaaS 项目核心架构约束与文档索引
alwaysApply: true
---
# 项目核心约束

完整规范见 `docs/`（索引 `docs/README.md`）。涉及某领域的改动前，先阅读对应文档。

## 仓库结构（monorepo）
- `backend/`：Laravel 13 + PHP 8.4，唯一的核心业务系统
- `frontend/`：基于 pure-admin-thin（i18n 分支），Vue 3 + TS + Vite + Element Plus
- `py-service/`：Python FastAPI，独立 AI / 数据分析服务
- `docs/`：设计文档；`docs/database/` 存放数据库表结构设计
- 根目录一个 `docker-compose.yml`

## 不可违背的架构红线
1. **多租户**：单库 + `tenant_code`，通过 TenantContext 自动隔离；严禁跨租户读写。→ `docs/03-multi-tenancy.md`
2. **库存**：余额是结果，流水（`wms_stock_log`）是事实；任何库存变化必须同事务写流水，且并发安全。→ `docs/05-inventory.md`
3. **Laravel 是唯一核心业务系统**：Python 只做分析，只通过 `/internal/v1/` API 交互，不直接写核心库。→ `docs/11-py-service.md`
4. **平台解耦**：订单为统一模型，第三方平台走 Connector/Adapter，核心表不写死平台逻辑。→ `docs/04-domain-model.md`
5. **状态机**：状态用 Enum + 集中定义的合法转换，禁止散落的 `if ($status == ...)`。
6. **业务编码优先**：业务关联优先使用 `sku_code`、`outbound_no` 等，自增 ID 仅作内部主键。
7. **MySQL 是事实数据源**，Redis 只做 Cache / Queue / Lock / Rate Limit。
8. **不过度设计**：第一阶段不引入 K8s、Kafka、ES、MongoDB、ClickHouse、微服务。

## 架构问题处理
需求存在架构问题时不要直接照做，先说明：问题 → 原因 → 推荐方案 → 替代方案 → 最终建议。
存在多个影响全局的合理方案时，先说明区别，由用户决定。

整个项目遵循：**简单、清晰、可维护、可扩展、业务优先。**