playwrite/docs/MAIN_CLEAN_FLOW.md

# main_clean.py 流程说明

## 概述

`main_clean.py` 是离散备料计划维护数据清理工具的主程序入口。该工具通过 Playwright 自动化登录用友 BIP 系统，读取生产订单号，然后逐个清理订单中不需要的物料数据。

---

## 系统架构图

```mermaid
flowchart TB
    Start([开始]) --> Init[初始化 DiscreteMaterialPlanCleaner]

    Init --> QueryDB[(查询数据库<br/>获取待删除物料列表)]

    QueryDB --> Login[登录用友BIP系统]

    Login --> OpenMenu[点击功能菜单]
    OpenMenu --> OpenPage[打开离散生产订单维护页面]

    OpenPage --> SetupQuery[设置查询界面]
    SetupQuery --> ReadFile[(读取ProductionID.txt)]
    ReadFile --> GetOrders[(查询数据库<br/>获取生产订单号)]

    GetOrders --> LoopStart{遍历订单}

    LoopStart --> ProcessOrder[处理单个订单]
    ProcessOrder --> QueryOrder[查询订单详情]
    QueryOrder --> OpenPlanPage[打开备料计划页面]
    OpenPlanPage --> WaitLoad[等待页面加载完成]

    WaitLoad --> CheckData{检查数据状态}

    CheckData -->|detail_count = 0| SkipOrder[跳过该订单]
    CheckData -->|status != 审批通过| SkipOrder
    CheckData -->|detail_count > 0<br/>status = 审批通过| ClickModify[点击修改按钮]

    ClickModify --> ExpandForm[展开详细信息表单]
    ExpandForm --> LoopMaterials{遍历物料}

    LoopMaterials --> GetMaterial[获取物料信息]
    GetMaterial --> CheckDelete{需要删除?}

    CheckDelete -->|是| MarkDelete[标记待删除]
    CheckDelete -->|否| KeepMaterial[保留物料]

    MarkDelete --> NextMaterial{下一个物料?}
    KeepMaterial --> NextMaterial

    NextMaterial -->|是| LoopMaterials
    NextMaterial -->|否| ClosePlanPage[关闭备料计划页面]

    SkipOrder --> ClosePlanPage
    ClosePlanPage --> NextOrder{下一个订单?}

    NextOrder -->|是| LoopStart
    NextOrder -->|否| Logout[注销账号]

    Logout --> CloseBrowser[关闭浏览器]
    CloseBrowser --> End([结束])

    style Init fill:#e1f5ff
    style QueryDB fill:#fff4e1
    style Login fill:#e1f5ff
    style End fill:#ffe1e1
    style CheckDelete fill:#fff4e1
    style CheckData fill:#fff4e1
```

---

## 详细流程说明

### 1. 初始化阶段

```mermaid
flowchart LR
    A[main函数] --> B[创建 DiscreteMaterialPlanCleaner 实例]
    B --> C[配置参数:<br/>username, password,<br/>manager_name, headless, verbose]

    style A fill:#e1f5ff
    style B fill:#e1f5ff
    style C fill:#e1f5ff
```

**代码位置**: `main_clean.py:9-24`

```python
cleaner = DiscreteMaterialPlanCleaner(
    username="BLDpengqiangqiang",
    password="Cqbld123456.",
    manager_name="彭羽",
    headless=False,
    verbose=True,
)
```

---

### 2. 数据准备阶段

```mermaid
flowchart TB
    A[clean.clean方法] --> B[查询数据库<br/>MaterialsToBeDeleted表]
    B --> C[获取指定负责人的<br/>待删除物料编码列表]

    style A fill:#fff4e1
    style B fill:#fff4e1
    style C fill:#fff4e1
```

**代码位置**: `utils/discrete_material_plan_cleaner.py:292-304`

| 模块 | 功能 | 文件 |
|------|------|------|
| `get_materials_to_delete()` | 查询待删除物料编码 | `db/materials_to_delete.py` |

---

### 3. 登录与导航

```mermaid
sequenceDiagram
    participant Main as main_clean.py
    participant Auth as auth.py
    participant Browser as Chromium Browser
    participant ERP as 用友BIP系统

    Main->>Auth: login(playwright, username, password)
    Auth->>Browser: launch(headless=False)
    Auth->>Browser: new_context()
    Auth->>Browser: new_page()
    Auth->>ERP: goto(登录页面URL)
    Auth->>ERP: 填写用户名和密码
    Auth->>ERP: 点击登录按钮
    alt 有强制登录弹窗
        ERP-->>Auth: 显示弹窗
        Auth->>ERP: 点击确定
    end
    Auth-->>Main: 返回 (browser, context, page, main_frame)
```

**代码位置**: `utils/auth.py:8-72`

---

### 4. 设置查询界面

```mermaid
flowchart TB
    A[点击图标按钮] --> B[选择"订单号查询"]
    B --> C[点击"全部"标签]
    C --> D{填充显示条数}
    D --> E{成功?}
    E -->|否| F[重试<br/>最多3次]
    F --> D
    E -->|是| G[继续]

    style D fill:#fff4e1
    style E fill:#fff4e1
    style F fill:#ffe1e1
```

