fw-pms-ai

fw-pms 配件管理系统 AI 扩展平台 — 基于 Python + LangChain + LangGraph

项目简介

本项目是 fw-pms 配件管理系统的 AI 能力扩展平台，使用大语言模型 (LLM) 和 Agent 技术，为配件业务提供多种智能化功能。

功能模块

状态	模块	说明
✅ 已实现	智能补货建议	分析库销比数据，LLM 逐配件分析各门店补货需求，生成结构化建议
✅ 已实现	分析报告	四大板块（库存概览/销量分析/健康度/补货建议）并发 LLM 分析
🚧 规划中	需求预测	基于历史销量预测未来配件需求
🚧 规划中	异常检测	识别库存和销量数据异常
🚧 规划中	智能定价	AI 辅助配件定价建议

技术栈

组件	技术	版本要求
编程语言	Python	≥ 3.11
Agent 框架	LangChain + LangGraph	LangChain ≥ 0.3, LangGraph ≥ 0.2
LLM 集成	智谱 GLM / 豆包 / OpenAI 兼容 / Anthropic 兼容	—
Web API	FastAPI + Uvicorn	FastAPI ≥ 0.109
数据库	MySQL (mysql-connector-python + SQLAlchemy)	SQLAlchemy ≥ 2.0
任务调度	APScheduler	≥ 3.10
配置管理	Pydantic Settings + python-dotenv	Pydantic ≥ 2.0
HTTP 客户端	httpx	≥ 0.25
重试机制	tenacity	≥ 8.0

系统架构

flowchart TB
    subgraph Scheduler ["定时调度 (APScheduler)"]
        S[每日凌晨触发]
    end

    subgraph API ["FastAPI API 层"]
        A[/tasks, details, logs, reports/]
    end

    subgraph Agent ["LangGraph 工作流"]
        direction TB
        B[1. fetch_part_ratio] --> C[2. sql_agent]
        C --> D{需要重试?}
        D -->|是| C
        D -->|否| E[3. allocate_budget]
        E --> F[4. generate_analysis_report]
        F --> G[END]
    end

    subgraph ReportSubgraph ["分析报告并发子图"]
        direction LR
        R1[库存概览 LLM] & R2[销量分析 LLM] & R3[健康度 LLM] & R4[补货建议 LLM]
    end

    subgraph Services ["业务服务层"]
        DS[DataService]
        RW[ResultWriter]
        RP[Repository]
    end

    subgraph LLM ["LLM 适配层"]
        L1[GLMClient]
        L2[DoubaoClient]
        L3[OpenAICompatClient]
        L4[AnthropicCompatClient]
    end

    subgraph DB ["数据存储"]
        MySQL[(MySQL)]
    end

    S --> Agent
    A --> Services
    B --> DS
    C --> LLM
    F --> ReportSubgraph
    ReportSubgraph --> LLM
    E --> RW
    DS --> MySQL
    RW --> MySQL
    RP --> MySQL

详细架构图见 docs/architecture.md

平台采用模块化设计，新增 AI 功能模块只需添加对应的 Agent 工作流节点和提示词文件。

补货建议工作流

补货建议模块的核心是一个 4 节点 LangGraph 工作流，按顺序执行：

序号	节点	功能	说明
1	fetch_part_ratio	获取库销比数据	通过 dealer_grouping_id 从 part_ratio 表查询配件数据
2	sql_agent	LLM 分析 + 建议生成	按 part_code 分组，逐配件分析各门店补货需求，支持错误重试
3	allocate_budget	转换补货明细	将 LLM 建议转换为结构化的补货明细记录
4	generate_analysis_report	生成分析报告	统计计算 + 4 路并发 LLM 分析生成结构化报告

分析报告四大板块

板块	统计计算	LLM 分析
库存概览	有效库存、资金占用、配件总数	库存状况综合评价
销量分析	月均销量、出库频次、销售趋势	销售趋势洞察
库存健康度	缺货/呆滞/低频/正常分类统计	健康度风险提示
补货建议汇总	按优先级分类统计补货数量和金额	补货策略建议

