外贸合规工作台

@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> 值。

配置

• TRADE_COMPLIANCE_DATA_DIR：上传源文件和生成文件目录
• 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