让开源，少一点语言距离。
npm包中文文档

@chenchaolong/plugin-trade-compliance-workbench

中文文档
1.0.233发布于 2026/11/05AGPL-3.0TypeScriptES Module近 30 天下载 7638

外贸合规工作台新版组织级插件

原始使用文档
中文原文
文档目录11 节
  1. 功能范围
  2. 开发
  3. 本地预览
  4. 视觉检查
  5. 目录解析样本验证
  6. 演示数据初始化
  7. 装箱批次解析与语言
  8. 供应商资料与出货文件币种
  9. 配置
  10. 完整验证
  11. 多采购单装箱批次

外贸合规工作台

@chenchaolong/plugin-trade-compliance-workbench 是面向 data-xpert 的组织级外贸合规插件，按照仓库内需求确认、重建设计、数据模型和固定 Excel 模板从零重建。

功能范围

  • 首页前端静态风险提示与固定业务流程
  • 管控商品目录、公司制裁目录及文件批次导入
  • 供应商、采购订单、采购商品三级采购合规管理
  • 唯一客户、客户合同七类关键条款及 AI 风险建议
  • 基于客户合同和采购订单编号实时派生销售订单与商品
  • 客户/订单定价利润率、收付款、退税、合规利润率与换汇成本
  • PI、CI、PL、报关单独立生成、历史下载与 Univer 在线审核
  • 采购和销售人民币实时分析
  • 企业、银行、利润规则和月度美元汇率设置

销售订单和销售商品不建立持久化副本；采购合同和客户合同重复时阻止入库；业务删除全部使用逻辑删除。

首页操作提醒与业务流程由前端静态维护，不在系统设置中编辑。数据模型不包含风险提示配置表；插件升级启动时物理删除旧表 plugin_trade_compliance_risk_notice_settings，删除失败会阻止插件启动。

开发

pnpm install
pnpm test
pnpm typecheck
pnpm build

插件入口为 dist/index.js，插件级别固定为 organization。

本地预览

pnpm build && pnpm preview

预览默认监听 127.0.0.1 的随机可用端口，并在终端输出访问地址；如需固定端口，可执行 PORT=4173 pnpm preview。在运行预览的终端按 Ctrl+C 停止服务。

视觉检查

pnpm visual:check

该命令生成 38 张原型映射截图、9 张窄屏截图和 3 张布局契约截图，共 50 张，写入 artifacts/visual-check/。检查覆盖 route、页面标题、dialog、关键字段、操作列策略、184/56px 侧栏、内部滚动、首页八步四列流程、按钮图标，以及页面和控件的溢出、重叠问题。

目录解析样本验证

混合目录管线对 XLS/XLSX、结构化 DOCX 和带文本表格层的 PDF 使用代码解析；无法验证的局部来源块进入 ChatKit/人工复核，旧 DOC、图片和扫描 PDF 回退兼容模式。可使用明确提供的样本路径运行只读验证：

pnpm verify:catalog-samples -- "/path/to/controlled-catalog.pdf" "/path/to/sanction-catalog.docx"

命令会先构建插件，再输出 PDF schema、自动接受数、复核原因、DOCX 实体/自然人数和别名统计；不会写入数据库。

演示数据初始化

警告：以下命令会向 XPERT_ORG_ID 指定的真实组织写入演示业务数据和演示 XLSX 文件。请先确认目标组织，生产组织不要执行。

演示数据绝不会在插件安装、bootstrap 或 startup 时自动初始化，只能通过显式脚本触发。执行用户必须拥有目标组织的 ORG_DEMO_EDIT 权限。每个租户/组织使用固定 marker DEMO-20260725 独立幂等：首次执行在单一数据库事务中写入完整演示数据并输出 inserted: true、marker、数据年份和各类记录数；再次执行输出 inserted: false、reason: "already_seeded" 和 marker，不会再次保存记录或文件。