四个 LLM 分析节点使用 LangGraph 子图 并发执行，单板块失败不影响其他板块。

业务术语

术语	定义	处理方式
呆滞件	有效库存 > 0，90天出库数 = 0	不做计划
低频件	月均销量 < 1 或 出库次数 < 3 或 出库间隔 ≥ 30天	不做计划
缺货件	有效库存 = 0，月均销量 ≥ 1	需要补货
正常件	不属于以上三类	按需补货

项目结构

fw-pms-ai/
├── src/fw_pms_ai/
│   ├── main.py                     # 应用入口
│   ├── agent/                      # LangGraph Agent 工作流
│   │   ├── state.py                # Agent 状态定义 (TypedDict + Annotated reducer)
│   │   ├── nodes.py                # 工作流节点 (fetch/sql_agent/allocate)
│   │   ├── analysis_report_node.py # 分析报告节点 (统计计算 + 并发 LLM 子图)
│   │   ├── replenishment.py        # ReplenishmentAgent 主类 (构建图 + 运行)
│   │   └── sql_agent/              # SQL Agent 子包
│   │       ├── agent.py            # SQLAgent 主类
│   │       ├── executor.py         # SQL 执行器
│   │       ├── analyzer.py         # 配件分析器 (逐配件 LLM 分析)
│   │       └── prompts.py          # 提示词加载
│   ├── api/                        # FastAPI REST API
│   │   ├── app.py                  # FastAPI 应用 (CORS + 静态文件 + 路由)
│   │   └── routes/
│   │       └── tasks.py            # 任务/明细/日志/汇总/报告 API
│   ├── config/
│   │   └── settings.py             # Pydantic Settings 配置管理
│   ├── llm/                        # LLM 适配层
│   │   ├── base.py                 # BaseLLMClient 抽象基类
│   │   ├── glm.py                  # 智谱 GLM 客户端
│   │   ├── doubao.py               # 豆包客户端
│   │   ├── openai_compat.py        # OpenAI 兼容客户端 (火山引擎等)
│   │   └── anthropic_compat.py     # Anthropic 兼容客户端
│   ├── models/                     # 数据模型 (Pydantic)
│   │   ├── task.py                 # 任务模型 + 状态枚举
│   │   ├── suggestion.py           # 补货建议模型
│   │   ├── part_ratio.py           # 配件库销比模型
│   │   ├── part_summary.py         # 配件汇总模型
│   │   ├── analysis_report.py      # 分析报告模型
│   │   ├── execution_log.py        # 执行日志模型
│   │   └── sql_result.py           # SQL 执行结果模型
│   ├── services/                   # 业务服务层
│   │   ├── db.py                   # 数据库连接管理
│   │   ├── data_service.py         # 数据查询服务
│   │   ├── result_writer.py        # 结果写入服务
│   │   └── repository/             # 仓库模式
│   │       ├── task_repo.py        # 任务仓库
│   │       ├── detail_repo.py      # 明细仓库
│   │       └── log_repo.py         # 日志仓库
│   └── scheduler/
│       └── tasks.py                # APScheduler 定时任务 + CLI 参数解析
├── prompts/                        # AI 提示词文件
│   ├── sql_agent.md                # SQL Agent 系统提示词
│   ├── suggestion.md               # 补货建议生成提示词
│   ├── suggestion_system.md        # 补货建议系统提示词
│   ├── part_shop_analysis.md       # 配件门店分析提示词
│   ├── part_shop_analysis_system.md
│   ├── report_inventory_overview.md  # 分析报告-库存概览提示词
│   ├── report_sales_analysis.md      # 分析报告-销量分析提示词
│   ├── report_inventory_health.md    # 分析报告-库存健康度提示词
│   └── report_replenishment_summary.md # 分析报告-补货建议提示词
├── ui/                             # 前端静态文件
│   ├── index.html                  # 主页面
│   ├── css/                        # 样式
│   ├── js/                         # JavaScript
│   └── merchant-report/            # 商家组合报告页面
├── sql/                            # 数据库脚本
│   ├── init.sql                    # 初始化建表 (4张表)
│   └── migrate_analysis_report.sql # 分析报告表迁移
├── docs/                           # 文档
│   ├── architecture.md             # 系统架构文档
│   └── 商家组合维度分析需求设计.md
├── pyproject.toml                  # 项目配置 (hatchling 构建)
├── .env                            # 环境变量
└── README.md

