cas / fw-pms-ai

README.md 12.3 KB

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 分析报告 — 补货建议板块