# fw-pms-ai

AI 配件系统 - 基于 Python + LangChain + LangGraph

## 项目简介

本项目是 `fw-pms` 的 AI 扩展模块，使用大语言模型 (LLM) 和 Agent 技术，为配件管理系统提供智能化的补货建议能力。

## 核心技术

### LangChain + LangGraph

| 技术 | 作用 |
|------|------|
| **LangChain** | LLM 框架，提供模型抽象、Prompt 管理、消息格式化 |
| **LangGraph** | Agent 工作流编排，管理状态机、定义节点和边、支持条件分支 |
| **SQL Agent** | 自定义 Text-to-SQL 实现，支持错误重试和 LLM 数据分析 |

```mermaid
graph LR
    A[用户请求] --> B[LangGraph Agent]
    B --> C[FetchPartRatio]
    C --> D[SQLAgent<br/>LLM分析]
    D --> E[AllocateBudget]
    E --> G[SaveResult]
```

详细架构图见 [docs/architecture.md](docs/architecture.md)

## 功能模块

### ✅ 已实现

| 模块 | 功能 | 说明 |
|------|------|------|
| **SQL Agent** | LLM 分析 | 直接分析 part_ratio 数据生成补货建议 |
| **补货分配** | Replenishment | 转换 LLM 建议为补货明细 |

### 🚧 计划中

| 模块 | 功能 |
|------|------|
| 预测引擎 | 基于历史销量预测未来需求 |
| 异常检测 | 识别数据异常 |

## 项目结构

```
fw-pms-ai/
├── src/fw_pms_ai/
│   ├── agent/              # LangGraph Agent
│   │   ├── state.py        # Agent 状态定义
│   │   ├── nodes.py        # 工作流节点
│   │   ├── sql_agent.py    # SQL Agent（Text-to-SQL + 建议生成）
│   │   └── replenishment.py
│   ├── api/                # FastAPI 接口
│   │   ├── app.py          # 应用入口
│   │   └── routes/         # 路由模块
│   ├── config/             # 配置管理
│   ├── llm/                # LLM 集成
│   │   ├── base.py         # 抽象基类
│   │   ├── glm.py          # 智谱 GLM
│   │   ├── doubao.py       # 豆包
│   │   ├── openai_compat.py
│   │   └── anthropic_compat.py
│   ├── models/             # 数据模型
│   │   ├── task.py         # 任务和明细模型
│   │   ├── execution_log.py # 执行日志模型
│   │   ├── part_ratio.py   # 库销比模型
│   │   ├── part_summary.py # 配件汇总模型
│   │   ├── sql_result.py   # SQL执行结果模型
│   │   └── suggestion.py   # 补货建议模型
│   ├── services/           # 业务服务
│   │   ├── db.py           # 数据库连接
│   │   ├── data_service.py # 数据查询服务
│   │   └── result_writer.py # 结果写入服务
│   ├── scheduler/          # 定时任务
│   └── main.py
├── prompts/                # AI Prompt 文件
│   ├── sql_agent.md        # SQL Agent 系统提示词
│   ├── suggestion.md       # 补货建议提示词
│   ├── suggestion_system.md
│   ├── part_shop_analysis.md
│   └── part_shop_analysis_system.md
├── ui/                     # 前端静态文件
├── sql/                    # 数据库迁移脚本
├── pyproject.toml
└── README.md
```


## 工作流程

```
1. FetchPartRatio  - 从 part_ratio 表获取库销比数据
2. SQLAgent        - LLM 分析数据，生成补货建议
3. AllocateBudget  - 转换建议为补货明细
4. SaveResult      - 写入数据库
```

### 业务术语

| 术语 | 定义 | 处理 |
|------|------|------|
| **呆滞件** | 有库存，90天无销量 | 不做计划 |
| **低频件** | 无库存，月均销量<1 | 不做计划 |
| **缺货件** | 无库存，月均销量≥1 | 需要补货 |

## 数据表说明

| 表名 | 说明 |
|------|------|
| `part_ratio` | 配件库销比数据（来源表） |
| `ai_replenishment_task` | 任务记录 |
| `ai_replenishment_detail` | 配件级别补货建议 |
| `ai_replenishment_part_summary` | 配件汇总表 |
| `ai_task_execution_log` | 任务执行日志 |

## 快速开始

### 1. 安装依赖

```bash
cd fw-pms-ai
pip install -e .
```

### 2. 配置环境变量

```bash
cp .env.example .env
```

必填配置项：
- `GLM_API_KEY` / `ANTHROPIC_API_KEY` - LLM API Key
- `MYSQL_HOST`, `MYSQL_USER`, `MYSQL_PASSWORD`, `MYSQL_DATABASE`

### 3. 初始化数据库

```bash
mysql -u root -p fw_pms < sql/init.sql
```

### 4. 运行

```bash
# 启动定时任务调度器
fw-pms-ai

# 立即执行一次
fw-pms-ai --run-once

# 指定参数
fw-pms-ai --run-once --group-id 2
```

## AI Prompt 文件

Prompt 文件存放在 `prompts/` 目录：

| 文件 | 用途 |
|------|------|
| `suggestion.md` | 补货建议生成（含业务术语定义） |
| `analyze_inventory.md` | 库存分析 |

## 开发

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/ -v
```