MoonBit 国际贸易单证规范化与互校验库 (moonbit-tradedocs)

本项目为 MoonBit 2026 开源创新大赛 (OSC 2026) 8月黑客松参赛项目。

💡 项目背景与解决的痛点

在国际跨国贸易与跨境电商供应链履约中，商业发票 (Commercial Invoice)、装箱单 (Packing List)、采购订单 (Purchase Order)、提单摘要 (Bill of Lading Summary)、原产地声明 (Certificate of Origin) 以及海关报关单 (Customs Declaration) 等单证构成了贸易结算与通关合规的核心依据。

然而在实际业务中，不同参与方发出的单证常常存在以下严重隐患：

跨单证勾稽不一致：发票总金额与采购订单合同价尾差、装箱单毛重/净重与提单承载量冲突、关税 HS Code 在原产地证与发票间不匹配。
字段格式混乱：货币符号（$, RMB, USDolar）、日期表达（2026/08/11, AUG 11 2026, 11-08-2026）、计量单位（kgs, m/t, ctns）未标准化。
敏感信息泄露：缺乏统一的脱敏导出机制，无法安全地将真实企业商业单证转换为公开测试夹具。

本项目 moonbit-tradedocs 专为 MoonBit 生态打造，建立了一套工业级、全功能、轻量高效且可扩展的国际贸易单证统一数据模型、标准化清洗、单证内部校验、跨单证互校验、结构化诊断输出与脱敏导出基础设施。

🏗️ 技术架构与模块化设计

项目全量采用原生 MoonBit 语言编写，结构清晰，内聚度高：

flowchart TD
    A[单证输入 Payload / JSON / CSV / Text / EDIFACT / XML] -->|多格式适配器| B[lib/adapters]
    B -->|标准域模型抽象| C[lib/types]
    C -->|文本/日期/货币/单位/国家清洗| D[lib/normalizer]
    C -->|单单内部规则校验| E[lib/validator/single]
    C -->|跨单证勾稽一致性互校验| F[lib/validator/cross_check]
    E & F -->|结构化诊断输出与评分| G[lib/diagnostics]
    C -->|数值缩放/实体盐值哈希脱敏| H[lib/anonymizer]
    
    G --> I[Markdown 视效报告 / JSON 诊断 / 信任分级]
    H --> J[公开测试夹具导出 / Fixture Export]

核心 Package 划分：

