docs/00-overview.md

2026-09-29 13:08:21 +08:00
parent c30f7e2e7b
commit cb9b7a4bd4
20 changed files with 1383 additions and 0 deletions
@@ -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。
@@ -0,0 +1,47 @@
 # 00 项目概述
 ## 项目定位
 从零开发一个**商业化、多租户 SaaS WMS（Warehouse Management System）**。
 它不是简单的 CRUD 后台，而是一个未来可以长期商业化的正式 SaaS 产品，需要支持：
 - 多个租户
 - 多个仓库
 - 3PL / 海外仓
 - 电商订单接入
 ## 角色要求
 开发者（含 AI Agent）应以以下身份工作：
 - 资深 SaaS / WMS 系统架构师
 - Laravel 后端工程师
 - Vue 3 前端工程师
 - 具备仓储物流、ERP、3PL、跨境电商仓储业务经验
 ## 最终目标
 最终系统应成为一个真正商业化的 **SaaS WMS**，支持：
 多租户 + 多仓库 + 多客户 + 多 SKU + 入库 + 出库 + 库存 + 波次 + 拣货 + 打包 + 物流 + 3PL + 电商订单 + 开放 API + AI 数据分析
 架构要能够支持未来的业务形态与对接对象：
 - 普通电商卖家
 - 海外仓
 - 第三方仓
 - 3PL
 - 跨境电商
 - ERP 对接
 - Amazon
 - Shopify
 - TikTok Shop
 - Temu
 - Mirakl
 **但第一阶段不要为了这些未来需求提前实现所有功能。**
 ## 一句话架构
 Laravel 负责应用层，Domain 负责 WMS 核心业务规则，Eloquent 负责数据持久化，Queue 负责异步任务，Adapter 负责第三方平台，TenantContext 负责多租户隔离。