XPERT_API_URL=http://localhost:3000 \
XPERT_TOKEN='Bearer <login-jwt>' \
XPERT_ORG_ID='<organization-uuid>' \
XPERT_ID='<xpert-uuid>' \
pnpm seed:demo

必需环境变量仅为 XPERT_API_URL、XPERT_TOKEN、XPERT_ORG_ID 和 XPERT_ID；可选的 XPERT_HTTP_TIMEOUT_MS 用于设置 1 到 300000 毫秒的请求超时，默认 15000。脚本只从外部环境读取这些值，不读取数据库，也不会输出 token；失败信息中的已配置 token 会被脱敏。它会按 manifest 的 source.plugin 精确发现当前插件并调用严格确认的 seed_demo_data action；XPERT_TOKEN 可以是原始 JWT 或完整的 Bearer <jwt> 值。

装箱批次解析与语言

上传供应商 PL 后按真实任务 ID 展示排队、提取、AI 解析、校验、保存及终态；关闭后重新打开可恢复。首次打开查询一次，仅有进行中任务时每五秒自动查询，任务结束即停止；无任务时可按需手动刷新。进行中任务和最近结果展开，较早结果折叠。相同采购合同或批次的活动任务会阻止重复上传；替换期间暂停目标批次的编辑和确认，相关订单暂停生成。状态查询走只读通道，不占用 Excel 保存操作。生成提交前会在组织锁内再次校验解析状态和装箱指纹。

PI、CI、PL 优先使用已审核的英文商品资料；未上传资料或个别字段缺失时，以采购商品信息为基础翻译，已有英文、型号、数量及包装数字不重复翻译。翻译失败保留为空并标记待核对，不向商品描述混入提示文字。报关单保留中文，不做英文翻译。合并生成时共享翻译结果，详细核对位置随文件保存。

供应商资料与出货文件币种

  1. 先上传并审核采购合同（PDF、DOC/DOCX、XLS/XLSX 或图片），采购商品数量和人民币采购价格是业务主数据。
  2. 上传客户框架合同并关联合同、维护利润率。界面名称仍为“利润率”，计算使用加价率：人民币销售单价 = 采购单价 × (1 + 利润率)。自动计算的单价、金额保留两位小数；手工维护的高精度单价及商品金额继续保留。
  3. 进入生成出货文件，按需展开“供应商资料（可选）”。英文报价资料仅补充英文品名、描述、型号和单位；其报价金额与币种不参与定价。报关商品资料仅补充报关品名、HS、规格型号、品牌、材质、用途和申报要素。解析完成后核对匹配并保存审核，生成时自动使用每件商品最新已审核资料。无英文资料时回退采购信息翻译，无报关资料时按已有采购信息生成待核对文件。
  4. 供应商装箱单仍单独导入，用于箱数、尺寸、毛净重、体积及共用包装；不替代采购商品数量和价格。资料数量、型号或 HS 不一致会列入核对清单，不覆盖采购数据。
  5. 生成文件时选择 CNY 或 USD，与报价单、银行选择解耦。USD 单价 = 人民币销售单价 ÷ 月度美元兑人民币汇率（1 USD = X CNY），逐条取所属采购订单下单日期的月份；跨月订单各取各自月份汇率。缺日期、日期无效、缺少或无效汇率会阻止生成，并提示补全对应数据。
  6. PI、CI 和报关文件使用同一输出定价快照；PL 无金额字段。销售订单、收付款及数据分析始终使用人民币。文件快照记录来源行、资料版本、币种、汇率月份及金额，后续资料或汇率变化不会改写历史文件。若手工总额覆盖与明细金额不一致，先调整明细或清除总额覆盖，避免生成无法对账的文件。

英文资料、报关资料支持原文件预览、下载、移除、任务重试及组织隔离。相同文件在相同采购范围内不会重复解析；审核后的来源信息保留，旧任务回调不能覆盖新解析结果。清空业务数据会移除这些业务资料，继续保留管控商品目录及公司制裁目录。

