# 海外合同自动生成 Skill - 开发文档（定稿版）

## 1. Skill 概述

### 1.1 名称
`auto-generate-export-contracts`

### 1.2 功能描述
根据用户提供的订单合同信息，自动基于模板生成：
1. **车辆销售合同 (Vehicle Sales Contract)** - Word (.docx) 格式
2. **Proforma Invoice** - Excel (.xlsx) 格式

如果订单信息中没有车型价格，则从内置的`单一车型价格表+配置.xlsx`中按型号匹配查找。若价格表中无匹配，则提示用户提供单价。

### 1.3 触发条件
当用户：
- 提供订单合同信息，要求生成销售合同和/或Proforma Invoice
- 提到"生成合同"、"制作PI"、"Proforma Invoice"、"销售合同"等相关关键词
- 提供包含车型、买方信息、贸易条款等订单信息时

---

## 2. 输入格式定义

### 2.1 支持两种输入格式

**格式A：结构化编号列表（标准格式）**
```
1. 姓名：陈凯武；
2.任职：经理；
3.意向车型：                 
（1） 荣光新双排货车  N350 Double Cab Pickup，- 型号：LZW1028SPY
国V China Ⅴ  代码：G33N    1台银色
（2）五菱荣光新卡双后轮 2.0L 5MT 单排 型号：LZW5030XXYLGHUG
国六B（RDE）  代码：AGMC  1台银色
4.合同签约公司中文名称：财货通（香港）国际供应链有限公司；
5.合同签约公司英文名称：Finmo (HongKong)International supply chain Co.,Ltd.
6.合同签约公司中文地址：香港德輔道西 93-97 號聯威商業大廈 13 樓 B-C 室
7.合同签约公司英文地址：FLAT B&C,13/F.,LUEN WAI COMMERCIAL BUILDING,93-97 DES VOEUX ROAD WEST,HONG KONG
8.合同联系电话：13640613242
9.国内出发港口：广州南沙；
10.目的地国家：巴拿马Panama
11.目的地港口：巴尔博亚港 Balboa
12.结算方式:FCA
```

**格式B：自然语言描述**
```
帮我生成销售合同，买方是财货通（香港）国际供应链有限公司，英文名Finmo (HongKong)International supply chain Co.,Ltd.，要买两辆五菱车：
1. 荣光新双排货车 LZW1028SPY，发动机代码G33N，1台银色
2. 五菱荣光新卡双后轮 LZW5030XXYLGHUG，发动机代码AGMC，1台银色
贸易条款FCA，出发港广州南沙，目的地巴拿马，联系电话13640613242
```

### 2.2 需要提取的核心字段

| 字段 | 说明 | 是否必填 |
|---|---|---|
| 买方公司中文名称 | | 必填 |
| 买方公司英文名称 | | 必填 |
| 买方中文地址 | | 必填 |
| 买方英文地址 | | 必填 |
| 合同联系电话 | | 必填 |
| 车型列表 | 每辆含：型号、发动机代码、数量、颜色 | 必填（至少1辆） |
| 贸易条款 | FCA / FOB / EXW / CIF 等 | 必填 |
| 出发港口 | | 必填 |
| 目的地国家 | | 必填 |
| 目的地港口 | | 可选 |
| 销售人员姓名 | | 可选 |
| 销售人员职位 | | 可选 |

**注意**：订单中的"付款公司"信息（创兴银行/账户等）**不在合同中体现**，模板中保留固定的卖方收款账户。

### 2.3 Skill自动生成的字段

| 字段 | 生成规则 |
|---|---|
| 合同编号 | `HLXYWPA{年月日}`，如 `HLXYWPA20260530` |
| 签署日期 | 当前日期 |
| 卖方信息 | 固定模板值 |
| 收款银行信息 | 固定模板值（卖方账户） |

---

## 3. 车型价格配置表

### 3.1 数据来源
`assets/vehicle-price-config.xlsx`（由 `单一车型价格表+配置.xlsx` 转换而来）

### 3.2 Sheet列表
| 索引 | Sheet名 |
|---|---|
| 0 | 五菱之光小卡 |
| 1 | 五菱之光 |
| 2 | 五菱宏光v |
| 3 | 新宏光S客车 |
| 4 | 星光560 |
| 5 | 星光730 |
| 6 | 缤果 |
| 7 | 星光 |
| 8 | 星光s |
| 9 | 悦也plus |
| 10 | 云海 |
| 11 | 宏光s3 |
| 12 | 星驰 |
| 13 | 扬光 |
| 14 | 迷你 |
| 15 | 五菱荣光新卡燃油 |
| 16 | 荣光小卡 |

### 3.3 列定义
| 列 | 字段名 | 说明 |
|---|---|---|
| A | 车型车系 | Vehicle Series |
| B | 市场名称 | Market Name (中文) |
| C | 版本 | Version |
| E | 官方指导价 | MSRP (RMB) |
| F | 系别 | Series Code (中英文) |
| G | 型号 | Model (ModelCode) |
| H | 车型代码 | Model Code |
| I | 发动机代码 | Engine Code |
| J | 主要配置描述 | Major Configurations Description (中英文) |
| K | FOB价格(人民币) | FOB Price (RMB) |
| L | FCA价格(人民币) | FCA Price (RMB) |
| M | EXW价格(人民币) | EXW Price (RMB) |
| N | FOB价格(美元) | FOB Price (USD) |
| O | FCA价格(美元) | FCA Price (USD) |
| P | EXW价格(美元) | EXW Price (USD) |