数据表说明

表名	说明	SQL 文件
part_ratio	配件库销比数据（来源表，只读）	—
ai_replenishment_task	任务记录	init.sql
ai_replenishment_detail	配件级别补货建议明细	init.sql
ai_replenishment_part_summary	配件汇总表（按配件编码聚合）	init.sql
ai_task_execution_log	任务执行日志（每步骤详情）	init.sql
ai_analysis_report	结构化分析报告（四大板块 JSON）	migrate_analysis_report.sql

API 接口

基于 FastAPI 提供 REST API，支持前端 UI 对接。

方法	路径	说明
GET	/api/tasks	任务列表（分页、状态/组合/日期筛选）
GET	/api/tasks/{task_no}	任务详情
GET	/api/tasks/{task_no}/details	配件建议明细（分页、排序、搜索）
GET	/api/tasks/{task_no}/logs	执行日志
GET	/api/tasks/{task_no}/part-summaries	配件汇总列表（分页、优先级筛选）
GET	/api/tasks/{task_no}/parts/{part_code}/shops	指定配件的门店明细
GET	/api/tasks/{task_no}/analysis-report	分析报告
GET	/health	健康检查
GET	/	主页面（静态文件）

运行后访问 /docs 查看 Swagger 文档。

LLM 集成

支持 4 种 LLM 客户端，通过环境变量自动选择：

客户端	环境变量	说明
OpenAICompatClient	OPENAI_COMPAT_API_KEY	OpenAI 兼容接口（火山引擎、智谱等）
AnthropicCompatClient	ANTHROPIC_API_KEY	Anthropic 兼容接口
GLMClient	GLM_API_KEY	智谱 GLM 原生 SDK
DoubaoClient	DOUBAO_API_KEY	豆包

优先级：OpenAI Compat > Anthropic Compat > GLM > Doubao

快速开始

1. 安装依赖

cd fw-pms-ai
pip install -e .

2. 配置环境变量

cp .env.example .env
# 编辑 .env 填写以下配置

必填配置项：

# LLM (至少配置一种)
OPENAI_COMPAT_API_KEY=your-key
OPENAI_COMPAT_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
OPENAI_COMPAT_MODEL=glm-4-7-251222

# 数据库
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=your-password
MYSQL_DATABASE=fw_pms

3. 初始化数据库

# 基础表结构
mysql -u root -p fw_pms < sql/init.sql

# 分析报告表
mysql -u root -p fw_pms < sql/migrate_analysis_report.sql

4. 运行

# 启动定时任务调度器（默认每日 02:00 执行）
fw-pms-ai

# 立即执行一次（所有商家组合）
fw-pms-ai --run-once

# 指定集团和商家组合
fw-pms-ai --run-once --group-id 2 --dealer-grouping-id 100

5. 启动 API 服务

uvicorn fw_pms_ai.api.app:app --host 0.0.0.0 --port 8000 --reload

开发

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

# 代码格式化
black src/
ruff check src/

# 运行测试
pytest tests/ -v

提示词文件

提示词文件存放在 prompts/ 目录，供 LLM 调用时使用：

文件	用途
sql_agent.md	SQL Agent 生成 SQL 查询的系统提示词
suggestion.md	配件补货建议生成
suggestion_system.md	补货建议系统角色提示词
part_shop_analysis.md	配件门店级别分析
part_shop_analysis_system.md	门店分析系统角色提示词
report_inventory_overview.md	分析报告 — 库存概览板块
report_sales_analysis.md	分析报告 — 销量分析板块
report_inventory_health.md	分析报告 — 库存健康度板块
report_replenishment_summary.md	分析报告 — 补货建议板块