配置

  • 销售文件（PI / CI / PL / 报关单）从工作台生成和编辑保存时使用平台专家/项目工作区文件接口，storageFileId 保存版本化的可移植工作区引用。下载按记录中的原工作区归属读取，并由平台验证当前访问权限；工作区服务不可用时明确报错，不降级到 API 容器本地目录。旧本地记录继续兼容读取；重新生成会创建工作区版本，不再复用旧本地缓存。已丢失且无备份的原文件需要重新生成，不能恢复丢失的人工编辑。
  • TRADE_COMPLIANCE_DATA_DIR：本地兼容存储目录（上传源文件、Logo 和历史销售文件）。生产环境必须显式配置为持久化目录（应用目录之外、挂载持久卷）；未配置时使用用户主目录下的 .trade-compliance-data 兜底，并在启动日志中告警。新写入的文件会以绝对路径作为存储标识，后续修改该配置不影响已有文件的读取
  • TRADE_COMPLIANCE_LEGACY_DATA_DIRS：冒号分隔的历史数据目录列表（可选）。存量文件（旧相对标识）读取失败时，会依次尝试当前目录、历史默认目录、插件进程自动探测到的本机 .trade-compliance-data 目录（常见挂载点一层，如 /srv、/home、/opt 等），以及这里显式指定的目录；找回后自动复制到当前目录。零配置即可完成部署迁移后的历史文件恢复
  • TRADE_COMPLIANCE_MAX_UPLOAD_MB：上传上限，默认 20
  • TRADE_COMPLIANCE_HS_BASE_URL：HS编码网地址，默认 https://hsbianma.com
  • TRADE_COMPLIANCE_HS_TIMEOUT_MS：海关编码查询超时
  • TRADE_COMPLIANCE_TRANSLATION_ENDPOINT：OpenAI 兼容翻译接口，默认千问兼容地址
  • TRADE_COMPLIANCE_TRANSLATION_API_KEY：翻译服务密钥，必须通过插件 secret 字段或运行环境注入
  • TRADE_COMPLIANCE_TRANSLATION_MODEL：翻译模型，默认 qwen3.6-flash
  • TRADE_COMPLIANCE_TRANSLATION_TARGET_LANGUAGE：默认 zh-CN
  • TRADE_COMPLIANCE_TRANSLATION_BATCH_SIZE：单个模型请求记录数，默认 10，最大 100
  • TRADE_COMPLIANCE_TRANSLATION_CONCURRENCY：并发请求数，默认 5，最大 20
  • TRADE_COMPLIANCE_TRANSLATION_TIMEOUT_MS：单个请求超时，默认 120000

目录快速管线会自动翻译纯翻译复核块，管控商品保留名称和管控说明原文，制裁公司保留法定名称和别名，只翻译制裁原因与备注。翻译失败的记录会释放回待复核队列，不会写入伪翻译或丢失来源证据。销售文件仍兼容原有单文本翻译适配器。

真实千问连通性验证不会输出密钥：

TRADE_COMPLIANCE_TRANSLATION_API_KEY='<plugin-secret>' pnpm verify:qwen-translation

使用真实 PostgreSQL、真实千问和两份目录文件执行解析、翻译、复核、发布及来源证据端到端验收：

TRADE_COMPLIANCE_TEST_POSTGRES_URL='<postgres-url>' \
TRADE_COMPLIANCE_TRANSLATION_API_KEY='<plugin-secret>' \
pnpm verify:catalog-e2e -- '<controlled-catalog.pdf>' '<sanction-catalog.docx>'

完整验证

pnpm test
pnpm typecheck
pnpm build
pnpm visual:check

pnpm -C /Users/chenchaolong/项目/xpert-plugins/plugin-dev-harness install
pnpm -C /Users/chenchaolong/项目/xpert-plugins/plugin-dev-harness build
node /Users/chenchaolong/项目/xpert-plugins/plugin-dev-harness/dist/index.js \
  --workspace /Users/chenchaolong/项目/trade-compliance-workbench \
  --plugin @chenchaolong/plugin-trade-compliance-workbench

