# @chenchaolong/plugin-trade-compliance-workbench 中文文档 规范地址：https://npmcn.com/package/%40chenchaolong/plugin-trade-compliance-workbench/ 版本：1\.0\.233 npm 元数据更新时间：2026-11-05T12:10:11.360Z 中文译文更新时间：2026-11-09T12:04:09.327Z 软件包许可：AGPL-3\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40chenchaolong/plugin-trade-compliance-workbench 原文对照：https://npmcn.com/package/%40chenchaolong/plugin-trade-compliance-workbench/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：22.6 MB，670 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：16 个 - 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 - 首次发布：2026-06-17T06:22:30.616Z - 最新版本发布：2026-11-05T12:10:11.175Z - 近 30 天下载量：7638（2026-10-10 至 2026-11-08，npm 官方下载统计） - 已发布版本数：309（近 12 个月 309 个） ## 中文简介 外贸合规工作台新版组织级插件 ## 安装 ```sh npm install @chenchaolong/plugin-trade-compliance-workbench ``` 也可以使用：`pnpm add @chenchaolong/plugin-trade-compliance-workbench`、`yarn add @chenchaolong/plugin-trade-compliance-workbench`、`bun add @chenchaolong/plugin-trade-compliance-workbench` ## README # 外贸合规工作台 `@chenchaolong/plugin-trade-compliance-workbench` 是面向 data-xpert 的组织级外贸合规插件，按照仓库内需求确认、重建设计、数据模型和固定 Excel 模板从零重建。 ## 功能范围 - 首页前端静态风险提示与固定业务流程 - 管控商品目录、公司制裁目录及文件批次导入 - 供应商、采购订单、采购商品三级采购合规管理 - 唯一客户、客户合同七类关键条款及 AI 风险建议 - 基于客户合同和采购订单编号实时派生销售订单与商品 - 客户/订单定价利润率、收付款、退税、合规利润率与换汇成本 - PI、CI、PL、报关单独立生成、历史下载与 Univer 在线审核 - 采购和销售人民币实时分析 - 企业、银行、利润规则和月度美元汇率设置 销售订单和销售商品不建立持久化副本；采购合同和客户合同重复时阻止入库；业务删除全部使用逻辑删除。 首页操作提醒与业务流程由前端静态维护，不在系统设置中编辑。数据模型不包含风险提示配置表；插件升级启动时物理删除旧表 `plugin_trade_compliance_risk_notice_settings`，删除失败会阻止插件启动。 ## 开发 ```bash pnpm install pnpm test pnpm typecheck pnpm build ``` 插件入口为 `dist/index.js`，插件级别固定为 `organization`。 ### 本地预览 ```bash pnpm build && pnpm preview ``` 预览默认监听 `127.0.0.1` 的随机可用端口，并在终端输出访问地址；如需固定端口，可执行 `PORT=4173 pnpm preview`。在运行预览的终端按 `Ctrl+C` 停止服务。 ### 视觉检查 ```bash pnpm visual:check ``` 该命令生成 38 张原型映射截图、9 张窄屏截图和 3 张布局契约截图，共 50 张，写入 `artifacts/visual-check/`。检查覆盖 route、页面标题、dialog、关键字段、操作列策略、184/56px 侧栏、内部滚动、首页八步四列流程、按钮图标，以及页面和控件的溢出、重叠问题。 ### 目录解析样本验证 混合目录管线对 XLS/XLSX、结构化 DOCX 和带文本表格层的 PDF 使用代码解析；无法验证的局部来源块进入 ChatKit/人工复核，旧 DOC、图片和扫描 PDF 回退兼容模式。可使用明确提供的样本路径运行只读验证： ```bash 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，不会再次保存记录或文件。 ```bash XPERT_API_URL=http://localhost:3000 \ XPERT_TOKEN='Bearer ' \ XPERT_ORG_ID='' \ XPERT_ID='' \ 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 ` 值。 ## 装箱批次解析与语言 上传供应商 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 目录快速管线会自动翻译纯翻译复核块，管控商品保留名称和管控说明原文，制裁公司保留法定名称和别名，只翻译制裁原因与备注。翻译失败的记录会释放回待复核队列，不会写入伪翻译或丢失来源证据。销售文件仍兼容原有单文本翻译适配器。 真实千问连通性验证不会输出密钥： ```bash TRADE_COMPLIANCE_TRANSLATION_API_KEY='' pnpm verify:qwen-translation ``` 使用真实 PostgreSQL、真实千问和两份目录文件执行解析、翻译、复核、发布及来源证据端到端验收： ```bash TRADE_COMPLIANCE_TEST_POSTGRES_URL='' \ TRADE_COMPLIANCE_TRANSLATION_API_KEY='' \ pnpm verify:catalog-e2e -- '' '' ``` ## 完整验证 ```bash 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 是什么？ 外贸合规工作台新版组织级插件 ### 如何安装 @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 和提交记录判断。