---
last_reviewed: 2026-06-15
---

# src — 主源码目录

包含财务报销自动化系统的全部源码模块。

## 架构分层

```
src/
├── agent/     Agent 调度层（协调提取-校验-修正循环）
├── core/      核心业务层（提取、匹配、校验）
├── infra/     基础设施层（浏览器、文档、LLM 提示词）
├── web/       Web 界面层（Flask + SSE）
├── pipeline.py      CLI 流程编排
├── pipeline_core.py CLI/Web 公共管道逻辑
├── main.py          CLI 入口
├── config.py        配置加载
└── exceptions.py    异常定义
```

## 模块清单

| 文件/目录 | 说明 |
|-----------|------|
| `agent/` | Agent 调度：校验-修正循环、状态机管理、SSE 事件发射 |
| `core/` | 核心业务逻辑：信息提取、金额匹配、信息校验 |
| `infra/` | 基础设施：浏览器自动填报、文档处理、LLM 提示词管理 |
| `web/` | Web 界面：Flask 应用、SSE 日志流、可编辑表格、移动端上传、会话隔离 |
| `pipeline.py` | CLI 流程编排：串联提取 → 类型判断 → 信息提取 → 浏览器填报 |
| `pipeline_core.py` | CLI/Web 公共管道逻辑：发票类型判断、缓存提取 |
| `main.py` | CLI 入口：`--step` 分步执行、`-u/-p` 覆盖凭据 |
| `config.py` | 配置加载：`config.json` + 环境变量 |
| `exceptions.py` | 异常层次定义 |

## 数据流

```mermaid
graph TD
    A[CLI/Web 入口] --> B["pipeline.py (编排)"]
    B --> C["core/extraction/extractor.py (统一提取入口)"]
    C --> D["infra/documents/pdf.py (PDF 渲染为图片)"]
    C --> E["core/extraction/llm_extractor.py (多模态 LLM 识别)"]
    E --> F["发票 invoice_type=train/hotel/general"]
    E --> G["支付记录 invoice_type=payment"]
    E --> H["出差事前申请单 invoice_type=application"]
    C --> I["core/matching/matcher.py (发票与支付记录按金额匹配)"]
    I --> J["一对一匹配 发票数 == 刷卡数"]
    I --> K["一对多匹配 贪心算法 相对容差 3%"]
    C --> L["infra/documents/invoice.py (CSV/JSON 读写)"]
    L --> M["payment_records.csv (支付记录级别)"]
    L --> N["invoice_summary.csv (发票级别)"]
    L --> O["travel_applications.json (出差申请单)"]
    B --> R{"判断报销类型"}
    R -->|差旅| T["core/extraction/llm_extractor.py (差旅信息提取)"]
    R -->|普通| V["core/extraction/llm_extractor.py (普通发票信息提取)"]
    T --> W["travel_info.json (差旅信息: 交通/住宿明细、补贴、附件清单)"]
    V --> X["normal_info.json (普通发票信息: 报销说明、发票总数、总金额、支付方式、附件清单)"]
    W --> P["infra/browser/ (浏览器填报 - 仅接收信息并填报)"]
    X --> P
    P --> Q["差旅模式: travel_info.json → 填报差旅单 → 上传差旅附件"]
    P --> S["普通模式: 基本信息 → 录入明细 → 支付信息 → 上传附件"]
```

## 子模块文档

| 目录 | 文档 |
|------|------|
| `agent/` | [`agent/README.md`](agent/README.md) |
| `core/` | [`core/README.md`](core/README.md) |
| `infra/` | [`infra/README.md`](infra/README.md) |
| `web/` | [`web/README.md`](web/README.md) |

## 启动方式

```bash
# CLI 模式
uv run python src/main.py --step all

# Web 模式
uv run python src/web/app.py
# 访问: http://localhost:5000
```

## 发票类型与路由

系统根据 `invoice_type` 字段自动分流：

| 发票类型 | 走什么流程 | 是否生成出库单 |
|----------|-----------|--------------|
| `train` / `hotel` | 差旅报销 | 否 |
| `general` | 普通报销 | 是（易耗品出库单） |
| `application` | 出差事前申请单 | 否（单独存储为 JSON） |

**注意**：差旅发票和普通发票不支持混报，混合时会报错。