docs/00-overview.md

docs/11-py-service.md

@@ -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，避免阻塞用户请求。