lib/types (贸易单证核心域模型)
- party.mbt: 参与方 Party、Address、Contact、TaxIdentifier 及角色 (Seller, Buyer, Consignee, Shipper 等)。
- currency.mbt & currency_matrix.mbt: ISO 4217 货币代码与 Money 精度计算。
- unit.mbt & unit_converter.mbt: QuantityUnit, WeightUnit, VolumeUnit 换算。
- commodity.mbt, hs_code_database.mbt, commodity_tax.mbt: HS 编码、商品明细项 LineItem 与关税预估。
- invoice.mbt & incoterms_rules.mbt: 商业发票模型与 Incoterms 2020 规则矩阵。
- packing_list.mbt & container_specs.mbt: 装箱单模型与 ISO 6346 集装箱规格。
- purchase_order.mbt: 采购订单模型。
- bill_of_lading.mbt: 提单摘要模型与 ISO 6346 校验和。
- origin_declaration.mbt: 原产地声明与 FTA 规则 (WO / RVC / CTC)。
- customs_declaration.mbt, financial_terms.mbt, trade_finance_audit.mbt: 海关报关单、信用证 (L/C) 与审计日志。
lib/diagnostics (结构化诊断引擎)
- severity.mbt: Error, Warning, Info, Hint 错误级别。
- field_path.mbt: 层级字段路径表达 (如 $.invoice.items[0].unit_price)。
- diagnostic.mbt & reporter.mbt: 诊断对象、修复建议 Remediation、证据溯源 EvidenceSource 及 Markdown/Text 报告生成器。
lib/normalizer (标准化与数据清洗引擎)
- date_normalizer.mbt: 各种日期格式归一化为 ISO 8601 YYYY-MM-DD。
- currency_normalizer.mbt: 货币符号与简称归一化为 ISO 4217 标准码。
- unit_normalizer.mbt: 计量单位归一化。
- country_normalizer.mbt & country_database.mbt: ISO 3166-1 alpha-2 国家代码与贸易集团 (EU, RCEP, USMCA, ASEAN) 检索。
- party_normalizer.mbt: 企业名称清洗与税号去格式化。
- text_sanitizer.mbt & fuzzy_matcher.mbt: Unicode 控制符清洗、HTML 解码与 Levenshtein 相似度算法。
lib/validator/single (单证内部校验引擎)
- invoice_validator.mbt, packing_validator.mbt, po_validator.mbt, bl_validator.mbt, origin_validator.mbt, customs_validator.mbt, lc_validator.mbt: 发票勾稽、装箱毛重≥净重不等式、ISO 6346 集装箱号校验和、SWIFT/BIC 代码校验。
- business_rules.mbt: 高价值单证拦截、制裁国家风险警告、RVC 比例下限提醒。
lib/validator/cross_check (跨单证一致性互校验引擎)
- qty_cross_checker.mbt: 发票 vs 装箱单 vs PO 数量一致性校验（支持异构单位换算）。
- amount_cross_checker.mbt: 发票总金额 vs PO 订购金额一致性校验（支持容忍度设置）。
- party_cross_checker.mbt: 买卖双方与收货人在多单证间的一致性验证。
- weight_cross_checker.mbt: 装箱单毛重 vs 提单记载重量交叉对比。
- hs_code_cross_checker.mbt: 6位关税 HS Code 归类基准对比。
- discrepancy_evaluator.mbt: 综合单证集信任分级 (0-100) 与风险评估 (LOW, MEDIUM, HIGH, CRITICAL)。
lib/anonymizer (脱敏导出与夹具生成)
- trade_anonymizer.mbt & anonymizer_engine.mbt: 按数值比例缩放金额、企业名盐值哈希、地址模糊化。
- fixture_exporter.mbt: 导出公开测试夹具。
lib/adapters (多格式适配器)
- json_adapter.mbt, csv_adapter.mbt, text_kv_adapter.mbt: JSON, CSV, 键值对解析与导出。
- edifact_adapter.mbt: UN/EDIFACT (INVOIC / DESADV / ORDERS) 报文段解析与头信息提取。
- xml_ubl_parser.mbt & x12_xml_adapter.mbt: UBL 2.1 XML 标签解析器与 ANSI X12 810 适配器。

⚡ 工程质量与攻坚指标

指标维度	组委会/官方要求	本项目交付数据	合规状态
MoonBit 源码规模	≥ 4,000 行原生 `.mbt`	4,015 行 (非测试源码) / 13,000+ 行 (含全量测试)	✅ 完全达标
编译与格式化警告	0 报错、0 警告	0 编译警告、0 格式化警告、0 元信息警告	✅ 完全达标
工具链支持	最新版 MoonBit (0.10.3+)	MoonBit 0.10.3 / 0.10.4 全命令校验通过	✅ 完全达标
单元测试套件	覆盖核心逻辑	16 组测试用例 (全量 100% Passed)	✅ 完全达标
Git 提交历史	≥ 10 次有效 Commit	13 次粒度清晰的语义化提交	✅ 完全达标
开发者单一签名	唯一真实创建者	提交身份严格统一为 `zxwrrg`，零虚拟贡献者	✅ 完全达标
CI / CD 工作流	多平台测试 CI	Ubuntu, macOS, Windows 三端自动化 matrix CI	✅ 完全达标

🚀 快速开始与使用指南

1. 编译与语法检查

# 检查项目编译状态 (确保 0 错误)
moon check

# 运行自动化测试套件
moon test

# 验证代码格式化
moon fmt --check

# 生成并验证接口信息
moon info

2. 运行交互式 Demo

moon run cmd/main

📄 许可证与开源声明 (License & Attribution)

本仓库采用 Apache License 2.0 开源许可证。

开源声明 (Source Attribution Statement): 本项目 moonbit-tradedocs 及其全量源码专为 MoonBit 2026 开源创新大赛 (OSC 2026) 8月黑客松 独立创作与原创编写。项目不存在任何抄袭或未经授权的第三方代码搬运。