### 3.4 匹配逻辑
```python
def match_vehicle(model_code: str, trade_term: str) -> dict:
    """
    遍历所有sheet，在G列(型号/ModelCode)精确匹配model_code
    根据trade_term选择对应USD价格列:
      - FCA -> O列
      - FOB -> N列  
      - EXW -> P列
    返回: {
        'unit_price_usd': float,
        'description_cn': str,   # B列市场名称
        'description_en': str,   # F列系别英文
        'model_code': str,       # G列
        'engine_code': str,      # I列
        'version': str,          # C列
    }
    """
```

**匹配失败处理**：如果G列精确匹配不到输入的ModelCode，**提示用户手动提供该车型的单价USD和配置描述**。

---

## 4. 模板替换规则

### 4.1 Proforma Invoice 模板替换字段

| 单元格 | 替换内容 |
|---|---|
| B7 | TO: {买方公司英文名称} |
| G7 | Contract NO.: {合同编号} |
| H8 | DATE: {当前日期} |
| B8 | ADD: {买方公司英文地址} |
| B9 | Tel: {合同联系电话} |
| B12 | ORIGINAL: LIUZHOU CHINA（固定） |
| G12 | SHIPPING MARKS: N/M（固定） |
| B17-B22 | 每行一辆车: 配置描述文本 |
| C17-C22 | 数量 |
| F17-F22 | 单价USD |
| H17-H22 | 金额公式 `=C*F` |
| E23 | FCA {出发港口} |
| H23 | =SUM(H17:H22) 保留公式 |
| B24 | SAY US {英文大写金额} only |
| B27 | Delivery terms: FCA {出发港口} |
| B29 | Payment terms（30%和70%动态计算） |

**银行账户信息区**：保持模板固定值（卖方GUANGXI HAOLING收款账户）。

### 4.2 销售合同模板替换字段

| 位置 | 替换内容 |
|---|---|
| No.: 后 | {合同编号} |
| Signature Date: 后 | {当前日期} |
| Buyer: | {买方公司英文名称} |
| 买方： | {买方公司中文名称} |
| ADD: | {买方公司英文地址} |
| 地址： | {买方公司中文地址} |
| Tel: | {合同联系电话} |
| Export Destination: | {目的地国家} |
| Incoterms: | {贸易条款} {出发港口} |

**Table0（车辆明细表）**：填入车型、数量、单价、总金额。
**Table1（银行账户）**：保持模板固定值。
**付款条款**：30%和70%金额动态计算。

---

## 5. 核心工作流

```
Step 1: 接收用户输入（支持编号列表或自然语言）
  └─> 使用LLM或正则解析提取核心字段

Step 2: 车型信息处理
  └─> IF 用户提供单价: 直接使用
  └─> ELSE: 在价格表中按ModelCode精确匹配
      └─> IF 匹配成功: 获取对应贸易条款的USD价格
      └─> IF 匹配失败: 提示用户手动提供单价USD

Step 3: 计算汇总
  └─> 总数量、总金额、30%金额、70%金额、英文大写

Step 4: 生成 Proforma Invoice (xlsx)
  └─> 复制模板，替换字段，保留公式

Step 5: 生成 销售合同 (docx)
  └─> 复制模板，替换段落和表格内容

Step 6: 输出
  └─> 输出两个文件 + 固定提示语
```

---

## 6. Skill 文件结构

```
auto-generate-export-contracts/
├── SKILL.md
├── scripts/
│   ├── generate_contracts.py
│   ├── match_vehicle.py
│   ├── number_to_words.py
│   └── parse_order_info.py
├── assets/
│   ├── proforma-invoice-template.xlsx
│   ├── vehicle-sales-contract-template.docx
│   └── vehicle-price-config.xlsx
└── references/
    └── field-mapping.md
```

---

## 7. 关键技术方案

### 7.1 依赖库
- `python-docx`: 读写 Word 文档
- `openpyxl`: 读写 Excel 文档
- `num2words`: 数字转英文单词

### 7.2 合同编号生成
```python
from datetime import datetime
contract_no = f"HLXYWPA{datetime.now().strftime('%Y%m%d')}"
# 示例: HLXYWPA20260530
```

### 7.3 数字转英文大写
```python
from num2words import num2words
amount = 14488
words = num2words(amount, lang='en').upper()
# FOURTEEN THOUSAND FOUR HUNDRED AND EIGHTY-EIGHT
```

---

## 8. 边界情况处理

| 场景 | 处理方式 |
|---|---|
| 价格表无匹配 | 提示用户手动提供单价USD |
| 用户提供的价格优先于价格表 | 使用用户值 |
| 多款车型（>2辆） | PI支持最多6行，销售合同表格动态扩展 |
| 非FCA/FOB/EXW贸易条款 | 替换文本，价格默认使用FCA列 |
| 出发港口为空 | 默认"Guangzhou nansha Port" |
| 目的地国家为空 | 提示用户补充 |
| 用户只要求生成一个文件 | 支持单独生成 |

---

## 9. 输出规范

### 9.1 文件名
- Proforma Invoice: `{合同编号}-Proforma Invoice.xlsx`
- 销售合同: `{合同编号}-车辆销售合同.docx`

### 9.2 输出后固定提示语
> 销售合同、Proforma Invoice已生成，报价员核对无误后再发送给客户。