---
description: Python FastAPI AI / 数据分析服务边界与规范
globs: py-service/**
alwaysApply: false
---
# Python Service（py-service）

详见 `docs/11-py-service.md`。

## 边界（红线）
- 只负责：AI 分析、库存分析、销量 / 缺货预测、补货建议、异常检测、AI 助手、机器学习。
- **不实现**用户、租户、SKU、仓库、库存、入库、出库等核心业务逻辑。
- **不直接连接或写入** Laravel 核心业务数据库；数据由 Laravel 推送，或通过 Laravel 只读接口获取。
- 分析结果返回给 Laravel，由 Laravel 决定是否落库或转化为业务动作。

## 接口
- 前缀 `/internal/v1/`，如 `POST /internal/v1/inventory/forecast`。
- 内部鉴权（Token / 签名），不对公网暴露。
- 请求必须带 `tenant_code`，缓存与结果按租户隔离。

## 结构与编码
```
py-service/app/
├── main.py  api/  services/  schemas/  models/
├── analysis/  ai/  tasks/  core/
```
- 路由在 `api/`，业务在 `services/`，请求响应模型用 Pydantic 定义在 `schemas/`。
- 全部函数写类型注解；配置用 pydantic-settings 从环境变量读取，密钥不入库不入 Git。
- 重型依赖（PyTorch 等）按需引入，不提前加入。