@@ -0,0 +1,63 @@
 # 01 技术栈
 ## 前端
 - Vue 3
 - TypeScript
 - Vite
 - Element Plus
 - Pinia
 - Vue Router
 - VueUse
 - ECharts
 - Axios
 - ESLint
 - Prettier
 前端 Admin 采用 [pure-admin-thin（i18n 分支）](https://github.com/pure-admin/pure-admin-thin/tree/i18n)。详见 [10-frontend.md](./10-frontend.md)。
 ## 后端
 - Laravel 13
 - PHP 8.4
 使用：
 - Laravel Sanctum
 - Laravel Queue
 - Laravel Scheduler
 - Redis
 - Laravel HTTP Client
 - Laravel Cache
 - Laravel Events / Listeners
 - Laravel Notifications（需要时使用）
 - Laravel Policies / Gates
 - Laravel API Resources
 - Laravel Form Requests
 - Laravel Service / Action 类
 - Laravel Console Commands
 API 采用 RESTful API，统一前缀 `/api/v1/...`。
 ## 数据库
 - MySQL 8
 - Redis 7
 ## Python 服务
 Python 作为独立服务存在，不参与 Laravel 核心业务 CRUD。
 - Python 3.x
 - FastAPI
 - Pydantic
 - HTTP API
 - Redis
 - 后期根据需要使用 Pandas / NumPy / Scikit-learn / PyTorch / LLM SDK
 详见 [11-py-service.md](./11-py-service.md)。
 ## 依赖原则
 - 不随意增加第三方依赖。
 - 第一阶段不引入 Kubernetes、Kafka、Elasticsearch、MongoDB、ClickHouse 等（见 [02-architecture.md](./02-architecture.md)）。
@@ -0,0 +1,81 @@
 # 02 总体架构
 ## 架构分层
 ```
 Vue 3
  ↓
 Laravel REST API
  ↓
 MySQL / Redis
  ↓
 Laravel Queue / Scheduler
 ```
 Python FastAPI 作为独立 AI / Data Service。
 ## 总体结构
 ```
                Vue 3
                  │
                  ▼
          Laravel API
                  │
   ┌──────────────┼──────────────┐
   │              │              │
   ▼              ▼              ▼
 MySQL          Redis          Queue
                                  │
                                  ▼
                               Workers
                                  │
                     ┌────────────┴────────────┐
                     │                         │
                     ▼                         ▼
              Third-party APIs           Python Service
                                                │
                                       ┌────────┼────────┐
                                       ▼        ▼        ▼
                                      AI      Analysis  Forecast
 ```
 ## 三者职责边界
 | 组件 | 职责 |
 | --- | --- |
 | Vue 3 | Admin 界面、交互、前端权限展示 |
 | Laravel | **唯一的核心业务系统**：租户、用户、SKU、仓库、库存、入库、出库、订单、物流、权限、审计 |
 | Python | 独立 AI / 数据分析服务：分析、预测、补货建议、异常检测、AI 助手 |
 - 核心业务逻辑不得迁移到 Python。
 - Python 不得直接修改 Laravel 核心业务数据库。
 ## Redis
 Redis 用于：
 - Cache
 - Queue
 - Rate Limit
 - Lock
 - 临时数据
 **不要把 Redis 当作核心业务数据库。MySQL 永远是业务事实数据源。**
 ## 不要过度设计
 第一阶段不要引入：
 - Kubernetes
 - Kafka
 - Elasticsearch
 - MongoDB
 - ClickHouse
 - 微服务
 - 独立认证中心
 - Service Mesh
 先使用：**Laravel + MySQL + Redis + Queue**。
 架构保持模块化，未来确实需要时再拆服务。
@@ -0,0 +1,54 @@
 # 03 SaaS 多租户
 ## SaaS First
 系统必须从第一天支持多租户。
 - 采用：**单数据库 + tenant_code**
 - 第一阶段不采用：一个租户一个数据库
 ## 需要租户隔离的表
 所有核心业务表原则上都需要 `tenant_code`，例如：
 - warehouse
 - warehouse_location
 - customer
 - product
 - sku
 - inventory
 - inbound
 - outbound
 - shipment
 - stock_log
 ## tenant_code 是核心数据隔离维度
 不要依赖开发人员到处手工编写：
 ```php
 Model::where('tenant_code', $tenantCode)
 ```
 应建立统一的租户上下文 **TenantContext**（或类似机制）。
 目标：
 1. 当前登录用户确定当前 `tenant_code`。
 2. 业务 Service / Repository / Query 默认自动限制当前租户。
 3. 创建数据时自动写入当前 `tenant_code`。
 **严禁出现：租户 A 可以查询到租户 B 数据。**
 ## 需要特别注意的场景
 TenantContext 不只存在于 HTTP 请求中，以下场景同样必须正确设置租户上下文：
 - Queue Job（在任务载荷中携带 `tenant_code`，执行时恢复上下文）
 - Scheduler / Console Command（按租户遍历执行）
 - 第三方 Webhook（根据店铺 / 应用凭证解析租户）
 - 缓存 Key、锁 Key（必须带 `tenant_code` 前缀）
 ## 测试
 Tenant Isolation 是核心测试项之一，见 [14-testing.md](./14-testing.md)。
@@ -0,0 +1,110 @@
 # 04 WMS 领域模型
 ## 业务编码优先
 业务系统尽量使用明确的业务编码：
 | 编码 | 含义 |
 | --- | --- |
 | tenant_code | 租户 |
 | warehouse_code | 仓库 |
 | location_code | 库位 |
 | customer_code | 客户 |
 | supplier_code | 供应商 |
 | product_code | 商品 |
 | sku_code | SKU |
 | order_no | 订单 |
 | inbound_no | 入库单 |
 | outbound_no | 出库单 |
 | picking_no | 拣货单 |
 | shipment_no | 发货单 |
 | package_no | 包裹 |
 不要让业务逻辑全部依赖数据库自增 ID。数据库 ID 可以作为内部主键，但业务关联应优先考虑业务编码。
 ## 业务模块（第一阶段设计）
 ### 1. SaaS
 租户、用户、角色、权限、租户设置、操作日志
 ### 2. 基础资料
 客户、供应商、商品、SKU、SKU 条码、包装规格、重量、尺寸
 ### 3. 仓库
 仓库、库区、库位、库位类型、库位容量、库位策略
 ### 4. 入库
 入库单、入库明细、收货、收货差异、质检、上架、入库流水
 ### 5. 出库
 出库单、出库明细、库存分配、波次、拣货任务、复核、打包、发货
 ### 6. 库存
 库存查询、库存余额、库存流水、库存锁定、库存调整、库存盘点、库存冻结、库存解冻、库存预警
 ### 7. 退货
 退货单、退货收货、退货质检、重新入库、报废
 ### 8. 物流
 物流渠道、承运商、物流服务、运费规则、面单、发货、Tracking
 ### 9. 报表
 库存报表、入库报表、出库报表、库存周转、SKU 销量、仓库作业统计
 ### 10. AI / 数据分析（预留 Python 服务接口）
 库存分析、SKU 销量分析、缺货预测、补货建议、库存周转分析、异常库存、AI WMS Assistant
 ## 订单模型
 WMS 不应和某一个电商平台强绑定，订单应抽象为统一订单模型，例如：
 - order
 - order_item
 - order_source
 - order_status
 - order_external_no
 - order_channel
 以后可以支持：Amazon、Shopify、TikTok Shop、Temu、Shopee、Mirakl、ERP、API、手工订单。
 **不要在核心订单表中写死 Amazon / TikTok 等平台业务逻辑。**
 ## 第三方平台架构
 第三方平台必须采用 **Adapter / Connector** 思路：
 ```
 MarketplaceConnector (接口)
 ├── AmazonConnector
 ├── ShopifyConnector
 ├── MiraklConnector
 └── TikTokShopConnector
 ```
 以后增加平台时，不应该修改大量核心 WMS 代码。核心 WMS 只关心：
 - 统一订单
 - 统一 SKU
 - 统一库存
 - 统一物流
 - 统一状态
 平台实现放在 `app/Infrastructure/Platforms/{Platform}/`，负责平台数据与统一模型之间的映射。
 ## 状态机
 入库、出库、订单、库存任务不要到处使用：
 ```php
 if ($status == xxx)
 ```
 应设计明确的状态流转。例如出库：
 ```
 draft → allocated → picking → picked → packing → packed → shipped → completed
 ```
 - 状态使用 PHP Enum 定义，禁止魔法字符串。
 - 允许的状态转换集中定义，**非法状态转换必须被阻止**。
 - 状态变更需记录日志（谁、何时、从何状态到何状态）。
@@ -0,0 +1,101 @@
 # 05 库存设计
 **库存设计是整个 WMS 的核心。**
 ## 库存模型
 不要简单设计 `sku + warehouse + quantity`，必须建立完整库存模型。
 ### 数量维度
 | 字段 | 含义 |
 | --- | --- |
 | available_qty | 可用数量 |
 | reserved_qty | 预占 / 锁定数量 |
 | picked_qty | 已拣货数量 |
 | hold_qty | 冻结数量 |
 | damaged_qty | 残损数量 |
 | in_transit_qty | 在途数量 |
 ### 位置与属性维度
 - 仓库
 - 库区
 - 库位
 - SKU
 - 批次
 - 库存状态
 ### 核心关系
 ```
 SKU
 ↓
 Warehouse
 ↓
 Zone
 ↓
 Location
 ↓
 Batch
 ↓
 Inventory
 ```
 ## 库存流水必须是核心数据
 必须设计 `wms_stock_log`，任何库存变化必须能够追溯。例如：
 ```
 入库 +100
 锁定 -20
 拣货 -5
 出库 -5
 盘点 +2
 调整 -1
 ```
 需要能够回答：**为什么这个 SKU 的库存从昨天的 100 变成今天的 76？**
 - 库存余额是结果。
 - 库存流水是事实。
 不要只修改 `inventory.quantity` 而不留下完整流水。库存余额更新与流水写入必须在同一事务中完成，流水需记录业务单据类型与单号（如 inbound_no / outbound_no）。
 ## 库存并发安全
 库存扣减必须考虑并发。
 **禁止：** 先 SELECT → PHP 计算 → UPDATE。这种方式容易产生超卖。
 根据实际业务采用：
 - 数据库事务
 - 行锁（`SELECT ... FOR UPDATE`）
 - 乐观锁（version 字段）
 - 原子更新
 - Redis 分布式锁（必要时）
 原子更新示例：
 ```sql
 UPDATE wms_inventory
 SET available_qty = available_qty - :qty,
    reserved_qty  = reserved_qty + :qty
 WHERE tenant_code = :tenant_code
  AND id = :id
  AND available_qty >= :qty;
 -- 受影响行数为 0 即库存不足，必须抛出业务异常
 ```
 必须保证：
 - `available_qty >= 扣减数量`
 - 多个并发请求不能导致负库存或重复扣减
 ## 并发验收用例
 两个请求同时扣减 8 个库存，而实际只有 10 个库存。必须保证：
 - 不会出现 `available_qty = -6`
 - 不能出现两个订单都成功扣减 8
@@ -0,0 +1,109 @@
 # 06 Laravel 后端结构
 ## 分层
 不要把所有业务代码写进 Controller。推荐：
 ```
 Controller
 ↓
 FormRequest
 ↓
 Service / Action
 ↓
 Domain Logic
 ↓
 Model / Repository
 ↓
 Database
 ```
 Controller 只负责：
 - 接收请求
 - 参数验证（通过 FormRequest）
 - 调用业务服务
 - 返回 API Resource
 复杂业务必须进入 Service / Action。
 ## Action 命名示例
 - CreateInboundAction
 - ReceiveInboundAction
 - PutawayInboundAction
 - AllocateOutboundAction
 - CreateWaveAction
 - PickOrderAction
 - PackOrderAction
 - ShipOrderAction
 - AdjustInventoryAction
 - StocktakeAction
 ## 目录结构
 ```
 app/
 ├── Domain/                 # WMS 核心业务规则（状态机、领域规则、值对象、枚举）
 │   ├── Inventory/
 │   ├── Order/
 │   ├── Inbound/
 │   ├── Outbound/
 │   ├── Warehouse/
 │   ├── Picking/
 │   ├── Packing/
 │   ├── Shipment/
 │   ├── Return/
 │   └── Logistics/
 │
 ├── Application/            # 应用层用例
 │   ├── Inventory/
 │   │   ├── Actions/
 │   │   ├── Services/
 │   │   └── DTOs/
 │   ├── Order/
 │   ├── Inbound/
 │   └── Outbound/
 │
 ├── Http/
 │   ├── Controllers/
 │   ├── Requests/
 │   └── Resources/
 │
 ├── Models/                 # Eloquent 模型（数据持久化）
 │
 ├── Jobs/
 ├── Events/
 ├── Listeners/
 ├── Policies/
 ├── Console/
 ├── Support/                # 通用支持：TenantContext、ApiResponse 等
 │
 └── Infrastructure/         # 外部适配
    ├── Cache/
    ├── Queue/
    ├── Logistics/
    └── Platforms/
        ├── Amazon/
        ├── TikTokShop/
        ├── Temu/
        ├── Shopee/
        └── Mirakl/
 ```
 ## 职责划分
 | 层 | 职责 |
 | --- | --- |
 | Laravel（Http / Application） | 应用层：请求、用例编排、事务边界 |
 | Domain | WMS 核心业务规则 |
 | Eloquent（Models） | 数据持久化 |
 | Queue（Jobs） | 异步任务 |
 | Adapter（Infrastructure） | 第三方平台、物流商 |
 | TenantContext | 多租户隔离 |
 ## 依赖方向
 - Http → Application → Domain；Infrastructure 实现 Domain / Application 定义的接口。
 - Domain 不依赖 Http、不依赖具体第三方平台。
 - 模块之间避免强耦合，跨模块协作优先通过 Application Service 或 Events。
@@ -0,0 +1,58 @@
 # 07 API 规范
 ## 路由
 RESTful，统一前缀 `/api/v1/`。
 ```
 GET  /api/v1/warehouses
 GET  /api/v1/skus
 GET  /api/v1/inventory
 POST /api/v1/inbounds
 POST /api/v1/inbounds/{inbound_no}/receive
 POST /api/v1/inbounds/{inbound_no}/putaway
 GET  /api/v1/outbounds
 POST /api/v1/outbounds/{outbound_no}/allocate
 POST /api/v1/outbounds/{outbound_no}/pick
 POST /api/v1/outbounds/{outbound_no}/pack
 POST /api/v1/outbounds/{outbound_no}/ship
 ```
 要点：
 - 资源名使用复数。
 - 路由参数优先使用业务编码（`inbound_no`、`outbound_no`），而非自增 ID。
 - 业务动作（状态流转）使用 `POST /{resource}/{code}/{action}`。
 - 认证使用 Laravel Sanctum，授权使用 Policies / Gates。
 ## 统一返回格式
 不要每个 Controller 自己定义一套返回结构。
 成功：
 ```json
 {
    "success": true,
    "message": "OK",
    "data": {}
 }
 ```
 失败：
 ```json
 {
    "success": false,
    "message": "操作失败",
    "errors": {}
 }
 ```
 分页数据使用统一格式（具体字段在 Phase 2 确定并固化到统一响应工具类中），所有列表接口保持一致。
 ## 内部 API（Python Service）
 Laravel 调用 Python 的内部接口统一使用 `/internal/v1/` 前缀，见 [11-py-service.md](./11-py-service.md)。
@@ -0,0 +1,46 @@
 # 08 Queue / Scheduler
 ## Queue
 以下任务原则上应进入 Queue：
 - 第三方订单同步
 - 库存同步
 - 物流同步
 - 批量导入
 - 批量导出
 - 面单生成
 - Tracking 同步
 - 大量库存计算
 - 报表生成
 - AI 分析
 - 邮件 / 通知
 - Webhook 处理
 **不要让用户 HTTP 请求长时间等待第三方 API。**
 Job 要求：
 - 携带 `tenant_code`，执行时恢复 TenantContext。
 - 幂等：重复执行不会产生重复业务数据或重复扣减库存。
 - 配置合理的重试次数、退避与超时。
 ## Scheduler
 使用 Laravel Scheduler，例如：
 - 订单同步
 - 库存同步
 - Tracking 同步
 - 异常订单检查
 - 库存预警
 - AI 分析任务
 - 报表任务
 所有定时任务必须可配置，并考虑：
 - 防重复执行
 - 失败重试
 - 日志
 - 超时
 - 租户隔离
@@ -0,0 +1,67 @@
 # 09 数据库设计
 ## 引擎
 - MySQL 8：业务事实数据源
 - Redis 7：缓存 / 队列 / 锁 / 限流（非业务数据源）
 ## 必须考虑的业务维度
 - 多租户
 - 多仓库
 - 多客户
 - 多 SKU
 - 批次
 - 库位
 - 库存流水
 - 库存锁定
 - 库存预占
 - 并发库存更新
 - 订单状态流转
 - WMS 作业任务
 - 数据审计
 ## 表设计规范
 所有表：
 - 使用 InnoDB
 - utf8mb4
 - 合理索引
 - `created_at`
 - `updated_at`
 重要业务表考虑：
 - `deleted_at`
 - `version`（乐观锁）
 - `status`
 但不要为了"统一"而无脑给所有表增加软删除。库存流水等事实数据不应被删除或修改。
 ## 核心业务表需包含 tenant_code
 见 [03-multi-tenancy.md](./03-multi-tenancy.md)。业务编码的唯一约束应包含租户维度，例如 `UNIQUE (tenant_code, sku_code)`。
 ## 索引
 索引必须围绕实际查询设计。特别关注：
 - tenant_code
 - warehouse_code
 - customer_code
 - sku_code
 - order_no
 - inbound_no
 - outbound_no
 - location_code
 - created_at
 - status
 复合索引通常以 `tenant_code` 作为最左列。
 ## 设计产出
 表结构设计统一存放在 [`docs/database/`](./database/README.md)。
 在写迁移之前，先在 `docs/database/` 中产出并确认表结构，把租户、仓库、库位、SKU、库存、库存流水、入库、出库这几个核心模型定死，再开始写 Laravel。迁移与设计文档必须保持一致。
@@ -0,0 +1,105 @@
 # 10 前端
 ## 技术栈
 Vue 3 + TypeScript + Vite + Element Plus + Pinia + Vue Router + VueUse + ECharts + Axios + ESLint + Prettier。
 ## Admin 框架
 前端 Admin 采用 [pure-admin-thin（i18n 分支）](https://github.com/pure-admin/pure-admin-thin/tree/i18n)，代码位于 `frontend/`。pure-admin 原生基于 Element Plus，并内置国际化。
 - 使用 pure-admin 提供的 Layout / Router / 权限 / 标签页 / i18n 等基础能力
 - Element Plus 作为唯一业务 UI 组件库，不引入 Naive UI 等第二套 UI 库
 - 不要重复实现 pure-admin 已有的 Admin 基础设施
 ## 目录结构
 ```
 src/
 ├── api/
 ├── assets/
 ├── components/
 ├── constants/
 ├── layouts/
 ├── router/
 ├── stores/
 ├── styles/
 ├── types/
 ├── utils/
 ├── views/
 │   ├── dashboard/
 │   ├── warehouse/
 │   ├── product/
 │   ├── inventory/
 │   ├── inbound/
 │   ├── outbound/
 │   ├── picking/
 │   ├── packing/
 │   ├── shipping/
 │   ├── customer/
 │   ├── supplier/
 │   ├── reports/
 │   └── system/
 └── App.vue
 ```
 页面必须按照业务领域组织。若所选 Admin 框架已有约定目录，以框架约定为准，在其中按业务领域组织。
 ## Element Plus 使用规范
 统一使用 Element Plus，重点组件：
 - ElTable
 - ElForm
 - ElDialog
 - ElDrawer
 - ElSelect
 - ElCascader
 - ElDatePicker
 - ElPagination
 - ElTabs
 - ElSteps
 - ElUpload
 - ElTree
 - ElDescriptions
 所有列表页尽量统一布局：
 ```
 查询区
 ↓
 Toolbar
 ↓
 Table
 ↓
 Pagination
 ```
 不要每个页面设计一套完全不同的交互，不要重复实现 Element Plus 已提供的组件。
 ## 前端权限
 支持：
 - 菜单权限
 - 页面权限
 - Button / API 权限
 - Role
 - Tenant
 权限码格式 `模块:动作`，例如：
 ```
 inventory:view
 inventory:adjust
 inventory:export
 inbound:view
 inbound:create
 inbound:receive
 outbound:view
 outbound:allocate
 outbound:pick
 outbound:ship
 ```
 前端权限仅用于展示控制，最终授权以后端 Policies / Gates 为准。
@@ -0,0 +1,76 @@
 # 11 Python AI / Data Service
 ## 定位
 Python 不参与 Laravel 核心业务 CRUD，作为独立服务存在。**Laravel 是唯一的核心业务系统。**
 ## 技术栈
 - Python 3.x
 - FastAPI
 - Pydantic
 - HTTP API
 - Redis
 - 后期根据需要使用 Pandas / NumPy / Scikit-learn / PyTorch / LLM SDK
 ## 负责范围
 - AI 分析
 - 库存分析
 - 销量预测
 - 缺货预测
 - 补货建议
 - 仓储数据分析
 - 异常检测
 - AI 助手
 - 后期机器学习
 ## 禁止范围
 不要把用户、租户、SKU、仓库、库存、入库、出库等核心业务逻辑迁移到 Python。
 **不要让 Python 直接修改 Laravel 核心业务数据库。**
 ## 目录结构
 ```
 py-service/
 └── app/
    ├── main.py
    ├── api/
    ├── services/
    ├── schemas/
    ├── models/
    ├── analysis/
    ├── ai/
    ├── tasks/
    └── core/
 ```
 ## 与 Laravel 交互
 Python 只通过 API 与 Laravel 交互，例如：
 ```
 POST /internal/v1/inventory/analyze
 POST /internal/v1/inventory/forecast
 POST /internal/v1/replenishment/recommend
 POST /internal/v1/ai/chat
 ```
 数据获取优先：
 ```
 Laravel → Python（推送数据）
 Python → 分析 → 返回结果
 ```
 或通过 Laravel 提供的只读数据接口获取。
 分析结果由 Laravel 决定是否落库、是否转化为业务动作（如生成补货建议单）。
 ## 注意
 - 内部接口需要鉴权（内部 Token / 签名），不对公网开放。
 - 请求中需携带 `tenant_code`，分析结果不得跨租户混用。
 - Laravel 调用 Python 的耗时任务应走 Queue，避免阻塞用户请求。
@@ -0,0 +1,51 @@
 # 12 日志、审计与安全
 ## 日志和审计
 必须考虑：
 - 登录日志
 - 操作日志
 - API 日志
 - 库存变更日志
 - 订单状态变更日志
 - 入库状态变更
 - 出库状态变更
 - 用户权限变更
 库存、订单等重要数据的关键变更必须能够追踪：
 | 字段 | 含义 |
 | --- | --- |
 | 谁 | 操作用户 / 系统任务 |
 | 什么时候 | 操作时间 |
 | 做了什么 | 操作类型 |
 | 修改前 | 变更前数据 |
 | 修改后 | 变更后数据 |
 | 来源 IP | 请求 IP |
 | 请求 ID | 全链路请求标识 |
 ## 安全要求
 必须考虑：
 - SQL Injection
 - XSS
 - CSRF
 - API Authentication
 - API Authorization
 - Rate Limit
 - Tenant Isolation
 - 文件上传安全
 - Webhook 签名
 - 密钥加密
 - 敏感信息保护
 - 日志脱敏
 ## 密钥管理
 任何第三方 API Token、Secret：**禁止直接写入 Git。**
 - 使用 `.env`（不提交）与 `.env.example`（仅占位）。
 - 租户级第三方凭证在数据库中加密存储。
 - 日志中不得输出 Token、密码、完整地址电话等敏感信息。
@@ -0,0 +1,20 @@
 # 13 Docker 开发环境
 ## 需要支持的服务
 - PHP 8.4
 - Laravel
 - MySQL 8
 - Redis 7
 - Nginx
 - Node.js
 - Python
 - FastAPI
 ## 原则
 - 在项目根目录提供一个统一的 `docker-compose.yml`。
 - **不要为每个小模块建立独立 Docker Compose。**
 - Queue Worker 与 Scheduler 作为独立容器 / 进程运行，复用 PHP 镜像。
 - 敏感配置通过 `.env` 注入，不写入镜像与 Git。
 - 第一阶段不引入 Kubernetes，生产部署方案在 Phase 17 再设计。
@@ -0,0 +1,41 @@
 # 14 测试要求
 核心业务必须有测试。**没有测试就不要继续堆功能。**
 ## 重点测试
 - Tenant Isolation
 - RBAC
 - Inventory
 - Concurrent Inventory
 - Inbound
 - Outbound
 - Allocation
 - Picking
 - Stocktake
 - Order Status
 - Queue
 - API Authorization
 尤其是库存。
 ## 库存并发用例
 两个请求同时扣减 8 个库存，而实际只有 10 个库存。必须保证：
 - 不会出现 `available_qty = -6`
 - 不能出现两个订单都成功扣减 8
 ## 租户隔离用例
 - 租户 A 的用户通过列表、详情、业务编码、批量操作等任何接口都无法读取或修改租户 B 的数据。
 - Queue Job、Scheduler 执行时只处理其所属租户的数据。
 ## 状态机用例
 - 合法状态转换成功，并记录状态变更日志。
 - 非法状态转换被拒绝（例如 `draft` 直接 `shipped`）。
 ## 库存流水用例
 - 每一次库存余额变化都有对应流水，且流水累计值与余额一致。
@@ -0,0 +1,84 @@
 # 15 开发工作方式
 ## 分阶段开发
 **不要一次生成整个项目。** 必须分阶段开发。
 每完成一个阶段：
 1. 检查代码
 2. 检查数据库
 3. 运行测试
 4. 检查 API
 5. 检查前端
 6. 修复问题
 7. 再进入下一阶段
 不要为了"快速完成"一次生成几百个文件。
 ## 修改代码前
 1. 先理解现有目录
 2. 搜索已有实现
 3. 不要重复创建已有功能
 4. 检查数据库结构
 5. 检查相关 API
 6. 检查前端调用
 7. 再修改代码
 ## 修改代码后
 1. 检查类型
 2. 检查语法
 3. 检查引用
 4. 检查数据库迁移
 5. 检查 API
 6. 检查权限
 7. 检查租户隔离
 8. 运行相关测试
 ## 代码质量
 代码必须：
 - 清晰
 - 可维护
 - 类型明确
 - 避免重复
 - 避免超大 Controller
 - 避免超大 Service
 - 避免魔法字符串
 - 避免硬编码
 - 避免重复 SQL
 - 避免跨模块强耦合
 优先可读性，而不是为了"高级架构"而复杂化。
 ## 需求存在架构问题时
 不要直接照做，请指出：
 1. 问题是什么
 2. 为什么有问题
 3. 推荐方案
 4. 替代方案
 5. 最终建议
 如果有多个合理方案，不要擅自选择影响整个项目架构的方案，先说明区别。
 ## 禁止事项
 - 为了快速开发跳过架构设计
 - Controller 堆业务逻辑
 - 一个 Model 承担所有业务
 - Python 直接修改核心 WMS 数据
 - 忽略 tenant_code
 - 忽略库存流水
 - 直接修改库存而没有业务记录
 - 不考虑并发库存
 - 把 Amazon 等平台逻辑写死到核心订单模型
 - 为了所谓高性能过早微服务化
 - 没有测试就继续堆功能
 - 随意增加第三方依赖
 - 重复实现 Element Plus 已经提供的组件
 - 修改已有代码前不检查上下文
@@ -0,0 +1,92 @@
 # 16 开发路线图
 ## 第一阶段必须先做设计
 在写大量代码之前，先输出：
 1. 系统架构
 2. 模块划分
 3. 数据库 ER 关系
 4. 核心数据表
 5. 租户隔离方案
 6. 库存模型
 7. 入库流程
 8. 出库流程
 9. 订单模型
 10. 权限模型
 11. API 设计
 12. Queue / Scheduler 设计
 13. Python Service 边界
 14. Docker 开发环境
 15. 项目目录结构
 ## 第一阶段不要直接实现业务
 先在 `docs/` 目录下生成以下设计文档及目录结构说明：
 - ARCHITECTURE.md
 - database/（数据库总览、ER 关系与表结构设计，入口 `database/README.md`）
 - API.md
 - DEVELOPMENT.md
 - DOCKER.md
 确认架构合理之后，再开始数据库和代码。建议优先产出 `docs/database/` 中的表结构设计，把租户、仓库、库位、SKU、库存、库存流水、入库、出库这几个核心模型定死。
 ## 开发顺序
 严格按照以下顺序：
 | Phase | 内容 |
 | --- | --- |
 | 1 | 项目架构设计 |
 | 2 | Laravel 基础项目 |
 | 3 | Vue 3 + Element Plus Admin |
 | 4 | SaaS 租户 / 用户 / RBAC |
 | 5 | 仓库 / 库区 / 库位 |
 | 6 | 商品 / SKU / 客户 |
 | 7 | 库存核心模型 |
 | 8 | 库存流水 / 库存并发 |
 | 9 | 入库 |
 | 10 | 出库 |
 | 11 | 拣货 / 波次 / 打包 / 发货 |
 | 12 | 物流 |
 | 13 | 报表 |
 | 14 | 第三方订单接口 |
 | 15 | Python AI / Data Service |
 | 16 | 测试 / 性能 / 安全 |
 | 17 | Docker / Production |
 ## 每个 Phase 开始前
 先说明本阶段：
 - 目标
 - 涉及模块
 - 数据库变化
 - API 变化
 - 前端变化
 - 测试方案
 - 风险
 然后再实施。
 ## 第一步任务
 不要写业务代码。先检查当前工作区，然后输出：
 1. 当前项目状态
 2. 推荐的最终目录结构
 3. 系统架构图
 4. Laravel / Vue / Python 三者职责边界
 5. SaaS 多租户方案
 6. WMS 核心领域模型
 7. 核心数据库表清单
 8. 库存模型设计
 9. 入库 / 出库流程
 10. API 分层设计
 11. Queue / Scheduler 设计
 12. Python Service 设计
 13. Docker 开发环境设计
 14. Phase 1 实施计划
 **暂时不要创建大量代码文件，先完成架构设计。**
@@ -0,0 +1,34 @@
 # WMS SaaS 项目文档索引
 本目录由根目录 `README.md`（项目总提示词）按主题拆分而来，是项目设计与开发的约束来源。
 | 文档 | 内容 | 对应原 README 章节 |
 | --- | --- | --- |
 | [00-overview.md](./00-overview.md) | 项目定位、最终目标 | 开头、四十 |
 | [01-tech-stack.md](./01-tech-stack.md) | 前端 / 后端 / 数据库 / Python 技术栈 | 一 ~ 四 |
 | [02-architecture.md](./02-architecture.md) | 总体架构、职责边界、Redis、避免过度设计 | 五、二十一、二十八 |
 | [03-multi-tenancy.md](./03-multi-tenancy.md) | SaaS 多租户、tenant_code、TenantContext | 六、七 |
 | [04-domain-model.md](./04-domain-model.md) | 业务编码、业务模块、订单模型、第三方平台、状态机 | 八、十二 ~ 十五 |
 | [05-inventory.md](./05-inventory.md) | 库存模型、库存流水、并发安全 | 九 ~ 十一 |
 | [06-backend-laravel.md](./06-backend-laravel.md) | Laravel 代码分层与目录结构 | 十六、后端框架结构 |
 | [07-api.md](./07-api.md) | API 路由规范与统一返回格式 | 十七、十八 |
 | [08-queue-scheduler.md](./08-queue-scheduler.md) | 队列与定时任务 | 十九、二十 |
 | [09-database.md](./09-database.md) | 数据库设计要求与规范 | 三、二十七 |
 | [10-frontend.md](./10-frontend.md) | 前端框架、目录、Element Plus、权限 | 一、二十三 ~ 二十五 |
 | [11-py-service.md](./11-py-service.md) | Python AI / Data Service（`py-service/`）边界与结构 | 四、二十二 |
 | [12-security-audit.md](./12-security-audit.md) | 日志审计与安全要求 | 二十六、三十五 |
 | [13-docker.md](./13-docker.md) | Docker 开发环境 | 二十九 |
 | [14-testing.md](./14-testing.md) | 测试要求 | 三十四 |
 | [15-development-workflow.md](./15-development-workflow.md) | 开发原则、代码质量、Cursor 工作方式、禁止事项 | 三十、三十六 ~ 三十九 |
 | [16-roadmap.md](./16-roadmap.md) | 设计先行、Phase 开发顺序、第一步任务 | 三十一 ~ 三十三、现在开始 |
 | [database/](./database/README.md) | 数据库表结构设计（按领域分文件） | — |
 ## 核心原则
 **简单、清晰、可维护、可扩展、业务优先。**
 - Laravel 是唯一的核心业务系统，MySQL 是业务事实数据源。
 - 所有核心业务数据按 `tenant_code` 隔离，由 TenantContext 统一处理。
 - 库存余额是结果，库存流水是事实；库存变更必须并发安全、可追溯。
 - Python 只做 AI / 数据分析，只通过 API 与 Laravel 交互。
 - 分阶段开发，每个 Phase 先说明方案、再实施、再验证。
@@ -0,0 +1,57 @@
 # 数据库表结构设计
 本目录存放 WMS SaaS 的数据库表结构设计，是 `backend/database/migrations` 的设计依据。通用规范见 [../09-database.md](../09-database.md)。
 **先设计、确认，再写迁移；改表时迁移与本目录文档同步更新。**
 ## 文件组织
 按业务领域一个文件，文件内包含该领域所有表：
 | 文件 | 领域 | 对应 Phase |
 | --- | --- | --- |
 | `00-conventions.md` | 命名、公共字段、类型、索引约定 | 1 |
 | `01-er-overview.md` | 全局 ER 关系图 | 1 |
 | `10-saas.md` | 租户、用户、角色、权限、租户设置、操作日志 | 4 |
 | `20-warehouse.md` | 仓库、库区、库位、库位类型 / 容量 / 策略 | 5 |
 | `30-master-data.md` | 客户、供应商、商品、SKU、条码、包装规格 | 6 |
 | `40-inventory.md` | 库存余额、批次、库存流水、锁定 / 冻结、调整、盘点 | 7、8 |
 | `50-inbound.md` | 入库单、明细、收货、差异、质检、上架 | 9 |
 | `60-outbound.md` | 订单、出库单、明细、分配、波次、拣货、复核、打包、发货 | 10、11 |
 | `70-return.md` | 退货单、退货收货、质检、重新入库、报废 | — |
 | `80-logistics.md` | 物流渠道、承运商、服务、运费规则、面单、Tracking | 12 |
 | `90-integration.md` | 第三方平台店铺、凭证、同步任务、Webhook 日志 | 14 |
 | `95-audit.md` | 登录日志、API 日志、状态变更日志、数据审计 | 4 起 |
 文件在对应 Phase 开始前创建，不提前为未来阶段编写。
 ## 单表设计模板
 ````markdown
 ### wms_xxx 表中文名
 用途：一句话说明。
 | 字段 | 类型 | 可空 | 默认 | 说明 |
 | --- | --- | --- | --- | --- |
 | id | BIGINT UNSIGNED | N | AUTO_INCREMENT | 内部主键 |
 | tenant_code | VARCHAR(32) | N | | 租户编码 |
 | xxx_code | VARCHAR(64) | N | | 业务编码 |
 | status | VARCHAR(32) | N | | 状态，取值见下方状态说明 |
 | version | INT UNSIGNED | N | 0 | 乐观锁（按需） |
 | created_at | TIMESTAMP | Y | | |
 | updated_at | TIMESTAMP | Y | | |
 索引：
 | 名称 | 类型 | 字段 | 支撑的查询 |
 | --- | --- | --- | --- |
 | uk_tenant_xxx_code | UNIQUE | (tenant_code, xxx_code) | 按业务编码查找 |
 | idx_tenant_status_created | INDEX | (tenant_code, status, created_at) | 列表筛选 |
 状态说明 / 合法流转（有状态字段时必填）。
 关联：与哪些表通过哪些业务编码关联。
 并发 / 审计说明：是否需要行锁、乐观锁、流水、软删除，及原因。
 ````