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 数据分析

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

详细架构图见 docs/architecture.md

功能模块

✅ 已实现

模块	功能	说明
SQL Agent	LLM 分析	直接分析 part_ratio 数据生成补货建议
补货分配	Replenishment	转换 LLM 建议为补货明细
分析报告	Report	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. GenerateReport  - LLM 生成分析报告
5. SaveResult      - 写入数据库

业务术语

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

数据表说明

表名	说明
part_ratio	配件库销比数据（来源表）
ai_replenishment_task	任务记录
ai_replenishment_detail	配件级别补货建议
ai_replenishment_report	分析报告
ai_task_execution_log	任务执行日志
ai_llm_suggestion_detail	LLM 建议明细

快速开始

1. 安装依赖

cd fw-pms-ai
pip install -e .

2. 配置环境变量

cp .env.example .env

必填配置项：

• GLM_API_KEY / ANTHROPIC_API_KEY - LLM API Key
• MYSQL_HOST, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE

3. 初始化数据库

mysql -u root -p fw_pms < sql/init.sql
mysql -u root -p fw_pms < sql/v2_add_log_tables.sql

4. 运行

# 启动定时任务调度器
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	库存分析
generate_report.md	报告生成

开发

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

# 运行测试
pytest tests/ -v