# edifact_summary 工作流程说明

本文说明 `edifact_summary.py` 从 EDIFACT 文本到摘要输出的完整处理路径。

## 1. 输入与解析

1. CLI 读取输入文件内容（UTF-8）。
2. 调用 `parse_edifact(document)` 把原始报文解析为结构化对象（interchange/group/transaction/segment）。
3. `build_summary(parsed)` 对解析结果进行业务摘要提取。

## 2. 摘要构建主流程

`build_summary` 的遍历层级：

1. `interchanges`
2. `functional_groups`
3. `transaction_sets`

对每个 transaction：

1. 调用 `summarize_transaction(transaction)` 生成单消息摘要。
2. 附加 interchange 元信息（sender/receiver/control_ref/date/time）。
3. 追加到 `messages` 列表。

最终输出结构：

- `interchange_count`: 互换组数量
- `messages`: 每条业务消息的摘要

## 3. 单消息摘要提取（summarize_transaction）

单消息提取按以下顺序进行：

1. 组装 transaction 全量 segments（start + body + end）。
2. 提取文档头 `BGM`：
   - `document.code`
   - `document.number`
   - `document.function_code`
3. 提取公共业务信息：
   - `extract_dates`：读取 `DTM`
   - `extract_references`：读取 `RFF`
   - `extract_parties`：读取 `NAD`
   - `extract_currency`：读取 `CUX`
4. 提取行项目：
   - `extract_line_items` 以 `LIN` 为锚点聚合关联的 `PIA/QTY/PRI`
   - 产出 `line_items` 与 `line_item_count`
5. 估算总金额 `estimated_total`：
   - 每行选取“优先数量限定符 + 优先价格限定符”
   - 执行 `qty * price` 后累加
   - 四舍五入到 2 位小数

## 4. 关键提取函数说明

- `safe_value(segment, element_index)`：按元素序号安全读取标量值。
- `safe_components(segment, element_index)`：读取复合元素组件值数组。
- `qualifier_name(...)`：限定符名称优先使用内置映射，缺失时回退到 parser 语义元数据。
- `pick_measure(entries, preferred_qualifiers)`：从候选列表中按优先限定符选择最合适值。

## 5. 输出模式

`edifact_summary.py` 支持两种输出：

1. `--json`：输出机器可读 JSON。
2. 默认文本模式：`render_summary_table` 生成 ASCII 表格，按消息分块展示。

## 6. 运行示例

```bash
python3 edifact_summary.py sample-orders.edifact -o sample-orders.summary.txt
python3 edifact_summary.py sample-orders.edifact --json -o sample-orders.summary.json
```

## 7. 设计取舍

- 优先保留“可读摘要”而非完整报文细节。
- 金额为估算值，依赖报文中可解析的数量与价格。
- 名称映射兼容两种来源：静态映射 + 语义元数据回退。