**代码位置**: `utils/discrete_material_plan_cleaner.py:263-290`

---

### 5. 获取生产订单号

```mermaid
flowchart LR
    A[read_production_ids] --> B[读取ProductionID.txt]
    B --> C[解析总排号列表]
    C --> D[query_production_order_numbers]
    D --> E[查询数据库<br/>获取生产订单号]

    style A fill:#fff4e1
    style D fill:#fff4e1
```

**代码位置**: `utils/discrete_material_plan_cleaner.py:41-59`

| 函数 | 功能 | 数据库表 |
|------|------|----------|
| `read_production_ids()` | 读取总排号文件 | 文件输入 |
| `query_production_order_numbers()` | 查询生产订单号 | ProductionOrder |

---

### 6. 订单处理流程

```mermaid
flowchart TB
    Start([开始处理订单]) --> FillInput[填充生产订单号]
    FillInput --> ClickQuery[点击查询按钮]
    ClickQuery --> WaitLoad[等待加载完成]

    WaitLoad --> ClickMore[点击"更多"按钮]
    ClickMore --> OpenPlan[打开"备料计划"页面]

    OpenPlan --> GetIframe[获取嵌套iframe]
    GetIframe --> WaitPlanLoad[等待备料计划页面加载]

    WaitPlanLoad --> ExtractInfo[提取信息:<br/>- 编码<br/>- 详细信息数量<br/>- 备料状态]

    ExtractInfo --> CheckStatus{状态检查}

    style Start fill:#e1f5ff
    style CheckStatus fill:#fff4e1
```

**代码位置**: `utils/discrete_material_plan_cleaner.py:61-167`

---

### 7. 物料清理流程

```mermaid
flowchart TB
    Check{detail_count > 0<br/>&<br/>status = 审批通过} -->|否| Skip[跳过处理]
    Check -->|是| ClickModify[点击修改按钮]

    ClickModify --> WaitSave[等待保存按钮可见]
    WaitSave --> Expand[点击展开按钮]
    Expand --> GetForm[获取表单容器]

    GetForm --> LoopStart{遍历物料}

    LoopStart --> GetSerial[定位序号]
    GetSerial --> GetCode[获取材料编码]
    GetCode --> GetName[获取材料名称]
    GetName --> GetQty1[获取累计待发数量]
    GetQty1 --> GetQty2[获取累计出库数量]

    GetQty2 --> Match{物料编码<br/>在待删除列表中?}

    Match -->|精确匹配| Delete[标记待删除]
    Match -->|未匹配| Keep[保留]

    Delete --> Next{下一个?}
    Keep --> Next

    Next -->|是| LoopStart
    Next -->|否| Done([完成])

    style Check fill:#fff4e1
    style Match fill:#fff4e1
    style Done fill:#e1f5ff
```

**代码位置**: `utils/discrete_material_plan_cleaner.py:169-261`

---

## 关键数据结构

### DiscreteMaterialPlanCleaner 类

```mermaid
classDiagram
    class DiscreteMaterialPlanCleaner {
        +str username
        +str password
        +str manager_name
        +bool headless
        +bool verbose
        +_print(args)
        +get_production_order_numbers(file)
        +process_order(frame, order_id, ...)
        +setup_query_interface(frame)
        +clean(file, debug_mode, ...)
    }

    class auth {
        +login(playwright, username, password)
        +logout(main_frame, verbose)
        +close_session(browser, context)
    }

    class materials_to_delete {
        +get_materials_to_delete(manager_name)
        +get_all_materials_to_delete()
    }

    class production_order_query {
        +read_production_ids(file)
        +query_production_order_numbers(ids)
    }

    DiscreteMaterialPlanCleaner --> auth
    DiscreteMaterialPlanCleaner --> materials_to_delete
    DiscreteMaterialPlanCleaner --> production_order_query
```

---

## 配置参数说明

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `username` | str | - | 登录用户名 |
| `password` | str | - | 登录密码 |
| `manager_name` | str | - | 负责人姓名（用于查询待删除物料） |
| `headless` | bool | False | 是否无头模式运行浏览器 |
| `verbose` | bool | True | 是否打印详细日志 |

---

## 文件依赖关系

```mermaid
graph TD
    A[main_clean.py] --> B[utils/discrete_material_plan_cleaner.py]
    B --> C[utils/auth.py]
    B --> D[db/production_order_query.py]
    B --> E[db/materials_to_delete.py]
    B --> F[db/connection.py]

    style A fill:#e1f5ff
    style B fill:#e1f5ff
```

---

## 执行入口

```bash
# 直接运行
python main_clean.py

# 或在虚拟环境中运行
.venv\Scripts\activate
python main_clean.py
```

---

## 注意事项

1. **浏览器模式**: 默认使用非无头模式 (`headless=False`)，便于调试观察
2. **日志输出**: 启用详细日志 (`verbose=True`)，打印每一步操作
3. **数据库连接**: 使用上下文管理器自动管理数据库连接
4. **异常处理**: 加载超时会自动重试或跳过
5. **调试模式**: 支持在指定订单处暂停调试