npm pack --dry-run

git diff --check
git status --short
rg -n '\b(TODO|TBD)\b' src scripts

验证时应确认测试、类型检查、构建和视觉检查退出码为 0，生命周期输出包含 Plugin loaded successfully，npm pack --dry-run 清单包含应用 JS/CSS、编辑器资源和模板；最后检查 diff 无空白错误且无未解决占位符。Workbench slot 名称由 provider 契约测试单独校验。

业务规则以以下文件为准：

  • docs/superpowers/specs/2026-07-22-trade-compliance-workbench-requirements-confirmation.md
  • docs/superpowers/specs/2026-07-22-trade-compliance-workbench-redesign.md
  • docs/superpowers/specs/2026-07-23-trade-compliance-workbench-data-model-confirmation.md

多采购单装箱批次

供应商 PL 按独立装箱批次上传，可关联同供应商、同客户的多张采购单；同一采购单也可选择多个分批出货批次。销售合规管理和销售文件管理共用批次选择与匹配核对界面。已有装箱单可直接关联其他采购单，不必重复上传。替换文件须指定批次，保留批次标识并递增版本。

匹配核对可编辑包装原始数据、分配采购商品及实际数量，并明确是否计入商品出货。唯一英文名称仍存在规格冲突时保持待确认。主机、闸杆、配件对应的物理包装仅汇总一次；跨单共箱单独生成时须明确箱数、毛重和体积分配。明确随主机共箱的辅助包装可人工设为 0 箱并取消商品数量计入，系统验证存在同商品的主包装，不将未知指标默认归零。

PL 使用所选批次实际出货数量，PI/CI 继续使用订单数量和金额。草稿明确标识 DRAFT，并提示缺失或未确认范围；正式生成要求批次已确认、商品分配完整、数量不超采购数量及包装指标完整。旧数据迁移只回填缺失关联，不覆盖人工核对结果；热刷新后的首次装箱服务调用也执行必要迁移。

版本与发布记录

@chenchaolong/plugin-trade-compliance-workbench 共发布 309 个版本，首次发布于 2026/06/17；过去 12 个月发布了 309 个版本。

版本发布日期距今
1.0.233latest2026/11/054 天前
1.0.2322026/11/054 天前
1.0.2312026/11/036 天前
1.0.2302026/11/036 天前
1.0.2292026/11/036 天前
1.0.2282026/10/2713 天前

关于 @chenchaolong/plugin-trade-compliance-workbench 的常见问题

@chenchaolong/plugin-trade-compliance-workbench 是什么？

外贸合规工作台新版组织级插件

如何安装 @chenchaolong/plugin-trade-compliance-workbench？

在项目目录运行 npm install @chenchaolong/plugin-trade-compliance-workbench，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^3.25.67）、react（>=18 <19）、typeorm（^0.3.24）、react-dom（>=18 <19）、@nestjs/core（^11.1.6）、@nestjs/common（^11.1.6）、@langchain/core（>=0.3.0）、@nestjs/typeorm（^11.0.0）、@xpert-ai/contracts（^3.15.18）、@xpert-ai/plugin-sdk（^3.18.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

@chenchaolong/plugin-trade-compliance-workbench 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@chenchaolong/plugin-trade-compliance-workbench 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module，更早的版本需要改用动态 import()。

@chenchaolong/plugin-trade-compliance-workbench 可以商用吗？

@chenchaolong/plugin-trade-compliance-workbench 使用 AGPL-3.0 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

@chenchaolong/plugin-trade-compliance-workbench 的下载量有多少？

根据 npm 官方下载统计，@chenchaolong/plugin-trade-compliance-workbench 在 2026/10/10 – 2026/11/08 这 30 天内被下载 7,638 次，日均约 255 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@chenchaolong/plugin-trade-compliance-workbench 还在维护吗？

最新版本 1.0.233 发布于 2026/11/05（4 天前）；至今共发布 309 个版本，其中过去 12 个月发布了 309 个；首次发布于 2026/06/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。