# P32 外贸单证中台（PI / CI / PL 自动生成）

文档编号：pcbjia-P32-TRADE-DOC-V1.0
状态：【评审通过】
定位：从成交订单直接生成单据，减少重复录入与错发风险；多币种、中英文双版、一键导出与留档。

---

## 1. 模块定位

打通订单、报价与样品单：读取产品、数量、单价、板材、净重毛重、交期，生成形式发票（PI）、商业发票（CI）、装箱单（PL），并支持报关辅助信息与 HS 编码管理。单据可预览、在线微调、导出 PDF、随邮件发送客户，保留版本记录。

入口约束：首页不改动，在供应商工作台与采购订单详情内新增「外贸单证」入口。

## 2. 单证类型

| 类型 | 用途 | 优先级 |
| --- | --- | --- |
| PI 形式发票 | 客户付款依据 | P0 |
| CI 商业发票 | 清关 | P0 |
| PL 装箱单 | 清关配套 | P0 |
| 报关辅助资料 | 品名、材质、申报要素 | P2 |
| 销售合同（中英） | 大额订单 | P2 |

可扩展：原产地证、唛头单、信用证配套单据。

## 3. 自动取值字段

- 客户信息：公司名、地址、联系人、邮箱、电话、Ship to / Bill to
- 供方信息：工厂名称、地址、税号、收款账户（含 SWIFT）
- 产品明细：层数、板材、表面工艺、尺寸、数量、单价、币种、金额
- 包装：净重 N.W.、毛重 G.W.、箱数、外箱尺寸
- 贸易条款：FOB / CIF / EXW / DAP
- 起运港、目的港、运输方式、交期
- HS 编码、申报要素、材质备注

## 4. 核心功能

1. 模板管理：多套模板（欧美版、东南亚版、越南清关版），可自定义抬头、备注、银行信息。
2. 自动填充 + 手动微调：单价、备注、唛头可改，改动留痕。
3. 币种与汇率：绑定平台汇率，人民币 / USD / EUR 换算，汇率可锁定。
4. 版本管理：每次保存生成版本，可回溯，避免单据纠纷。
5. PDF 导出：高清、无第三方水印，可直接发客户与报关行。
6. 邮件发送：选择单据附带 PDF 发送（平台邮件能力受限时改为下载后人工发送）。
7. 单证台账：按订单号、客户、日期检索。
8. 唛头管理：自定义唛头并自动打印到装箱单。

## 5. 权限

- 供应商主账号：生成本厂单据、维护银行抬头与模板
- 供应商子账号：可生成，不可修改银行基础信息
- 海外采购方：仅查看已发送单据
- 平台管理员：全局模板、HS 编码库、单证审计

## 6. 联动

- 订单模块：读取明细、数量、工艺参数
- 消息模块：单证发送通知
- 权限模块：单证入口与字段级权限
- 埋点：生成、下载、发送次数
- 风控：导出与发送内容关键词拦截

## 7. 优先级

- P0：PI / CI / PL 模板、自动填充、PDF 导出、台账
- P1：多模板切换、HS 编码库、汇率换算、版本回溯
- P2：邮件发送、唛头自定义、申报要素
- P3：原产地证、批量导出、外贸数据统计

## 8. 接口

```
GET    /api/v1/trade/template/list
POST   /api/v1/trade/template/save
GET    /api/v1/trade/template/:id
GET    /api/v1/trade/hs/list
POST   /api/v1/trade/hs/save
POST   /api/v1/trade/doc/generate
GET    /api/v1/trade/doc/list
GET    /api/v1/trade/doc/:id
POST   /api/v1/trade/doc/save-edit
POST   /api/v1/trade/doc/export-pdf
POST   /api/v1/trade/doc/send-mail
GET    /api/v1/trade/doc/versions
POST   /api/v1/trade/doc/revert
```

## 9. 建表（PostgreSQL 设计稿，仅参考不在本站执行）

```sql
CREATE TABLE trade_doc_template (
  id bigserial PRIMARY KEY,
  template_name varchar(128),
  doc_type varchar(32),          -- pi / ci / pl / contract
  supplier_id bigint DEFAULT 0,  -- 0 = 平台全局
  lang varchar(16) DEFAULT 'en',
  content text,
  bank_info text,
  remark varchar(255),
  status smallint DEFAULT 1,
  created_at timestamptz DEFAULT now(),
  updated_at timestamptz DEFAULT now()
);

CREATE TABLE trade_hs_code (
  id bigserial PRIMARY KEY,
  hs_code varchar(32),
  product_name_cn varchar(255),
  product_name_en varchar(255),
  declare_element text,
  tax_rate numeric(5,2),
  remark varchar(255),
  created_at timestamptz DEFAULT now()
);

CREATE TABLE trade_document (
  id bigserial PRIMARY KEY,
  doc_sn varchar(64) NOT NULL UNIQUE,
  order_id bigint,
  rfq_id bigint,
  supplier_id bigint NOT NULL,
  buyer_id bigint,
  doc_type varchar(32),
  template_id bigint,
  currency varchar(16) DEFAULT 'USD',
  exchange_rate numeric(10,4),
  total_amount numeric(12,2),
  trade_term varchar(16),
  ship_port varchar(128),
  dest_port varchar(128),
  mark text,
  nw varchar(64),
  gw varchar(64),
  box_qty int DEFAULT 0,
  pdf_url varchar(512),
  version int DEFAULT 1,
  status smallint DEFAULT 1,
  created_by bigint,
  created_at timestamptz DEFAULT now(),
  updated_at timestamptz DEFAULT now()
);

CREATE TABLE trade_document_item (
  id bigserial PRIMARY KEY,
  doc_id bigint NOT NULL,
  product_desc varchar(512),
  layers varchar(32),
  material varchar(128),
  surface_finish varchar(128),
  qty int,
  unit_price numeric(12,2),
  amount numeric(12,2),
  hs_code varchar(32),
  created_at timestamptz DEFAULT now()
);
```

## 10. 模板制作说明

- 三种单据共用变量占位：`{{buyer}}`、`{{supplier}}`、`{{items}}`、`{{total}}`、`{{currency}}`、`{{trade_term}}`、`{{ports}}`、`{{nw_gw}}`、`{{mark}}`。
- PI 增加付款条款与有效期；CI 增加 HS 编码与申报要素列；PL 增加箱数与外箱尺寸列。
- 英文模板使用全大写表头，金额保留两位小数，币种符号统一。
- PDF 由服务端渲染，前端只负责预览与字段校验。

## 11. 平台能力限制

邮件自动发送、支付与资金相关动作不在当前平台能力内，实际交付为：生成单据、导出 PDF、下载后由用户自行发送。