# fw-pms-ai 系统架构

## 技术栈

| 组件 | 技术 |
|------|------|
| 编程语言 | Python 3.11+ |
| Agent 框架 | LangChain + LangGraph |
| LLM | 智谱 GLM / 豆包 / OpenAI 兼容接口 |
| 数据库 | MySQL |
| API 框架 | FastAPI |
| 任务调度 | APScheduler |

---

## 系统架构图

```mermaid
flowchart TB
    subgraph API ["FastAPI API 层"]
        A[/tasks endpoint/]
    end

    subgraph Agent ["LangGraph Agent"]
        direction TB
        B[fetch_part_ratio] --> C[sql_agent]
        C --> D{需要重试?}
        D -->|是| C
        D -->|否| E[allocate_budget]
        E --> F[END]
    end

    subgraph Services ["业务服务层"]
        G[DataService]
        H[ResultWriter]
    end

    subgraph LLM ["LLM 集成"]
        I[GLM]
        J[Doubao]
        K[OpenAI Compat]
    end

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

    A --> Agent
    B --> G
    C --> LLM
    E --> H
    G --> L
    H --> L
```

---

## 工作流节点说明

| 节点 | 职责 | 输入 | 输出 |
|------|------|------|------|
| `fetch_part_ratio` | 获取商家组合的配件库销比数据 | dealer_grouping_id | part_ratios[] |
| `sql_agent` | LLM 分析配件数据，生成补货建议 | part_ratios[] | llm_suggestions[], part_results[] |
| `allocate_budget` | 转换 LLM 建议为补货明细 | llm_suggestions[] | details[] |

---

## 核心数据流

```mermaid
sequenceDiagram
    participant API
    participant Agent
    participant SQLAgent
    participant LLM
    participant DB

    API->>Agent: 创建任务
    Agent->>DB: 保存任务记录
    Agent->>DB: 查询 part_ratio
    Agent->>SQLAgent: 分析配件数据
    
    loop 每个配件
        SQLAgent->>LLM: 发送分析请求
        LLM-->>SQLAgent: 返回补货建议
    end
    
    SQLAgent-->>Agent: 汇总建议
    Agent->>DB: 保存补货明细
    Agent->>DB: 更新任务状态
    Agent-->>API: 返回结果
```

---

## 目录结构

```
src/fw_pms_ai/
├── agent/              # LangGraph 工作流
│   ├── state.py        # 状态定义 (TypedDict)
│   ├── nodes.py        # 工作流节点
│   ├── sql_agent.py    # SQL Agent 实现
│   └── replenishment.py # 主入口
├── api/                # REST API
├── config/             # 配置管理
├── llm/                # LLM 适配器
├── models/             # 数据模型
├── services/           # 业务服务
└── scheduler/          # 定时任务
```

---

## 数据库表结构

| 表名 | 用途 |
|------|------|
| `part_ratio` | 配件库销比数据（只读） |
| `ai_replenishment_task` | 任务记录 |
| `ai_replenishment_detail` | 补货明细 |
| `ai_replenishment_part_summary` | 配件级汇总 |
| `ai_task_execution_log` | 执行日志 |